From f1dcb91fa94196caac014f0a2ca83275fe39d7c5 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Tue, 4 Aug 2026 15:41:19 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0AGENTS.md=20=E5=BF=AB?= =?UTF-8?q?=E9=80=9F=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 29 ++++-- README.md | 2 +- docs/头程项目目录结构与服务说明.md | 137 +++++++++-------------------- file/AGENTS.md | 16 +++- firstleg/AGENTS.md | 24 ++++- integration-service/AGENTS.md | 5 +- order/AGENTS.md | 2 + warehouse/AGENTS.md | 11 ++- 8 files changed, 120 insertions(+), 106 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ee0ad0f9e..8f0e93a83 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ ## 适用范围 - 本文件适用于 `baiyue-firstleg/` 整个 Maven 多模块仓库；进入子模块后同时遵守该模块的 `AGENTS.md`。 -- 开始修改前先读根目录 `README.md`、`pom.xml` 和 `docs/头程项目目录结构与服务说明.md`；业务边界以本文件及该说明的“项目定位、主要调用关系、开发和拆分约束”为准。 +- 普通开发先读本文件、目标模块 `AGENTS.md` 和相邻代码；项目概览或聚合构建问题再读 `README.md`、`pom.xml`，跨服务架构、端口数据库、根目录结构、启动或部署问题再读 `docs/头程项目目录结构与服务说明.md`。 - 本仓只承载国内头程业务。尾程源码、数据库、Redis、Nacos 和内部接口不得并入本仓。 ## 模块快速索引 @@ -20,10 +20,10 @@ | `gateway/` | 路由、CORS、入口安全、请求标识、访问域隔离 | `config/`、`filter/CorrelationIdWebFilter.java`、`src/main/resources/application*.yml` | | `auth/` | 登录、令牌、注册、账号、密码与账号归属范围 | `InternalAccountController.java`、`AccountManagementService.java`、`AccountManagementDtos.java`、`src/main/resources/db/` | | `iam/` | 租户、商户成员、平台统一用户管理、企业资料/资质、RBAC 与授权快照 | `PlatformUserManagementController.java`、`PlatformTenantController.java`、`ProfileResourceController.java`、`RbacController.java` | -| `order/` | 订单主数据、租户运单数、持久化幂等、状态编排、快照与 Outbox | `PlatformFirstLegOrderController.java`、`OrderApplicationService.java`、`TenantOrderCountResponse.java`、`README-ORDER.md` | -| `firstleg/` | 履约任务分页/详情、操作分配与分配历史 | `PlatformFulfillmentAssignmentController.java`、`FulfillmentTaskService.java`、`src/main/resources/db/phase1-firstleg-task-list-index.sql` | -| `warehouse/` | 仓库、地址、服务能力、往来单位多类型、快递公司与 XLSX 导入 | `controller/`、`PlatformPartnerQueryService.java`、`PartnerImportService.java`、`ExpressCompanyImportService.java` | -| `file/` | 企业资质文件与公共导出/下载中心 | 资质：`QualificationFileController.java`、`LocalQualificationStorage.java`；导出：`PlatformExportTaskController.java`、`ExportStateService.java`、`mq/`、`GenericXlsxExportRunner.java`、`ExportReconciler.java` | +| `order/` | 订单主数据、租户运单数、持久化幂等、状态编排、快照、货物明细内部查询与 Outbox | `PlatformFirstLegOrderController.java`、`OrderApplicationService.java`、`InternalOrderCargoController.java`、`README-ORDER.md` | +| `firstleg/` | 履约任务与分配；二期入库单、测量/OCR 结果、审核、FBA 计费和自动完成入库 | 履约：`PlatformFulfillmentAssignmentController.java`、`FulfillmentTaskService.java`；入库：`controller/PlatformInbound*.java`、`service/Inbound*.java`、`service/Fba*.java` | +| `warehouse/` | 仓库、地址、服务能力、往来单位、快递公司；二期托盘、库位、预占和占用 | 主数据：`controller/`、`PlatformPartnerQueryService.java`；二期：`PlatformPalletController.java`、`PlatformLocationController.java`、`PalletLocationAllocationService.java` | +| `file/` | 企业资质文件、公共导出/下载中心；入库测量图片与重量 OCR 协作 | 资质：`QualificationFileController.java`；导出：`PlatformExportTaskController.java`、`ExportStateService.java`；测量图片：`PlatformMeasurementImageController.java`、`InternalMeasurementImageController.java`、`MeasurementImageService.java` | | `print/` | 打印中心边界 | 当前为应用、健康检查和 `print/src/main/resources/db/print.sql` 骨架 | | `audit-service/` | 审计事件接收与持久化 | `AuditIngestController.java`、`AuditIngestService.java`；当前接收接口未实现内部令牌保护 | | `integration-service/` | 重量 OCR、百度 OCR、Amazon 等第三方适配 | `controller/WeightOcrController.java`、`service/ocr/`、`provider/ocr/`、`IntegrationProperties.java` | @@ -42,6 +42,24 @@ | HTTP 200、body code、成功码 `"200"` | `docs/统一响应约定改造方案-HTTP200.md`、`common-core/ResultCode.java`、`common-web/GlobalExceptionHandler.java` | | 单服务 Jenkins 构建或部署 | 总控 `Jenkinsfile`、子 Job `Jenkinsfile.service`、模块/JAR 映射 `deploy/service-map.yml` | +## 二期入库快速索引 + +| 业务链路 | API 与编排入口 | 数据、跨服务与验证入口 | +|---|---|---| +| 平台入库单列表、页签与聚合详情 | `firstleg/.../controller/PlatformInboundOrderController.java` → `service/InboundOrderQueryService.java` | `repository/InboundOrderRepository.java`、`mapper/InboundAllocationQueryMapper.java`；测试 `service/InboundOrderQueryServiceTest.java`、`controller/InboundOrderControllerContractTest.java` | +| 平台测量草稿、提交及重量 OCR 结果 | `firstleg/.../controller/PlatformInboundMeasurementController.java` → `service/InboundMeasurementService.java`、`MeasurementSubmissionService.java` | 图片走 `client/MeasurementImageClient.java`，托盘库位走 `client/WarehousePalletLocationClient.java`；测试 `service/InboundMeasurementServiceTest.java`、`MeasurementSubmissionServiceTest.java` | +| 第三方尺寸测量回传 | `firstleg/.../controller/OpenApiInboundMeasurementController.java` → `security/MeasurementRequestAuthenticator.java` → `service/InboundMeasurementOpenApiService.java` | 订单货物校验走 `client/OrderCargoClient.java` → `order/.../controller/InternalOrderCargoController.java`；证据图片走 File 内部接口；配置 `config/MeasurementOpenApiProperties.java`，测试 `service/InboundMeasurementOpenApiServiceTest.java` | +| 测量审核、异常放行与自动完成入库 | `firstleg/.../controller/PlatformInboundMeasurementReviewController.java` → `service/MeasurementReviewService.java` → `AutomaticInboundCompletionService.java` | 费用与入库状态编排在 `FbaPricingService.java`、`InboundCompletionOrchestrator.java`；测试 `service/MeasurementReviewServiceTest.java`、`InboundCompletionOrchestratorTest.java` | +| FBA 客户规则、承运商价格与费用快照 | 主数据 `firstleg/.../controller/PlatformFbaMasterDataController.java` → `service/FbaMasterDataService.java`；计费 `PlatformFbaPricingController.java` → `service/FbaPricingService.java` | `repository/FbaPricingRepository.java`、`src/main/resources/openapi/fba-pricing-v1.yaml`、`src/main/resources/db/phase2-fba-pricing-migration.sql`；测试 `service/FbaMasterDataServiceTest.java`、`FbaPricingServiceTest.java` | +| 商户查看入库费用 | `firstleg/.../controller/MerchantInboundBillingController.java` → `service/MerchantInboundBillingService.java` | 只按已认证商户租户查询；接口为 `/api/merchant/v1/first-leg/orders/{orderId}/inbound-billing` | +| 托盘、库位与预占/占用 | 平台 CRUD：`warehouse/.../controller/PlatformPalletController.java`、`PlatformLocationController.java`；内部事务接口：`InternalPalletLocationController.java` | `service/PalletApplicationService.java`、`LocationApplicationService.java`、`PalletLocationAllocationService.java`；表与迁移在 `warehouse/src/main/resources/db/phase2-*.sql` | +| 称重图片、OCR 重试与第三方测量证据 | 平台入口 `file/.../controller/PlatformMeasurementImageController.java`；Firstleg 内部入口 `InternalMeasurementImageController.java` | `service/MeasurementImageService.java`、`MeasurementImageStorage.java`、`client/WeightOcrClient.java`；重量识别服务入口 `integration-service/.../controller/WeightOcrController.java` | +| 入库状态、幂等、历史与 Outbox | `firstleg/.../domain/InboundProcessStatus.java`、`service/InboundIdempotencyService.java`、`repository/InboundWorkflowRepository.java` | 表结构与增量在 `firstleg/src/main/resources/db/phase2-*.sql`；SQL 契约测试 `repository/InboundWorkflowSqlContractTest.java` | +| 二期数据库部署 | 测试环境/存量环境统一入口 `deploy/sql/2026-08-04-二期入库新增表字段-MySQL8一键执行.sql` | 覆盖 `baiyue_file`、`baiyue_firstleg`、`baiyue_warehouse`；前置、可重复执行边界和末尾 `PASS` 核验见脚本头及 `deploy/sql/README.md`，不得在未核对目标库和备份的情况下执行 | + +- 上表中的 `模块/.../` 从对应模块的 `src/main/java/com/baiyue//` 起算；二期链路跨 `order`、`firstleg`、`warehouse`、`file`、`integration-service`，修改 DTO、内部令牌、状态或表结构时必须逐个检查调用方与被调用方。 +- 二期入库主状态归 `firstleg`，订单货物主数据仍归 `order`，托盘/库位资源归 `warehouse`，文件对象归 `file`，OCR 供应商适配归 `integration-service`；禁止通过跨库查询绕过内部 API。 + ## 配置、数据库与验证入口 - 服务本地配置在各模块 `src/main/resources/application.yml`；Nacos 环境配置集中在 `config/nacos/local/` 和 `config/nacos/cn/`。 @@ -54,6 +72,7 @@ - 平台管理与头程履约补齐的本地数据库只读核验、SQL 清单和回归结果见 `docs/2026-07-31平台管理与头程履约补齐回归报告.md`。 - IAM 授角、订单主数据、File、Gateway CORS 与文件日志的本轮结果见 `docs/2026-07-31-P0-P2问题修复回归报告.md`。 - 本轮测试环境数据库增量统一从 `deploy/sql/2026-07-31一期回归测试环境增量迁移.sql` 执行，执行边界与核验方式见 `deploy/sql/README.md`。 +- 二期入库新建或存量测试环境升级使用 `deploy/sql/2026-08-04-二期入库新增表字段-MySQL8一键执行.sql`；旧的 `2026-08-03-二期入库表结构-TEST环境一键执行.sql` 只保留为早期基线参考，不替代 8 月 4 日最终增量入口。 - CI 总控入口是 `Jenkinsfile`，负责按变更或勾选项并行调度 11 个独立服务 Job；单服务构建、镜像与部署逻辑在 `Jenkinsfile.service`。Job 名必须以模块名结尾，公共模块或 `deploy/` 变化会触发全部服务。 - 从本目录运行全量校验：`mvn -DskipTests validate`、`mvn test`。单模块修改优先运行 `mvn -pl -am test`。 - 公共导出中心测试环境真实任务验收使用 `scripts/export-center-test-env-acceptance.ps1`；脚本只调用 Gateway，不负责部署或停止 Broker/File/IAM，故障注入由有权限的运维配合。 diff --git a/README.md b/README.md index d63c55004..35b0b0a48 100644 --- a/README.md +++ b/README.md @@ -39,4 +39,4 @@ CORS_ALLOWED_ORIGINS=https://merchant.example.com,https://admin.example.com ## 仓库边界 -详细规则见 `docs/repository-boundary.md`。本仓不得引入尾程源码，不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。 +仓库边界、服务调用和拆分规则见 `docs/头程项目目录结构与服务说明.md` 的“项目定位”“主要调用关系”和“开发和拆分约束”。本仓不得引入尾程源码，不允许跨区域共享数据库、Redis 或 Nacos，也不允许通过公网直接调用对方内部服务。 diff --git a/docs/头程项目目录结构与服务说明.md b/docs/头程项目目录结构与服务说明.md index 215b125b4..aafdd8de5 100644 --- a/docs/头程项目目录结构与服务说明.md +++ b/docs/头程项目目录结构与服务说明.md @@ -1,5 +1,13 @@ # 头程项目目录结构与服务说明 +## 文档定位与读取时机 + +本文是面向架构理解和运维协作的服务总览，主要说明技术基线、目录结构、服务端口、数据库归属、调用关系和启动部署拓扑。 + +- 普通单模块开发不需要预先通读本文；先读仓库根 `AGENTS.md` 和目标模块 `AGENTS.md`。 +- 涉及跨服务设计、模块拆分、端口或数据库归属、根目录调整、本地启动和部署拓扑时再读本文。 +- Controller、Service、SQL、测试和当前实现入口以各级 `AGENTS.md` 与代码为准；本文不维护文件级快速索引，避免与执行指引重复和漂移。 + ## 1. 项目定位 `baiyue-firstleg` 是国内头程业务后端仓库，采用 Maven 多模块单仓结构。仓库内包含 7 个公共模块和 11 个可独立启动、构建、制作镜像的微服务。 @@ -34,9 +42,9 @@ baiyue-firstleg/ ├─ auth/ # 统一登录与账号凭据 ├─ iam/ # 租户、成员、角色、权限、企业审核 ├─ order/ # 头程订单中心 -├─ firstleg/ # 头程履约任务与分配 -├─ warehouse/ # 仓库与往来单位主数据 -├─ file/ # 文件中心 +├─ firstleg/ # 履约任务、二期入库、测量与计费 +├─ warehouse/ # 仓库主数据、托盘与库位资源 +├─ file/ # 资质、导出与测量图片文件中心 ├─ print/ # 打印中心 ├─ audit-service/ # 审计日志中心 ├─ integration-service/ # 第三方平台集成适配 @@ -80,10 +88,10 @@ baiyue-firstleg/ | `gateway` | `gateway` | 9000 | 无 | 统一路由、CORS、JWT/Redis 会话校验、商户端与平台端访问域隔离、Swagger 聚合 | | `auth` | `auth-service` | 9100 | `baiyue_auth` | 登录、刷新 Token、退出、商户注册、账号密码和账号内部管理 | | `iam` | `iam-service` | 9201 | `baiyue_iam` | 租户、企业资料、企业审核、成员、角色、权限、按钮权限、个人资料和授权快照 | -| `firstleg` | `firstleg-service` | 9202 | `baiyue_firstleg` | 履约任务、操作分配和分配历史；不是订单主数据服务 | +| `firstleg` | `firstleg-service` | 9202 | `baiyue_firstleg` | 履约任务与分配；二期入库单、测量审核、FBA 计费、费用发布和完成入库编排；不是订单主数据服务 | | `order` | `order-service` | 9204 | `baiyue_order` | 订单草稿、编辑、提交、详情、状态历史、货物、往来单位快照、内部备注和 Outbox | -| `warehouse` | `warehouse-service` | 9205 | `baiyue_warehouse` | 仓库、仓库地址、服务能力、启停校验，以及往来单位查询；往来单位不单独拆服务 | -| `file` | `file-service` | 9206 | `baiyue_file` | 文件存储与鉴权；实现企业资质上传预览及公共异步导出、下载中心 | +| `warehouse` | `warehouse-service` | 9205 | `baiyue_warehouse` | 仓库、地址、服务能力、往来单位、快递公司，以及二期托盘、库位、预占和占用；往来单位不单独拆服务 | +| `file` | `file-service` | 9206 | `baiyue_file` | 企业资质文件、公共异步导出下载、入库测量图片及重量 OCR 调用协作 | | `print` | `print-service` | 9207 | `baiyue_print` | 打印中心边界已经建立；当前主要是服务骨架、健康检查和数据库结构，打印模板与任务仍需继续完善 | | `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 | | `event-bridge-service` | `event-bridge-service` | 9300 | `baiyue_event_bridge` | 国内外事件接收、签名/内部令牌保护、幂等 Inbox 和接收结果 | @@ -95,119 +103,55 @@ MySQL、Redis、Nacos 是外部基础设施，不属于上述 11 个业务服务 ### 5.1 `gateway/`：统一入口 -主要内容： - -- `config/`：网关安全、CORS、访问域规则和 Redis 会话过滤 -- `filter/`：可信身份请求头处理 -- `application.yml`：本地默认路由与安全配置 -- `application-cn.yml`：国内环境路由和 Swagger 聚合配置 - -前端只应访问 Gateway，不应直接暴露各业务服务端口。网关负责入口认证和路由，业务服务仍需执行租户、数据范围和按钮权限检查。 +Gateway 负责统一路由、CORS、入口认证、可信身份头和 Swagger 聚合。前端只访问 Gateway，不直接暴露业务服务端口；业务服务仍需执行租户、访问域、数据范围和按钮权限校验，不能把网关认证视为最终授权。 ### 5.2 `auth/`：统一登录与账号凭据 -主要内容： - -- `controller/AuthController`：登录、刷新 Token、退出、注册入口 -- `controller/InternalAccountController`：IAM 调用的账号管理接口 -- `service/AuthService`：认证和 Token 生命周期 -- `service/AccountManagementService`：密码修改、密码重置和账号状态处理 -- `service/MerchantRegistrationService`：商户注册协作 -- `client/`：向 IAM 获取授权快照和企业注册结果 -- `resources/db/`：账号和刷新 Token 表结构、一期初始化账号 - -密码散列、登录失败锁定和刷新 Token 属于 Auth。成员资料、角色和权限属于 IAM，不能放入 Auth。 +Auth 负责登录、Token 生命周期、商户注册协作、账号密码和账号状态。密码散列、登录失败锁定和刷新 Token 属于 Auth；成员资料、角色、权限和企业审核属于 IAM，两者通过内部接口协作，不共享数据库。 ### 5.3 `iam/`：租户、成员和权限中心 -主要内容： - -- `MerchantTenantController`：商户端企业、成员相关接口 -- `PlatformTenantController`：平台端企业审核和管理接口 -- `ProfileResourceController`：个人资料、企业资料和资质资源 -- `RbacController`：角色、权限资源、启停和角色授权 -- `InternalAuthorizationController`：向 Auth/其他服务返回权限快照 -- `entity/`：租户、用户、成员关系、角色、权限、数据范围、企业地址和资质审核 -- `resources/db/`：IAM 主结构及一期成员、角色、权限、企业入驻扩展脚本 - -IAM 以 `tenant_id` 作为核心隔离维度，同时维护两套访问域：商户端和平台后台端。按钮权限通过 permission code / permissionIds 管理，不能只依赖前端隐藏按钮。 +IAM 负责租户、企业资料与审核、成员、平台用户、角色、菜单、按钮权限、数据范围和授权快照。它以 `tenant_id` 为核心隔离维度，并区分商户端与平台后台访问域；权限必须由后端校验，不能只依赖前端隐藏按钮。 ### 5.4 `order/`：订单中心 -主要内容： +Order 负责订单草稿、提交、平台处理状态、货物、参与方和主数据快照、状态历史、内部备注、幂等记录与 Outbox。订单保存关键业务快照，Warehouse 或往来单位后续变化不能改写历史订单。 -- `MerchantFirstLegOrderController`：商户端订单草稿、编辑、提交和查询 -- `PlatformFirstLegOrderController`：平台端订单查询和内部处理入口 -- `OrderApplicationService`：订单业务编排和状态转换 -- `OrderEligibilityGuard`：企业审核资格校验 -- `OrderMasterDataGuard`：仓库、往来单位和主数据有效性校验 -- `OrderScopeGuard`：租户与访问范围校验 -- `entity/`：订单、货物、订单参与方快照、状态历史、内部备注和 Outbox 事件 -- `client/`：调用 IAM、Warehouse 获取资格和主数据 - -订单保存的是仓库、往来单位等关键字段的业务快照，主数据后续修改不能改变历史订单。跨服务通知通过 Outbox/事件方式演进，不应让数据库跨库直连。 +企业资格和仓库主数据通过 IAM、Warehouse 内部接口校验；Firstleg 查询订单货物明细也通过受保护的内部接口完成。服务之间不建立跨库外键或跨库查询，通知优先通过 Outbox 和事件演进。 ### 5.5 `firstleg/`：头程履约中心 -主要内容： +Firstleg 承担订单提交后的履约任务、操作分配与历史，以及二期入库单查询、测量回传、人工测量、审核、异常放行、FBA 计费、费用发布和完成入库状态编排。 -- `PlatformFulfillmentAssignmentController`：平台端履约分配入口 -- `FulfillmentTaskService`：履约任务和分配业务 -- `FulfillmentTaskEntity`：履约任务 -- `AssignmentHistoryEntity`：分配历史 +订单主单和货物主数据仍属于 Order；托盘和库位资源属于 Warehouse；图片对象属于 File；OCR 供应商协议属于 Integration。Firstleg 只保存自身业务状态、快照和逻辑引用，通过内部 DTO 调用其他服务，不复制对方领域模型。 -该服务承担订单提交后的执行过程。订单主单及商户草稿仍属于 `order`，避免订单交易状态与履约作业状态混在同一张表。 +### 5.6 `warehouse/`：仓库与仓储资源 -### 5.6 `warehouse/`：仓库与往来单位 +Warehouse 负责仓库、地址、服务能力、往来单位、快递公司，以及二期托盘、库位、预占和占用资源。往来单位只是 Warehouse 下的主数据配置，保存在 `baiyue_warehouse.wh_partner`，不创建独立服务和数据库。 -主要内容： - -- 商户端、平台端和内部仓库 Controller -- `WarehouseApplicationService`：仓库查询、地址、能力和状态校验 -- `PartnerQueryService`：往来单位只读查询和停用过滤 -- `WarehouseEntity`、`WarehouseAddressEntity`、`ServiceCapabilityEntity` -- `PartnerEntity`：往来单位 -- `warehouse-seed.sql`：测试环境仓库初始化数据 - -往来单位只是 Warehouse 服务下的主数据配置，数据库表为 `baiyue_warehouse.wh_partner`，不创建独立微服务和数据库。 +Firstleg 通过内部接口发起托盘库位预占、确认和释放，只保存逻辑引用与入库快照。容量、共享溢出、预占和占用一致性由 Warehouse 的数据库事务和条件更新最终保证。 ### 5.7 `file/`：文件中心 -主要内容： +File 负责企业资质文件、公共异步导出与下载、入库称重图片和第三方测量证据。企业资质审核及其业务元数据仍归 IAM；测量图片通过 `file_object` 保存文件元数据，并调用 Integration 执行受控重量 OCR。 -- `QualificationFileController`：商户端企业资质文件 -- `PlatformQualificationFileController`：平台端鉴权查看 -- `PlatformExportTaskController`：平台异步导出任务、下载与失败重试 -- `ExportTaskHandler`：业务导出类型扩展点；接入规则见 `docs/公共导出与下载中心接入说明.md` -- `QualificationFileStorage`：存储抽象 -- `LocalQualificationStorage`：当前本地磁盘实现 -- `IamQualificationClient`：校验企业资质访问权限 - -生产环境应把存储实现替换为对象存储或共享文件存储。数据库保存元数据，文件内容不写入 Git，也不依赖应用容器临时目录。 +当前文件内容使用本地或共享磁盘实现，生产环境应演进为对象存储或稳定共享存储。文件内容不写入 Git，也不能依赖应用容器临时目录；入库和测量状态仍归 Firstleg。 ### 5.8 `print/`：打印中心 -当前目录已有独立应用、端口、数据库脚本、公共安全和审计依赖，但业务 Controller 目前只有健康检查。后续应在此目录增加： - -- 打印模板版本管理 -- 打印任务和状态机 -- PDF/标签生成 -- 失败重试和幂等键 -- 打印文件与 File 服务的引用关系 - -订单服务只提交打印请求，不应自己生成面单或直接操作打印机。 +Print 已建立独立服务、端口和数据库边界，当前主要是应用骨架、健康检查和目标表结构。打印模板版本、打印任务、PDF/标签生成、失败重试和与 File 的文件引用仍需按阶段需求继续实现；Order 只提交打印请求，不直接生成面单或操作打印机。 ### 5.9 `audit-service/`：审计日志中心 -通过 `AuditIngestController` 接收审计事件，`AuditIngestService` 处理后写入 `baiyue_audit`。公共模块负责采集和脱敏，本服务负责集中持久化、查询扩展和留存策略。 +公共审计模块负责采集、脱敏和发送，Audit Service 负责集中接收并写入 `baiyue_audit`，后续查询和留存策略也归本服务。审计链路不得记录密码、Token、第三方密钥或未经脱敏的客户敏感数据。 ### 5.10 `integration-service/`：第三方集成中心 -当前包含百度 OCR 和 Amazon Logistics/SP-API 适配器，以及第三方能力状态查询。服务不使用业务数据库，密钥必须通过 Jenkins Credentials、环境变量或 Nacos 密文注入。 +Integration 负责百度 OCR、重量识别和 Amazon Logistics/SP-API 等第三方协议适配及能力状态。二期重量 OCR 由 File 调用，业务图片和入库状态不归 Integration；服务不使用业务数据库，真实外部调用默认关闭，密钥必须通过 Jenkins Credentials、环境变量或 Nacos 密文注入。 ### 5.11 `event-bridge-service/`：跨区域事件桥 -负责接收国内外服务器之间的业务事件，并通过 Inbox 表实现事件去重。它只传输必要业务事件，不共享头程和尾程数据库。事件载荷遵循 `common-event-contract`，应包含事件 ID、来源区域、目标区域、业务键、版本、时间和 Payload 哈希。 +Event Bridge 负责接收国内外服务器之间的必要业务事件，并通过 Inbox 实现幂等。事件载荷遵循 `common-event-contract`，包含事件 ID、来源和目标区域、业务键、版本、时间及 Payload 哈希；头程与尾程不共享 MySQL、Redis、Nacos 或内部接口。 ## 6. 配置、部署和辅助目录 @@ -229,6 +173,8 @@ deploy/ ├─ env/.env.test.example # 环境变量示例 ├─ scripts/deploy-services.sh # Jenkins 增量部署脚本 ├─ docker-compose.yml # 11 个业务服务编排 +├─ docker-compose.rocketmq.yml # 公共导出 RocketMQ 基础设施 +├─ sql/ # 测试/存量环境统一迁移入口与说明 └─ service-map.yml # 模块、JAR、端口映射 ``` @@ -240,6 +186,7 @@ deploy/ - `phase1-business-maturity-regression.ps1`：业务成熟度回归 - `phase1-onboarding-order-e2e.ps1`：企业入驻到订单端到端验证 - `order-warehouse-real-api-regression.ps1`：订单、仓库、往来单位真实 API 回归 +- `export-center-test-env-acceptance.ps1`：公共导出中心测试环境验收 ### `docs/` 与 `reports/` @@ -254,12 +201,16 @@ deploy/ ├─ IAM ── Auth（内部账号管理） ├─ Order ── IAM（企业资格） │ └─ Warehouse（仓库、往来单位） - ├─ Firstleg（履约任务与分配） - ├─ File ── IAM（资质文件鉴权） + ├─ Firstleg（履约、入库、测量审核与计费） + │ ├─ Order（订单货物明细） + │ ├─ Warehouse（托盘、库位预占与占用） + │ └─ File（第三方测量证据图片） + ├─ File + │ ├─ IAM（资质文件鉴权与登记） + │ └─ Integration Service（重量 OCR） ├─ Print └─ 平台内部能力 ├─ Audit Service - ├─ Integration Service └─ Event Bridge Service ── 国外尾程事件入口 ``` @@ -269,11 +220,11 @@ deploy/ 推荐顺序： -1. 外部基础设施：MySQL、Redis、Nacos。 +1. 外部基础设施：MySQL、Redis、Nacos；启用公共导出时再准备 RocketMQ。 2. 核心认证：IAM、Auth。 -3. 业务主数据：Warehouse、File。 -4. 核心业务：Order、Firstleg、Print。 -5. 支撑能力：Audit、Integration、Event Bridge。 +3. 主数据与适配：Warehouse、Integration。 +4. 业务依赖：Order、File。 +5. 核心编排与支撑：Firstleg、Print、Audit、Event Bridge。 6. 最后启动 Gateway。 Nacos 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。 diff --git a/file/AGENTS.md b/file/AGENTS.md index fb5758dd0..18f1778c4 100644 --- a/file/AGENTS.md +++ b/file/AGENTS.md @@ -4,9 +4,10 @@ - File 服务是企业资质文件的唯一公开上传入口。必须先持久化并验证真实文件，再调用 IAM 内部接口登记元数据；禁止只生成或改写一个不存在文件的 URL。 -- 负责企业资质文件的上传、存储、读取和访问鉴权；当前实现只使用本地磁盘，文件内容不进入 Git。 -- `src/main/resources/db/file.sql` 是文件元数据、下载令牌和下载日志的目标表结构，当前代码尚未接入 Entity、Mapper 或 Repository，不能据此判断元数据持久化已实现。 +- 负责企业资质文件、公共导出文件和二期入库测量图片的上传、存储、读取及访问鉴权；当前文件内容使用本地磁盘，不能进入 Git。 +- `src/main/resources/db/file.sql` 中的 `file_object` 已由测量图片链路通过 `FileObjectEntity`、`FileObjectMapper` 接入，导出任务表也已接入；企业资质文件元数据仍归 IAM，不能把不同文件链路的持久化状态混为一谈。 - 企业资质审核状态和元数据归 `iam/`；本模块通过 IAM 客户端校验访问权限，不跨库读取 IAM 数据。 +- 入库单和测量状态归 `firstleg/`，重量识别适配归 `integration-service/`；File 只保存图片对象、返回逻辑文件 ID 并代理受控 OCR 调用。 ## 快速索引 @@ -23,7 +24,11 @@ | 毒消息隔离 | `mq/ExportDlqHandler.java`；定位必须使用四个 User Properties，不解析损坏 body | | 未被当前 Controller 使用的旧实现 | `service/QualificationFileStorage.java` | | IAM 权限协作 | `client/IamQualificationClient.java`；商户登记 `/qualifications`，平台登记/替换 `/platform-qualifications` | -| 目标表结构（尚未接入） | `src/main/resources/db/file.sql` | +| 平台称重图片上传、OCR 重试与查看 | `controller/PlatformMeasurementImageController.java`（`/api/platform/v1/files/measurements`）→ `service/MeasurementImageService.java` | +| Firstleg 第三方测量证据图片 | `controller/InternalMeasurementImageController.java`（`/internal/file/v1/measurement-images`）→ `MeasurementImageService.uploadMeasurementEvidence/deleteMeasurementEvidence`；必须校验内部令牌 | +| 测量图片磁盘与元数据 | `service/MeasurementImageStorage.java`、`entity/FileObjectEntity.java`、`mapper/FileObjectMapper.java`；表结构 `src/main/resources/db/file.sql` | +| 重量 OCR 下游 | `client/WeightOcrClient.java` → `integration-service` 的 `/internal/integrations/weight-ocr/single`；尺寸测量证据不触发重量 OCR | +| 测量图片测试 | `controller/PlatformMeasurementImageControllerContractTest.java`、`InternalMeasurementImageControllerTest.java`、`service/MeasurementImageServiceEvidenceTest.java` | | 历史资质文件迁移 | `../scripts/migrate-local-qualification-file.ps1`、`../docs/企业资质文件迁移说明.md`；只适用于当前本地/共享目录存储实现 | | 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/file-service.yml` | | 上传契约与存储测试 | `src/test/java/com/baiyue/file/controller/QualificationFileContractTest.java`、`service/LocalQualificationStorageTest.java` | @@ -33,7 +38,10 @@ - 严格校验租户、文件名/路径、大小、类型和读取权限，防止目录穿越、越权访问和任意文件上传。 - 企业资质文件只接受 PDF、JPG 和 PNG，单个文件上限 5MB；Client、Admin 与 `LocalQualificationStorage` 的限制和提示必须保持一致。 - 生产存储应使用对象存储或共享文件存储；容器本地目录仅适合当前本地实现，不得硬编码环境路径。 -- 接入元数据持久化时需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller。 +- 企业资质元数据后续若迁入 File，需同时实现 Entity、Mapper、Repository、事务和迁移验证，并同步检查 IAM 资质流程及平台/商户 Controller；不得复用测量图片 `file_object` 的已接入状态宣称资质元数据已迁移。 +- 测量图片必须同时按 `tenantId + inboundId + fileId + businessType` 校验归属。平台称重图片使用 `INBOUND_WEIGHT_IMAGE` 并可调用 OCR；第三方尺寸证据使用 `INBOUND_MEASUREMENT_IMAGE`，只允许内部上传/删除且不得触发重量 OCR。 +- 平台测量图片权限与 Firstleg 权限码保持一致：上传和重试要求 `platform:firstleg:inbound:weight:edit`，查看要求 `platform:firstleg:inbound:measure:view`；内部证据接口只信任共享内部令牌和明确操作人。 +- OCR 失败时保留已落盘文件和 `file_object` 元数据供重试或人工录入；删除第三方证据采用逻辑删除并校验业务类型，不能删除称重图片或其他租户文件。 - 从父目录运行 `mvn -pl file -am test`，并按接口影响验证商户/平台上传、替换、预览、无权限、签名伪造和磁盘故障场景。 - 非本地环境必须显式配置 `FILE_STORAGE_ROOT` 并挂载持久化可写目录；服务启动时会校验目录，存储不可用时直接启动失败，避免健康检查正常而首次上传才返回 HTTP 200 + `S0503`。 - 文件写入失败属于基础设施故障，统一返回 `S0503`，服务日志保留实际目录和底层异常；禁止将磁盘故障包装成 `B0001`。 diff --git a/firstleg/AGENTS.md b/firstleg/AGENTS.md index a6eb59d3b..30c1be11f 100644 --- a/firstleg/AGENTS.md +++ b/firstleg/AGENTS.md @@ -2,8 +2,9 @@ ## 职责边界 -- 负责订单提交后的国内头程履约任务、操作分配和分配历史。 +- 负责订单提交后的国内头程履约任务、操作分配和分配历史，以及二期入库单、测量、审核、FBA 计费、费用发布和完成入库状态编排。 - 订单主单、商户草稿和交易状态属于 `order/`；不要把订单模型复制进本服务。 +- 订单货物明细归 `order/`，托盘和库位资源归 `warehouse/`，图片对象归 `file/`，OCR 供应商适配归 `integration-service/`；本服务只保存业务快照、逻辑引用和自身状态。 ## 快速索引 @@ -20,6 +21,22 @@ | OpenAPI 与测试 | `src/main/resources/openapi/firstleg-v1.yaml`、`service/FulfillmentTaskServiceTest.java`、`controller/FulfillmentTaskControllerContractTest.java`（测试路径均从 `src/test/java/com/baiyue/firstleg/` 起算） | | 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/firstleg-service.yml` | +## 二期入库快速索引 + +以下 Java 包路径从 `src/main/java/com/baiyue/firstleg/` 起算，测试路径从 `src/test/java/com/baiyue/firstleg/` 起算。 + +| 功能 | API 与业务入口 | 持久化、协作与测试 | +|---|---|---| +| 入库单列表、状态页签和聚合详情 | `controller/PlatformInboundOrderController.java` → `service/InboundOrderQueryService.java` | `repository/InboundOrderRepository.java`、`mapper/InboundAllocationQueryMapper.java`；测试 `service/InboundOrderQueryServiceTest.java`、`controller/InboundOrderControllerContractTest.java` | +| 平台测量草稿、提交和重量结果 | `controller/PlatformInboundMeasurementController.java` → `service/InboundMeasurementService.java`、`MeasurementSubmissionService.java` | `repository/InboundMeasurementRepository.java`；图片 `client/MeasurementImageClient.java`，托盘库位 `client/WarehousePalletLocationClient.java`；测试 `service/InboundMeasurementServiceTest.java`、`MeasurementSubmissionServiceTest.java` | +| 第三方尺寸测量回传 | `controller/OpenApiInboundMeasurementController.java` → `security/MeasurementRequestAuthenticator.java` → `service/InboundMeasurementOpenApiService.java` | 货物明细 `client/OrderCargoClient.java`，证据图片 `client/MeasurementImageClient.java`；配置 `config/MeasurementOpenApiProperties.java`；测试 `service/InboundMeasurementOpenApiServiceTest.java`、`controller/OpenApiInboundMeasurementControllerContractTest.java` | +| 测量审核、驳回和异常放行 | `controller/PlatformInboundMeasurementReviewController.java` → `service/MeasurementReviewService.java` | 自动后续流程 `service/AutomaticInboundCompletionService.java`；测试 `service/MeasurementReviewServiceTest.java`、`controller/InboundMeasurementReviewContractTest.java` | +| 客户规则和承运商价格版本 | `controller/PlatformFbaMasterDataController.java` → `service/FbaMasterDataService.java` | `repository/FbaPricingRepository.java`、`src/main/resources/openapi/fba-pricing-v1.yaml`；测试 `service/FbaMasterDataServiceTest.java` | +| 费用计算、确认、发布与快照 | `controller/PlatformFbaPricingController.java` → `service/FbaPricingService.java` | 自动计费和完成入库 `AutomaticInboundCompletionService.java`、`InboundCompletionOrchestrator.java`；测试 `service/FbaPricingServiceTest.java`、`InboundCompletionOrchestratorTest.java` | +| 商户入库费用查询 | `controller/MerchantInboundBillingController.java` → `service/MerchantInboundBillingService.java` | 测试 `service/MerchantInboundBillingServiceTest.java`、`controller/MerchantInboundBillingControllerContractTest.java` | +| 状态、幂等、历史和 Outbox | `domain/InboundProcessStatus.java`、`service/InboundIdempotencyService.java` | `repository/InboundWorkflowRepository.java`、`entity/Inbound*.java`、`mapper/Inbound*.java`；测试 `service/InboundIdempotencyServiceTest.java`、`repository/InboundWorkflowSqlContractTest.java` | +| 二期表结构和增量 | `src/main/resources/db/phase2-inbound-schema.sql`、`phase2-inbound-workflow-migration.sql`、`phase2-inbound-measurement-maintenance.sql`、`phase2-measurement-openapi.sql`、`phase2-third-party-single-measurement-migration.sql`、`phase2-fba-pricing-migration.sql` | 测试/存量环境统一入口为 `../deploy/sql/2026-08-04-二期入库新增表字段-MySQL8一键执行.sql`，执行说明见 `../deploy/sql/README.md` | + ## 修改与验证 - 任务状态与订单状态保持领域分离；需要联动时使用稳定 DTO 或事件，不共享 Order Entity 或数据库。 @@ -28,5 +45,10 @@ - 普通任务不存在、状态冲突和参数错误均遵循 HTTP 200 + body code，平台 Security 拒绝仍保留真实 403。 - 新建库由 `firstleg.sql` 创建查询索引；既有库必须再执行可重复部署的 `phase1-firstleg-task-list-index.sql`，不能只依赖 `CREATE TABLE IF NOT EXISTS`。 - 修改任务查询、状态或分配逻辑时同步扩展 Service 测试和 Controller 契约测试，不以模块构建代替行为验证。 +- 二期入库所有平台查询和写入必须显式校验目标租户；商户费用查询只能使用登录态租户。状态推进、审核、计费和完成入库必须保留乐观锁、幂等键、历史和审计语义。 +- 第三方测量入口必须执行签名、时间窗、防重放和请求哈希校验；一条回传绑定一条订单货物明细及一张 File 证据图片，不得信任第三方直接提交的租户或订单快照。 +- Firstleg 调用 Order、Warehouse、File 的内部接口统一使用共享 `INTERNAL_SERVICE_TOKEN`，只通过客户端 DTO 协作；任何内部接口、Feign DTO 或状态变化都要同步检查被调用模块和契约测试。 +- 测量审核通过后的自动链路依次完成计费、确认、费用发布与入库完成；异常放行必须受配置开关、权限和审核历史共同约束，不能跳过测量门禁直接改状态。 - 从父目录运行 `mvn -pl firstleg -am test`。 - 数据库执行顺序：新库执行 `firstleg.sql`；已有库在此后执行 `phase1-firstleg-task-list-index.sql`，为任务列表、按订单查询和分配历史分页补齐索引。 +- 二期数据库不得只执行单个建表脚本覆盖存量库；测试/存量环境按 `../deploy/sql/README.md` 使用 8 月 4 日统一脚本，并确认末尾核验全部为 `PASS`。 diff --git a/integration-service/AGENTS.md b/integration-service/AGENTS.md index 18603c154..f56b4535a 100644 --- a/integration-service/AGENTS.md +++ b/integration-service/AGENTS.md @@ -4,6 +4,7 @@ - 集中承载百度 OCR、Amazon Logistics/SP-API 等第三方适配器和能力启停状态。 - 不保存业务主数据，不把第三方 DTO 泄漏为内部领域模型；真实外部调用默认关闭，密钥仅从安全配置注入。 +- 二期入库重量 OCR 由 `file/` 调用本服务；Firstleg 只消费 File 返回的识别结果，不直接依赖供应商协议。 ## 快速索引 @@ -12,7 +13,7 @@ | 应用与配置扫描 | `src/main/java/com/baiyue/integration/IntegrationServiceApplication.java` | | `baiyue.integration` 配置 | `config/IntegrationProperties.java` | | 内部供应商状态 API | `controller/IntegrationProviderController.java` | -| 重量 OCR 内部 API | `controller/WeightOcrController.java` | +| 重量 OCR 内部 API | `controller/WeightOcrController.java`；目录批处理 `POST /internal/integrations/weight-ocr/batches`，单图识别 `POST /internal/integrations/weight-ocr/single` | | 能力状态模型与服务 | `dto/ProviderStatus.java`、`service/ProviderStatusService.java` | | 适配器抽象 | `provider/IntegrationProviderAdapter.java` | | 百度 OCR 状态与客户端 | `provider/BaiduOcrAdapter.java`、`provider/ocr/BaiduMeterClient.java` | @@ -20,6 +21,7 @@ | 重量 OCR 批处理 | `service/ocr/WeightOcrBatchService.java` | | 图片裁剪与重量筛选 | `service/ocr/ImageCropper.java`、`service/ocr/WeightCandidateSelector.java` | | OCR 文件访问边界 | `service/ocr/WeightOcrStoragePolicy.java` | +| 二期调用方 | `../file/src/main/java/com/baiyue/file/client/WeightOcrClient.java`、`../file/src/main/java/com/baiyue/file/service/MeasurementImageService.java`；File 负责图片持久化和业务归属，本服务只返回识别结果 | | Amazon | `provider/AmazonLogisticsAdapter.java` | | 内部服务令牌 | `security/InternalServiceTokenGuard.java` | | 配置与 OCR 测试 | `src/test/java/com/baiyue/integration/config/IntegrationPropertiesTest.java`、`src/test/java/com/baiyue/integration/service/ocr/` | @@ -33,4 +35,5 @@ - OCR 目录批处理只能访问 `WEIGHT_OCR_INPUT_ROOT` 和 `WEIGHT_OCR_OUTPUT_ROOT` 内的路径，不得恢复任意服务器路径读取。 - OCR 接口只允许内部服务令牌调用；图片大小、解码像素数、单批数量和并发批次限制不得绕过。 - OCR 原始响应和第三方密钥不得写入应用日志，真实供应商调用必须保持默认关闭。 +- 单图接口只接收 File 传入的受控图片内容，不负责保存 `file_object`、入库单或重量确认记录；响应 DTO 或错误语义变化时同步检查 File 的 `WeightOcrClient`、`MeasurementImageService` 和契约测试。 - 从父目录运行 `mvn -pl integration-service -am test`。 diff --git a/order/AGENTS.md b/order/AGENTS.md index 21a5cf53b..a882c7dc1 100644 --- a/order/AGENTS.md +++ b/order/AGENTS.md @@ -12,6 +12,7 @@ | 商户订单创建、编辑、列表、详情、提交、取消 | `controller/MerchantFirstLegOrderController.java`；列表校验 `merchant:order:list`，详情校验 `merchant:order:view` | | 平台订单列表、详情、审核、接单、开始、完成、取消 | `controller/PlatformFirstLegOrderController.java`；列表和详情校验 `platform:order:list` | | 平台批量客户运单数 | `PlatformFirstLegOrderController.java` 的 `GET /tenant-counts`、`service/OrderApplicationService.countByTenantIds`、`repository/OrderRepository.countByTenantIds`、`dto/TenantOrderCountResponse.java` | +| Firstleg 查询订单货物明细 | `controller/InternalOrderCargoController.java`（`GET /internal/order/v1/cargoes/{tenantId}/{orderId}/{cargoId}`）→ `repository/OrderRepository.findCargo`；契约测试 `controller/InternalOrderCargoControllerTest.java` | | 内部备注与快递信息 | `PlatformFirstLegOrderController.java` | | 核心编排与状态机 | `service/OrderApplicationService.java`、`entity/OrderStatus.java` | | 企业下单资格 | `service/OrderEligibilityGuard.java`、`client/TenantEligibilityClient.java` | @@ -31,6 +32,7 @@ - 客户列表中的真实运单数归 Order，不得写回 IAM。`GET /api/platform/v1/orders/first-leg/tenant-counts?tenantIds=...` 仅允许平台 `platform:order:list`，一次接收 1 至 200 个有效租户 ID，并对没有订单的租户返回 0。 - Warehouse 往来单位已支持多类型；下单校验优先使用 `PartnerClient.Partner.types`，`partnerType` 只作为旧数据兼容。类型语义变化需同步 Warehouse 的 `wh_partner_type`、Order 客户端契约与快照测试。 - 跨服务只通过 `client/` 或事件演进，不跨库查询 IAM/Warehouse；跨域通知优先使用 Outbox。 +- 二期第三方测量绑定订单货物时，Firstleg 只能通过 `InternalOrderCargoController` 校验 `tenantId + orderId + cargoId` 并读取必要快照；该接口必须保留内部令牌校验，不能暴露到 Gateway，也不能返回 Order Entity。 - Order 到 Warehouse 的内部调用使用 Nacos 服务名 `warehouse-service`，不经过 Gateway；只有隔离端口回归显式设置 `WAREHOUSE_SERVICE_URL`。内部接口返回 403 时应将外部响应规范化为 `S0503`，并提示核对内部服务凭证，禁止输出真实令牌。 - 新增状态或动作时同步修改 Controller、Service 状态机、历史记录、DTO、SQL、前端消费者和测试。 - 创建草稿和提交订单必须接收 `Idempotency-Key`；幂等范围按租户、操作者和操作隔离，请求指纹包含资源，并由数据库唯一键保证并发安全。 diff --git a/warehouse/AGENTS.md b/warehouse/AGENTS.md index 5f2f5b830..adb308af7 100644 --- a/warehouse/AGENTS.md +++ b/warehouse/AGENTS.md @@ -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`。