java-project/baiyue-firstleg

Fork 0

Files

T

ouyangxq fdb1e8af1c 优化

2026-08-03 18:28:35 +08:00

15 KiB

Raw Blame History

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

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`	履约任务、操作分配和分配历史；不是订单主数据服务
`order`	`order-service`	9204	`baiyue_order`	订单草稿、编辑、提交、详情、状态历史、货物、往来单位快照、内部备注和 Outbox
`warehouse`	`warehouse-service`	9205	`baiyue_warehouse`	仓库、仓库地址、服务能力、启停校验，以及往来单位查询；往来单位不单独拆服务
`file`	`file-service`	9206	`baiyue_file`	文件存储与鉴权；实现企业资质上传预览及公共异步导出、下载中心
`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 和接收结果
`audit-service`	`audit-service`	9700	`baiyue_audit`	接收公共审计事件并持久化；当前配置默认关闭业务审计发送，可按环境开启

MySQL、Redis、Nacos 是外部基础设施，不属于上述 11 个业务服务，也不应打包进业务镜像。

5. 各服务文件夹说明

5.1 `gateway/`：统一入口

主要内容：

config/：网关安全、CORS、访问域规则和 Redis 会话过滤
filter/：可信身份请求头处理
application.yml：本地默认路由与安全配置
application-cn.yml：国内环境路由和 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。

5.3 `iam/`：租户、成员和权限中心

主要内容：

MerchantTenantController：商户端企业、成员相关接口
PlatformTenantController：平台端企业审核和管理接口
ProfileResourceController：个人资料、企业资料和资质资源
RbacController：角色、权限资源、启停和角色授权
InternalAuthorizationController：向 Auth/其他服务返回权限快照
entity/：租户、用户、成员关系、角色、权限、数据范围、企业地址和资质审核
resources/db/：IAM 主结构及一期成员、角色、权限、企业入驻扩展脚本

IAM 以 tenant_id 作为核心隔离维度，同时维护两套访问域：商户端和平台后台端。按钮权限通过 permission code / permissionIds 管理，不能只依赖前端隐藏按钮。

5.4 `order/`：订单中心

主要内容：

MerchantFirstLegOrderController：商户端订单草稿、编辑、提交和查询
PlatformFirstLegOrderController：平台端订单查询和内部处理入口
OrderApplicationService：订单业务编排和状态转换
OrderEligibilityGuard：企业审核资格校验
OrderMasterDataGuard：仓库、往来单位和主数据有效性校验
OrderScopeGuard：租户与访问范围校验
entity/：订单、货物、订单参与方快照、状态历史、内部备注和 Outbox 事件
client/：调用 IAM、Warehouse 获取资格和主数据

订单保存的是仓库、往来单位等关键字段的业务快照，主数据后续修改不能改变历史订单。跨服务通知通过 Outbox/事件方式演进，不应让数据库跨库直连。

5.5 `firstleg/`：头程履约中心

主要内容：

PlatformFulfillmentAssignmentController：平台端履约分配入口
FulfillmentTaskService：履约任务和分配业务
FulfillmentTaskEntity：履约任务
AssignmentHistoryEntity：分配历史

该服务承担订单提交后的执行过程。订单主单及商户草稿仍属于 order，避免订单交易状态与履约作业状态混在同一张表。

5.6 `warehouse/`：仓库与往来单位

主要内容：

商户端、平台端和内部仓库 Controller
WarehouseApplicationService：仓库查询、地址、能力和状态校验
PartnerQueryService：往来单位只读查询和停用过滤
WarehouseEntity、WarehouseAddressEntity、ServiceCapabilityEntity
PartnerEntity：往来单位
warehouse-seed.sql：测试环境仓库初始化数据

往来单位只是 Warehouse 服务下的主数据配置，数据库表为 baiyue_warehouse.wh_partner，不创建独立微服务和数据库。

5.7 `file/`：文件中心

主要内容：

QualificationFileController：商户端企业资质文件
PlatformQualificationFileController：平台端鉴权查看
PlatformExportTaskController：平台异步导出任务、下载与失败重试
ExportTaskHandler：业务导出类型扩展点；接入规则见 docs/公共导出与下载中心接入说明.md
QualificationFileStorage：存储抽象
LocalQualificationStorage：当前本地磁盘实现
IamQualificationClient：校验企业资质访问权限

生产环境应把存储实现替换为对象存储或共享文件存储。数据库保存元数据，文件内容不写入 Git，也不依赖应用容器临时目录。

