diff --git a/docs/头程项目目录结构与服务说明.md b/docs/头程项目目录结构与服务说明.md new file mode 100644 index 000000000..498508392 --- /dev/null +++ b/docs/头程项目目录结构与服务说明.md @@ -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 仓库、两套数据库和两套运行环境。