4.6 KiB
4.6 KiB
国内头程后端项目指引
适用范围与定位
- 本文件适用于
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，仓储资源归warehouse，文件对象归file，OCR 适配归integration-service；通过内部客户端、DTO 和服务令牌协作。 - 普通业务成功/失败使用 HTTP 200 + body
code（成功为字符串"200"）；认证、基础设施和网关拒绝可使用真实 401/403/503。
服务路由（按关键词定位）
| 任务关键词 | 首选服务 | 先看入口 |
|---|---|---|
| 登录、Token、密码、注册 | auth/ |
auth/AGENTS.md |
| 客户档案、成员、审核、RBAC、授权快照 | iam/ |
iam/AGENTS.md |
| 订单、货物、快照、状态、幂等、Outbox | order/ |
order/AGENTS.md |
| 履约分配、入库、测量、审核、FBA 计费 | firstleg/ |
firstleg/AGENTS.md |
| 分柜、柜次、智能排柜、预装/装柜清单、PDA | firstleg/ |
firstleg/AGENTS.md，再按 split/、loading/、outbound/ 定位 |
| 订舱、船期、拖车、报关 | firstleg/ |
oceanbooking/、portschedule/、outbound/dispatch/、customs/ |
| 仓库、往来单位、快递、托盘、库位 | warehouse/ |
warehouse/AGENTS.md |
| 资质、导出、测量图片、文件下载 | 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完成登录、客户/RBAC、公共仓、订单闭环；先读../docs/一期/README.md及闭环设计。 - 二期：
firstleg主导入库/测量/审核/计费，warehouse管托盘库位，file管测量图片，integration-service管 OCR，order仅提供货物内部查询；终点为WAIT_SPLIT + APPROVED + CONFIRMED，不实现分柜、装柜、PDA 和完整财务。 - 三期：已确认范围可按
../docs/三期/三期开工门禁.md进入契约和模块实现。firstleg负责履约编排、柜次、排柜、订舱、拖车、PDA 与LOADED门禁；order、warehouse、file、iam、gateway和integration-service仅在各自契约需要时协作。未冻结的字段、权限、迁移或跨服务调用只阻断对应模块。
契约、数据库与验证入口
- 跨服务修改先检查调用方
client/、被调用方 Controller/DTO、src/main/resources/openapi/和双方契约测试；禁止共享领域 Entity。 - 数据库只访问所属服务库。模块迁移位于
<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/数据库，除非用户明确要求。
阶段文档入口
- 一期：
../docs/一期/README.md、../docs/一期/一期头程订单闭环设计.md - 二期：
../docs/二期/README.md、../docs/二期/二期需求优化版-v2-测量计费入库主流程.md、需求确认清单及联调报告 - 三期：
../docs/三期/README.md、../docs/三期/三期开工门禁.md、../docs/三期/三期开发规划.md、../docs/三期/三期需求确认表.md、页面与原型清单
进度、排期、负责人或验收状态问题再读取阶段进度表和验收报告；普通开发定位只使用范围、契约、模块指引和当前代码。