ai-contract-platform/project-docs/V2-P1-06-domestic-electronic-signature-esign-connector-2026-08-25.md

P1-06 实施与验收报告：国内电子签署连接器（e签宝 SaaS API V3）

日期：2026-08-25
状态：功能、迁移、接口、合同详情页、自动化验证与超级管理员 Chrome UAT 已完成；本地 UAT 使用无有效法律效力模拟通道，正式 e签宝企业账号、印章授权及生产回调验收属于发布门禁。

1. 阶段目标

1. 完成一家主流国内电子签约平台集成，不自建 CA、实名认证或签名基础设施。
2. 从“已审批合同”发起个人或企业签署，返回逐签署人的短时链接。
3. 通过供应商签名回调或主动查询确认完成状态，回写已签文件、签署证书及区块链存证元数据。
4. 对签署账号、链接、回调、文件下载、租户隔离和合同版本变化建立明确安全边界。
5. 为无外部账号的本地/UAT 环境提供明确标注“无有效法律效力”的模拟器，避免把模拟结果当成正式签署。

2. 产品与业务流程

合同详情页新增“电子签署与证据”区域。管理员或法务可在合同审批通过后：

1. 查看当前提供方、沙箱/生产环境及法律效力开关。
2. 添加最多 10 名个人或企业签署人并设置顺序。
3. 发起签署并仅在当前响应中取得签署链接；链接不持久化。
4. 查看脱敏账号、签署状态、回调验证结果、证据同步状态和错误码。
5. 重新输入原始手机号或邮箱并通过摘要比对后，按需重新获取对应签署人的链接。
6. 手动同步提供方状态，下载已签文件或签署证书，并查看存证哈希比对结果。

本地模拟完成只把电子签流程标记为 completed，合同仍保持 approved。只有配置为 e签宝生产环境、显式启用法律效力、提供方完成状态经验证且合同正文 SHA-256 与发起时一致，合同才进入 signed；正文变化时记录错误，绝不静默签署新正文。

3. 技术架构与安全边界

3.1 提供方适配器

• esign_saas_v3：实现 API V3 HMAC-SHA256 请求签名、文件上传和转换轮询、按文件创建签署流程、逐签署人链接、流程查询、签署文件/证书下载和蚂蚁链存证查询。
• development_mock：仅允许 local 或 test 环境，强制 legal_effect=false，用于浏览器验收和回归测试。
• disabled：不显示发起入口，保留既有合同能力。

3.2 数据最小化与完整性

• 数据库存储签署账号脱敏值与使用独立密钥生成的 HMAC 摘要，不存储手机号/邮箱明文。
• 签署 URL 只在发起或重新获取接口响应中返回，不写数据库、审计元数据或日志。
• 回调入口不依赖浏览器会话，但必须校验 App ID、时间窗口和请求体 HMAC；事件 ID 幂等去重，保存请求体 SHA-256 而非原始载荷。
• 上传及证据下载只允许 HTTPS 的 e签宝/阿里云对象存储可信域名，不跟随重定向，证据文件限制为 50 MiB。
• 已签文件落入租户/流程隔离目录；区块链 fileHash 与本地文件 SHA-256 不一致时标记 signed_artifact_hash_mismatch，不显示证据同步成功。

3.3 状态与回退

状态机覆盖 creating → signing → completed/cancelled/expired/rejected/failed。回调失败由供应商重试；运营人员也可执行主动查询与证据重拉。相同业务幂等键不会重复发起签署，重复回调不会重复改变合同状态或写入证据。

4. 数据、接口与界面

迁移：20260825_0064。

新增表：

• electronic_signature_flows
• electronic_signature_events
• electronic_signature_artifacts

新增接口：

• GET /api/v1/electronic-signature/provider-status
• GET|POST /api/v1/contracts/{contract_id}/signature-flows
• POST /api/v1/signature-flows/{flow_id}/sign-url
• POST /api/v1/signature-flows/{flow_id}/refresh
• GET /api/v1/signature-flows/{flow_id}/artifacts/{artifact_id}/download
• POST /api/v1/integrations/electronic-signature/esign/callback
• POST /api/v1/signature-flows/{flow_id}/simulate-completion（仅本地/测试模拟器）

