baiyue-firstleg/docs/project-structure-after-region-split.md

国内外区域拆分后的项目结构审核稿

更新时间：2026-07-29
审核状态：待审核
适用仓库：D:\baiyue

1. 拆分结论

项目继续使用一个 Git 仓库和一套业务源码，通过“国内部署聚合入口、海外部署聚合入口、区域独立配置”形成两个部署单元。当前拆分没有复制或移动业务源码，也没有把国内、海外拆成两个 Git 仓库。

一期全部服务可以先部署在国内服务器，但源码、数据库命名、配置和事件契约从现在起按国内与海外边界约束。后期迁移时只迁移尾程及海外作业单元，新尾程聚合切到海外主写，国内旧尾程单排空；严禁同一聚合在两个区域同时写入。

2. 拆分后的目录树

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，用于一期尾程临时部署在国内的兼容场景。

一期包含尾程的国内构建命令：

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. 构建与校验命令

根工程完整校验：

cd D:\baiyue
mvn clean test

国内部署单元：

cd D:\baiyue\deployments\cn
.\build.ps1
mvn -f pom.xml -DskipTests validate

上面是默认 18 模块构建；一期需要连同国内尾程一起构建时执行 .\build.ps1 -IncludePhase1Lastleg，对应 19 模块。

海外部署单元：

cd D:\baiyue\deployments\overseas
.\build.ps1
mvn -f pom.xml -DskipTests validate

事件契约：

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. 是否确认先在国内回环验证事件可靠性，再建设海外影子环境和灰度切流。