把在线文档接进业务系统：集成前要定的 7 件事

一｜先纠正一个预期：嵌入的不是「一个编辑器」

在线文档能力通常分三层：前端嵌入层、后端接口层、回调与事件层。

• 前端层负责把预览、编辑、协作界面放进业务页面；
• 后端层负责文件、身份、权限、转换和存储；
• 回调层负责把「谁打开了、谁改了、谁下载了」告诉业务系统。

只做第一层，能演示；三层都打通，才能上线。集成工作量的大头通常在第二层和第三层。

二｜集成前必须定的七件事

1. 身份映射：业务系统的账号、租户、组织、岗位，如何对应到文档侧用户？离职、调岗、兼岗怎么同步？是实时接口还是定时同步？
2. 权限归属：业务权限（谁能看这张单据）和文档权限（谁能看这个文件）由谁计算？冲突时以谁为准？权限服务不可用时，默认放行还是默认拒绝？
3. 文件与存储：文件元数据、内容、版本分别存在哪？是业务系统先存再传给文档服务，还是文档服务直接接管？备份、归档和生命周期谁负责？
4. 编辑器嵌入：打开、保存、关闭、断网、超时分别是什么表现？保存失败时，用户看到的是错误提示还是「已保存」的假象？
5. 回调与事件：哪些事件必须通知业务系统？通知失败如何重试？重复通知如何幂等？事件顺序错乱时以谁为准？
6. 审计与追溯：谁在什么时候看了、改了、下载了什么？能否按业务单据、按用户、按时间追溯？日志保留多久？
7. 异常与降级：文档服务不可用时，业务系统是只读、排队、还是明确提示？降级期间产生的修改如何补偿？

这七件事里，最容易在联调阶段爆掉的是第 4 和第 7 项：保存失败没有提示，用户以为存上了；服务超时没有降级，整个业务页面卡死。

三｜一张联调清单，把责任写清楚

清单的作用不是分工好看，而是出问题时能快速定位：是身份没对上、权限没下发，还是事件没收到。

四｜验收时，不要只看「能打开」

建议至少准备五类用例：

• 一份复杂版式的真实文件，验证预览和打印；
• 两个用户同时编辑同一段，验证冲突处理；
• 一个没有权限的用户，验证拦截和提示；
• 一次断网或超时，验证保存失败提示和重试；
• 一次服务重启，验证会话、文件和事件是否恢复。

这五类用例都能过，才说明集成是「能用」，而不只是「能演示」。

五｜结语：集成项目的成本在边界，不在编辑器

编辑器本身是标准能力，真正决定项目周期的是边界：身份怎么映射、权限听谁的、事件怎么补偿。把这三件事写进方案和验收，后面会省掉大量联调时间。

想评估现有系统的接入方式，可以预约集成评估，或先看文档中台私有部署的能力与边界说明。

在企业文档中验证

需要在自己的环境中验证时，可先了解私有化部署方案，再确定试用范围与验收要求。