38 lines
3.3 KiB
Markdown
38 lines
3.3 KiB
Markdown
# Warehouse Service 模块指引
|
||
|
||
## 职责边界
|
||
|
||
- 负责国内收货仓、仓库地址、服务能力、启停校验和往来单位主数据。
|
||
- 往来单位保存在 `baiyue_warehouse.wh_partner`，不是独立服务；订单只通过内部接口校验并保存快照。
|
||
|
||
## 功能快速索引
|
||
|
||
| 功能 | 入口 |
|
||
|---|---|
|
||
| 商户可用仓库列表与详情 | `controller/MerchantWarehouseController.java` |
|
||
| 平台仓库增改查与启停 | `controller/PlatformWarehouseController.java` |
|
||
| 内部仓库有效性校验 | `controller/InternalWarehouseController.java` |
|
||
| 商户往来单位候选与详情 | `controller/MerchantPartnerController.java` |
|
||
| 内部往来单位有效性校验 | `controller/InternalPartnerController.java` |
|
||
| 平台往来单位增改查与启停 | `controller/PlatformPartnerController.java`、`service/PlatformPartnerQueryService.java` |
|
||
| 平台快递公司增改查与启停 | `controller/PlatformExpressCompanyController.java`、`service/ExpressCompanyQueryService.java` |
|
||
| 服务与数据库结构状态 | `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/` |
|
||
| 表结构、伙伴、快递公司与种子数据 | `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/` 和订单快照逻辑。
|
||
- Warehouse 内部仓库/往来单位接口使用 `X-Internal-Service-Token`，不存在或跨租户返回 404，记录存在但已停用返回 409；数据库或结构故障保持 503。内部路径不加入 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`。
|
||
- 从父目录运行 `mvn -pl warehouse -am test`，再运行 `scripts/order-warehouse-real-api-regression.ps1`。
|