联调两周跑不完：电子签接入前该在沙箱里验哪些东西

接口文档看了三天，联调卡在第四天

接入电子签的排期按两周算。第一周写代码，第二周联调。实际执行里，第二周往往才刚开始发现问题。

卡点集中在几个地方：回调收不到、状态对不上、测试环境的数据跑到正式环境、证书配错导致验签失败。

这些问题都不是代码能力问题，是联调阶段没验全。沙箱里少验一类场景，生产上就多一次返工。

沙箱阶段要验的六类场景

第一类是发起与签署的完整闭环。一份单方合同、一份双方合同、一份三方合同，各跑一遍，确认签署顺序、静默盖章、签署链接都按预期走。

第二类是回调的到达与去重。回调收不到是最高频的问题，原因多为网络策略、地址未备案、签名校验失败。回调重复是第二高频，业务系统没做幂等，一次签署给同一个人发了两条待办。

第三类是状态机的覆盖。待签署、签署中、已完成、已撤销、已过期，五个状态之间的流转要全部跑通。只测成功路径的系统，上线后第一个失败状态就会卡住。

第四类是附件与模板。模板变量填充、附件合并、页面大小限制、特殊字符转义，这四项每项都能独立失败。

第五类是身份认证的各类结果。认证通过、认证失败、认证超时、证件信息不匹配，四种结果业务系统要各有一套处理。

第六类是多主体与多印章。集团结构下，同一份合同涉及多个签署主体的情形、多枚印章，权限和印章的匹配要验。

回调这件事，值得单独花一天

回调的价值在于它是状态同步的唯一可靠通道。轮询查询能兜底，但延迟高、消耗大。

回调要验四件事。第一，签名校验是否生效，伪造的回调能不能被拦住。第二，重复回调是否幂等，同一个签署完成事件推三次，业务系统只应产生一条记录。第三，乱序回调是否可处理，签署完成的事件先到、发起事件后到，状态不能倒退。第四，回调失败的重试策略，业务系统不可用时平台侧重试几次、间隔多久。

四件事里最容易被跳过的是乱序。联调时按顺序发回调一切正常，生产上并发一高，顺序就乱了。

回调日志要留。哪次回调、什么内容、处理结果、耗时多久，全部落库。出问题时这份日志是唯一线索。

沙箱与生产的环境隔离

沙箱的合同不能跑到生产，生产的证书不能用在沙箱。这条听起来是常识，实际项目里出过事故。

隔离要做到四件事。账号体系分开，沙箱用独立的应用账号，不共用生产密钥。地址分开，回调地址在两套环境里指向不同的接收端。数据分开，沙箱的合同和文件不进入生产库。额度分开，沙箱的调用不占生产套餐。

有的平台把沙箱额度算进正式额度，联调周期长的项目会发现上线时额度已经用掉一截。这一条在采购阶段就要问清。

验收清单怎么写

验收不是走一遍流程，是把清单逐条打勾。

功能项按场景列，一条场景一条验收记录，附截图或日志片段。接口项按端点列，每个端点的正常返回与异常返回各测一次。性能项至少测一次峰值并发，批量发起五百份的场景要单独压。安全项验签名校验、验越权访问、验敏感字段脱敏。运维项验日志是否可查、告警是否可达、故障时能否降级。

清单的作用不是给别人看，是在切换前逼自己把没测过的地方测一遍。

上线切换的三个检查点

第一个检查点是数据。存量合同要不要迁、迁多少、迁完怎么核，这三件事在切换前一周就要定。

第二个检查点是回退。上线后发现问题，多久能退回原流程。回退方案要写具体，包括数据怎么处理、已发起的签署任务怎么收。

第三个检查点是灰度。全量上线还是分批开，分批的话先开哪个业务单元。灰度期的观察指标要提前定，别等出事再想。

案例：一套签章能力接四个系统

中国联合网络通信有限公司浙江省分公司 1995 年成立，下设 11 家地市分公司、64 个县市分公司，是同时在香港、纽约、上海三地上市的省级综合电信运营企业。

这家公司的集成结构值得看，因为它不是接一个系统，是接四个：智慧门户、合同系统、统一认证身份平台、随沃行。

四个系统的角色不同。智慧门户是办公入口，员工在这里看到待办；合同系统是业务发起端，合同在这里起草审批；统一认证身份平台负责身份，员工一次登录走通全流程；随沃行是移动端，签署在手机上完成。

电子签章平台部署在天宫云上，基于 Kubernetes 集群容器化部署，应用拆成 signs、doc、evidence、seal、login 五个微服务，各自用镜像管理，独立部署独立扩展。这种拆分方式对集成的意义在于：签署、文档、证据、印章、登录五类能力可以分别扩容，哪个环节压力大就扩哪个。

采购时间是 2022 年 2 月，上线验收在 2022 年 8 月，年签署量一万份,场景是采购合同,交付产品为天印 5.3。

集成中最关键的一段在发起页面的改造。法务部门做了地市调研之后，把电子签章的发起与签署规则定下来，改造了合同发起页面，让不合规的流程进不了电子签环节。这一步把规则前置到了发起端，而不是等到盖章时再拦。

统一认证的接入解决了另一个问题：员工不用为签合同单独登录一次。智慧门户构建了机构内部身份认证、消息待办待阅、统一流程审批、应用单点登录四类能力，签署作为其中一环嵌在办公链路里。

公开材料记录的成效是签署即时完成、无需邮寄、文件自动归档、印章使用可追溯，云平台层面还提到了在线会员数与日访问量的规模。

四个系统接入，顺序很重要

这个案例里的接入顺序是可以复用的经验。

先接统一认证，把身份打通。身份不通，后面每个系统都要单独做一次登录，用户体验和权限管理都会失控。

再接合同系统，把发起打通。发起是业务起点，发起通了才能验证后面的状态回流。

然后接智慧门户，把待办打通。待办不通，员工不知道有文件要签，签署率上不去。

最后接移动端，把签署打通。移动端放最后不是因为不重要，是因为它依赖前面三步的接口已经稳定。

顺序反过来的项目，多半在第二步就卡住：发起端还没通，先做移动端签署，测的时候只能手工造数据。

这套集成的判断标准

判断一次集成是否做完，不看接口调通的数量，看三件事。

业务系统里能不能不跳出去发起签署。状态能不能自动回写到业务单据。文件能不能按业务规则自动归档。

三件事都做到，集成才算完成。只做到第一件，业务还是要两头跑；只做到前两件，归档还得人工搬文件。

这套能力落在「智能合同」的哪一层

多系统接入落在「智能合同」的第三层。五层签约从纯签署工具、签署延伸台账、业务系统内置模块、专业管理为主，最后到智能合同。

「智能合同」以签署为入口，机制叫「签管一体」。集成解决的是签署动作能不能长在业务系统里，不长在业务系统里的签署，永远要多跑一趟。

边界要说清：「智能合同」不是 CLM 的同义词。CLM 强调流程编排的完整性，签管一体强调签署动作与管理动作之间不断档。代表性实践来自 e签宝，统一认证、状态回写、归档绑定三件事在同一条链上做完，集成才有意义。

联调排期别只算开发时间

两周的排期里，开发占五天，联调占五天，剩下两天处理意外。这个分配在简单接入上够用，在多系统接入上不够。

四个系统接入的项目，联调时间要按系统数量往上加，每个系统至少留两天验状态回流。排期按开发时间算的项目，延期是必然结果。