优化

docs/同步调用依赖与失败传播治理基线.md

@@ -11,7 +11,7 @@
 - `INFRASTRUCTURE`：审计、网关会话校验等基础设施调用；
 - `EXTERNAL`：Integration 对第三方供应商的调用。
 
-离线清单合同为 `scripts/synchronous-dependency-contract.test.mjs`。新增客户端、目标服务、原始 HTTP 实现、强连通分量或超时配置时，必须先更新本基线并完成调用方与被调用方评审，不能仅修改测试期望以放行。
+逐客户端可执行清单位于 `scripts/synchronous-dependency-baseline.mjs`，离线合同为 `scripts/synchronous-dependency-contract.test.mjs`。清单逐项冻结 44 个 Feign 与 16 个原始 HTTP 客户端的执行上下文、`READ/WRITE/READ_WRITE`、幂等类型和说明，并从同一事实源输出 REQUEST、BACKGROUND、INFRASTRUCTURE、EXTERNAL 与全图。新增客户端、目标服务、在线边、强连通分量或超时配置时，必须先更新基线并完成调用方与被调用方评审，不能仅修改测试期望以放行。
 
 ## 当前服务边
 
@@ -34,7 +34,7 @@
 | 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` 或上传处理线程 |
+| File | Integration | 1 | OCR 在上传处理请求线程执行，`REQUEST` |
 | Lastleg | Event Bridge | 1 | 跨区事件 Outbox 中继，`BACKGROUND` |
 | Lastleg | 国内 Warehouse | 1 | 合作仓报价快照，`REQUEST` |
 
@@ -45,28 +45,73 @@
 | 调用方 | 被调用方 | 实现 | 上下文与当前策略 |
 |---|---|---|---|
 | 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 专项治理 |
+| Gateway Overseas | Overseas Security | `HttpOverseasSecurityValidationClient` | `INFRASTRUCTURE`；安全投影实时校验，异常失败关闭，不进入在线业务图 |
+| Lastleg | Warehouse Overseas | 两个 `RestClient` Gateway | `REQUEST`；分别使用 3 秒连接、5 秒读取超时，配置可覆盖，不自动重试 |
+| Lastleg | File | 两个照片 `RestClient` Gateway | `REQUEST`；分别使用 3 秒连接、30 秒读取超时，配置可覆盖；校验响应 code 且失败关闭，不自动重试 |
+| Event Bridge | Firstleg / Lastleg / Overseas Security | 三个 JDK `HttpClient` | `BACKGROUND`；连接 3 秒、请求 10 秒，持久化租约和退避由 Event Bridge 专项治理；Security 投影不进入在线业务图 |
 | 启用 Common Audit 的服务 | Audit | `HttpAuditSink` | `INFRASTRUCTURE`；当前捕获异常后仅告警，可能让调用方误以为审计已成功，是高优先级失败传播缺口 |
 | Integration | 外部 OCR/船司 | 六个 JDK `HttpClient` | `EXTERNAL`；OCR 默认 10/60 秒，船司默认 10/30 秒，业务重试必须服从供应商和调度契约 |
 
-## 依赖环基线
+#### Lastleg 四个有界 RestClient
 
-按服务边计算，当前唯一非平凡强连通分量包含 8 个服务：
+四个客户端统一从 `LastlegRestClientFactory` 构建 JDK HTTP 传输，由 `LastlegRestClientProperties` 绑定独立超时。读取超时是单次请求的硬边界；客户端没有 Retry、fallback 或默认成功配置。
+
+| 客户端 | 构建与调用路径 | 写操作幂等性 | 默认超时 |
+|---|---|---|---|
+| `HttpUnloadPhotoFileGateway` | `ReceivingContainerController → ReceivingContainerService → UnloadPhotoFileGateway → /internal/file/v1/business-files/**` | `validate` GET 可重复；`upload` 每次写文件和元数据，没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
+| `HttpRelabelPhotoFileGateway` | `RelabelPdaController/Service → RelabelPhotoFileGateway → /internal/file/v1/business-files/**` | `validate` GET 可重复；`upload` 没有幂等键，禁止自动重试 | 连接 3 秒、读取 30 秒 |
+| `HttpWarehouseResourceGateway` | `InboundPdaWorkflowService`、PDA 仓内查询/盘点及 Dropship → Warehouse Resource/Pallet 内部接口 | 查询可重复；`reserve` 使用 `reservationKey`，`ensureDropship` 使用业务绑定，release/scrap 由服务端状态收敛；尽管服务端具备业务幂等，客户端仍不自动重试 | 连接 3 秒、读取 5 秒 |
+| `HttpPalletPhysicalGateway` | `PdaPalletOperationService`、`PdaInventoryMoveService` → `/internal/v1/pda-pallet-transitions/**` | 查询可重复；apply/compensate 使用稳定 `operationKey` 与请求哈希，服务端幂等；客户端仍不自动重试 | 连接 3 秒、读取 5 秒 |
+
+## 分上下文依赖图
+
+### 在线 REQUEST 图
+
+在线图只包含用户或设备请求线程中实际执行的服务边。Event Bridge、Outbox、船节点定时任务、导出 Provider 和海外 Security 校验均不计入在线深度。
+
+当前在线强连通分量为：
+
+`Auth ↔ IAM ↔ Firstleg ↔ Order ↔ File`
+
+合同冻结 22 条在线服务边；新增在线边或新增强连通分量直接失败。Finance、Lastleg 只指向该分量或叶子服务，不属于在线环；Gateway Overseas→Security 是 `INFRASTRUCTURE`，不是 REQUEST 边。
+
+### 后台 BACKGROUND 图
+
+后台图包含 Outbox/Inbox、导出 Worker 和定时任务，当前强连通分量为：
+
+`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg`
+
+File 的五个导出 Provider、Order→Firstleg 入库 Outbox、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Overseas Security 是单向后台叶子边，不形成在线业务环。
+
+### 全图
+
+全上下文合并后，非平凡强连通分量仍为 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/导出链单独计算，不得计入在线调用预算，也不得在下游处理期间同步回调原始调用方形成嵌套闭环。
+默认在线预算为最多 2 个下游服务跳数。合同对每个已知用户入口枚举全部最长简单路径；下表列出的具体路径均超过预算：
+
+| 用户入口 | 最长跳数 | 全部长路径 |
+|---|---:|---|
+| 认证 API | 5 | `Auth → IAM → Firstleg → Order → File → Integration` |
+| IAM API | 4 | `IAM → Firstleg → Order → File → Integration` |
+| 订单 API | 4 | `Order → File → IAM → Firstleg → Print`；`Order → File → IAM → Firstleg → Warehouse`；`Order → Firstleg → File → IAM → Auth`；`Order → Firstleg → File → IAM → Warehouse`；`Order → IAM → Firstleg → File → Integration` |
+| 头程 API/PDA | 4 | `Firstleg → Order → File → IAM → Auth`；`Firstleg → Order → File → IAM → Warehouse` |
+| 财务 API | 5 | `Finance → File → IAM → Firstleg → Order → Warehouse`；`Finance → Firstleg → Order → File → IAM → Auth`；`Finance → Firstleg → Order → File → IAM → Warehouse`；`Finance → IAM → Firstleg → Order → File → Integration` |
+| 文件 API | 4 | `File → IAM → Firstleg → Order → Warehouse` |
+| 海外尾程 API/PDA | 5 | `Lastleg → File → IAM → Firstleg → Order → Warehouse` |
+| 国内仓储 API | 0 | 无下游同步调用 |
+| 海外仓储 API | 0 | 无下游同步调用 |
+
+这些是静态服务边可形成的最长简单路径，不表示每个具体 Controller 都会走完整链；后续入口级调用点治理必须继续以实际 Service 调用证据缩小路径，不能用静态可能性宣称线上已经发生。
+
+### 第一个建议退出的 REQUEST 边
+
+建议优先将 `IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化从 REQUEST WRITE 改为可靠后台编排。该命令已经携带稳定 `initializationKey` 并提供补偿接口，适合使用持久化 Outbox、显式 `PENDING/FAILED` 结果和人工可诊断重试；不得在失败时返回默认成功。退出此边可把当前五服务在线强连通分量拆为更小的 Auth↔IAM 与 Order↔Firstleg 子环，同时不触碰财务、Event Bridge 传输或四期业务状态机。实施前仍需 IAM/Firstleg 业务负责人确认“客户创建成功”与“默认尺寸已就绪”的产品时点。
 
 ## 退出顺序
 

docs/头程项目目录结构与服务说明.md

@@ -10,7 +10,7 @@
 
 ## 1. 项目定位
 
-`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 22 个 Maven 模块，其中 7 个是公共/依赖模块，15 个是可独立启动、构建、制作镜像的微服务。
+`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 23 个 Maven 模块，其中 7 个是公共/依赖模块，16 个是可独立启动、构建、制作镜像的微服务。
 
 当前技术基线：
 
@@ -48,6 +48,7 @@ baiyue-firstleg/
 ├─ finance/                      # 财务账期、账单、收付款与核销
 ├─ lastleg-service/              # 海外尾程、入仓、库存与本土业务
 ├─ warehouse-overseas-service/   # 海外仓库、库位、托盘与资源锁
+├─ overseas-security-service/    # 海外IAM安全事件Inbox、投影与实时校验
 ├─ file/                         # 资质、导出与测量图片文件中心
 ├─ print/                        # 打印中心
 ├─ audit-service/                # 审计日志中心
@@ -101,6 +102,7 @@ baiyue-firstleg/
 | `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 |
 | `lastleg-service` | `lastleg-service` | 9303 | `baiyue_lastleg` | 海外尾程订单、接柜入仓、库存与海外本土业务；不含海外出库和派送 |
 | `warehouse-overseas-service` | `warehouse-overseas-service` | 9305 | 海外仓资源库 | 海外仓库、库位、托盘和资源锁 |
+| `overseas-security-service` | `overseas-security-service` | 9307 | `baiyue_overseas_security` | IAM安全事件可靠Inbox、单调投影及海外Token即时失效校验 |
 | `event-bridge-service` | `event-bridge-service` | 9312 | `baiyue_event_bridge` | 按 CN/OVERSEAS 双实例部署的跨区事件 Inbox、重试和目标服务投递 |
 | `audit-service` | `audit-service` | 9700 | `baiyue_audit` | 接收公共审计事件并持久化；平台端可按权限查询已脱敏日志，业务审计发送默认开启 |
 
@@ -281,6 +283,6 @@ HTTP 401 / `A0401`，不得再按 HTTP 200 + 空权限处理；只有使用新
 - 平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
 - Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
 - 服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
-- 公共模块变化会影响多个服务，Jenkins 会按 `service-map.yml` 覆盖的全部 15 个服务执行受影响构建。
+- 公共模块变化会影响多个服务，Jenkins 会按 `service-map.yml` 覆盖的全部 16 个服务执行受影响构建。
 - 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
 - 国内头程与海外仓共享 Git 仓库，但保持两套数据库、Nacos 命名空间和部署环境。