优化

AGENTS.md

@@ -85,6 +85,16 @@
 - 上表中的 `模块/.../` 从对应模块的 `src/main/java/com/baiyue/<domain>/` 起算；二期链路跨 `order`、`firstleg`、`warehouse`、`file`、`integration-service`，修改 DTO、内部令牌、状态或表结构时必须逐个检查调用方与被调用方。
 - 二期入库主状态归 `firstleg`，订单货物主数据仍归 `order`，托盘/库位资源归 `warehouse`，文件对象归 `file`，OCR 供应商适配归 `integration-service`；禁止通过跨库查询绕过内部 API。
 
+## 一期/二期/三期后端阶段索引
+
+| 阶段 | 后端边界与入口 | 开始工作前阅读 | 状态边界 |
+|---|---|---|---|
+| 一期：头程订单闭环 | `auth/` 登录与账号、`iam/` 客户/RBAC/资质审核、`warehouse/` 公共仓与主数据、`order/` 订单主数据、`firstleg/` 履约任务、`file/` 资质文件 | `../docs/一期/README.md` → `../docs/一期/一期开发进度表.md` → `../docs/一期/一期头程订单闭环设计.md`；再读目标模块 `AGENTS.md`、Controller/DTO/OpenAPI 与迁移脚本 | 客户审核与必填资质通过后才具备下单资格；订单状态由 `order/` 主导，履约分配由 `firstleg/` 主导；不得把二期入库状态回写为一期订单状态 |
+| 二期：到仓与头程计费 | `firstleg/` 入库、测量、审核、FBA 计费与完成编排；`warehouse/` 托盘/库位预占占用；`file/` 测量图片；`order/` 仅提供货物内部查询；`integration-service/` OCR | `../docs/二期/README.md` → `../docs/二期/二期需求优化版-v2-测量计费入库主流程.md` → `../docs/二期/二期V2需求确认清单.md`/`二期计费财务需求确认表.md` → 联调报告；旧 `二期开发进度表.md` 仅作历史参考 | 当前技术验收终点为 `WAIT_SPLIT + APPROVED + CONFIRMED`；`WAIT_SPLIT` 等待三期分柜，二期不得实现分柜、装柜、PDA 或完整财务应收应付 |
+| 三期：国内出仓 | 当前 NO-GO；待契约确认后再进入 `order/`、`firstleg/`、`warehouse/`、`file/` 的出仓扩展，并与 PDA/外部接口协作 | `../docs/三期/README.md` → `../docs/三期/三期开发规划.md` → `../docs/三期/三期需求确认表.md` → `../docs/三期/三期开发进度表.md`、`../docs/三期/三期页面与原型清单.md`；先解除 P3-Q1/Q2/Q5/Q9/Q11/Q12/Q13 | 阶段终点为国内出仓、等待装船；确认项未解除前不得把复用接口或原型当作正式三期契约 |
+
+跨阶段修改必须先锁定 `order`/`firstleg` 状态机归属，再同步检查 `warehouse`、`file`、`auth`、`iam` 的内部 DTO、权限码、令牌和数据库增量；不得跨库读取或跳过内部 API。
+
 ## 配置、数据库与验证入口
 
 - 服务本地配置在各模块 `src/main/resources/application.yml`；Nacos 环境配置集中在 `config/nacos/local/` 和 `config/nacos/cn/`。
@@ -96,8 +106,7 @@
 - 本地环境切换看 `docs/数据库环境切换说明.md`、`scripts/local-env.ps1` 与 `config/nacos/local/`；接口契约优先读目标模块 `src/main/resources/openapi/` 和 Controller，回归入口在 `scripts/`，历史资质文件迁移使用 `scripts/migrate-local-qualification-file.ps1`。
 - 平台管理与头程履约补齐的本地数据库只读核验、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 日最终增量入口。
+- 测试环境数据库增量统一从 `deploy/sql/头程数据库统一增量-MySQL8.sql` 执行，执行边界与末尾核验方式见 `deploy/sql/README.md`；历史日期脚本只用于追溯，不能作为当前部署入口。
 - CI 总控入口是 `Jenkinsfile`，负责按变更或勾选项并行调度 11 个独立服务 Job；单服务构建、镜像与部署逻辑在 `Jenkinsfile.service`。Job 名必须以模块名结尾，公共模块或 `deploy/` 变化会触发全部服务。
 - 从本目录运行全量校验：`mvn -DskipTests validate`、`mvn test`。单模块修改优先运行 `mvn -pl <module> -am test`。
 - 公共导出中心测试环境真实任务验收使用 `scripts/export-center-test-env-acceptance.ps1`；脚本只调用 Gateway，不负责部署或停止 Broker/File/IAM，故障注入由有权限的运维配合。