添加AGENTS.md 快速索引
This commit is contained in:
+44
-93
@@ -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 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。
|
||||
|
||||
Reference in New Issue
Block a user