重置项目上下文与规范文档

openspec/specs/external-integration/spec.md

@@ -0,0 +1,95 @@
+# external-integration 当前行为
+
+## Purpose
+
+描述企业微信、支付渠道、Gateway 与运营商回调的当前失败、重试和幂等边界。
+
+## Requirements
+
+### Requirement: 企微审批状态
+
+系统 SHALL 将审批状态按 0=提交中、1=审批中、2=已通过、3=已拒绝、4=已撤销、5=通过后撤销、6=已删除、7=提交失败、8=提交结果未知返回。
+
+#### Scenario: 企微审批状态
+
+- **GIVEN** 审批实例存在
+- **WHEN** 查询审批
+- **THEN** 返回数值状态和对应中文名称
+
+### Requirement: 企微回调与补偿
+
+系统 SHALL 对企业微信回调执行验签解密，并使回调、轮询和人工同步进入同一权威状态同步语义。
+
+#### Scenario: 企微回调与补偿
+
+- **GIVEN** 同一审批变化由多个同步来源到达
+- **WHEN** 处理同步
+- **THEN** 审批终态和业务终态至多生效一次
+
+### Requirement: 外部失败边界
+
+系统 SHALL 将第三方超时、渠道错误和无效响应转换为当前稳定的系统错误；已接入外部交互日志的渠道同时保留脱敏结果。
+
+#### Scenario: 外部失败边界
+
+- **GIVEN** 外部系统超时或返回失败
+- **WHEN** 调用依赖该系统的操作
+- **THEN** 客户端收到当前稳定错误；已接入外部交互日志的调用记录脱敏渠道结果
+
+### Requirement: 外部调用重试边界
+
+系统 SHALL 仅对 Gateway 客户端超时、连接失败和 DNS 失败自动重试，默认最多重试两次且每次重新签名；HTTP 非 200、响应解析失败、Gateway 业务失败和调用方取消不重试。企业微信审批只有确认尚未调用提交接口的失败可释放后重试，提交结果未知时不得盲目重建审批。
+
+#### Scenario: 外部写请求结果未知
+
+- **GIVEN** 企业微信审批提交请求可能已到达渠道但本地未取得确定结果
+- **WHEN** Worker 处理该失败
+- **THEN** 系统保留提交结果未知状态且不自动创建第二张审批单
+
+### Requirement: 富友调用超时兼容行为
+
+系统 SHALL 保持当前富友预下单客户端未设置独立 HTTP 超时的兼容行为；调用可能持续等待底层连接结束，此行为作为当前缺陷记录而不在基线任务中修复。
+
+#### Scenario: 富友端点不返回响应
+
+- **GIVEN** 富友连接建立后持续不返回响应
+- **WHEN** 系统发起预下单
+- **THEN** 当前适配器没有自身超时门禁，调用结果保持未确定直到底层请求返回错误或响应
+
+### Requirement: 运营商回调幂等
+
+系统 SHALL 以渠道业务标识与标准化载荷生成的幂等键记录运营商实名及网络状态回调；重复回调只应用一次，字段冲突作为独立冲突事实保留且不得覆盖已确认状态。
+
+#### Scenario: 重复运营商回调
+
+- **GIVEN** 同一合法运营商回调已经成功应用
+- **WHEN** 渠道再次发送相同业务事实
+- **THEN** 系统返回渠道可接受响应且不重复推进卡状态
+
+## 可达操作索引
+
+本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
+
+### 企业微信审批
+
+`GET /api/admin/wecom/applications`（查询企业微信应用配置）；`POST /api/admin/wecom/applications`（创建或更新企业微信应用配置）；`PUT /api/admin/wecom/applications/{id}/default-creator`（保存企业微信应用默认审批发起人）；`GET /api/admin/wecom/applications/{id}/members`（分页查询企业微信应用可见成员）；`POST /api/admin/wecom/applications/{id}/members/sync`（同步企业微信应用可见成员）；`POST /api/admin/wecom/applications/{id}/templates/inspect`（读取企业微信审批模板控件）；`POST /api/admin/wecom/applications/{id}/test`（测试企业微信应用连接）；`GET /api/admin/wecom/scenes`（分页查询企业微信审批场景配置）；`PUT /api/admin/wecom/scenes/{business_type}`（保存并校验企业微信审批场景模板映射）；`GET /api/admin/wecom/scenes/{business_type}/fields`（查询企业微信审批场景可映射字段）。账号与企业微信成员的绑定属于账号身份能力。
+
+### 企业微信审批回调
+
+`GET /api/callback/wecom/approval/{application_id}`（验证企业微信审批回调地址）；`POST /api/callback/wecom/approval/{application_id}`（接收企业微信审批状态变化回调）。
+
+### 微信支付配置管理
+
+`GET /api/admin/wechat-configs`（获取支付配置列表）；`POST /api/admin/wechat-configs`（创建支付配置）；`DELETE /api/admin/wechat-configs/{id}`（删除支付配置）；`GET /api/admin/wechat-configs/{id}`（获取支付配置详情）；`PUT /api/admin/wechat-configs/{id}`（更新支付配置）；`POST /api/admin/wechat-configs/{id}/activate`（激活支付配置）；`POST /api/admin/wechat-configs/{id}/deactivate`（停用支付配置）；`GET /api/admin/wechat-configs/active`（获取当前生效的支付配置）。
+
+### 对象存储
+
+`POST /api/admin/storage/batch-download-urls`（批量获取文件下载预签名 URL）；`POST /api/admin/storage/upload-url`（获取文件上传预签名 URL）。
+
+### 运营商回调
+
+`POST /api/callback/carriers/cmcc/realname`（移动实名结果回调）；`POST /api/callback/carriers/ctcc/realname`（电信实名结果回调）；`POST /api/callback/carriers/cucc/realname`（联通实名结果回调）；`POST /api/callback/carriers/cucc/realname/remove`（联通解除实名回调）。
+
+### 运营商管理
+
+`GET /api/admin/carriers`（运营商列表）；`POST /api/admin/carriers`（创建运营商）；`DELETE /api/admin/carriers/{id}`（删除运营商）；`GET /api/admin/carriers/{id}`（获取运营商详情）；`PUT /api/admin/carriers/{id}`（更新运营商）；`PUT /api/admin/carriers/{id}/status`（更新运营商状态）。