一、基础名词释义#
| 角色 / 概念 | 说明 |
|---|
| 用户 | 使用你的应用的用户，比如用户需要通过你的 OA 系统编辑或者预览 Excel 表格。 |
| 你的应用后端 | 你的应用后端服务，可以是 Java、Go、PHP、Python 实现，主要用提供你的平台前端业务需要的后端接口，同时也负责和石墨文档中台进行数据互通。 |
| 你的应用前端 | 你的应用前端代码，可以是 Web 或者 HTML5。 |
| 你的应用回调 URL 地址 | 石墨文档中台需要通过这个 URL 去请求你实现的回调接口，比如 https://your-endpoint-url.com |
| 石墨文档中台 | 石墨文档中台服务，提供了文件的预览和编辑等核心能力。 |
| 石墨文档中台域名 | 部署在你的机房的私有化版本石墨中台的访问域名，比如：https://weboffice-shimo-local.com |
1.1 整体架构#
二、用户（User）#
用户是你业务系统的实际用户，也是最终使用文档能力的人，比如打开文档、编辑文档、预览文件、评论或协作的人。从系统关系上看，用户不是直接“对接石墨”，而是始终在你的业务系统产品里发起动作。用户看到的入口、页面、按钮、权限提示，首先都属于你的业务系统。三、文件（File）#
文件首先是你应用的一个内容实体，在你的业务系统中定义，每个文件拥有的唯一的 fileId（文件 ID） 。它是一个标注类型的的文档对象，可能是表格（Excel）、文稿（Word）、幻灯片（PPT）、应用表格（多维表格）等。四、应用（App）#
应用是你向内部或外部用户提供服务的载体，也是你调用石墨文档中台所提供的开放能力的载体。应用是指的通过石墨文档中台下发的 AppID/AppSecret 来唯一区分，一个应用的数据可能会在你的多个内部业务系统之间共享。比如说你的在你的知识库平台中创建了一个文档，这个文档同时可以在你的 IM 中预览。这个例子中知识库和 IM 是你的两个内部业务系统，但是他们都同属于一个应用（App）。不同应用在石墨文档中台中的数据是逻辑隔离的，它们的数据是无法互相联通的。“你的应用”包含“你的应用前端“以及”你的应用后端”两部 分实现。你的应用前端：
通常由 HTML、JavaScript 及其上层框架构成，负责承载业务交互入口，并在获得后端下发的接入参数后，通过 JSSDK 或 iframe 将石墨编辑器、预览页集成到现有页面中。
你的应用后端：
通常基于 Java、Go、PHP、Python 等服务端技术栈实现，负责签名凭证生成、业务身份透传、文件元信息与权限模型维护，以及文档中台回调接口和服务端 API 的对接。
4.1 你的应用前端#
你的应用前端是用户真正接触到的界面层，比如 Web 页面、管理台、知识库页面、云盘页面或业务系统里的文档详情页。使用石墨 JS SDK 或 iframe 把文档能力嵌入页面
4.2 你的应用后端#
你的应用后端是整个对接方案里的控制中枢，也是最关键的一层。用户数据管理：保存和维护用户基本信息、组织架构信息。
文件信息管理：保存和维护文件权限信息、文件基本元信息（比如文件名、文件创建用户 ID、文件创建时间等）。
实现回调接口：实现文档中台所需的回调接口，在回调时告诉文档中台“当前用户是谁、当前文件是什么、当前权限是什么”
调用石墨文档中台的服务端 API：从石墨文档中台获取必要的文档编辑器相关信息（比如获取单元格内容、获取文件的纯文本内容）、将文件导出为其他格式等。
四、回调（Callback）#
回调接口是你的应用后端需要实现、由石墨主动来调的一组 HTTP 接口。石墨文档中台采用无状态架构——它不存你的用户表、文件表、权限表；用户每次打开、编辑、预览、搜索、@ 时，石墨实时向你的应用回调要这些信息。事件类回调则反过来：当编辑器内发生评论、@ 人、内容更新时，石墨主动推送给你的应用。配置回调地址的路径如下：
运维平台 -> 文档中台 -> 应用管理 -> 新增/编辑应用
访问地址：ip/mdp/editor-ops/apps
五、石墨文档中台（Shimo WebOffice）#
文档中台是石墨提供的文档能力平台，本质上是一个文档服务层。提供文档编辑器前端 SDK 或 iframe 页面
六、说明#
6.1. 石墨文档中台和你的应用间的边界#
宏观上看，石墨文档中台并不是接管你的应用数据，而是作为一个“文档渲染与协同能力中心”存在。用户仍然在你的应用里操作，你的应用前后端仍然掌握用户、文件、权限和业务数据，石墨文档中台只在需要时被调用，并通过回调接口向你的应用后端获取必要的数据。边界 1：你的应用实现具体业务#
文档中台虽然负责渲染文档，但它并不替你的应用决定：边界 2：石墨文档中台实现文档能力#