前端对应新增六组受会话保护的边缘代理；供应商回调直接进入合同 API，不经过登录代理。

5. 正式发布门禁

1. 企业完成 e签宝生产应用、实名主体、印章与授权配置，App Secret 通过密钥管理系统注入而非写入仓库。
2. 设置官方生产端点、可公网访问的 HTTPS 回调 URL、业务返回 URL和独立的账号摘要密钥。
3. 仅在隔离预发布环境完成真实个人与企业签署、拒签、过期、重复回调、回调延迟和主动补偿查询。
4. 核验已签 PDF、签署证书、提供方流程详情及蚂蚁链存证四方一致，抽样验证 local_hash_verified=true。
5. 验证发起后修改合同正文不会把合同状态变为 signed；验证跨租户流程、证据和下载均不可见。
6. 由法务确认用户告知、授权、实名认证、电子签名适用范围、证据保留期和争议处理文案。
7. 完成密钥轮换、提供方超时、对象存储不可用、回调积压和人工补偿演练后，才启用 ELECTRONIC_SIGNATURE_LEGAL_EFFECT_ENABLED=true。

6. 明确边界

• 当前开发机没有用户企业的 e签宝生产 App ID/App Secret、印章授权或公网 HTTPS 回调，因此没有发起任何真实外部签署。
• 沙箱与本地模拟结果只证明系统集成流程，不证明可靠电子签名成立，也不能作为正式签署证据。
• 电子签署适用性、签署主体授权和证据保留策略需要企业法务结合具体合同类型确认；技术开关不能代替法律判断。
• 当前版本支持单一 e签宝适配器；法大大等第二提供方、异步回调队列和运营批量补偿可在后续阶段扩展。

7. 验收记录

• 合同后端：362 collected，358 passed，4 skipped；无失败。4 个新增专项测试覆盖租户隔离、幂等、账号脱敏、模拟证据哈希校验及重启后读取、生产状态转换、官方 HMAC 请求、文件上传/轮询、逐签署人链接以及回调防篡改/过期。
• 前端：TypeScript、41 个 Node 测试和 Next.js 生产 build 全部通过；生成路由包含六组电子签署边缘代理。
• OpenAPI：127 paths / 193 schemas，YAML 与全部 schema 引用可解析。
• 数据库：PostgreSQL 已升级到 20260825_0064 (head)。
• 服务：Contract API 8100 health=ok，Web 3000 可访问，AI API 8101 health=ok；运行配置明确显示 development_mock / sandbox / legal_effect=false。
• 超级管理员 Chrome UAT：账号 uat.legal.20260823@example.test，工作区“Playbook 隔离 UAT”，合同 contract-339de8ffc560，流程 sign-flow-07e6c2c9cbf24b7fa34c5ea3dbd9ce4c。
• UAT 状态流：已审批合同发起模拟签署，签署账号显示 138****8000，原始账号摘要匹配后可重新取得链接；完成后 completion_verified=true、evidence_status=synced、2 个证据制品、local_hash_verified=true。
• UAT 安全边界：刷新页面后签署链接消失且原始账号不可见；流程虽为 completed，合同仍为 approved，页面明确显示“无效力环境”；浏览器控制台错误为 0。

8. 官方实现依据

• e签宝 SaaS API V3 开发说明：https://open.esign.cn/doc/opendoc/apiv3-guide/tfb6gn
• 请求签名说明：https://open.esign.cn/doc/opendoc/dev-guide3/tggw2e
• 本地文件上传：https://open.esign.cn/doc/opendoc/pdf-sign3/rlh256
• 基于文件创建签署流程：https://open.esign.cn/doc/opendoc/pdf-sign3/nxhgcl3bfgqz8qlz
• 获取签署链接：https://open.esign.cn/doc/opendoc/pdf-sign3/pvfkwd/
• 回调通知与签署完成事件：https://open.esign.cn/doc/opendoc/notify3/sblzg8、https://open.esign.cn/doc/opendoc/notify3/glqgy1
• 已签文件下载与蚂蚁链存证：https://open.esign.cn/doc/opendoc/pdf-sign3/kczf8g、https://open.esign.cn/doc/opendoc/pdf-sign3/ugtag2

详细配置、上线、故障处置和回退步骤见 project-docs/electronic-signature-esign-operations-runbook-2026-08-25.md。