56 lines
5.5 KiB
Markdown
56 lines
5.5 KiB
Markdown
# 国内头程后端项目指引
|
||
|
||
## 适用范围与定位
|
||
|
||
- 本文件适用于 `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` |
|
||
| 资质、导出、测量图片、文件下载 | `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` 仅在各自契约需要时协作。未冻结的字段、权限、迁移或跨服务调用只阻断对应模块。
|
||
- 财务：作为跨阶段独立业务域，范围先读 `../docs/财务管理/README.md` 中已确认的产品结论与契约；`finance` 保存财务状态，`firstleg` 只提供不可变费用来源和柜次成本快照，`file` 保存收付款/成本凭证。不要把财务范围反向并入二期计费或三期履约。
|
||
|
||
## 契约、数据库与验证入口
|
||
|
||
- 跨服务修改先检查调用方 `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`、页面与原型清单
|
||
- 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束
|
||
|
||
进度、排期、负责人或验收状态问题再读取阶段进度表和验收报告；普通开发定位只使用范围、契约、模块指引和当前代码。
|