暂存提交

2026-07-30 18:34:59 +08:00
parent 72d86cf1d2
commit 4e78c5d548
1 changed files with 288 additions and 0 deletions
@@ -0,0 +1,288 @@
+# 头程项目目录结构与服务说明
+
+## 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. 根目录结构
+
+```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 网关
+├─ 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`：平台端鉴权查看
+- `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/`
+
+```text
+config/nacos/
+├─ local/    # 本地联调配置
+└─ cn/       # 国内服务器配置模板
+```
+
+每套目录包含公共配置 `baiyue-common.yml` 和 11 个服务配置。配置模板可以提交，真实密码和第三方密钥不能提交。
+
+### `deploy/`
+
+```text
+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. 主要调用关系
+
+```text
+前端
+  └─ Gateway
+      ├─ Auth ── IAM（授权快照、企业注册）
+      ├─ IAM ── Auth（内部账号管理）
+      ├─ Order ── IAM（企业资格）
+      │         └─ Warehouse（仓库、往来单位）
+      ├─ Firstleg（履约任务与分配）
+      ├─ File ── IAM（资质文件鉴权）
+      ├─ Print
+      └─ 平台内部能力
+          ├─ Audit Service
+          ├─ Integration Service
+          └─ Event Bridge Service ── 国外尾程事件入口
+```
+
+服务间优先使用 Nacos 服务发现。跨区域通信只走事件桥或明确的公网契约，不直接调用对方内部接口，不共享 MySQL、Redis 或 Nacos。
+
+## 8. 本地启动顺序
+
+推荐顺序：
+
+1. 外部基础设施：MySQL、Redis、Nacos。
+2. 核心认证：IAM、Auth。
+3. 业务主数据：Warehouse、File。
+4. 核心业务：Order、Firstleg、Print。
+5. 支撑能力：Audit、Integration、Event Bridge。
+6. 最后启动 Gateway。
+
+Nacos 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。
+
+## 9. 开发和拆分约束
+
+- 每个业务服务只访问自己的数据库；禁止跨库 Join 和直接读取其他服务表。
+- 所有商户业务数据必须带租户维度，并在后端执行租户隔离。
+- 平台端和商户端权限分别管理，接口与按钮权限都必须由后端校验。
+- Controller 负责协议转换，Service 负责业务编排，Repository/Mapper 负责持久化。
+- 服务之间只传 DTO 或事件契约，不能依赖其他服务的 Entity、Mapper。
+- 公共模块变化会影响多个服务，Jenkins 会自动重建全部 11 个服务。
+- 单一 Git 仓库不等于单一部署单元；每个服务仍生成独立 JAR、镜像和容器。
+- 头程与尾程保持两个 Git 仓库、两套数据库和两套运行环境。