8.8 KiB
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: 富友主扫统一下单与订单查询
系统 SHALL 通过富友主扫统一下单创建微信二维码支付并返回 qr_code 二维码链接；系统 SHALL 通过富友订单查询按 trans_stat 将状态映射为已支付、已关闭、待支付或未知，未知状态 MUST 保持待恢复。下单与查询失败 MUST 映射为项目稳定错误，已接入外部交互日志的调用保留脱敏结果。
Scenario: 主扫下单成功返回二维码链接
- GIVEN 富友支付配置完整
- WHEN 系统发起主扫统一下单且渠道返回成功
- THEN 系统返回
qr_code作为支付链接，业务以该链接生成二维码
Scenario: 查询映射支付成功
- WHEN 富友订单查询返回
trans_stat=SUCCESS - THEN 系统将状态映射为已支付并取得渠道交易号、金额与支付时间
Scenario: 查询映射已关闭
- WHEN 富友订单查询返回
trans_stat为PAYERROR、CLOSED或REVOKED - THEN 系统将状态映射为已关闭
Scenario: 查询映射待支付
- WHEN 富友订单查询返回
trans_stat为USERPAYING或NOTPAY - THEN 系统将状态映射为待支付
Scenario: 查询状态未知保持待恢复
- WHEN 富友订单查询返回系统错误、找不到交易或无法识别的
trans_stat - THEN 系统将状态映射为未知并保持本地支付单待恢复，不得据此确认收款或关闭订单
Scenario: 下单失败返回稳定错误
- WHEN 富友主扫统一下单返回失败或请求结果未知
- THEN 系统返回项目稳定错误且已接入外部交互日志的调用记录脱敏结果
Requirement: 外部交互日志逐日物理留存
系统 SHALL 以 Asia/Shanghai 已结束的自然日为单位物理留存 tb_integration_log。删除某日在线外部交互日志前，系统 MUST 为该日生成最终归档版本，确认不存在待完成记录，并验证归档对象、清单、日期范围、记录数量和校验摘要可作为恢复凭证。每次执行 SHALL 从最早尚未完成清理的归档日连续处理至昨天；任一日期不能形成或验证最终归档时，系统 MUST 不删除该日及更晚日期的在线外部交互日志。
Scenario: 最终归档通过后清理在线外部交互日志
- GIVEN 某已结束自然日的外部交互日志均已进入终态，且该日最终归档对象和清单校验成功
- WHEN 日留存任务处理该日期
- THEN 系统分批删除该日的在线外部交互日志并将该归档日标记为已清理，归档对象保持可用
Scenario: 存在待完成外部交互日志
- GIVEN 某归档日仍存在待完成的外部交互日志
- WHEN 日留存任务尝试处理该日期
- THEN 系统不删除该日及更晚日期的在线外部交互日志，并在独立日留存日志中记录该日期未形成最终归档的原因
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（更新运营商状态）。