diff --git a/AGENTS.md b/AGENTS.md index cbee3f977..77c072cba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ -# 国内头程后端项目指引 +# 头程与海外仓后端项目指引 ## 适用范围与定位 -- 本文件适用于 `baiyue-firstleg/` Maven 多模块仓库；进入具体服务后继续读取该服务的 `AGENTS.md`。 +- 本文件适用于 `baiyue-firstleg/` Maven 多模块仓库，包含国内头程与海外区域服务；进入具体服务后继续读取该服务的 `AGENTS.md`。 - 本层只负责：服务边界、跨服务契约、数据库部署总入口、阶段路由和通用验证。Controller、Service、DTO、SQL 细节以模块级指引为准。 - 普通任务先读本文件和目标模块指引；聚合构建/架构问题再读 `README.md`、`pom.xml`、`docs/头程项目目录结构与服务说明.md`。 @@ -10,7 +10,7 @@ - 当前产品只有“平台—客户”两级。`tenant_id=0` 是平台技术作用域；`tenant_id>0` 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。 - 公共仓库、往来单位、快递、托盘、库位统一归属 `tenant_id=0`；订单、文件、费用等客户数据按客户 `tenant_id>0` 隔离。不得跨库 Join 或信任客户端客户 ID。 -- 订单交易状态归 `order`，履约/入库状态归 `firstleg`，财务账期、账单、收款、成本与核销归 `finance`，仓储资源归 `warehouse`，文件对象归 `file`，OCR 适配归 `integration-service`；通过内部客户端、DTO 和服务令牌协作。 +- 国内订单交易状态归 `order`，头程履约/入库状态归 `firstleg`，财务账期、账单、收款、成本与核销归 `finance`，国内仓储资源归 `warehouse`；海外尾程订单、入仓计划、库存业务与海外本土业务归 `lastleg-service`，海外仓库/库位/托盘资源归 `warehouse-overseas-service`，海外公网入口归 `gateway-overseas`。文件对象归 `file`，第三方适配归 `integration-service`；跨服务通过内部客户端、DTO、事件和服务令牌协作。 - 普通业务成功/失败使用 HTTP 200 + body `code`（成功为字符串 `"200"`）；认证、基础设施和网关拒绝可使用真实 401/403/503。 ## 服务路由（按关键词定位） @@ -32,6 +32,9 @@ | 资质、导出、测量图片、文件下载 | `file/` | `file/AGENTS.md` | | 路由、CORS、JWT 入口、访问域 | `gateway/` | `gateway/AGENTS.md` | | 百度/Amazon/OCR/第三方适配 | `integration-service/` | `integration-service/AGENTS.md` | +| 海外 API 路由、海外 Token、Audience/JWKS | `gateway-overseas/` | `gateway-overseas/AGENTS.md` | +| 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | `lastleg-service/` | `lastleg-service/AGENTS.md`，再按 `inboundplan/`、`relabel/`、`inventory/`、`procurement/`、`trucking/` 定位 | +| 海外仓库、海外库位、海外托盘、资源锁 | `warehouse-overseas-service/` | `warehouse-overseas-service/AGENTS.md` | | PDF 标签、审计、事件 | `print/`、`audit-service/`、`event-bridge-service/` | 各服务指引 | ## 全量验收路由 @@ -44,6 +47,7 @@ - 国内头程 Auth 是唯一用户账号和 Token 签发方；Admin/Client 共用一套前端和用户体系，海外仓不得另建登录或权限模型。 - 统一使用 RS256/JWKS。国内登录/刷新时由 Auth 同时签发国内 Token 和短时海外 Token；前端统一认证层按国内/海外 API Base 自动选择。国内服务叠加 Redis 会话校验，海外服务不得访问国内 Redis，只按限定 Audience 的海外 Token Claims 完成本地认证和授权；海外业务请求不得经国内 Gateway 中转。 - 头程与海外仓的入库单、装柜结果、费用来源和财务回传走 MQ Outbox/Inbox 事件链；事件不携带用户 JWT，服务身份由 MQ TLS/ACL 或内部服务令牌负责。跨区事件契约、幂等和死信分别查 `common-event-contract/`、`event-bridge-service/` 与目标消费者。 +- 海外浏览器请求只进入 `gateway-overseas/`，由其路由到 `lastleg-service/`、`warehouse-overseas-service/` 及海外部署的公共服务；不得经国内 `gateway/` 中转。`lastleg-service` 不读取头程数据库，`warehouse-overseas-service` 不读取尾程订单库。 ## 契约、数据库与验证入口 @@ -69,6 +73,7 @@ - 一期：`../docs/一期/README.md`、`../docs/一期/一期头程订单闭环设计.md` - 二期：`../docs/二期/README.md`、`../docs/二期/二期需求优化版-v2-测量计费入库主流程.md`、需求确认清单及联调报告 - 三期：`../docs/三期/README.md`、`../docs/三期/三期开工门禁.md`、`../docs/三期/三期开发规划.md`、`../docs/三期/三期需求确认表.md`、页面与原型清单 +- 四期：`../docs/四期/README.md`；海外入口 `gateway-overseas/`，尾程与入仓库存 `lastleg-service/`，海外仓储资源 `warehouse-overseas-service/` - 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束 全量验收任务再读取对应阶段进度表、验收报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。 diff --git a/gateway-overseas/AGENTS.md b/gateway-overseas/AGENTS.md index 8d4aff60e..dfcc35264 100644 --- a/gateway-overseas/AGENTS.md +++ b/gateway-overseas/AGENTS.md @@ -1,4 +1,4 @@ -# Gateway 模块指引 +# Overseas Gateway 模块指引 ## 职责边界 @@ -25,6 +25,5 @@ ## 修改与验证 -- 定向验证：`mvn -pl gateway -am test`。 +- 定向验证：`mvn -pl gateway-overseas -am test`。 - 安全变更覆盖合法令牌、错误 Audience、缺失 Claims、过期/错误签名和身份头伪造测试。 - diff --git a/lastleg-service/AGENTS.md b/lastleg-service/AGENTS.md index 7a71049e7..1d5999c8b 100644 --- a/lastleg-service/AGENTS.md +++ b/lastleg-service/AGENTS.md @@ -20,14 +20,22 @@ | 入仓计划转换/查询 | `inboundplan/controller/InboundPlanController.java`、`inboundplan/service/InboundPlanService.java` | | 托盘分配算法 | `inboundplan/service/PalletAllocator.java` | | PDA 入仓、实收、上架、合托、完成 | `inboundplan/pda/controller/`、`inboundplan/pda/service/InboundPdaWorkflowService.java` | +| 入仓后库存余额、库位和流水 | `inventory/`；平台库存命令从 `inventory/command/controller/InventoryCommandController.java` 进入 | | 仓储资源调用 | `inboundplan/pda/gateway/WarehouseResourceGateway.java`、`HttpWarehouseResourceGateway.java` | | 仓储转运、历史订单/入仓绑定、可选换标联动 | `transfer/controller/WarehouseTransferController.java`、`transfer/service/WarehouseTransferService.java` | | 一件代发接收、SKU/箱唛库存 | `dropship/service/DropshipOrderService.java`、`dropship/entity/`、`dropship/mapper/` | | 货物废弃、待审锁箱、审批扣减 | `discard/controller/CargoDiscardController.java`、`discard/service/CargoDiscardService.java` | | 海外采购、客户下单、采购审核、手工出库与采购库存 | `procurement/controller/`、`procurement/service/OverseasProcurementService.java` | +| 美国/本土卡车订单 | `trucking/controller/PlatformUsTruckOrderController.java`、`MerchantUsTruckOrderController.java` 及同子域 Service/DTO | | 数据库基线、表索引与中文注释契约 | `src/main/resources/db/lastleg.sql`、`src/test/java/com/baiyue/lastleg/schema/SchemaChineseCommentContractTest.java` | | 测试 | `src/test/java/com/baiyue/lastleg/` | +## 四期开发范围路由 + +- 四期在本服务内只进入尾程订单、入仓计划/PDA 入仓、换标、产品与箱唛快照、库存、海外采购和本土卡车；本土散板新增实现也归本服务的独立稳定子域。 +- `dispatch/`、`delivery/`、出库单、PDA 出库拣货、派送和其他库存离仓能力虽然已存在于服务代码或表结构中，但不属于当前四期开发与验收范围，不得因代码已存在而自动纳入。 +- 海外仓库、库位、实物托盘和资源锁归 `warehouse-overseas-service/`；浏览器 API 统一经 `gateway-overseas/`，本服务不得复制仓储资源主数据或另建公网认证入口。 + ## 数据库表索引与注释约束 | 业务域 | 表名 | 中文含义 | diff --git a/warehouse-overseas-service/AGENTS.md b/warehouse-overseas-service/AGENTS.md index e3b1498dc..f3e53ff47 100644 --- a/warehouse-overseas-service/AGENTS.md +++ b/warehouse-overseas-service/AGENTS.md @@ -1,4 +1,4 @@ -# Warehouse Service 模块指引 +# Overseas Warehouse Service 模块指引 ## 职责与边界 @@ -42,4 +42,4 @@ ## 修改与验证 - 字段、注释和索引同步维护基线 SQL 与统一增量 SQL。 -- 定向验证：`mvn -pl warehouse -am test`。 +- 定向验证：`mvn -pl warehouse-overseas-service -am test`。