# 国内外区域拆分后的项目结构审核稿 更新时间：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. 是否确认先在国内回环验证事件可靠性，再建设海外影子环境和灰度切流。