优化

2026-08-25 11:52:25 +08:00
parent d64706e97b
commit 4fbf8bfb53
16 changed files with 1101 additions and 16 deletions
@@ -0,0 +1,105 @@
+# 同步调用依赖与失败传播治理基线
+
+## 目的与口径
+
+本基线覆盖后端服务之间的 OpenFeign、`RestClient`、`WebClient` 与 JDK `HttpClient` 调用。它用于识别同步依赖方向、在线请求深度、后台中继、超时、重试、熔断、幂等、错误映射和失败传播，不改变 Finance 或四期业务状态机。
+
+“存在双向服务边”不等于“一次在线请求会递归调用”。每条边必须继续区分：
+
+- `REQUEST`：用户或设备请求线程内，失败直接影响当前业务结果；
+- `BACKGROUND`：Outbox、Inbox、定时器或导出 Worker 中的同步传输，业务事务已与传输解耦；
+- `INFRASTRUCTURE`：审计、网关会话校验等基础设施调用；
+- `EXTERNAL`：Integration 对第三方供应商的调用。
+
+离线清单合同为 `scripts/synchronous-dependency-contract.test.mjs`。新增客户端、目标服务、原始 HTTP 实现、强连通分量或超时配置时，必须先更新本基线并完成调用方与被调用方评审，不能仅修改测试期望以放行。
+
+## 当前服务边
+
+### OpenFeign
+
+| 调用方 | 被调用方 | 客户端数 | 主要上下文 |
+|---|---|---:|---|
+| Auth | IAM | 2 | 登录授权、注册，`REQUEST` |
+| IAM | Auth | 1 | 账号开通/管理，`REQUEST` |
+| IAM | Firstleg | 1 | 客户尺寸规则，`REQUEST` |
+| IAM | Warehouse | 1 | 海外仓储费协作，`REQUEST` |
+| IAM | Event Bridge | 1 | 安全事件中继，`BACKGROUND` |
+| Order | Firstleg | 3 | 计价/统一订单查询为 `REQUEST`，入库协作为 Outbox `BACKGROUND` |
+| Order | IAM / File / Warehouse | 各 1 | 资格、图片、仓库守卫，`REQUEST` |
+| Firstleg | Order | 2 | 货物查询与分拆回写，`REQUEST` |
+| Firstleg | IAM / Finance / Integration / Event Bridge / Print | 各 1 | IAM、Integration、Print 为 `REQUEST`；Finance 与 Event Bridge 为 `BACKGROUND` 中继 |
+| Firstleg | File | 7 | 测量、装柜、凭证、报关、拖车等，`REQUEST` |
+| Firstleg | Warehouse | 4 | 主数据、供应商、库位/托盘，`REQUEST` |
+| Finance | Firstleg | 2 | 费用来源/成本快照，事件消费与平台操作混合 |
+| Finance | File / IAM / Warehouse | 各 1 | 凭证、客户、供应商校验，`REQUEST` |
+| File | IAM | 2 | 资质登记为 `REQUEST`；导出 Provider 为 `BACKGROUND` |
+| File | Order / Firstleg / Finance / Warehouse | 各 1 | 导出 Provider，`BACKGROUND` |
+| File | Integration | 1 | OCR，`BACKGROUND` 或上传处理线程 |
+| Lastleg | Event Bridge | 1 | 跨区事件 Outbox 中继，`BACKGROUND` |
+| Lastleg | 国内 Warehouse | 1 | 合作仓报价快照，`REQUEST` |
+
+合计 44 个 Feign 客户端。公共默认连接/读取超时为 3 秒/5 秒；File 的五个导出 Provider 客户端读取超时单独为 15 秒。
+
+### 原始 HTTP
+
+| 调用方 | 被调用方 | 实现 | 上下文与当前策略 |
+|---|---|---|---|
+| Gateway Overseas | Auth | `HttpPdaSessionValidationClient` | `INFRASTRUCTURE`；总超时 2 秒，异常由网关失败关闭 |
+| Lastleg | Warehouse Overseas | 两个 `RestClient` Gateway | `REQUEST`；当前未看到客户端级连接/读取超时，是高优先级缺口 |
+| Lastleg | File | 两个照片 `RestClient` Gateway | `REQUEST`；校验响应 code 且失败关闭，但当前未看到客户端级连接/读取超时 |
+| Event Bridge | Firstleg / Lastleg | 两个 JDK `HttpClient` | `BACKGROUND`；连接 3 秒、请求 10 秒，持久化租约和退避由 Event Bridge 专项治理 |
+| 启用 Common Audit 的服务 | Audit | `HttpAuditSink` | `INFRASTRUCTURE`；当前捕获异常后仅告警，可能让调用方误以为审计已成功，是高优先级失败传播缺口 |
+| Integration | 外部 OCR/船司 | 六个 JDK `HttpClient` | `EXTERNAL`；OCR 默认 10/60 秒，船司默认 10/30 秒，业务重试必须服从供应商和调度契约 |
+
+## 依赖环基线
+
+按服务边计算，当前唯一非平凡强连通分量包含 8 个服务：
+
+`Auth ↔ IAM ↔ Order ↔ Firstleg ↔ Finance ↔ File ↔ Event Bridge ↔ Lastleg`
+
+其中优先关注的直接双向边为：
+
+1. `Auth ↔ IAM`：账号写模型与授权读模型相互同步依赖；
+2. `Order ↔ Firstleg`：订单交易与履约同时存在查询、命令和 Outbox 投递；
+3. `IAM ↔ Firstleg`：客户规则与客户快照双向查询；
+4. `Firstleg ↔ Finance`：费用 Outbox 投递后 Finance 同步回读不可变快照；
+5. `Firstleg ↔ File`：业务文件请求边与 File 导出 Worker 回调边叠加；
+6. `File ↔ Finance`：凭证请求边与导出 Worker 回调边叠加。
+
+强连通分量说明静态图无法给出有限的“最大服务跳数”。在线深度治理必须以入口用例为单位：默认不新增超过 2 个下游服务跳数的在线链；后台 Outbox/导出链单独计算，不得计入在线调用预算，也不得在下游处理期间同步回调原始调用方形成嵌套闭环。
+
+## 退出顺序
+
+1. **冻结与分层。** 先用清单合同阻止未评审新边；为每个客户端补齐 `REQUEST/BACKGROUND/INFRASTRUCTURE/EXTERNAL`、读写语义、幂等键和失败映射。这个阶段不改变业务状态。
+2. **统一失败传播与时间预算。** 为 Feign 和原始 HTTP 明确连接/读取/总超时；默认禁用自动重试，只有具备幂等键且由业务明确拥有退避状态的后台操作可以重试；禁止空数据、默认成功或仅日志告警替代远端失败。
+3. **先退出伪在线环。** File 导出 Provider、Firstleg/Lastleg Event Bridge、Firstleg→Finance 费用投递继续作为后台链路，但必须从在线深度图剥离，并禁止 Worker 消费时无界同步回调。
+4. **退出 `Order ↔ Firstleg` 在线双向命令。** 保留一个方向的权威查询，将反向状态推进改为带版本、幂等和审计的 Outbox/Inbox；不复制 Order 交易状态或 Firstleg 履约状态。
+5. **退出 `Auth ↔ IAM` 在线双向写。** Auth 保持账号与 Token 唯一所有者，IAM 保持客户/RBAC 所有者；注册和账号开通使用可恢复编排，登录授权快照失败关闭，不引入第二套账号事实。
+6. **收敛 `IAM ↔ Firstleg`。** 客户维度规则和客户快照确定单一事实方向；允许短期只读查询，禁止两个服务互相修正对方数据。
+7. **在财务总控确认后退出 `Firstleg ↔ Finance` 回调。** 优先让版本化事件携带 Finance 校验所需的不可变快照或使用单向快照读取，保持 Finance 状态机和 Firstleg 费用事实边界不变。
+8. **收敛 File 相关环。** File 只拥有文件对象与导出任务；业务服务拥有导出数据和业务归属。凭证/照片校验失败关闭，导出 Worker 使用受限批次、超时和显式失败状态。
+
+## 错误、重试与熔断基线
+
+- 远端 HTTP 非 2xx、响应体 `code != "200"`、空响应和 DTO 不完整是四类不同失败，均不得变成成功或空列表。
+- 在线查询/命令默认不自动重试。若启用重试，必须同时证明方法幂等、请求具有稳定幂等键、最大尝试次数和总时间预算可控。
+- Outbox/Inbox 重试由持久化状态拥有，Feign/JDK 客户端不得再叠加隐式重试造成次数乘法。
+- 熔断打开时返回统一“依赖不可用”错误并保留 request/trace 关联信息，不配置业务成功型 fallback。
+- 404 只有在契约明确“资源不存在”时可映射为领域未找到；连接失败、超时、5xx、空响应必须映射为依赖不可用。
+- Common Audit 当前“只记录告警后返回”列为已知例外，不能据此推广静默降级；其可靠性与业务阻断口径需和审计/总控共同冻结。
+
+## 直接受影响验证
+
+| 变更范围 | 最低验证 |
+|---|---|
+| 图、客户端或超时配置 | `node --test scripts/synchronous-dependency-contract.test.mjs` |
+| 单个 Feign/HTTP 签名或错误映射 | `mvn -pl <调用方>,<被调用方> -am test-compile`，并运行双方直接相关测试 |
+| Auth/IAM | `mvn -pl auth,iam -am test` |
+| Order/Firstleg | `mvn -pl order,firstleg -am test` |
+| IAM/Firstleg | `mvn -pl iam,firstleg -am test` |
+| Firstleg/Finance | `mvn -pl firstleg,finance -am test`；业务口径先由财务总控确认 |
+| Firstleg/File 或 File/Finance | `mvn -pl firstleg,file,finance -am test`，按实际消费者缩小模块集 |
+| Lastleg 原始 HTTP | `mvn -pl lastleg-service,warehouse-overseas-service,file -am test`；不改变四期状态机 |
+| 全部治理阶段收口 | `mvn -DskipTests validate` 后执行 `mvn test` |
+
+以上均为本地离线验证；未经明确授权不启动 Java/Nacos/数据库，不执行 SQL、部署或测试环境 HTTP 验收。