baiyue-lastleg/docs/repository-boundary.md

尾程仓库边界说明

一、拆分目标

尾程仓库是可独立构建、发布和部署的海外业务单元。其生命周期、数据库、Nacos 命名空间、Redis、对象存储和发布流水线均与头程仓库隔离。两个仓库只通过已发布的 Maven 公共制品和版本化跨区事件建立依赖。

二、允许进入本仓库的能力

• 海外网关及尾程显式路由。
• 尾程履约、海外仓储、文件、打印、审计和外部渠道适配服务。
• 跨区事件桥及其 Outbox、Inbox、投递尝试数据。
• 海外 Nacos 模板、环境变量模板和部署脚本。
• 尾程专用数据库脚本、测试和中文文档。

三、禁止进入本仓库的能力

• 登录、注册、刷新令牌和账号凭据管理。
• 租户、企业、成员、角色、菜单、页面、按钮和接口权限主数据管理。
• 国内订单主档、头程订舱、装柜、报关和国内仓作业源码。
• common-* 公共源码以及头程仓父工程源码。
• 对国内 MySQL、Redis、Nacos 和内部服务的公网同步调用。
• 国内服务的网关路由、Swagger 聚合地址和服务发现自动路由。

四、依赖方向

头程公共源码 -> Maven 私有仓库 -> 尾程项目
国内业务事实 -> 国内 Outbox -> 跨区事件桥 -> 海外 Inbox -> 尾程本地投影
尾程业务事实 -> 海外 Outbox -> 跨区事件桥 -> 国内 Inbox -> 国内轨迹投影

尾程业务模块不得反向成为公共制品的依赖，公共制品也不得引用任一区域的业务模块。

五、认证授权落地规则

1. 国内统一认证中心使用 RS256 或 ES256 签发 JWT，并发布可轮换的 JWKS。
2. 海外只缓存公钥，禁止存放国内签名私钥或共享对称密钥。
3. JWT 至少携带 userId、tenantId、appCode、roles、authorities、permissionVersion、jti、iat 和 exp。
4. 海外网关先验证签名、签发方、有效期和应用端，再由业务服务校验按钮权限、租户和资源归属。
5. 权限变更、账号停用、租户冻结通过事件更新海外本地权限投影，不允许请求时跨区查询。
6. 权限事件延迟期间通过短时效令牌、权限版本比较和高风险操作冻结规则控制风险。

六、服务和数据库所有权

服务	所有事实	禁止事项
尾程服务	到港、清关、拆柜、入海外仓、派送、签收	修改国内订单主档
海外仓储服务	海外库位、库存和作业流水	查询国内仓储库
海外文件服务	海外文件元数据和对象存储引用	承担企业资质审核流程
海外打印服务	海外标签模板、打印任务和状态	跨库读取文件表
海外审计服务	海外操作审计	写入国内审计库
海外集成服务	海外承运商、清关和平台适配	直接修改尾程核心表
海外事件桥	收发状态、幂等键和重试记录	代替业务服务处理领域规则

七、跨区事件最低规范

事件信封必须包含事件编号、事件类型、契约版本、来源区域、目标区域、聚合编号、聚合版本、租户编号、发生时间、链路编号和负载摘要。消费者使用事件编号保证幂等，使用聚合版本拒绝乱序覆盖，契约只允许向后兼容演进。

禁止通过跨区同步 HTTP 调用创建或修改尾程聚合。事件桥必须具备持久化 Outbox、持久化 Inbox、指数退避重试、死信、人工补投、摘要冲突检测和可观测指标；生产链路使用 HTTPS 双向证书或私网连接。

八、当前草案状态

• 已完成独立根 POM、业务模块抽取、公共依赖坐标调整和海外配置收敛。
• 已移除文件服务中依赖国内权限服务的企业资质链路。
• 海外网关已改为 JWKS 验签，强制校验 Audience 和必要身份声明，并默认启用海外显式路由。
• 公共安全组件的 JWKS 解码、本地权限快照和冻结事件处理仍需在公共制品中完成。
• 海外提单、装箱单、清关文件和签收证明能力仍待实现。
• 海外事件桥到尾程消费者的本地调度已具备租约、指数退避、投递审计、死信和人工补投；头程跨区发送端、尾程反向回传和生产 mTLS 仍需完成联调验收。

只有上述待办完成并通过故障注入、跨区断网、重复事件、乱序事件和密钥轮换验收后，尾程服务才允许迁移到海外生产环境。