5.8 `print/`：打印中心

当前目录已有独立应用、端口、数据库脚本、公共安全和审计依赖，但业务 Controller 目前只有健康检查。后续应在此目录增加：

打印模板版本管理
打印任务和状态机
PDF/标签生成
失败重试和幂等键
打印文件与 File 服务的引用关系

订单服务只提交打印请求，不应自己生成面单或直接操作打印机。

5.9 `audit-service/`：审计日志中心

通过 AuditIngestController 接收审计事件，AuditIngestService 处理后写入 baiyue_audit。公共模块负责采集和脱敏，本服务负责集中持久化、查询扩展和留存策略。

5.10 `integration-service/`：第三方集成中心

当前包含百度 OCR 和 Amazon Logistics/SP-API 适配器，以及第三方能力状态查询。服务不使用业务数据库，密钥必须通过 Jenkins Credentials、环境变量或 Nacos 密文注入。

5.11 `event-bridge-service/`：跨区域事件桥

负责接收国内外服务器之间的业务事件，并通过 Inbox 表实现事件去重。它只传输必要业务事件，不共享头程和尾程数据库。事件载荷遵循 common-event-contract，应包含事件 ID、来源区域、目标区域、业务键、版本、时间和 Payload 哈希。

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 个业务服务编排
└─ 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 回归

`docs/` 与 `reports/`

docs/ 保存长期有效的架构、数据库、接口、部署与验收说明。reports/ 保存某一次测试执行结果，可以用于追踪联调结论，但不能替代长期文档。

7. 主要调用关系

前端
  └─ Gateway
      ├─ Auth ── IAM（授权快照、企业注册）
      ├─ IAM ── Auth（内部账号管理）
      ├─ Order ── IAM（企业资格）
      │         └─ Warehouse（仓库、往来单位）
      ├─ Firstleg（履约任务与分配）
      ├─ File ── IAM（资质文件鉴权）
      ├─ Print
      └─ 平台内部能力
          ├─ Audit Service
          ├─ Integration Service
          └─ Event Bridge Service ── 国外尾程事件入口

服务间优先使用 Nacos 服务发现。跨区域通信只走事件桥或明确的公网契约，不直接调用对方内部接口，不共享 MySQL、Redis 或 Nacos。

8. 本地启动顺序

推荐顺序：

外部基础设施：MySQL、Redis、Nacos。
核心认证：IAM、Auth。
业务主数据：Warehouse、File。
核心业务：Order、Firstleg、Print。
支撑能力：Audit、Integration、Event Bridge。
最后启动 Gateway。

Nacos 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。

9. 开发和拆分约束

每个业务服务只访问自己的数据库；禁止跨库 Join 和直接读取其他服务表。
所有商户业务数据必须带租户维度，并在后端执行租户隔离。
平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
公共模块变化会影响多个服务，Jenkins 会自动重建全部 11 个服务。
单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
头程与尾程保持两个 Git 仓库、两套数据库和两套运行环境。

15 KiB Raw Blame History Unescape Escape

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

1. 项目定位

2. 根目录结构

3. 公共模块说明

4. 可运行服务总览

5. 各服务文件夹说明

5.1 gateway/：统一入口

5.2 auth/：统一登录与账号凭据

5.3 iam/：租户、成员和权限中心

5.4 order/：订单中心

5.5 firstleg/：头程履约中心

5.6 warehouse/：仓库与往来单位

5.7 file/：文件中心

5.8 print/：打印中心

5.9 audit-service/：审计日志中心

5.10 integration-service/：第三方集成中心

5.11 event-bridge-service/：跨区域事件桥

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

config/

deploy/

scripts/

docs/ 与 reports/

7. 主要调用关系

8. 本地启动顺序

9. 开发和拆分约束

15 KiB

Raw Blame History

5.1 `gateway/`：统一入口

5.2 `auth/`：统一登录与账号凭据

5.3 `iam/`：租户、成员和权限中心

5.4 `order/`：订单中心

5.5 `firstleg/`：头程履约中心

5.6 `warehouse/`：仓库与往来单位

5.7 `file/`：文件中心

5.8 `print/`：打印中心

5.9 `audit-service/`：审计日志中心

5.10 `integration-service/`：第三方集成中心

5.11 `event-bridge-service/`：跨区域事件桥

`config/`

`deploy/`

`scripts/`

`docs/` 与 `reports/`