ouyangxq
19745e46c1
18 个服务与公共模块重复复制的 314 字符数据库访问约束改为指向后端根唯一定义，并给索引门禁增加防退化校验。 - 18 处重复段落合并为一句指针，规则正文只在后端根 AGENTS.md 维护 - 门禁新增路由表行宽上限（根/Admin/Client/后端根/海外 PDA），防止业务规则重新回流表格 - 同步包含此前未提交的链接与锚点、表格存在性校验 - 仅索引文档与门禁脚本，未改动业务代码
54 lines
7.5 KiB
Markdown
54 lines
7.5 KiB
Markdown
# Warehouse Service 模块指引
|
||
|
||
## 数据库访问与中文注释约束
|
||
|
||
- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。
|
||
|
||
## 职责与边界
|
||
|
||
- Mapper 只由 `BaiyueWarehouseApplication.java` 对 `com.baiyue.warehouse` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
|
||
- 负责国内收货仓及现有平台仓库主数据、地址/能力、往来单位、快递公司、平台公共供应商、国内整柜库存/出入库，以及托盘主数据、库位预占和占用。海外仓业务只在本模块扩展“海外仓合作仓”仓库类型及其公共主数据契约。
|
||
- 入库单、测量和入库状态归 `firstleg/`；订单只通过内部接口校验并保存快照。
|
||
- 海外接柜、卸货、入仓、换标、产品、箱号、库存、库内作业、出库和派送归 Lastleg，不落入本 Warehouse Service；海外实物资源归 Warehouse Overseas。已知主档或资源接口沿实际调用定位，只有跨模块流程范围不明时读 `../../docs/海外仓业务/README.md`。
|
||
- 公共资源统一 `tenant_id=0`，不得绑定客户或要求客户筛选。
|
||
|
||
## 模块入口
|
||
|
||
| 目标 | 入口 |
|
||
|---|---|
|
||
| 仓库/地址/能力 | `controller/PlatformWarehouseController.java`、`MerchantWarehouseController.java`、`service/WarehouseApplicationService.java`；国内 PDA 仓库目录由 `InternalWarehouseController.java` 的 `/internal/warehouses/domestic` 提供给 Firstleg |
|
||
| FBA 目的仓公共主数据与 Admin 候选 | 权威表 `wh_warehouse` 的 `tenant_id=0 + warehouse_type=FBA` 记录；Admin 直接调用 `GET /api/platform/v1/warehouse-admin?warehouseType=FBA&status=ACTIVE&page=1&size=200`，权限 `platform:warehouse:list`，DTO `WarehouseSummaryResponse` 的 `id/warehouseCode/warehouseName/status/countryCode/primaryAddress.stateProvince` 分别作为 ID/编码/名称/状态/国家/区域 |
|
||
| FBA 目的仓内部校验 | `InternalWarehouseController.java` 的 `GET /internal/warehouses/0/{warehouseId}/active`，使用内部服务令牌返回 `WarehouseDetailResponse`；调用方仍须校验 `warehouseType=FBA` 及 ID/编码/名称一致，不得把 `OVERSEAS` 实际收货仓或 `DOMESTIC` 中转仓当作 FBA 目的仓 |
|
||
| 公共海外收货仓内部目录 | `controller/InternalWarehouseController.java` 的 `/internal/warehouses/shared-overseas`、`/shared-overseas/{warehouseId}`，响应 `dto/SharedOverseasWarehouseResponse.java`；只返回平台公共 `OVERSEAS + ACTIVE + RECEIVING` 仓，供海外资源服务按 warehouseId 引用 |
|
||
| 公共海外收货仓平台候选 | `controller/PlatformOverseasReceivingOptionsController.java`；统一 Gateway 的 `/api/platform/v1/warehouse-admin/overseas-receiving-options`，权限 `platform:overseas-warehouse:warehouse:list`，平台主体且公共作用域，固定 `OVERSEAS + ACTIVE + RECEIVING`；分页上限200，契约见 `src/main/resources/openapi/warehouse-v1.yaml` |
|
||
| 海外仓合作仓类型 | 沿用仓库/地址/能力入口；同步核对仓库 DTO、OpenAPI、`src/main/resources/db/`、统一 SQL 及 Admin `modules/warehouses/`，并与普通海外仓语义明确区分 |
|
||
| 往来单位/快递 | `controller/PlatformPartnerController.java`、`PlatformExpressCompanyController.java`、`service/PlatformPartnerQueryService.java`、`PartnerImportService.java` |
|
||
| 托盘 | `controller/PlatformPalletController.java`、`service/PalletApplicationService.java` |
|
||
| 库位与分配 | `controller/PlatformLocationController.java`、`InternalPalletLocationController.java`、`service/PalletLocationAllocationService.java` |
|
||
| 海外仓阶梯费用 | `controller/PlatformOverseasStorageFeeController.java`、`service/OverseasStorageFeeService.java` |
|
||
| 平台公共供应商 | `controller/PlatformSupplierController.java`、`service/SupplierService.java`；TRUCKING 必须设置互斥 `truckingScope=DOMESTIC（国内拖车）/OVERSEAS（海外车队）`，其他类别为空；分页/导出支持类型筛选，导入模板版本3必填类型；契约见 `src/main/resources/openapi/supplier-v1.yaml` `controller/InternalSupplierController.java` 的 `/{supplierId}/trucking-contact` 为 Firstleg 提供平台 TRUCKING + OVERSEAS 海外车队邮箱资料，取消旧请求允许读取已停用车队邮箱，仍验证内部令牌及平台归属。 |
|
||
| 国内整柜业务 | `domesticcontainer/controller/PlatformDomesticContainerController.java`、`domesticcontainer/service/DomesticContainerService.java`；契约见 `src/main/resources/openapi/domestic-container-v1.yaml` |
|
||
| DTO/持久化 | `dto/`、`entity/`、`mapper/`、`repository/` |
|
||
| SQL | `src/main/resources/db/`；存量统一 `../deploy/sql/头程数据库统一增量-MySQL8.sql` |
|
||
| 测试/验证 | Java 测试 `src/test/java/com/baiyue/warehouse/`，执行 `mvn -pl warehouse -am test`；公共 FBA 仓 CSV 与 SQL 离线合同 `scripts/warehouse-public-master-data-contract.test.mjs`，从后端根执行 `node --test warehouse/scripts/warehouse-public-master-data-contract.test.mjs`；局部说明见 `scripts/README.md` |
|
||
|
||
## 修改约束
|
||
|
||
- 内部仓储接口使用 `X-Internal-Service-Token`，不加入 Gateway 公网路由；资源停用/不存在遵循统一 body code。
|
||
- 仓库 ID、类型、状态、地址和服务能力在本模块唯一维护；海外服务不得复制仓库主档。共享海外收货仓目录只接受内部服务令牌，列表和单项必须使用相同的 `tenant_id=0 + OVERSEAS + ACTIVE + RECEIVING` 判定。
|
||
- 导入先全量校验再原子写入；调整 DTO、类型或容量规则时同步 Order/Firstleg 客户端和契约测试。
|
||
|
||
## 国内货柜履约托盘、库位与 A0 规则
|
||
|
||
- 托盘是可复用标识和称重主数据，不参与 `AVAILABLE → RESERVED → OCCUPIED → AVAILABLE`；同一托盘主数据可被多条分配复用。
|
||
- 普通库位保持单活动预占/占用；A0 是系统创建的共享临时溢出位，可承载多条占用，但每条库位占用仍必须通过 `reservation_id`、`occupancy_id` 独立识别。
|
||
- 头程 PDA 结算接口 `/internal/warehouse/v1/pallet-locations/settlements` 是释放、子单转移和全部释放后重新分配的原子边界。不得将其拆成多个可独立提交的远程操作。
|
||
- 部分拣货的资源操作必须按 `reservationId` 定位，不能按 `locationId` 定位；A0 多托盘共享时，按 `locationId` 会误释放或合并资源。
|
||
- 当父单全部库位释放但子单仍有剩余数量时，在同一仓库事务内优先分配自然 A-Z 顺序的普通空闲库位；普通库位不足时使用 A0，并保持预占、占用和子单归属一致。
|
||
- A0 换绑入口包括内部接口和平台接口：平台人员使用 `/api/platform/v1/locations/temporary-occupancies/{occupancyId}/rebind`，需要 `platform:location:edit`。目标必须为同仓 `AVAILABLE` 的普通库位；A0 不允许人工编辑、停用或删除。
|
||
- 资源结算、释放、转移和换绑必须保存可重放的幂等记录或具有等价的状态幂等语义，并在测试中覆盖并发状态变更。
|
||
|
||
## 全量验收导航
|
||
|
||
本模块承载公共仓与主数据、托盘/库位预占占用、海外仓费用、PDA 拣货和资源结算协作；按本次验收链路读取对应业务域文档，核对实时库存、当前位置、可用量、原子结算和客户隔离。不扩展未确认的完整 WMS，设备真机事项不改变服务端资源契约。
|