192 lines
12 KiB
Markdown
192 lines
12 KiB
Markdown
# 国内外区域拆分后的项目结构审核稿
|
|
|
|
更新时间：2026-07-29
|
|
审核状态：待审核
|
|
适用仓库：`D:\baiyue`
|
|
|
|
## 1. 拆分结论
|
|
|
|
项目继续使用一个 Git 仓库和一套业务源码，通过“国内部署聚合入口、海外部署聚合入口、区域独立配置”形成两个部署单元。当前拆分没有复制或移动业务源码，也没有把国内、海外拆成两个 Git 仓库。
|
|
|
|
一期全部服务可以先部署在国内服务器，但源码、数据库命名、配置和事件契约从现在起按国内与海外边界约束。后期迁移时只迁移尾程及海外作业单元，新尾程聚合切到海外主写，国内旧尾程单排空；严禁同一聚合在两个区域同时写入。
|
|
|
|
## 2. 拆分后的目录树
|
|
|
|
```text
|
|
D:\baiyue
|
|
├─ pom.xml 根 Maven 聚合，一个 Git 仓库
|
|
├─ common-core 统一返回、异常码等公共模型
|
|
├─ common-web 统一异常处理和 Web 公共能力
|
|
├─ common-security JWT、租户和权限上下文
|
|
├─ common-openapi Swagger/OpenAPI 公共配置
|
|
├─ common-audit 审计事件采集客户端
|
|
├─ common-event-contract 国内外共享的版本化事件信封和类型
|
|
├─ event-bridge-service 跨区事件接收幂等和投递记录基础骨架
|
|
├─ gateway 区域网关源码，按区域独立部署
|
|
├─ auth 统一登录与令牌服务
|
|
├─ iam 租户、成员、角色、菜单和按钮权限
|
|
├─ order 订单主档、状态历史和订单 Outbox
|
|
├─ firstleg 国内头程履约
|
|
├─ lastleg 尾程履约，后期迁移到海外主写
|
|
├─ warehouse 仓储源码，国内仓和海外仓分别部署
|
|
├─ file 文件服务源码，按区域分别部署
|
|
├─ print 打印服务源码，按区域分别部署
|
|
├─ audit-service 审计落库服务，按区域分别部署
|
|
├─ integration-service 第三方适配，按区域启用不同提供方
|
|
├─ deployments
|
|
│ ├─ cn
|
|
│ │ ├─ pom.xml 国内部署聚合入口
|
|
│ │ ├─ env.example 国内环境变量清单
|
|
│ │ ├─ build.ps1 国内单元构建脚本
|
|
│ │ └─ README.md 国内部署说明
|
|
│ └─ overseas
|
|
│ ├─ pom.xml 海外部署聚合入口
|
|
│ ├─ env.example 海外环境变量清单
|
|
│ ├─ build.ps1 海外单元构建脚本
|
|
│ └─ README.md 海外部署说明
|
|
├─ config\nacos Nacos 配置模板
|
|
└─ docs 架构、数据和实施审核文档
|
|
```
|
|
|
|
`event-bridge-service` 已生成基础骨架，默认端口 `9300`，独立数据库 `baiyue_event_bridge`。它已实现事件信封校验、规范化摘要、内部服务令牌校验、目标区域校验和 Inbox 幂等接收。事件桥自身 8 项测试、公共事件契约 6 项测试通过；基础骨架不等于真实跨区链路已可用。
|
|
|
|
## 3. 模块职责与部署归属
|
|
|
|
| 模块 | 核心职责 | 一期物理位置 | 目标主写位置 |
|
|
| --- | --- | --- | --- |
|
|
| `gateway` | 统一入口、路由、鉴权前置校验、Swagger 聚合 | 国内 | 国内和海外各一套 |
|
|
| `auth` | 注册、登录、刷新、退出、令牌会话 | 国内 | 国内 |
|
|
| `iam` | 租户、成员、角色、菜单、按钮、数据范围和资质审核 | 国内 | 国内 |
|
|
| `order` | 商户订单主档、平台审核、状态机、订单 Outbox | 国内 | 国内 |
|
|
| `firstleg` | 国内头程任务与履约交接 | 国内 | 国内 |
|
|
| `lastleg` | 到港前、清关、提柜、海外仓、派送、签收 | 国内运行一期版本 | 海外 |
|
|
| `warehouse` | 仓库资料与仓内作业边界 | 国内 | 国内仓、海外仓各自区域主写 |
|
|
| `file` | 文件元数据、授权下载、区域对象存储适配 | 国内 | 国内和海外各一套 |
|
|
| `print` | 模板、打印任务和状态历史 | 国内 | 按区域各一套 |
|
|
| `audit-service` | 不可篡改操作审计的落库边界 | 国内 | 按区域本地记录 |
|
|
| `integration-service` | OCR、港务、海关、Amazon 和承运商适配 | 国内 | 国内和海外各一套 |
|
|
| `common-event-contract` | 事件信封、类型、区域码、校验规则 | 仅参与编译 | 两区共享同一版本 |
|
|
| `event-bridge-service` | 跨区事件接收幂等、待发送记录和投递尝试 | 国内回环验证 | 国内和海外各部署一套 |
|
|
|
|
## 4. 国内与海外启动清单
|
|
|
|
### 4.1 一期国内服务器
|
|
|
|
一期核心闭环建议启动：`gateway`、`auth-service`、`iam-service`、`order-service`、`warehouse-service`、`firstleg-service`、`audit-service`、`integration-service`。涉及资质附件时启动 `file-service`；涉及标签和作业单时启动 `print-service`；开发尾程交接闭环后再启动 `lastleg-service`。
|
|
|
|
当前 `deployments/cn/pom.xml` 已聚合公共库、`common-event-contract`、`event-bridge-service`，以及 `gateway/auth/iam/order/firstleg/warehouse/file/print/audit-service/integration-service`。默认构建为 18 个 Reactor 模块，不包含 `lastleg`，用于表达长期区域职责；启用 `phase1-domestic-lastleg` Profile 后为 19 个 Reactor 模块并包含 `lastleg`，用于一期尾程临时部署在国内的兼容场景。
|
|
|
|
一期包含尾程的国内构建命令：
|
|
|
|
```powershell
|
|
cd D:\baiyue\deployments\cn
|
|
.\build.ps1 -IncludePhase1Lastleg
|
|
|
|
# 等效 Maven 命令
|
|
mvn -f pom.xml -Pphase1-domestic-lastleg -DskipTests package
|
|
```
|
|
|
|
默认构建不带 `-IncludePhase1Lastleg`。长期迁移完成后停止使用该 Profile，国内单元恢复默认 18 模块，旧国内尾程单按迁移方案排空。
|
|
|
|
### 4.2 后期海外服务器
|
|
|
|
`deployments/overseas/pom.xml` 当前聚合公共库、`common-event-contract`、`event-bridge-service`，以及 `gateway/lastleg/warehouse/file/print/audit-service/integration-service`。海外不部署 `auth`、`iam`、`order`、`firstleg` 的写实例。
|
|
|
|
海外正式上线前必须具备：独立 Nacos、独立 MySQL、独立 Redis、独立对象存储、独立域名和证书、跨区可靠事件、海外本地鉴权、监控告警和回滚能力。当前目录聚合只代表结构已拆分，不代表这些生产资源已经创建。
|
|
|
|
## 5. 共享源码规则
|
|
|
|
1. 国内与海外共用同一 Git 仓库、同一模块源码和同一版本号，不复制 `warehouse/file/print/integration/audit` 源码。
|
|
2. 区域差异必须通过环境变量、Spring Profile、Nacos Namespace 和适配器开关表达，禁止在业务代码中散落主机地址判断。
|
|
3. 公共模块只提供无区域主写状态的能力，不保存业务数据，不单独启动。
|
|
4. 事件契约必须向后兼容；新增字段优先可选，破坏性变更必须升级事件版本。
|
|
5. 国内和海外可使用相同服务注册名，但只能注册到各自 Nacos，不能互相发现。
|
|
6. 跨区调用只使用版本化事件或受控文件复制，不通过 OpenFeign 直接跨公网调用业务服务。
|
|
|
|
## 6. 构建与校验命令
|
|
|
|
根工程完整校验：
|
|
|
|
```powershell
|
|
cd D:\baiyue
|
|
mvn clean test
|
|
```
|
|
|
|
国内部署单元：
|
|
|
|
```powershell
|
|
cd D:\baiyue\deployments\cn
|
|
.\build.ps1
|
|
mvn -f pom.xml -DskipTests validate
|
|
```
|
|
|
|
上面是默认 18 模块构建；一期需要连同国内尾程一起构建时执行 `.\build.ps1 -IncludePhase1Lastleg`，对应 19 模块。
|
|
|
|
海外部署单元：
|
|
|
|
```powershell
|
|
cd D:\baiyue\deployments\overseas
|
|
.\build.ps1
|
|
mvn -f pom.xml -DskipTests validate
|
|
```
|
|
|
|
事件契约：
|
|
|
|
```powershell
|
|
cd D:\baiyue
|
|
mvn -pl common-event-contract -am test
|
|
```
|
|
|
|
构建成功只证明依赖、编译和自动化测试通过，不代表数据库初始化、Nacos 配置、网络连通、跨区事件或生产部署已验收。
|
|
|
|
## 7. 数据与基础设施边界
|
|
|
|
### 7.1 MySQL
|
|
|
|
- 国内主库：`baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_firstleg`，以及带区域归属的国内仓储、文件、打印、集成和审计数据库。
|
|
- 一期尾程位于国内时使用独立的 `baiyue_lastleg_cn`，不与订单、头程或仓储跨库联表。
|
|
- 海外目标库：尾程、海外仓储、海外文件、海外打印、海外集成和海外审计各自独立数据库。
|
|
- 禁止跨区外键、跨区事务、共享数据库账号和双写；订单号等公共标识由应用生成，避免区域自增冲突。
|
|
|
|
现有各模块默认配置仍主要使用 `baiyue_warehouse`、`baiyue_file`、`baiyue_print`、`baiyue_lastleg` 等未带区域后缀的本地库名。区域化库名属于目标配置，必须在部署环境变量或 Nacos 中显式覆盖，不能把目标名称写成当前已经生效。
|
|
|
|
### 7.2 Nacos
|
|
|
|
国内使用独立集群和 `prod-cn` Namespace，海外使用独立集群和 `prod-overseas` Namespace，现阶段 Group 保持 `BAIYUE`。两区的 `8848` 不暴露公网，海外服务不连接国内 Nacos。
|
|
|
|
### 7.3 Redis
|
|
|
|
国内登录和网关当前会检查国内 Redis 中的令牌会话。海外正式运行前必须改为短期非对称签名令牌、本地 JWKS 缓存和海外本地撤销信息，不能把跨公网读取国内 Redis 当作生产方案。两区 Redis 的密码、库和键空间独立。
|
|
|
|
### 7.4 对象存储
|
|
|
|
当前文件资质上传仍使用本地磁盘目录，适合本地开发，不适合双区域。目标方案是国内文件进入国内对象存储，海外文件进入海外对象存储；跨区只复制履约所需文件，事件仅携带文件标识、版本和摘要，不携带文件正文。
|
|
|
|
## 8. 当前真实落地状态
|
|
|
|
| 能力 | 状态 | 说明 |
|
|
| --- | --- | --- |
|
|
| 单 Git 仓库、多模块 Maven 工程 | 已实现 | 根工程统一管理源码和依赖 |
|
|
| 国内、海外部署聚合目录 | 已生成，待部署验证 | 已有 POM、环境变量示例、构建脚本和说明 |
|
|
| 事件信封和类型公共契约 | 已实现基础契约 | 有源码和单元测试，尚未接入完整业务链路 |
|
|
| 事件桥服务 | 已实现基础骨架 | 内部令牌、目标区域、信封与摘要校验及 Inbox 幂等已实现，8 项测试通过；mTLS、来源白名单、RocketMQ、真实跨区发送、Outbox 扫描和业务消费者未实现 |
|
|
| 登录、租户、菜单和按钮权限模型 | 已实现一期基础能力 | 管理员与权限初始化已有验收记录；写接口权限仍需系统覆盖 |
|
|
| 订单主档和状态机 | 已实现一期主要接口 | 已有订单 Outbox 表和本地事务写入；可靠发布未闭环 |
|
|
| 头程服务 | 部分实现 | 已有任务、分配历史和消费记录，完整到仓、排柜、订舱、装柜、报关未完成 |
|
|
| 尾程服务 | 骨架 | 当前主要为健康接口，尾程业务闭环和 Inbox 尚未完成 |
|
|
| 仓储服务 | 部分实现 | 仓库资料维护和查询已具备，仓内入库、测量、拆货、打托等作业未闭环 |
|
|
| 文件服务 | 部分实现 | 资质上传下载和表结构已存在；当前仍依赖本地磁盘，对象存储未落地 |
|
|
| 打印服务 | 基础骨架 | 有表结构和健康接口，模板渲染、任务执行和打印机适配未完成 |
|
|
| 审计服务 | 基础能力已实现 | 有内部采集接口和审计表；跨区审计汇总未完成 |
|
|
| 集成服务 | 基础骨架 | 可查询提供方状态；真实 OCR、Amazon、海关、港务、承运商调用待实现 |
|
|
| 跨区 Outbox/Inbox 可靠链路 | 部分骨架，未完成 | Inbox 持久化基础已存在；mTLS、真实跨区发送、RocketMQ 发布消费、重试死信和人工补投仍待实现 |
|
|
| 海外独立基础设施与灰度 | 未完成 | 尚未进入海外生产部署和切流阶段 |
|
|
|
|
## 9. 审核决策点
|
|
|
|
1. 是否确认长期归属为“订单和头程国内唯一主写，尾程海外唯一主写”。
|
|
2. 是否确认一期尾程允许先在国内运行，但数据库和聚合从第一天保留 `execution_region`。
|
|
3. 是否确认仓储、文件、打印、审计、集成采用同源码双区域部署，而不是复制出海外模块。
|
|
4. 是否确认跨区只走可靠事件和受控文件复制，不开放 MySQL、Redis、Nacos 公网互通。
|
|
5. 是否确认先在国内回环验证事件可靠性，再建设海外影子环境和灰度切流。
|