添加AGENTS.md 快速索引

2026-08-04 15:41:19 +08:00
parent f330098ff6
commit f1dcb91fa9
8 changed files with 120 additions and 106 deletions
@@ -2,8 +2,9 @@

 ## 职责边界

- 负责国内收货仓、仓库地址、服务能力、启停校验和往来单位主数据。
+- 负责国内收货仓、仓库地址、服务能力、启停校验、往来单位主数据，以及二期托盘、库位、预占和占用资源。
 - 往来单位保存在 `baiyue_warehouse.wh_partner`，不是独立服务；订单只通过内部接口校验并保存快照。
+- 入库流程状态和测量数据属于 `firstleg/`；本模块只维护仓储资源及其容量、预占和占用状态，不复制入库单领域模型。

 ## 功能快速索引

@@ -16,6 +17,9 @@
 | 内部往来单位有效性校验 | `controller/InternalPartnerController.java` |
 | 平台往来单位增改查、启停与 XLSX 导入 | `controller/PlatformPartnerController.java`、`service/PlatformPartnerQueryService.java`、`PartnerImportService.java`；模板 `/import-template`，导入 `/import` |
 | 平台快递公司增改查、启停与 XLSX 导入 | `controller/PlatformExpressCompanyController.java`、`service/ExpressCompanyQueryService.java`、`ExpressCompanyImportService.java`；模板 `/import-template`，导入 `/import` |
+| 平台托盘增改查 | `controller/PlatformPalletController.java` → `service/PalletApplicationService.java` → `repository/PalletRepository.java`；体积分托盘规则在 `service/PalletVolumeSplitter.java` |
+| 平台库位增改查、可用库位与容量 | `controller/PlatformLocationController.java` → `service/LocationApplicationService.java`、`LocationResourceService.java` → `repository/LocationRepository.java` |
+| Firstleg 托盘库位预占、确认和释放 | `controller/InternalPalletLocationController.java`（`/reservations`、`/confirm`、`/release`）→ `service/PalletLocationAllocationService.java`；只允许内部令牌调用 |
 | 服务与数据库结构状态 | `controller/WarehouseHealthController.java`、`service/WarehouseSchemaReadinessService.java` |
 | 数据访问异常映射 | `controller/WarehouseDataAccessExceptionHandler.java`；数据库不可用或结构漂移统一返回 `S0503/503` |
 | 仓库业务编排 | `service/WarehouseApplicationService.java` |
@@ -23,6 +27,7 @@
 | 请求与详情 DTO | `dto/WarehouseRequests.java`、`WarehouseDetailResponse.java`、`MasterDataQueries.java` |
 | 仓库、地址、能力、往来单位与快递公司持久化 | `entity/`、`mapper/`、`repository/`；往来单位多类型关联为 `PartnerTypeEntity.java` 与 `wh_partner_type` |
 | 表结构、伙伴、快递公司与种子数据 | `src/main/resources/db/warehouse.sql`、`warehouse-partner.sql`、`warehouse-express-company.sql`、`phase1-warehouse-schema-migration.sql`、`warehouse-seed.sql` |
+| 二期托盘库位表与迁移 | `src/main/resources/db/phase2-pallet-location-schema.sql`、`phase2-pallet-location-schema-migration.sql`、`phase2-location-overflow-migration.sql`；统一部署入口 `../deploy/sql/2026-08-04-二期入库新增表字段-MySQL8一键执行.sql` |
 | 测试 | `src/test/java/com/baiyue/warehouse/` |

 ## 修改与验证
@@ -34,8 +39,12 @@
 - 往来单位与快递公司导入只接收标准 XLSX 模板，文件上限 5MB、最多 1000 行；先完成整表头、字段、文件内重复和数据库重复校验，再原子写入，任一行失败整批不落库。权限分别是 `platform:counterparty:import` 与 `platform:express:import`。
 - 模板与导入 DTO 在 `dto/MasterDataQueries.java`，Apache POI 依赖在 `pom.xml`；调整模板版本、列顺序或枚举时同步修改生成、解析、错误行号和两组 ImportService 测试。
 - Warehouse 内部仓库/往来单位接口使用 `X-Internal-Service-Token`；不存在或跨租户使用 HTTP 200 + body code `A0404`，已停用使用 HTTP 200 + `A0409`，`WarehouseDataAccessExceptionHandler` 捕获的数据库或结构故障保留真实 HTTP 503 + `S0503`。内部路径不加入 Gateway 公网路由。
+- 托盘和库位平台接口必须执行平台访问域、目标租户和对应权限校验；预占、确认、释放只通过 `InternalPalletLocationController` 提供给 Firstleg，不加入 Gateway 公网路由。
+- 库位容量、共享溢出、预占和占用必须在数据库事务及条件更新中保持一致；修改分配算法时同步覆盖并发冲突、容量不足、重复确认、释放和共享溢出测试。
+- Firstleg 只保存托盘/库位逻辑引用和入库快照。内部 DTO、预占状态或容量口径变化时同步检查 `firstleg/client/WarehousePalletLocationClient.java`、`MeasurementLocationOccupationService.java` 和双方测试。
 - 数据表、Entity、Mapper、Repository 与种子数据必须同步；历史订单不随主数据更新。
 - 既有数据库发布必须按 `warehouse.sql`、`warehouse-partner.sql`、`warehouse-express-company.sql`、`phase1-warehouse-schema-migration.sql`、`warehouse-seed.sql` 的顺序执行；服务不在启动时自动跑 SQL。
 - `/api/platform/v1/warehouses/status` 必须执行真实字段探针；缺表或缺列时返回 `DEGRADED/503`，不得只根据进程存活伪报 `UP`。
 - Warehouse 的数据库访问异常和 readiness/结构状态探针都保留真实 HTTP 503；其他由公共异常处理器捕获的业务失败才使用 HTTP 200 + body code。
 - 从父目录运行 `mvn -pl warehouse -am test`，再运行 `scripts/order-warehouse-real-api-regression.ps1`。
+- 二期直接验证至少运行 `PalletApplicationServiceTest`、`LocationApplicationServiceTest`、`LocationResourceServiceTest`、`PalletLocationAllocationServiceTest` 及两个平台 Controller 契约测试；存量数据库迁移后确认统一脚本末尾 Warehouse 核验全部为 `PASS`。