289 lines
20 KiB
Markdown
289 lines
20 KiB
Markdown
# 头程项目目录结构与服务说明
|
||
|
||
## 文档定位与读取时机
|
||
|
||
本文是面向架构理解和运维协作的服务总览，主要说明技术基线、目录结构、服务端口、数据库归属、调用关系和启动部署拓扑。
|
||
|
||
- 普通单模块开发不需要预先通读本文；先读仓库根 `AGENTS.md` 和目标模块 `AGENTS.md`。
|
||
- 涉及跨服务设计、模块拆分、端口或数据库归属、根目录调整、本地启动和部署拓扑时再读本文。
|
||
- Controller、Service、SQL、测试和当前实现入口以各级 `AGENTS.md` 与代码为准；本文不维护文件级快速索引，避免与执行指引重复和漂移。
|
||
|
||
## 1. 项目定位
|
||
|
||
`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 23 个 Maven 模块，其中 7 个是公共/依赖模块，16 个是可独立启动、构建、制作镜像的微服务。
|
||
|
||
当前技术基线：
|
||
|
||
- Java 17、Spring Boot 3.2.9
|
||
- Spring Cloud 2023.0.3、Spring Cloud Alibaba 2023.0.3.2
|
||
- Nacos 注册与配置中心
|
||
- Spring Cloud Gateway 统一入口
|
||
- MyBatis-Plus、MySQL
|
||
- Redis 登录会话校验
|
||
- Spring Security、JWT
|
||
- SpringDoc OpenAPI / Swagger
|
||
- GitLab、Jenkins、Docker Compose
|
||
|
||
国内与海外服务共享源码仓库和公共制品，但保持独立数据库、Nacos 命名空间与部署边界；跨区域业务协作使用版本化 Outbox/Inbox 事件，不共享业务数据源。
|
||
|
||
## 2. 根目录结构
|
||
|
||
```text
|
||
baiyue-firstleg/
|
||
├─ platform-bom/ # 公共依赖版本清单
|
||
├─ common-core/ # 统一返回、错误码、基础实体、MyBatis-Plus
|
||
├─ common-web/ # Web 通用能力、全局异常、请求链路标识
|
||
├─ common-security/ # JWT、Redis 会话、鉴权异常处理
|
||
├─ common-openapi/ # Swagger / OpenAPI 自动配置
|
||
├─ common-audit/ # 业务审计注解、切面、脱敏和发送能力
|
||
├─ common-event-contract/ # 国内外跨区域事件统一契约
|
||
│
|
||
├─ gateway/ # 统一 API 网关
|
||
├─ gateway-overseas/ # 海外区域 API 网关
|
||
├─ auth/ # 统一登录与账号凭据
|
||
├─ iam/ # 租户、成员、角色、权限、企业审核
|
||
├─ order/ # 头程订单中心
|
||
├─ firstleg/ # 履约任务、二期入库、测量与计费
|
||
├─ warehouse/ # 仓库主数据、托盘与库位资源
|
||
├─ finance/ # 财务账期、账单、收付款与核销
|
||
├─ lastleg-service/ # 海外尾程、入仓、库存与本土业务
|
||
├─ warehouse-overseas-service/ # 海外仓库、库位、托盘与资源锁
|
||
├─ overseas-security-service/ # 海外IAM安全事件Inbox、投影与实时校验
|
||
├─ file/ # 资质、导出与测量图片文件中心
|
||
├─ print/ # 打印中心
|
||
├─ audit-service/ # 审计日志中心
|
||
├─ integration-service/ # 第三方平台集成适配
|
||
├─ event-bridge-service/ # 国内外跨区域事件接收桥
|
||
│
|
||
├─ config/ # Nacos 配置模板
|
||
├─ deploy/ # Jenkins、Docker 使用的部署文件
|
||
├─ docs/ # 架构、接口、测试和部署文档
|
||
├─ scripts/ # 本地启动、配置发布和回归脚本
|
||
├─ reports/ # 回归测试结果，不属于业务源码
|
||
│
|
||
├─ pom.xml # Maven 聚合父工程
|
||
├─ Jenkinsfile # 多服务增量构建和部署流水线
|
||
├─ .gitlab-ci.yml # GitLab 校验与打包流水线
|
||
├─ docker-compose-infra.yml # 本地基础设施编排
|
||
├─ .gitignore # Git 忽略规则
|
||
├─ .gitattributes # Git 文本和换行规则
|
||
└─ README.md # 仓库入口说明
|
||
```
|
||
|
||
`target/`、`.idea/`、运行日志、上传文件和本地 `.env` 都不是源码，不应提交到 Git。
|
||
|
||
## 3. 公共模块说明
|
||
|
||
| 文件夹 | Maven artifactId | 主要职责 | 使用边界 |
|
||
| --- | --- | --- | --- |
|
||
| `platform-bom` | `baiyue-platform-bom` | 集中管理公共组件版本 | 只管理版本，不放业务代码 |
|
||
| `common-core` | `baiyue-common-core` | `ApiResponse`、`PageResult`、`ResultCode`、`BizException`、基础实体和 MyBatis-Plus 配置 | 不调用具体业务服务 |
|
||
| `common-web` | `baiyue-common-web` | 统一异常处理、请求 ID 和链路上下文 | 不存放具体 Controller |
|
||
| `common-security` | `baiyue-common-security` | JWT 解码、认证过滤器、Redis Token 会话校验、401/403 JSON 返回 | 负责通用鉴权，不负责角色业务维护 |
|
||
| `common-openapi` | `baiyue-common-openapi` | SpringDoc 分组和 Swagger 自动配置 | 只提供文档能力 |
|
||
| `common-audit` | `baiyue-common-audit` | `@BusinessAudit`、审计切面、敏感数据脱敏、HTTP/日志审计输出 | 审计持久化由 `audit-service` 负责 |
|
||
| `common-event-contract` | `common-event-contract` | 事件信封、事件类型、区域编码、幂等标识、Payload 哈希和校验 | 只放稳定跨区域契约，不放头程领域实体 |
|
||
|
||
公共模块只能提供技术能力和稳定契约。订单、仓库、权限等业务实体不能放入公共模块，否则后续服务会再次耦合成单体。
|
||
|
||
## 4. 可运行服务总览
|
||
|
||
| 文件夹 | 注册服务名 | 端口 | 数据库 | 当前职责与实现情况 |
|
||
| --- | --- | ---: | --- | --- |
|
||
| `gateway` | `gateway` | 9000 | 无 | 统一路由、CORS、JWT/Redis 会话校验、商户端与平台端访问域隔离、Swagger 聚合 |
|
||
| `gateway-overseas` | `gateway-overseas` | 9300 | 无 | 海外区域 API 入口、海外 Audience/JWKS 校验及海外服务路由 |
|
||
| `auth` | `auth-service` | 9100 | `baiyue_auth` | 登录、刷新 Token、退出、商户注册、账号密码和账号内部管理 |
|
||
| `iam` | `iam-service` | 9201 | `baiyue_iam` | 租户、企业资料、企业审核、成员、角色、权限、按钮权限、个人资料和授权快照 |
|
||
| `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` | 企业资质文件、公共异步导出下载、入库测量图片及重量 OCR 调用协作 |
|
||
| `print` | `print-service` | 9207 | 无 | 无状态 PDF 渲染服务；调用方传入完整标签数据，服务在内存中生成一次性多页 PDF |
|
||
| `integration-service` | `integration-service` | 9210 | 无 | 百度 OCR、Amazon SP-API 等第三方适配器和启停状态；默认关闭外部调用 |
|
||
| `lastleg-service` | `lastleg-service` | 9303 | `baiyue_lastleg` | 海外尾程订单、接柜入仓、库存与海外本土业务；不含海外出库和派送 |
|
||
| `warehouse-overseas-service` | `warehouse-overseas-service` | 9305 | 海外仓资源库 | 海外仓库、库位、托盘和资源锁 |
|
||
| `overseas-security-service` | `overseas-security-service` | 9307 | `baiyue_overseas_security` | IAM安全事件可靠Inbox、单调投影及海外Token即时失效校验 |
|
||
| `event-bridge-service` | `event-bridge-service` | 9312 | `baiyue_event_bridge` | 按 CN/OVERSEAS 双实例部署的跨区事件 Inbox、重试和目标服务投递 |
|
||
| `audit-service` | `audit-service` | 9700 | `baiyue_audit` | 接收公共审计事件并持久化；平台端可按权限查询已脱敏日志，业务审计发送默认开启 |
|
||
|
||
MySQL、Redis、Nacos 是外部基础设施，不属于上述业务服务，也不应打包进业务镜像。
|
||
|
||
## 5. 各服务文件夹说明
|
||
|
||
### 5.1 `gateway/`：统一入口
|
||
|
||
Gateway 负责统一路由、CORS、入口认证、可信身份头和 Swagger 聚合。前端只访问 Gateway，不直接暴露业务服务端口；业务服务仍需执行租户、访问域、数据范围和按钮权限校验，不能把网关认证视为最终授权。
|
||
|
||
### 5.2 `auth/`：统一登录与账号凭据
|
||
|
||
Auth 负责登录、Token 生命周期、商户注册协作、账号密码和账号状态。密码散列、登录失败锁定和刷新 Token 属于 Auth；成员资料、角色、权限和企业审核属于 IAM，两者通过内部接口协作，不共享数据库。
|
||
|
||
### 5.3 `iam/`：租户、成员和权限中心
|
||
|
||
IAM 负责租户、企业资料与审核、成员、平台用户、角色、菜单、按钮权限、数据范围和授权快照。它以 `tenant_id` 为核心隔离维度，并区分商户端与平台后台访问域；权限必须由后端校验，不能只依赖前端隐藏按钮。
|
||
|
||
### 5.4 `order/`：订单中心
|
||
|
||
Order 负责订单草稿、提交、平台处理状态、货物、参与方和主数据快照、状态历史、内部备注、幂等记录与 Outbox。订单保存关键业务快照，Warehouse 或往来单位后续变化不能改写历史订单。
|
||
|
||
企业资格和仓库主数据通过 IAM、Warehouse 内部接口校验；Firstleg 查询订单货物明细也通过受保护的内部接口完成。服务之间不建立跨库外键或跨库查询，通知优先通过 Outbox 和事件演进。
|
||
|
||
### 5.5 `firstleg/`：头程履约中心
|
||
|
||
Firstleg 承担订单提交后的履约任务、操作分配与历史，以及二期入库单查询、测量回传、人工测量、审核、异常放行、FBA 计费、费用发布和完成入库状态编排。
|
||
|
||
订单主单和货物主数据仍属于 Order；托盘和库位资源属于 Warehouse；图片对象属于 File；OCR 供应商协议属于 Integration。Firstleg 只保存自身业务状态、快照和逻辑引用，通过内部 DTO 调用其他服务，不复制对方领域模型。
|
||
|
||
### 5.6 `warehouse/`：仓库与仓储资源
|
||
|
||
Warehouse 负责仓库、地址、服务能力、往来单位、快递公司，以及二期托盘、库位、预占和占用资源。往来单位只是 Warehouse 下的主数据配置，保存在 `baiyue_warehouse.wh_partner`，不创建独立服务和数据库。
|
||
|
||
Firstleg 通过内部接口发起托盘库位预占、确认和释放，只保存逻辑引用与入库快照。容量、共享溢出、预占和占用一致性由 Warehouse 的数据库事务和条件更新最终保证。
|
||
|
||
### 5.7 `file/`：文件中心
|
||
|
||
File 负责企业资质文件、公共异步导出与下载、入库称重图片和第三方测量证据。企业资质审核及其业务元数据仍归 IAM；测量图片通过 `file_object` 保存文件元数据，并调用 Integration 执行受控重量 OCR。
|
||
|
||
当前文件内容使用本地或共享磁盘实现，生产环境应演进为对象存储或稳定共享存储。文件内容不写入 Git，也不能依赖应用容器临时目录；入库和测量状态仍归 Firstleg。
|
||
|
||
### 5.8 `print/`：打印中心
|
||
|
||
Print 是无数据库的无状态 PDF 渲染服务。业务归属服务完成权限和数据真实性校验，组装完整 `labels[]` 后通过内部令牌调用 Print；Print 只在内存中生成一次性多页 PDF 并同步返回。本服务不保存模板、任务、历史或文件，不调用 File，不连接打印机，也不提供二次下载地址。
|
||
|
||
业务服务接入时先读 `print/README.md`，机器可读契约以 `print/src/main/resources/openapi/print-internal-v1.yaml` 为准。
|
||
|
||
### 5.9 `audit-service/`：审计日志中心
|
||
|
||
公共审计模块负责采集、脱敏和发送，Audit Service 负责集中接收并写入 `baiyue_audit`。平台端使用 `GET /api/platform/v1/audit/logs` 和 `GET /api/platform/v1/audit/logs/{id}` 查询，需具备 `platform:audit:list` 权限；列表不返回变更快照，详情仅返回已脱敏快照。审计链路不得记录密码、Token、第三方密钥或未经脱敏的客户敏感数据。
|
||
|
||
### 5.10 `integration-service/`：第三方集成中心
|
||
|
||
Integration 负责百度 OCR、重量识别和 Amazon Logistics/SP-API 等第三方协议适配及能力状态。二期重量 OCR 由 File 调用，业务图片和入库状态不归 Integration；服务不使用业务数据库，真实外部调用默认关闭，密钥必须通过 Jenkins Credentials、环境变量或 Nacos 密文注入。
|
||
|
||
### 5.11 `event-bridge-service/`：跨区域事件桥
|
||
|
||
Event Bridge 负责接收国内外服务器之间的必要业务事件，并通过 Inbox 实现幂等。事件载荷遵循 `common-event-contract`，包含事件 ID、来源和目标区域、业务键、版本、时间及 Payload 哈希；头程与尾程不共享 MySQL、Redis、Nacos 或内部接口。
|
||
|
||
头程装柜完成事件以实际集装箱为顶层批次，`orders[]` 中每项是一张实际发运的来源入仓单；一个柜可包含多张入仓单。每个货物明细携带来源明细 ID、实际装运箱数和完整的国内箱唛池。国内不要求在装柜时逐箱扫描冻结，完整箱唛池可以大于本柜实际装运箱数；海外按实际首次扫描的箱唛确认归属和实收，未扫描箱唛保留给后续子订单。海外将同柜各来源入仓单分别生成入库计划，但以同一集装箱号关联，并且只允许同一目的仓的箱子合托。
|
||
|
||
## 6. 配置、部署和辅助目录
|
||
|
||
### `config/`
|
||
|
||
```text
|
||
config/nacos/
|
||
├─ local/ # 本地联调配置
|
||
└─ cn/ # 国内服务器配置模板
|
||
```
|
||
|
||
`local/`、`cn/`、`overseas/` 按部署区域保存公共配置和该区域需要的服务配置。配置模板可以提交，真实密码和第三方密钥不能提交。
|
||
|
||
### `deploy/`
|
||
|
||
```text
|
||
deploy/
|
||
├─ docker/Dockerfile # 通用 Java 17 镜像
|
||
├─ env/.env.test.example # 环境变量示例
|
||
├─ scripts/deploy-services.sh # Jenkins 增量部署脚本
|
||
├─ docker-compose.yml # 国内区域服务编排
|
||
├─ docker-compose.overseas.yml # 海外区域服务编排
|
||
├─ docker-compose.rocketmq.yml # 公共导出 RocketMQ 基础设施
|
||
├─ sql/ # 测试/存量环境统一迁移入口与说明
|
||
└─ service-map.yml # 模块、JAR、端口映射
|
||
```
|
||
|
||
### `scripts/`
|
||
|
||
- `local-env.ps1`：本地服务环境变量
|
||
- `publish-local-nacos-config.ps1`：发布本地 Nacos 配置
|
||
- `phase1-acceptance.ps1`：一期验收入口
|
||
- `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/`
|
||
|
||
`docs/` 保存长期有效的架构、数据库、接口、部署与验收说明。`reports/` 保存某一次测试执行结果，可以用于追踪联调结论，但不能替代长期文档。
|
||
|
||
## 7. 主要调用关系
|
||
|
||
```text
|
||
前端
|
||
└─ Gateway
|
||
├─ Auth ── IAM（授权快照、企业注册）
|
||
├─ IAM ── Auth（内部账号管理）
|
||
├─ Order ── IAM（企业资格）
|
||
│ └─ Warehouse（仓库、往来单位）
|
||
├─ Firstleg（履约、入库、测量审核与计费）
|
||
│ ├─ Order（订单货物明细）
|
||
│ ├─ Warehouse（托盘、库位预占与占用）
|
||
│ └─ File（第三方测量证据图片）
|
||
├─ File
|
||
│ ├─ IAM（资质文件鉴权与登记）
|
||
│ └─ Integration Service（重量 OCR）
|
||
├─ Print
|
||
└─ 平台内部能力
|
||
├─ Audit Service
|
||
└─ Event Bridge Service ── 国外尾程事件入口
|
||
```
|
||
|
||
服务间优先使用 Nacos 服务发现。跨区域通信只走事件桥或明确的公网契约，不直接调用对方内部接口，不共享 MySQL、Redis 或 Nacos。
|
||
|
||
## 8. 本地启动顺序
|
||
|
||
推荐顺序：
|
||
|
||
1. 外部基础设施：MySQL、Redis、Nacos；启用公共导出时再准备 RocketMQ。
|
||
2. 核心认证：Auth、IAM。
|
||
3. 主数据与适配：Warehouse、Integration。
|
||
4. 业务依赖：Order、File。
|
||
5. 核心编排与支撑：Firstleg、Print、Audit、Event Bridge。
|
||
6. 最后启动 Gateway。
|
||
|
||
Nacos 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。
|
||
|
||
### Auth/IAM RBAC 会话撤销发布验证
|
||
|
||
角色启停或角色权限全量变更会由 IAM 调用 Auth 的
|
||
`POST /internal/auth/accounts/sessions/revoke`，批量撤销受影响成员的 Access/Refresh 会话。
|
||
该契约发布时必须先部署 Auth，再部署 IAM，不得只更新 IAM。
|
||
|
||
发布后至少完成以下验证：
|
||
|
||
1. 确认 Auth、IAM 使用同一提交对应的镜像版本，且 IAM 能通过服务发现和内部服务令牌访问上述 Auth 内部接口；404、连接失败、内部令牌不一致或非成功业务码均不得放行 IAM 角色变更。
|
||
2. 为测试成员分配带订单查看权限的自定义角色，成员登录并确认订单列表可访问。
|
||
3. 停用该角色必须返回业务成功；继续使用停用前的 Access Token 访问订单列表必须被拒绝，旧 Refresh Token 也必须失效。
|
||
4. 成员重新登录后权限集合应为空；重新启用角色并再次登录后，原角色权限应恢复。
|
||
5. 修改角色权限集合后重复验证旧 Access/Refresh Token 失效，避免 `grantPermissions` 路径遗留旧权限。
|
||
|
||
2026-08-08 测试环境曾出现版本不一致：停用已分配角色返回 HTTP 200、业务码 `S0503`，
|
||
提示“认证会话撤销失败，角色变更未生效”。证据报告为
|
||
`reports/client-test-env-20260808021636-b5090589.json`，`requestId=client-e2e-d9e860c8-b061-43fd-b67b-196f76d95b3d`，
|
||
`traceId=f2812578869349b1b4393421498d05df`。该结果说明 IAM 已包含会话撤销调用，但 Auth
|
||
内部接口尚未部署或不可达；必须在 Auth 先行部署并通过连通性检查后重新执行上述验收。
|
||
|
||
本轮 Client 扩展测试的发布前最终基准为
|
||
`reports/client-test-env-20260808022313-1798dc6c.json`：共 150 项，143 通过、5 失败、2 跳过。
|
||
5 个阻断项分别为角色停用和角色权限收缩时 Auth/IAM 版本不一致导致 `S0503`、清空成员角色未撤销旧 JWT、
|
||
缺少 `Idempotency-Key` 返回 `S0500`、跨客户资质文件读取返回 `B0001`。订单条件必填 `A0422`、
|
||
已提交订单编辑 `A0409`、密码恢复和报告脱敏均已通过。后续发布验证应以该报告为对照，确认上述 5 项全部关闭。
|
||
|
||
部署完成后的最终验收报告为 `reports/client-test-env-20260808032107-59bca758.json`：
|
||
163 项全部通过，0 失败、0 跳过，`success=true`。发布前 5 个失败项和 2 个依赖跳过项均已关闭，
|
||
包括角色停用、角色权限收缩和成员角色清空后的旧会话撤销，缺少 `Idempotency-Key` 返回 `A0400`，
|
||
以及跨客户资质文件读取返回 `A0404`。角色停用后，旧 Token 查询实时权限也必须返回
|
||
HTTP 401 / `A0401`，不得再按 HTTP 200 + 空权限处理；只有使用新会话查询停用角色的有效权限时才返回空集合。
|
||
账号原密码恢复和报告脱敏检查同时通过。本报告作为本轮 Client 全量 HTTP 验收的最终通过基线。
|
||
|
||
## 9. 开发和拆分约束
|
||
|
||
- 每个业务服务只访问自己的数据库；禁止跨库 Join 和直接读取其他服务表。
|
||
- 所有商户业务数据必须带租户维度，并在后端执行租户隔离。
|
||
- 平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
|
||
- Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
|
||
- 服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
|
||
- 公共模块变化会影响多个服务，Jenkins 会按 `service-map.yml` 覆盖的全部 16 个服务执行受影响构建。
|
||
- 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
|
||
- 国内头程与海外仓共享 Git 仓库，但保持两套数据库、Nacos 命名空间和部署环境。
|