baiyue-firstleg/warehouse/AGENTS.md

Warehouse Service 模块指引

职责边界

• 负责国内收货仓、仓库地址、服务能力、启停校验和往来单位主数据。
• 往来单位保存在 baiyue_warehouse.wh_partner，不是独立服务；订单只通过内部接口校验并保存快照。

功能快速索引

功能	入口
商户可用仓库列表与详情	controller/MerchantWarehouseController.java
平台仓库增改查与启停	controller/PlatformWarehouseController.java
内部仓库有效性校验	controller/InternalWarehouseController.java
商户往来单位候选与详情	controller/MerchantPartnerController.java
内部往来单位有效性校验	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/WarehouseHealthController.java、service/WarehouseSchemaReadinessService.java
数据访问异常映射	controller/WarehouseDataAccessExceptionHandler.java；数据库不可用或结构漂移统一返回 S0503/503
仓库业务编排	service/WarehouseApplicationService.java
往来单位查询与停用过滤	service/PartnerQueryService.java
请求与详情 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/test/java/com/baiyue/warehouse/

修改与验证

• 商户只看到可用且符合租户/服务范围的数据；平台启停必须检查业务约束，不能只改状态字段。
• 平台仓库管理接口必须同时校验平台访问域和按钮权限：列表/详情使用 platform:warehouse:list，新增使用 platform:warehouse:create，编辑使用 platform:warehouse:edit，启停使用 platform:warehouse:status；OpenAPI 的 403 响应说明必须与权限码同步。
• 往来单位与仓库查询供 Order 使用，DTO 或有效性语义变化需同步检查 order/client/ 和订单快照逻辑。
• 往来单位类型以 types 多值集合和 wh_partner_type 为准，允许同一单位同时作为客户、供应商等；wh_partner.partner_type 与 DTO 的 partnerType 仅保留旧数据兼容。写入时 Entity、Mapper、Repository、平台保存/导入和 Order 客户端必须一起核对。
• 往来单位与快递公司导入只接收标准 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 公网路由。
• 数据表、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。