你的应用如何设计文件数据模型？

一、文件是什么？

文件模型的核心是 “你的业务系统如何用一套稳定的文件标识和元信息，把业务文件映射到石墨能力上”。

在石墨文档中台里，文件首先是你业务系统中的一个内容实体，在你的业务系统中定义，每个文件拥有的唯一的 fileId（文件 ID） 。它是一个标注类型的的文档对象，可能是轻文档、专业文档、表格、幻灯片、表单、应用表格。

石墨之所以能正确理解这个文件，依赖的是你后端返回的文件基础信息，例如 fileId（文件 ID）、name（文件名）、type（文件类型） 和 permissions（文件权限）。

若处于预览场景，普通 Office 文件在石墨文档中台中也被视为“文件”，但它的 type 固定为 file，更接近一个可下载、可预览的资源，而不是一个可以协同编辑的石墨文档。

二、如何设并定义文件唯一 ID（fileId）？

fileId 是接入方定义的业务文件唯一 ID，你可以用数据库表中的唯一自增主键，或者用特定的唯一 ID 算法来生成。fileId 至少应该满足几个要求：

稳定性：同一个文件不能变更 fileId。

唯一性：不同文件不能共用一个 fileId。

可回查：你的业务系统后端必须能根据 fileId 找到真实文件记录信息和权限信息。

石墨文档中台和你的业务系统通过 fileId 来确认某个具体的文件。

你的业务系统负责定义文件是谁、属于哪个租户、谁能访问、当前是什么状态。

石墨文档中台负责根据文件类型提供协同编辑、在线预览、导入导出等能力。

三、如何确定文件的使用场景？

文件模型里最容易混淆的，是“协同编辑文件” 和 “预览文件”。它们虽然都可能通过 fileId 进入石墨，但生命周期和返回结构不同。

1. 预览文件

如果你只是希望能通过石墨文档中台来实现对本地文件的预览，并不需要对这个文件进行编辑，那么这个文件就是 预览文件。

这类文件的核心是文件源地址可下载、格式可识别、权限允许预览。

你的业务系统保留源文件，例如 .docx、.xlsx、.pptx、.pdf。

石墨文档中台负责下载源文件并生成预览页，不直接进入协同编辑。

文件元信息回调接口返回的石墨文档类型 type 字段值只能是 file。

文件元信息回调接口还需要返回 permissions、creatorId、createdAt、updatedAt、downloadUrl、ext 等字段。

2. 协同编辑文件

如果你希望能通过石墨文档中台创建一个空的可以随时编辑的文件，或者希望可以把本地的文件导入到石墨文档中台后，通过石墨文档中台来进行编辑。那么这个文件就是 协同编辑文件。

通过请求石墨文档中台的 POST /sdk/v2/api/files 接口来创建。

文件内容由石墨协同编辑器承载，适合多人实时编辑。

文件元信息回调返回石墨文档类型 type 字段值可选值是 document、documentPro、spreadsheet、presentation、table。

文件元信息回调接口还需要返回 permissions、creatorId、createdAt、updatedAt 等字段。

四、如何定义文件信息回调接口的具体实现？

文件信息回调接口（GET {endpoint_url}/files/{fileId}）是文件模型最关键的回调之一。石墨文档会向你的业务系统请求这个接口来查询文件的必要信息，包括：

这个 fileId 对应的文件是否存在？

这是协同编辑文件还是预览文件？

当前用户是否有权读取、编辑、评论、导出这个文件？

文件标题、创建者、更新时间等展示信息是什么？

如果是预览文件，源文件下载地址和扩展名是什么？

你的业务系统需要维护哪些文件信息？

石墨请求你的业务系统的 [文件信息回调接口]（GET {endpoint_url}/files/{fileId}）时，你的业务系统需要返回如下字段：

需要定义石墨文档中台需要的文件【基础字段】：

name: 标题

type: 类型

creatorId: 创建者

createdAt: 创建时间

updatedAt: 更新时间

permissions: 文件权限信息

石墨文档中台强依赖上述字段，你需要根据实际业务场景进行定义，石墨中台会通过 [文件信息回调接口]（GET {endpoint_url}/files/{fileId}）请求你的业务系统获取到这些数据。

需要定义你的业务系统的文件【内部扩展字段】:

你的业务系统可能需要定义如下的扩展字段：

tenant: 所属租户。

team: 所属团队。

project: 所属业务空间或项目。

source: 文件来源信息。它是石墨协同文档、外部源文件，还是某个任务流程产物。石墨文档中台不依赖此字段，你的业务系统根据实际需求定义和使用。

其他字段可根据你的业务实际需求灵活补充。

石墨文档中台不依赖这些字段，你的业务系统可以根据你的实际需求来定义和使用。

五、其他需要关注的要点

业务文件 ID 需要全局唯一。

预览文件如果有版本，建议把版本信息纳入文件记录或 fileId 设计，避免预览缓存和实际文件版本不一致。

不要让协同编辑文件和预览文件共用同一个 fileId，否则回调接口返回结构会互相冲突。

如果是你的业务系统支持多租户，建议保证 fileId 能稳定映射到唯一租户，避免跨租户取错文件。

石墨文档中台没有文件列表概念，文件列表等数据仍然在你的业务系统中自由维护。

石墨文档中台只把 fileId 作为和你的业务系统识别文件的 key，不维护它和租户、权限、文件类型之间的映射关系，这些关系仍然在你的业务系统自由维护。

一、文件是什么？#

二、如何设并定义文件唯一 ID（fileId） ？#

三、如何确定文件的使用场景？#

1. 预览文件#

2. 协同编辑文件#

四、如何定义文件信息回调接口的具体实现？#

你的业务系统需要维护哪些文件信息？#

需要定义石墨文档中台需要的文件【基础字段】：#

需要定义你的业务系统的文件【内部扩展字段】:#

五、其他需要关注的要点#