diff --git a/四期/README.md b/四期/README.md index e6b128a..2a8a4c2 100644 --- a/四期/README.md +++ b/四期/README.md @@ -22,7 +22,7 @@ | 海外仓 PDA 柜号签收与入仓 | 独立应用 `../../apps/pda-overseas-uniapp/`;当前真实前端只开放拆柜收货,完成柜号认领、三类照片、FBA 按 SKU 箱数/OVERSEAS 逐箱实收与全柜完成 | 前端 `src/api/inbound.js`、`receiving-adapter.js`、`pages/operation/operation.vue`;Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/controller/ReceivingContainerController.java`、`ReceivingContainerService.java`,经 `gateway-overseas/` | | 海外仓 PDA 库内、托盘、换标与查询 | Lastleg 已提供 PDA 专用盘点、同仓整托移库、托盘组拆换绑、换标与库存/库位/托盘查询后端;海外 PDA 工作台入口仍禁用,前端接入前不得宣称全链路完成 | Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`;契约 `src/main/resources/openapi/overseas-pda-operations-v1.yaml` | | 海外业务 | 本土散板、采购订单、本土卡车;Admin 入口 `../../apps/admin-web/src/modules/overseas-business/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`;Backend `../../baiyue-firstleg/lastleg-service/` 的 `procurement/`、`trucking/` 及后续本土散板子域 | -| 头程仓库主数据 | 在现有仓库类型中增加“海外仓合作仓”;实际海外仓资源独立维护 | Admin `../../apps/admin-web/src/modules/warehouses/`;国内公共主数据 `../../baiyue-firstleg/warehouse/`;海外仓资源 `../../baiyue-firstleg/warehouse-overseas-service/` | +| 仓库主数据与海外资源 | 仓库 ID、类型、状态、地址、能力统一由国内仓库主数据维护;海外服务只维护库位、托盘和资源锁 | Admin `../../apps/admin-web/src/modules/warehouses/`;国内权威 `../../baiyue-firstleg/warehouse/`;海外资源 `../../baiyue-firstleg/warehouse-overseas-service/` | | 通用资料 | 海外仓报价、汇率管理、车辆列表;Admin 入口 `../../apps/admin-web/src/modules/overseas-master-data/` | `../悦/货代SAAS平台后台/prototype-src/modules/10-general.html` | | 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点,保存最新节点、异常和查询历史,贯通目的港提柜至还柜事实 | 标准语义见[船节点标准化契约](船节点标准化契约.md);Admin `../../apps/admin-web/src/modules/port-schedules/`、`ocean-bookings/` 及货柜详情;Backend `../../baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/portschedule/`、`../../baiyue-firstleg/integration-service/` | @@ -75,9 +75,10 @@ ## 系统边界与索引维护 - 海外仓合作仓是现有头程仓库主数据的类型扩展,需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者;不得因此把海外库存业务写入国内 Warehouse Service。 -- 海外库存、库内作业和海外本土业务已有明确服务入口:`gateway-overseas/` 是海外 API 网关,`lastleg-service/` 拥有尾程订单、入仓计划、换标、库存业务、采购和本土卡车,`warehouse-overseas-service/` 拥有海外仓库、库位、托盘及资源锁。不得把这些能力塞入国内 `firstleg/` 或 `warehouse/`。 +- 海外库存、库内作业和海外本土业务已有明确服务入口:`gateway-overseas/` 是海外 API 网关,`lastleg-service/` 拥有尾程订单、入仓计划、换标、库存业务、采购和本土卡车;国内 `warehouse-service` 是仓库主数据唯一权威,`warehouse-overseas-service/` 只拥有库位、托盘及资源锁并引用国内 `warehouseId`。不得把海外库存业务塞入国内 `firstleg/` 或 `warehouse/`。 +- 国内装柜完成事件只在海外生成 `PENDING_ASSIGNMENT` 尾程订单、冻结快照和 `FIRST_LEG` 在途库存,不自动生成入仓计划。平台确认后必须人工调用 `POST /api/platform/v1/last-leg/inbound-plans/convert`;转换成功才创建计划、将尾程订单推进为 `INBOUND_PLANNED`,并把库存余额的来源入仓码展示快照替换为 `planNo`。 - 船节点是头程海运在途事实与四期海外接柜之间的衔接能力,业务聚合继续由 Firstleg 持有;到港/可提柜结果通过明确契约或跨区域事件提供给海外区域,不复制第二套轮询任务。 - Admin、Client 仍使用统一账号体系,并按根 `AGENTS.md` 的双区域 API、海外 Token 和跨区域事件约定接入;业务页面不自行实现第二套登录。 - 海外仓 PDA 使用独立 `apps/pda-overseas-uniapp/` 工程和发布身份,但账号仍由国内 Auth 唯一签发;真实作业请求必须经海外 Gateway 的显式 PDA 路由。当前拆柜收货已接真实 API;库内、托盘、换标和查询仍按工作台禁用状态管理,即使 Lastleg Controller 已存在也不得据此宣称设备端联调完成。 -- 海外 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 仓也不得冒充实际收货仓。 +- 海外 PDA 的实际收货仓是国内 `warehouse-service` 中 `tenant_id=0`、类型为 `OVERSEAS`、状态 `ACTIVE` 且启用 `RECEIVING` 能力的平台共享物理仓,并由 `WAREHOUSE_PICKER` 的 Token Claim 固定;海外数据库只保存相同 `warehouseId` 引用。PDA 不接收仓库 ID,也不能切换柜号。海外 Gateway 对每个 `/api/pda/**` 请求在本地验签后向 Auth 实时核对账号 `token_version` 与当前仓绑定,换仓或清空绑定后旧 Token 立即失效,Auth 不可用时拒绝请求。待收柜在首次准备时原子认领到该仓,入仓计划、尾程订单和收货会话冻结实际仓 ID/名称;国内装柜事件的仓库仅作为来源仓快照,目的仓/FBA 仓也不得冒充实际收货仓。 - 新增实际代码模块、API、权限、OpenAPI 或数据库入口后,同步更新根 `AGENTS.md`、对应应用/服务 `AGENTS.md` 和本文件;不把排期、完成比例或临时任务状态写入快速索引。 diff --git a/四期/三期装柜完成后至四期人工验收手册.md b/四期/三期装柜完成后至四期人工验收手册.md index eb8f07f..5405ff7 100644 --- a/四期/三期装柜完成后至四期人工验收手册.md +++ b/四期/三期装柜完成后至四期人工验收手册.md @@ -26,7 +26,7 @@ 1. 国内出仓确认与撤销边界; 2. 出仓后自动创建船节点查询任务; 3. 十个标准船节点、预计/实际时间、异常和停止条件; -4. 国内装柜完成事件跨区生成尾程订单和入仓计划; +4. 国内装柜完成事件跨区生成待分配尾程订单和冻结快照,平台人工转换后才生成入仓计划; 5. `PICKUP_READY` 对海外 PDA 待收柜的门禁; 6. 海外 PDA 柜号签收、三类照片、FBA 按箱数收货、OVERSEAS 逐箱收货和整柜完成; 7. 海外库存余额、位置、流水、托盘和换标结果查询; diff --git a/跨区域认证与服务通信契约.md b/跨区域认证与服务通信契约.md index 8f4d90c..52a9a8b 100644 --- a/跨区域认证与服务通信契约.md +++ b/跨区域认证与服务通信契约.md @@ -29,6 +29,12 @@ - MQ 使用独立的服务身份、TLS 和 ACL;服务间事件鉴权与用户 JWT 鉴权分开。只有明确的同步 HTTP 内部接口才使用内部服务令牌。 - 修改事件时联查 `common-event-contract/`、`event-bridge-service/`、生产服务、消费服务、幂等记录、重试/死信和契约测试。 +### 国内仓库目录同步读取 + +- 国内 `warehouse-service` 是 Warehouse ID、类型、状态、地址和能力的唯一权威。海外数据库不得复制仓库、地址或服务能力主表。 +- `warehouse-overseas-service` 只保存库位、托盘、资源锁及其国内 `warehouseId` 引用;资源写入和 Lastleg PDA 仓绑定校验通过受内部服务令牌保护的国内只读目录完成。 +- 只允许平台共享、`OVERSEAS`、`ACTIVE` 且启用 `RECEIVING` 的仓作为海外实际收货仓。低频正结果可缓存 30 分钟,空目录、不存在和停用结果不得长缓存。 + ### IAM 安全事件海外投影冻结 - `IamUserStatusChanged`、`IamTenantStatusChanged`、`IamPermissionVersionChanged` V1 固定由 Lastleg 独立安全入口 `/internal/lastleg/security/v1/events` 消费;不得投递到 Lastleg 的 LoadingCompletedConsumer。