15 KiB
头程项目目录结构与服务说明
文档定位与读取时机
本文是面向架构理解和运维协作的服务总览，主要说明技术基线、目录结构、服务端口、数据库归属、调用关系和启动部署拓扑。
- 普通单模块开发不需要预先通读本文；先读仓库根
AGENTS.md和目标模块AGENTS.md。 - 涉及跨服务设计、模块拆分、端口或数据库归属、根目录调整、本地启动和部署拓扑时再读本文。
- Controller、Service、SQL、测试和当前实现入口以各级
AGENTS.md与代码为准；本文不维护文件级快速索引，避免与执行指引重复和漂移。
1. 项目定位
baiyue-firstleg 是国内头程业务后端仓库，采用 Maven 多模块单仓结构。仓库内包含 7 个公共模块和 11 个可独立启动、构建、制作镜像的微服务。
当前技术基线：
- 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
本仓库只保存头程代码。尾程业务位于独立 Git 仓库，不允许把尾程源码、数据库或配置重新放回本仓库。
2. 根目录结构
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 网关
├─ auth/ # 统一登录与账号凭据
├─ iam/ # 租户、成员、角色、权限、企业审核
├─ order/ # 头程订单中心
├─ firstleg/ # 履约任务、二期入库、测量与计费
├─ warehouse/ # 仓库主数据、托盘与库位资源
├─ 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 等第三方适配器和启停状态；默认关闭外部调用 |
event-bridge-service |
event-bridge-service |
9300 | baiyue_event_bridge |
国内外事件接收、签名/内部令牌保护、幂等 Inbox 和接收结果 |
audit-service |
audit-service |
9700 | baiyue_audit |
接收公共审计事件并持久化；平台端可按权限查询已脱敏日志，业务审计发送默认开启 |
MySQL、Redis、Nacos 是外部基础设施，不属于上述 11 个业务服务，也不应打包进业务镜像。
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 或内部接口。
6. 配置、部署和辅助目录
config/
config/nacos/
├─ local/ # 本地联调配置
└─ cn/ # 国内服务器配置模板
每套目录包含公共配置 baiyue-common.yml 和 11 个服务配置。配置模板可以提交，真实密码和第三方密钥不能提交。
deploy/
deploy/
├─ docker/Dockerfile # 通用 Java 17 镜像
├─ env/.env.test.example # 环境变量示例
├─ scripts/deploy-services.sh # Jenkins 增量部署脚本
├─ docker-compose.yml # 11 个业务服务编排
├─ 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. 主要调用关系
前端
└─ 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. 本地启动顺序
推荐顺序：
- 外部基础设施：MySQL、Redis、Nacos；启用公共导出时再准备 RocketMQ。
- 核心认证：IAM、Auth。
- 主数据与适配：Warehouse、Integration。
- 业务依赖：Order、File。
- 核心编排与支撑：Firstleg、Print、Audit、Event Bridge。
- 最后启动 Gateway。
Nacos 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。
9. 开发和拆分约束
- 每个业务服务只访问自己的数据库；禁止跨库 Join 和直接读取其他服务表。
- 所有商户业务数据必须带租户维度，并在后端执行租户隔离。
- 平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
- Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
- 服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
- 公共模块变化会影响多个服务，Jenkins 会自动重建全部 11 个服务。
- 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
- 头程与尾程保持两个 Git 仓库、两套数据库和两套运行环境。