业务系统接入石墨办公文档中台私有部署（Shimo Office SDK，以下简称文档中台），需要同时对接文件、用户、权限和文档事件。预览页面能够打开，是最初的连接结果；当编辑内容能按业务规则保存、提交并进入后续流程，才形成可用的协同闭环。
官方产品说明提供 JSSDK、JSAPI、服务端 API 和事件回调等接入方式，覆盖预览、编辑、格式转换与多人协作。文档中台不替代已有业务入口，接入方仍需设计身份、权限、事件通知和异常处理；具体接口与格式范围以当前开发文档为准。
从一条附件流程开始
建议先选择一条边界清晰的流程，例如合同经办人在原系统中打开附件，法务参与审阅，经办人提交指定版本，审批完成后按规则归档。将每个动作写出触发条件、参与角色和完成依据，再判断哪些动作由业务系统承担，哪些使用文档能力。
合同列表、审批状态、签署与档案规则通常属于业务系统。文档中台提供范围内的文档操作，不会因为嵌入编辑页面就自动完成审批、消息分发或归档。需要完整员工协作空间时，应先参考石墨办公套件私有部署（以下简称办公套件）与文档中台的产品分工。
先统一四个基础对象
| 对象 | 需要确定的内容 | 建议检查点 |
|---|---|---|
| 文件 | 业务附件与文档标识如何关联 | 打开的是正确文件，更新不会误写其他附件 |
| 用户 | 登录身份如何映射为协作身份 | 人员展示、操作归属与账号停用一致 |
| 权限 | 业务角色如何映射为文档操作 | 不同流程节点只允许约定操作 |
| 事件 | 需要接收什么事件、交给谁处理 | 能关联业务记录，重复或失败有处理规则 |
接口鉴权、请求参数与事件结构应逐项按当前开发文档实现。不要从演示代码推导生产授权，也不要将前端隐藏按钮作为服务端权限控制的替代。
把“保存”和“业务提交”分别定义
编辑过程中内容保存与合同提交审批，是两个不同含义的动作。项目应明确提交时引用哪个文件状态、提交后是否继续允许修改，以及后续审批查看的是当前内容还是指定版本。
建议用真实脱敏样例执行修改、保存、关闭、重新打开和业务提交，再由另一角色核对结果。涉及格式转换或导出时，检查输出内容和业务要求；复杂排版、公式或特殊格式应单独验证，不能因常规样例成功而承诺全部文件无差异。
事件接入要考虑重复、延迟和失败
业务系统接收文档事件后，可能需要更新状态、通知人员或记录审计。应根据接口协议设计校验、去重与失败处理，避免重复通知或重复推进流程。事件到达与业务处理完成应分别记录，便于定位问题。
这些是接入方需要确认的工程要求，并非对平台已经替业务系统实现全部重试和去重的描述。若通知涉及敏感信息，还应控制通知内容与接收范围，避免把正文或链接发送给不再有权访问的人员。
上线前同时验证正常与异常路径
正常路径包括打开、编辑、协作、提交与归档；异常路径包括无权限访问、会话过期、请求失败和业务节点变化。对于多人编辑，记录网络、文件规模和参与方式，并核对最终内容，实际表现以目标环境验证结果为准。
私有部署还应明确文档、临时处理数据、日志与备份的存放和维护责任。在线操作并不意味着所有数据天然不会落到终端或其他系统，数据流转应按实际接口与部署方案检查。
准备现有系统架构、身份方式、文件样例和一条完整流程后，可预约 Shimo Office SDK 演示，讨论最小接入闭环与验收范围。