已有 OA 如何集成在线文档：架构边界与 PoC 验收清单

已有 OA、合同或项目系统时，引入在线文档能力的难点通常不在"能否嵌入编辑页面"，而在登录入口、身份传递、权限裁决、文件读写、版本生成和保存回写能否形成闭环。技术团队应先明确每条链路由谁负责，再用异常用例验证。本文给出一套通用参考架构和 PoC 方法，不把其中的设计项视为任何产品的默认能力。

一、先确定目标：保留 OA，还是新建协作入口

文档项目常见两条路线。

第一条是建设独立的企业协作空间。员工进入新的统一入口，在其中创建、整理和协作文档。此时项目重点是组织接入、空间规划、内容迁移、团队权限和运营推广。

第二条是保留 OA 或业务系统入口，在原来的审批、合同、项目等页面中补充在线预览、编辑或多人协作。此时文档组件只是链路的一部分，OA 仍掌握业务上下文，项目重点变成接口和责任边界。

两条路线都可能采用私有部署，也都可能涉及信创环境，但架构责任不同。已有 OA 且不准备改变员工入口的项目，通常应先按第二条路线设计，而不是先搭一套独立空间再考虑怎么与 OA 打通。

二、通用参考架构：把"嵌入编辑器"拆成七个环节

下面的角色是逻辑角色，一套系统可以承担多个角色：

用户入口：OA、门户、合同系统或其他业务系统页面。
身份提供方：企业现有统一身份认证、目录或组织系统。
业务权限服务：根据业务单据、项目成员、密级或流程状态判断访问权限。
集成服务层：负责身份映射、短期访问凭证、参数签名、回调校验和错误转换。
文档能力服务：提供预览、编辑或协作会话。具体接口和行为必须以所选产品当前文档为准。
文件与元数据存储：保存文件正文、文件标识、版本关系及业务关联信息。
日志与监控系统：记录请求链路、回写结果、错误码和关键操作事件。

一个典型的打开流程可以写成：

text 复制代码

用户进入 OA 业务页面
  -> OA 校验登录状态与业务权限
  -> OA 或集成服务生成本次访问上下文
  -> 文档能力服务校验必要参数
  -> 文档能力服务按约定获取文件或打开既有文档
  -> 用户进入预览或编辑会话

保存流程则可能是：

text 复制代码

用户提交编辑结果
  -> 文档能力服务产生保存事件或结果
  -> 集成服务校验事件来源与幂等键
  -> 文件服务写入正文或新版本
  -> OA 更新业务元数据与状态
  -> 监控系统记录链路结果

这只是参考流程，不代表所有产品都采用相同的文件拉取、推送、回调或版本机制。选型时必须把每个箭头对应到实际接口、调用方向和失败处理。

三、入口边界：用户到底从哪里进

入口问题看似简单，却会影响后面的身份、权限和文件归属。

项目组至少要写清四件事：

主入口是 OA、统一门户，还是独立协作平台；
同一文件能否从多个入口打开；
移动端、PC 端和特定终端是否使用同一认证链路；
OA 不可用时，文档是否允许被其他入口直接访问。

如果业务要求"文件只能随单据访问"，就不应让独立入口绕过 OA 的业务权限。反过来，如果企业要建立公共知识空间，也不宜把每次访问都绑在某一张流程单据上。

PoC 应检查浏览器地址、分享链接、历史记录和收藏夹等路径。用户复制一个编辑地址后再次打开，系统是重新鉴权、拒绝访问，还是继续使用旧会话？这个结果不能靠猜。

四、身份边界：登录成功不等于身份正确

单点登录只解决"用户是谁"的一部分问题。文档服务还需要知道企业用户与自身账号、租户、组织或会话之间如何映射。

建议为每次访问至少确认以下信息：

json 复制代码

{
  "subject": "企业内唯一用户标识",
  "tenant": "组织或租户标识",
  "document": "业务文件标识",
  "action": "view 或 edit",
  "issued_at": "签发时间",
  "expires_at": "过期时间",
  "request_id": "链路追踪标识"
}

字段名称只是示意，不是某款产品的接口定义。实际项目要根据接口文档确认哪些信息由 OA 提供、哪些由集成层转换、哪些由文档服务生成。

身份 PoC 不要只测正常登录，还要覆盖：

新增用户尚未完成组织同步；
用户调岗，部门或角色已经变化；
用户离职或账号被禁用；
同名用户、账号合并或历史账号迁移；
访问凭证过期、重复使用或时间偏差；
一个用户同时在多个终端保持会话。

