baiyue-firstleg/AGENTS.md

国内头程后端项目指引

适用范围与定位

• 本文件适用于 baiyue-firstleg/ Maven 多模块仓库；进入具体服务后继续读取该服务的 AGENTS.md。
• 本层只负责：服务边界、跨服务契约、数据库部署总入口、阶段路由和通用验证。Controller、Service、DTO、SQL 细节以模块级指引为准。
• 普通任务先读本文件和目标模块指引；聚合构建/架构问题再读 README.md、pom.xml、docs/头程项目目录结构与服务说明.md。

不可突破的产品与数据边界

• 当前产品只有“平台—客户”两级。tenant_id=0 是平台技术作用域；tenant_id>0 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。
• 公共仓库、往来单位、快递、托盘、库位统一归属 tenant_id=0；订单、文件、费用等客户数据按客户 tenant_id>0 隔离。不得跨库 Join 或信任客户端客户 ID。
• 订单交易状态归 order，履约/入库状态归 firstleg，财务账期、账单、收款、成本与核销归 finance，仓储资源归 warehouse，文件对象归 file，OCR 适配归 integration-service；通过内部客户端、DTO 和服务令牌协作。
• 普通业务成功/失败使用 HTTP 200 + body code（成功为字符串 "200"）；认证、基础设施和网关拒绝可使用真实 401/403/503。

服务路由（按关键词定位）

任务关键词	首选服务	先看入口
登录、Token、密码、注册	auth/	auth/AGENTS.md
客户档案、成员、审核、RBAC、授权快照	iam/	iam/AGENTS.md
消息中心、站内通知、消息模板、收件箱	iam/	iam/AGENTS.md，再按 src/main/java/com/baiyue/iam/notification/ 定位；业务事件生产者回到所属服务
订单、货物、快照、状态、幂等、Outbox	order/	order/AGENTS.md
履约分配、入库、测量、审核、FBA 计费	firstleg/	firstleg/AGENTS.md
分柜、柜次、智能排柜、预装/装柜清单、PDA	firstleg/	firstleg/AGENTS.md，再按 split/、loading/、outbound/ 定位
订舱、船期、拖车、报关	firstleg/	oceanbooking/、portschedule/、outbound/dispatch/、customs/
客户账期、费用池、账单、收款、成本、核销	finance/	finance/AGENTS.md；费用来源和柜次成本快照再联查 firstleg/AGENTS.md，凭证再联查 file/AGENTS.md
仓库、往来单位、快递、托盘、库位	warehouse/	warehouse/AGENTS.md
供应商、国内整柜库存与出入库	warehouse/	warehouse/AGENTS.md；OpenAPI warehouse/src/main/resources/openapi/supplier-v1.yaml、domestic-container-v1.yaml
客户运营统计、在途柜量	firstleg/	firstleg/AGENTS.md；OpenAPI firstleg/src/main/resources/openapi/customer-statistics-v1.yaml
平台操作日志与审计查询	audit-service/	audit-service/AGENTS.md；平台查询接口 /api/platform/v1/audit/logs
资质、导出、测量图片、文件下载	file/	file/AGENTS.md
路由、CORS、JWT 入口、访问域	gateway/	gateway/AGENTS.md
百度/Amazon/OCR/第三方适配	integration-service/	integration-service/AGENTS.md
PDF 标签、审计、事件	print/、audit-service/、event-bridge-service/	各服务指引

全量验收路由

• 当前一期、二期、三期及财务统一进入全量验收；按本次链路读取对应阶段/专题文档，不以历史阶段终点阻断跨服务联调或回归。
• auth、iam、warehouse、order、firstleg、file、finance、integration-service 及出仓相关能力按各自模块契约协作；状态、权限、数据库和 OpenAPI 以当前实现及已确认契约为准。

契约、数据库与验证入口

• 跨服务修改先检查调用方 client/、被调用方 Controller/DTO、src/main/resources/openapi/ 和双方契约测试；禁止共享领域 Entity。
• 平台后台存在正式列表页时，*:list 同时授权列表、详情及只读辅助接口；create、edit、delete、status、approve、review、export、upload、complete 等操作保持独立。当前未上线，不兼容旧独立 *:view，Controller 不得使用 hasAnyAuthority(list, view)，OpenAPI 和角色初始化只保留 *:list。
• 供应商查询接口固定只使用 platform:supplier:list；IAM 中 platform:supplier:list 是正式菜单资源，platform:supplier:view 必须停用/移除，不得重新提升或兼容。
• 权限语义变更必须同步 Controller @PreAuthorize、OpenAPI、模块权限 SQL、IAM 菜单资源、统一增量脚本和契约测试。并行模块任务不得覆盖菜单与权限总控已写入共享 SQL 或权限契约的改动。
• 数据库只访问所属服务库。模块迁移位于 <module>/src/main/resources/db/；测试/存量环境唯一部署入口是 deploy/sql/头程数据库统一增量-MySQL8.sql，说明见 deploy/sql/README.md，历史日期脚本仅追溯。
• 通用配置在 config/nacos/{local,cn}/；服务日志、上传文件、target/、reports/ 不属于源码。
• 全量验证：mvn -DskipTests validate、mvn test；单服务优先 mvn -pl <module> -am test。不要在本地启动 Java/Nacos/数据库，除非用户明确要求。

全量 HTTP 验收脚本路由

• 全量验收唯一指向测试环境 HTTP：平台端执行 scripts/admin-test-env-acceptance.mjs，客户端执行 scripts/client-test-env-acceptance.mjs；二期兼容场景才单独执行 scripts/client-phase2-test-env-acceptance.mjs。
• Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 --modules <name>，模块名称和静态合同先查 scripts/admin-test-env-modules/README.md。
• 这些脚本会创建、更新或最终停用测试数据，必须在当前对话明确授权测试环境验收后执行，并保存 JSON 报告；未授权不得请求 Gateway。
• 后端 Maven、前端 pnpm test/typecheck、PDA node --test 和数据库 Dry-run 都是本地质量检查，不属于全量 HTTP 验收。
• HTTP 全量通过后，才进入 Admin/Client 真实页面调用、浏览器样式和 PDA 页面/设备验收；自动化 HTTP 通过不代表视觉验收完成。

阶段文档入口

• 一期：../docs/一期/README.md、../docs/一期/一期头程订单闭环设计.md
• 二期：../docs/二期/README.md、../docs/二期/二期需求优化版-v2-测量计费入库主流程.md、需求确认清单及联调报告
• 三期：../docs/三期/README.md、../docs/三期/三期开工门禁.md、../docs/三期/三期开发规划.md、../docs/三期/三期需求确认表.md、页面与原型清单
• 财务：../docs/财务管理/README.md 中已确认的范围、对象、状态和接口约束

全量验收任务再读取对应阶段进度表、验收报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。