From f88495778c01d6cedaf503ef3bfa688d2138c8b1 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Tue, 25 Aug 2026 10:39:45 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 四期/README.md | 2 +- 测试环境Jenkins部署指南.md | 1 + 跨区域认证与服务通信契约.md | 4 ++-- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/四期/README.md b/四期/README.md index 57bfc5c..3b6cefe 100644 --- a/四期/README.md +++ b/四期/README.md @@ -74,5 +74,5 @@ - 船节点是头程海运在途事实与四期海外接柜之间的衔接能力，业务聚合继续由 Firstleg 持有；到港/可提柜结果通过明确契约或跨区域事件提供给海外区域，不复制第二套轮询任务。 - Admin、Client 仍使用统一账号体系，并按根 `AGENTS.md` 的双区域 API、海外 Token 和跨区域事件约定接入；业务页面不自行实现第二套登录。 - 海外仓 PDA 使用独立 `apps/pda-overseas-uniapp/` 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经海外 Gateway 的显式 PDA 路由。当前工作台/通用作业页是静态原型时不得据此宣称 Lastleg 或 Warehouse Overseas 已完成设备联调。 -- 海外 PDA 的实际收货仓是 `warehouse-overseas-service` 中 `customer_id=0`、类型为 `OVERSEAS`、启用 `RECEIVING` 能力的平台共享物理仓，并由 `WAREHOUSE_PICKER` 的 Token Claim 固定；PDA 不接收仓库 ID，也不能切换柜号。待收柜在首次准备时原子认领到该仓，入仓计划、尾程订单和收货会话冻结实际仓 ID/名称；国内装柜事件的仓库仅作为来源仓快照，目的仓/FBA 仓也不得冒充实际收货仓。 +- 海外 PDA 的实际收货仓是 `warehouse-overseas-service` 中 `customer_id=0`、类型为 `OVERSEAS`、启用 `RECEIVING` 能力的平台共享物理仓，并由 `WAREHOUSE_PICKER` 的 Token Claim 固定；PDA 不接收仓库 ID，也不能切换柜号。海外 Gateway 对每个 `/api/pda/**` 请求在本地验签后向 Auth 实时核对账号 `token_version` 与当前仓绑定，换仓或清空绑定后旧 Token 立即失效，Auth 不可用时拒绝请求。待收柜在首次准备时原子认领到该仓，入仓计划、尾程订单和收货会话冻结实际仓 ID/名称；国内装柜事件的仓库仅作为来源仓快照，目的仓/FBA 仓也不得冒充实际收货仓。 - 新增实际代码模块、API、权限、OpenAPI 或数据库入口后，同步更新根 `AGENTS.md`、对应应用/服务 `AGENTS.md` 和本文件；不把排期、完成比例或临时任务状态写入快速索引。 diff --git a/测试环境Jenkins部署指南.md b/测试环境Jenkins部署指南.md index 0cecd3c..54c44ff 100644 --- a/测试环境Jenkins部署指南.md +++ b/测试环境Jenkins部署指南.md @@ -129,6 +129,7 @@ Admin 和 Client Job 无部署参数，触发后会直接构建并重建对应 - `common-*`、父 `pom.xml`、`platform-bom/`、`Jenkinsfile*` 或 `deploy/` 中非 `deploy/sql/` 的部署设施变化：`AUTO` 会选择全部 12 个服务。能够证明公共变更影响全部服务时可直接部署；无法证明范围时按第 1 节取得确认。 - `deploy/sql/` 变化：`AUTO` 只标记存在待执行的数据库迁移，不据此扩大服务范围；同一提交中的服务目录变化仍按目录选择对应服务。若提交只有 SQL 变化，则不调度服务 Job。数据库迁移必须独立审核、取得明确授权并执行，不能由普通服务部署隐式触发。 - Gateway 路由、CORS 或访问域变化：选择 `gateway`，并检查受影响业务服务。 +- 海外 PDA 换仓即时失效链变化：同时选择 `gateway-overseas`、`auth`、`iam`；Jenkins 环境文件必须提供非空 `AUTH_SESSION_VALIDATION_URL`，并复用既有 `INTERNAL_SERVICE_TOKEN`，不得把 URL、服务令牌或 raw 用户 Token 写入源码/Nacos 明文。普通海外 Admin/Client 路径不调用该同步校验。 - 跨服务 DTO/OpenAPI/内部客户端变化：同时选择生产者和消费者。 - 数据库结构变化：不能仅部署服务。先按数据库变更规则取得明确授权并完成迁移，再部署依赖该结构的服务。 - Finance 服务部署使用模块名 `finance`，Jenkins 下游 Job 必须命名为 `baiyue-firstleg-finance`；测试环境凭据 `firstleg-test-env` 必须包含非空 `FINANCE_DB_URL`、`FINANCE_DB_USERNAME`、`FINANCE_DB_PASSWORD`。 diff --git a/跨区域认证与服务通信契约.md b/跨区域认证与服务通信契约.md index 69f4388..21698a4 100644 --- a/跨区域认证与服务通信契约.md +++ b/跨区域认证与服务通信契约.md @@ -10,9 +10,9 @@ - Admin、Client 只维护一套前端和一套用户账号体系；用户登录和 Token 签发统一归国内头程 Auth，不得为海外仓再创建独立登录、账号或权限体系。 - 统一使用 RS256/JWKS 信任链，但区分 Token 用途：国内登录/刷新时由同一 Auth 同时签发国内 Token 和短时海外 Token；海外 Token 限定海外 Audience，并携带海外 API 所需身份、客户范围和权限快照。 -- 平台 `WAREHOUSE_PICKER` 必须在 IAM 成员关系中绑定一个启用的实际海外收货仓；Auth 将该绑定以可空 `overseas_warehouse_id` Claim 同步写入国内与海外 Token。该 Claim 只用于已绑定的平台仓管员，页面和 PDA 请求不得传入或覆盖仓库身份；换仓后必须撤销既有会话并重新签发 Token。 +- 平台 `WAREHOUSE_PICKER` 必须在 IAM 成员关系中绑定一个启用的实际海外收货仓；Auth 将该绑定以可空 `overseas_warehouse_id` Claim 同步写入国内与海外 Token，海外 Token 同时携带账号 `token_version`。该 Claim 只用于已绑定的平台仓管员，页面和 PDA 请求不得传入或覆盖仓库身份；修改或清空仓绑定时 IAM 必须调用 Auth 撤销该账号全部会话并递增 `token_version`，随后重新签发 Token。 - 用户只登录一次，由前端统一认证模块按目标 API 自动选择 Token，不在页面或业务模块中分叉登录逻辑。 -- JWKS 只暴露公钥验证能力，不暴露私钥；国内服务验证登录 Token 并结合 Redis 会话实现即时退出和权限变更，海外服务不访问国内 Redis，只验证海外访问 Token 的签名、Issuer、Audience、有效期、应用域、客户范围和权限 Claims。 +- JWKS 只暴露公钥验证能力，不暴露私钥；国内服务验证登录 Token 并结合 Redis 会话实现即时退出和权限变更，海外业务服务不访问国内 Redis。`gateway-overseas` 对普通 Admin/Client 海外接口只验证海外 Token 的签名、Issuer、Audience、有效期、应用域、客户范围和权限 Claims；仅 `/api/pda/**` 在本地验签后，以内部服务身份向 Auth 发送 `userId/tokenVersion/overseasWarehouseId` 做无缓存实时核对。该调用不得传递 raw Token 或用户凭据，Auth 超时、不可用、账号停用、版本或仓绑定不一致均 fail-closed。 ## 区域 API 路由