验收时应能回答：账号状态变化后，旧会话最长还能使用多久？如果身份映射失败，系统会拒绝访问，还是创建一个无法治理的临时身份？

五、权限边界：只保留一个最终裁决方

OA 集成中最危险的做法，是 OA 认为用户只读，而文档服务又给了编辑权限；或者 OA 已撤销权限，旧编辑会话仍可保存。

先建立一张权限动作表：

动作	建议裁决来源	是否需要实时或关键节点复核
查看	OA 业务权限或统一权限服务	打开时复核
编辑	OA 业务权限或统一权限服务	打开与保存时复核
下载	按项目规则确定	执行前复核
分享	按项目规则确定	创建分享时复核
改名、移动、删除	文件权威系统	执行前复核
恢复历史版本	文件权威系统或指定管理员	执行前复核

"建议裁决来源"仍需按实际架构调整。关键不是表格中的默认答案，而是项目只能有一套可解释的最终规则。

权限 PoC 至少要制造三类冲突：

OA 允许查看，文档侧残留编辑权限；
用户打开文件后，OA 立即撤销其权限；
用户调岗后仍持有旧链接或旧会话。

记录每个冲突发生后，打开、编辑、保存、下载和分享分别得到什么结果。若系统使用权限缓存，还要记录缓存位置、最长时间和主动失效方式。

六、文件边界：先找出哪一份是权威文件

"文件存在哪里"不能只回答一个磁盘路径。至少要区分：

OA 或业务系统中的文件正文；
文档服务编辑期间使用的工作副本或中间态；
保存后生成的结果文件；
文件元数据，如名称、业务单号、所有者和状态；
历史版本、日志及备份。

项目组应为每个对象标记权威来源。例如，合同正文由合同系统管理，文档服务只负责编辑会话；保存完成后，结果必须回到合同系统，合同系统生成新的业务版本。也可能采用另一种设计，由文档平台保存正文，OA 只保留文件标识。两种都能成立，但不能在同一条链路里含糊切换。

建议建立文件标识映射：

标识	生成方	是否可变	用途
business_id	OA 或业务系统	通常不变	关联业务单据
file_id	文件权威系统	按方案确定	标识逻辑文件
version_id	版本权威系统	每次版本变化	标识具体版本
session_id	文档能力服务或集成层	会话级	跟踪一次编辑
request_id	调用方或网关	请求级	日志追踪与排障

表中的命名仍是通用示例。PoC 要确认重复打开、另存为、覆盖保存、文件改名和业务单据复制时，这些标识如何变化。

七、版本边界：别把"保存成功"当成版本正确

保存按钮返回成功，只能证明某次请求被接受。它不能证明以下问题已经解决：

两名用户先后保存时，版本顺序是否稳定；
网络重试是否产生重复版本；
OA 版本号与文档侧版本号是否一一对应；
回写成功但业务状态更新失败时如何处理；
历史版本恢复后，是否生成新版本及审计记录；
定稿、归档或签署后，是否仍允许普通编辑。

版本设计最好明确三个规则：

谁生成权威版本号；
什么事件会生成新版本；
失败重试如何保持幂等。

幂等可以通过业务操作号、版本前置条件或请求唯一键实现，但具体机制取决于产品接口和企业集成层。不要在未核验接口前写死实现方式。

八、回写边界：成功、失败和"结果未知"要分开

回写链路通常比打开链路更容易出问题。一次保存可能经历文件生成、上传、元数据更新、业务状态变更和事件通知。任一步骤超时，都可能出现三种状态：

明确成功；
明确失败；
调用方超时，但接收方可能已经成功，即"结果未知"。

第三种状态最考验设计。如果调用方直接重试，可能产生重复版本；如果不重试，可能让 OA 永远看不到已保存的内容。

PoC 中建议记录一张状态表：

阶段	成功证据	失败后的处理	可否重试	幂等依据
结果文件生成
文件写入权威存储
版本元数据更新
OA 业务状态更新
事件或回调确认

回调接收方还应校验来源、签名或其他约定的可信机制，并保存可追踪的处理结果。具体安全机制和字段以实际接口文档为准。

九、异常边界：PoC 要故意把链路弄坏

正常演示很容易通过。真正能暴露问题的是异常测试。

1. 认证与授权异常

令牌过期；
用户被禁用；
权限在编辑期间被撤销；
请求中的用户与业务单据不匹配；
旧链接被再次使用。

2. 文件异常

文件不存在、被删除或已归档；
文件被其他流程锁定；
文件格式或大小超出当前方案范围；
文件元数据存在，但正文读取失败；
保存目标版本已经发生变化。

