baiyue-firstleg/docs/头程项目目录结构与服务说明.md

# 头程项目目录结构与服务说明

## 文档定位与读取时机

本文是面向架构理解和运维协作的服务总览，主要说明技术基线、目录结构、服务端口、数据库归属、调用关系和启动部署拓扑。

- 普通单模块开发不需要预先通读本文；先读仓库根 `AGENTS.md` 和目标模块 `AGENTS.md`。
- 涉及跨服务设计、模块拆分、端口或数据库归属、根目录调整、本地启动和部署拓扑时再读本文。
- Controller、Service、SQL、测试和当前实现入口以各级 `AGENTS.md` 与代码为准；本文不维护文件级快速索引，避免与执行指引重复和漂移。

## 1. 项目定位

`baiyue-firstleg` 是国内头程与海外仓后端仓库，采用 Maven 多模块单仓结构。根 POM 聚合 20 个 Maven 模块，其中 7 个是公共/依赖模块，13 个是可独立启动、构建、制作镜像的微服务。

当前技术基线：

- 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

当前源码与发布清单统一为 TEST 单机、一个 Gateway/Auth 会话和 Nacos 命名空间；业务服务保留独立 Schema，可靠事件使用 Outbox 直接投递及消费幂等。真实环境切换仍待验收，不能把本地配置视为已部署。

## 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/             # 退役待清理，不参与构建/发布
├─ auth/                         # 统一登录与账号凭据
├─ iam/                          # 租户、成员、角色、权限、企业审核
├─ order/                        # 头程订单中心
├─ firstleg/                     # 履约任务、入库、测量与计费
├─ warehouse/                    # 仓库主数据、托盘与库位资源
├─ finance/                      # 财务账期、账单、收付款与核销
├─ lastleg-service/              # 海外尾程、入仓、库存与本土业务
├─ warehouse-overseas-service/   # 海外仓库、库位、托盘与资源锁
├─ 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 聚合 |
| `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 | 海外仓资源库 | 海外仓库、库位、托盘和资源锁 |
| `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 业务事件直接投递

Firstleg、Lastleg 与 Finance 通过内部服务身份直接投递业务事件，保留事务 Outbox、消费幂等、结构化 ACK 与失败重试；精确事件表只维护在外层 `docs/统一认证与服务通信契约.md`。旧 Event Bridge 和海外 Gateway 源码退役待清理，不作为当前实现入口。

头程装柜完成事件以实际集装箱为顶层批次，`orders[]` 中每项是一张实际发运的来源入仓单；一个柜可包含多张入仓单。每个货物明细携带来源明细 ID、实际装运箱数和完整的国内箱唛池。国内不要求在装柜时逐箱扫描冻结，完整箱唛池可以大于本柜实际装运箱数；海外按实际首次扫描的箱唛确认归属和实收，未扫描箱唛保留给后续子订单。海外将同柜各来源入仓单分别生成入库计划，但以同一集装箱号关联，并且只允许同一目的仓的箱子合托。

## 6. 配置、部署和辅助目录

### `config/`

```text
config/nacos/
└─ test/     # 公共配置 + 13 服务，统一实际 Namespace ID
```

`test/` 保存公共配置和全部保留服务的 14 个 Data ID；旧区域目录已退役。配置模板可以提交，真实密码和第三方密钥不能提交。

### `deploy/`

```text
deploy/
├─ docker/Dockerfile          # 通用 Java 17 镜像
├─ env/.env.test.example      # 环境变量示例
├─ scripts/deploy-services.sh # Jenkins 增量部署脚本
├─ docker-compose.yml         # 13 服务统一 TEST 编排
├─ docker-compose.rocketmq.yml # 公共导出 RocketMQ 基础设施
├─ sql/                       # TEST 空库基线入口与执行说明
└─ service-map.yml            # 模块、JAR、端口映射
```

### `scripts/`

- `local-env.ps1`：本地服务环境变量
- `publish-nacos-config.ps1`：发布统一 TEST Nacos 配置；DryRun 不联网，正式发布须授权
- `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` 覆盖的13 个保留服务执行受影响构建。
- 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
- 国内头程与海外仓共用 TEST 单机基础设施与 Nacos 命名空间，保留各服务数据归属和 Schema。

前端 phase4 定向离线检查入口为 `apps/admin-web/scripts/phase4-test-frontend-acceptance.mjs`（工作区相对路径），由 Admin 的 `pnpm test:phase4:test` 使用 `vitest.phase4-test.config.ts` 执行；不替代真实HTTP、页面或PDA验收。