3. 网络与服务异常

OA 调用文档服务超时；
文档服务取文件超时；
保存过程中网络中断；
回调超时或重复送达；
依赖的存储、数据库或消息组件不可用。

4. 数据一致性异常

文件已写入，版本表未更新；
版本已生成，OA 状态仍显示旧版本；
同一请求重复执行；
恢复历史版本后，业务系统仍引用原版本；
日志显示成功，但用户实际打开的是旧内容。

每个异常用例都要写明预期状态、用户提示、日志位置、重试责任和人工处理入口。错误页上只有一句"系统异常，请稍后重试"，不算完成验收。

十、PoC 验收清单

以下清单可直接改成测试用例。

A. 入口与身份

用户从指定 OA 页面进入，无需重复登录。
直接复制编辑地址后，系统会按项目规则重新鉴权或拒绝访问。
用户调岗、离职和禁用后，访问状态在约定时间内更新。
会话和访问凭证过期后的行为符合设计。
身份映射失败时，不会创建无法追踪的账号或放行访问。

B. 权限

只读用户不能通过页面、接口或旧链接完成编辑。
编辑权限被撤销后，打开、编辑和保存行为都有明确结果。
下载、分享、删除、恢复版本等动作分别经过权限校验。
OA 与文档侧权限冲突时，结果符合唯一裁决规则。
管理员和运维人员的文件访问范围有明确约束。

C. 文件与版本

能明确指出权威文件、工作副本、结果文件和备份的位置。
文件标识、业务标识、版本标识之间可追踪。
多人编辑、连续保存和重复提交不会产生不可解释的版本。
历史版本查看与恢复结果符合业务要求。
定稿、归档等业务状态能正确限制后续编辑。

D. 保存与回写

保存成功后，OA 能读取正确的文件或版本。
回写失败时，用户、运维和业务系统都能识别状态。
超时后的"结果未知"有查询、对账或补偿办法。
重复回调或重复请求不会破坏版本关系。
关键链路可通过 request_id 等标识完成日志追踪。

E. 环境与运维

已在目标操作系统、芯片、数据库、中间件和网络环境完成测试。
监控能发现打开失败、保存失败、回写积压等问题。
备份与恢复测试覆盖文件、元数据及版本关系。
升级前后的接口兼容范围和回退方案明确。
产品厂商、集成商、OA 团队和基础设施团队的责任已经书面确认。

十一、如何写验收标准

"支持 OA 集成""支持在线编辑""支持多人协作"都太宽，难以验收。更合适的写法包含环境、前置条件、操作、预期结果和证据。例如：

在项目指定的测试环境中，测试用户从 OA 合同详情页打开具有编辑权限的 DOCX 文件，完成修改并保存。OA 在约定时间内显示新版本；文件内容、业务单号和版本关系一致；重复发送同一保存事件不产生额外业务版本；系统日志可通过同一链路标识查询打开、保存和回写结果。

时间、文件格式、并发量和错误处理要求应由项目组结合真实业务填写，不能从通用文章直接抄成指标。

十二、产品只在路线明确后进入候选

石墨办公面向政企，提供办公套件私有部署、文档中台私有部署、单机版等产品，以及咨询、实施、迁移、运维等专业服务。

对于保留 OA、ERP、CRM、合同或门户入口，主要补充文档能力的项目，可以将石墨办公文档中台私有部署列入候选，并根据实际产品资料核对 API / SDK、身份接入、权限映射、文件处理、版本与回写方式，再通过 PoC 验证完整链路。

如果企业的目标是新建统一员工协作空间，则应评估石墨办公套件私有部署，项目重点会转向组织、空间、内容迁移、权限治理和运维。两种产品路线也可以组合，但需要先确定哪些文件留在业务系统，哪些内容进入统一协作空间。

这里提到的入口校验、令牌设计、幂等、回调、重试、监控和异常补偿，都是 OA 集成时应评估的通用架构事项。除非当前产品文档、技术方案和 PoC 已经证明，否则不能据此推断石墨办公默认采用某种实现，或默认具备本文列出的全部机制。

结语

OA 集成项目的验收对象不是一个嵌入页面，而是一条能解释、能追踪、能恢复的业务链路。入口决定用户从哪里来，身份说明用户是谁，权限决定他能做什么，文件和版本说明结果存在哪里，回写保证 OA 获得正确状态，异常处理则决定系统出问题后能否恢复。

技术方案评审时，可以把本文的七个环节逐一画到实际系统上。凡是箭头没有责任方、数据没有权威来源、失败没有状态定义的地方，都应进入 PoC 或合同验收项。