baiyue-firstleg/docs/business-domain-and-phase1-plan.md

业务域梳理与一期任务实施审核稿

更新时间：2026-07-30
审核状态：一期前端联调能力已验收，完整头程生产闭环待审核
目标：一期在国内服务器形成“注册与审核、下单、国内仓、头程交接、事件通知”的可演示闭环，并为后期尾程迁移海外保留稳定边界。

1. 一期业务主链路

商户注册
  -> 提交企业资料和资质文件
  -> 平台审核并激活租户
  -> 商户管理员登录并配置成员权限
  -> 商户创建、提交头程订单
  -> 平台审核、受理订单
  -> 生成头程履约任务
  -> 国内仓预约到货、收货测量和差异处理
  -> 排柜、订舱、拖车、装柜、报关
  -> 装船发运并固化交接快照
  -> Outbox 可靠发布交接事件
  -> 一期国内尾程 Inbox 幂等接收并回执
  -> 国内统一轨迹投影
  -> 异步订单通知

一期不要求立刻把服务物理部署到海外，但要求尾程交接不依赖跨库联表、同步跨区 Feign 或共享 Redis，以便后期只迁移尾程执行单元。

2. 业务域边界

业务域	唯一主数据	对外输入	对外输出	明确不负责	当前状态
租户权限	租户、成员、角色、菜单、按钮、数据范围、资质审核	注册资料、成员和授权变更	授权快照、租户下单资格	密码校验、订单业务状态	个人资料、成员、角色、按钮权限和租户隔离已通过真实回归
统一登录	账号、密码哈希、刷新令牌、登录会话	注册、登录、刷新、退出	JWT 和会话状态	菜单权限主数据	登录、刷新轮换、退出、改密和会话撤销已通过真实回归；海外本地验签待完成
订单	商户委托、货物、收发方、订单状态和历史	商户下单、平台审核和受理	订单事件、履约创建指令、查询视图	仓内作业、头程执行细节、尾程事实	主要接口与状态机已存在，可靠事件发布未闭环
国内仓	国内仓资料、往来单位配置、联系人地址、库位及仓内作业事实	到仓预约、收货、测量、装柜指令	有效仓库与往来单位候选、入库结果、差异、装柜证据	订单审核、订舱、报关、尾程	仓库和往来单位资料能力已有，仓内作业待实现
头程	头程履约任务、订舱、柜、航次、报关和发运交接	已受理订单、仓储作业结果	发运交接事件和头程里程碑	商户订单主档、海外派送	任务分配基础已有，完整履约待实现
尾程交接	尾程聚合、交接版本、执行区域、到港至签收事实	不可变发运交接事件	接收/拒绝回执、尾程里程碑、完成事件	修改国内订单和头程事实	当前主要为骨架，Inbox 与业务流程未完成
文件	文件元数据、存储定位、版本、摘要、下载授权和日志	文件上传或受控复制	文件标识、短期下载授权	在事件中传输文件正文、业务审批	资质上传下载已有，本地磁盘需迁对象存储
打印	模板、打印任务、状态历史	业务单据数据和模板版本	生成文件标识、打印结果	保存订单或仓储主数据	表结构与健康接口已有，执行能力待实现
审计	操作人、租户、动作、对象、结果和追踪号	各服务异步或内部审计事件	审计查询与留痕	代替业务状态历史	采集落库基础已有，关键写动作覆盖需核对
集成	提供方配置、外部请求映射、回调幂等键	业务服务抽象调用、第三方回调	标准化结果和外部事件	持有订单、头程、尾程主状态	提供方状态骨架已有，真实适配器待实现
事件通知	Outbox、Inbox、投递、重试、死信、通知订阅和发送记录	领域事件	站内信、短信/邮件/回调结果和统一轨迹	直接推进源聚合状态	公共事件契约已存在，可靠桥和通知链路未完成

3. 服务间协作规则

1. auth-service 登录时向 iam-service 获取授权快照；JWT 携带可信租户、端和权限信息。
2. order-service 只通过 IAM 内部接口判断租户是否允许下单，不跨库查询 IAM 表。
3. order-service 通过 warehouse-service 内部接口校验仓库和往来单位；二者均属于 baiyue_warehouse，订单只保存不可变业务快照，不跨库读取配置表。
4. 订单受理后通过事件或明确的内部契约创建头程任务，头程不得修改订单表。
5. 国内仓回传测量、差异和装柜结果；头程维护履约编排，仓储维护仓内事实。
6. 只有“装船发运且交接快照固化”才能产生尾程交接事件，订单审核通过事件不能替代尾程交接。
7. 尾程以 event_id + event_version 幂等接收，以聚合版本拒绝旧事件覆盖新状态。
8. 海外里程碑通过事件回到国内只读轨迹投影，客户端只查询国内统一时间线。
9. 文件事件只传 file_id、版本、摘要和用途；打印任务只保存业务引用和 file_id。
10. 通知消费者失败不能回滚订单或履约事务，必须重试、死信并可人工补投。
11. 每个写操作同时校验登录身份、端、租户和按钮权限，不能只依赖前端隐藏按钮。

4. 一期范围

4.1 必须完成

• 平台端和商户端统一登录、租户隔离、菜单与按钮权限。
• 商户注册、资质提交、平台审核、租户激活、允许下单联动。
• 普通头程订单创建、编辑、提交、审核、受理和取消。
• 国内仓到仓、收货、测量、差异确认、装柜证据的最小闭环。
• 头程排柜、订舱、装柜、报关、装船发运和交接快照。
• 国内回环的 Outbox、事件桥、Inbox、回执、统一轨迹和订单通知。
• 文件对象存储抽象、审计、监控、自动化验收和部署手册。

4.2 延后到后续迭代

• 完整快递、换标、海外仓增值服务产品线。
• 全量 Amazon SP-API、各国海关、港务和多承运商适配。
• 海外正式生产切流、多区域高可用和历史执行中聚合迁移。
• 高级智能排柜、智能计费、复杂结算和财务对账。

5. 一期详细任务节点

状态取值：已有基础 表示代码或表已存在但仍需按验收标准补齐；待实现 表示尚未形成可用闭环。

编号	任务	输入	输出	依赖	验收标准	优先级	建议迭代	当前状态
P1-001	固化一期状态机与跨服务契约	原型、订单状态、头尾程节点	状态表、接口契约、事件目录	产品审核	非法流转有明确错误码；契约评审通过并版本化	P0	迭代 0	待审核
P1-002	统一环境与数据库初始化	服务清单、SQL、Nacos 模板	可重复初始化脚本和环境检查	MySQL、Redis、Nacos	空环境一键初始化；重复执行无副作用；密码不入库	P0	迭代 0	已有基础
P1-003	统一登录回归	账号、密码、端类型	Access Token、Refresh Token、退出结果	Auth、IAM、Redis	平台/商户登录刷新退出全通过；错误端和禁用账号被拒绝	P0	迭代 1	已完成真实回归
P1-004	注册审核激活闭环	注册资料、资质文件	待审核租户、审核记录、激活账号	Auth、IAM、File	注册后不可下单；审核通过自动激活；拒绝原因可查；重复请求幂等	P0	迭代 1	部分实现，需闭环回归
P1-005	两端菜单按钮授权	角色、资源、成员	授权快照和 JWT 权限	IAM、Auth	平台与商户资源完全隔离；菜单和按钮权限正确下发	P0	迭代 1	已有基础并有验收记录
P1-006	写接口后端鉴权全覆盖	按钮权限码、写接口清单	@PreAuthorize 或等效策略	P1-005	未授权直调所有写接口均返回 403；跨租户访问为 403/404	P0	迭代 1	本次成员、角色、仓库、往来单位和订单接口已通过；其余后续业务写接口随功能实现验收
P1-007	首次登录改密和凭据治理	初始账号、密码策略	强制改密状态、修改密码接口	Auth	初始账号未改密不能进入业务；密码不记录日志	P1	迭代 1	待实现
P1-008	商户头程订单最小闭环	可下单租户、货物和收发方	草稿、提交、审核、受理、取消状态	P1-004、P1-006	正常路径和拒绝/取消路径通过；状态历史完整；租户隔离通过	P0	迭代 2	商户草稿创建、编辑、提交、快照和异常路径已通过；平台审核、受理、取消仍待闭环
P1-009	订单 Outbox 状态机	订单本地事务和领域事件	待投递、投递中、成功、重试、死信记录	P1-001、P1-008	业务提交与 Outbox 同事务；进程崩溃后可恢复；无事件丢失	P0	迭代 2	有表和写入基础，发布未完成
P1-010	头程任务创建与幂等消费	订单受理事件	唯一头程任务、消费记录	P1-009	同一事件重复 10 次只创建一个任务；失败可重试	P0	迭代 2	任务、消费表和分配基础已有
P1-011	国内仓到仓预约与收货	头程任务、预约信息、实收件	入库单、收货时间和操作人	Warehouse、Firstleg	可登记预约和实收；租户/订单引用有效；完整审计	P0	迭代 2	待实现
P1-012	测量与差异处理	实收货物、实测重量体积	测量记录、差异结果、确认记录	P1-011	原始值和实测值可追溯；超阈值必须人工确认后继续	P0	迭代 2	待实现
P1-013	仓库及往来单位基础数据完善	仓库、地址、能力、往来单位联系人与地址、状态	可供商户选择的有效仓库和往来单位列表	Warehouse	租户隔离、停用过滤、商户只读查询、订单快照校验通过	P1	迭代 2	已补查询、过滤、样本和订单校验
P1-014	头程排柜与订舱	合格入库货物、航线和柜型	柜计划、订舱单、航次信息	P1-012、Integration	容量校验、重复分配保护、订舱失败可重试且不重复	P0	迭代 3	待实现
P1-015	拖车、装柜和证据链	柜计划、装柜货物	装柜明细、柜号、封条号、照片文件引用	P1-014、File	装柜数量一致；照片摘要可校验；柜号封条唯一；留审计	P0	迭代 3	待实现
P1-016	报关与放行	货物、企业资质、装柜数据	报关单、申报结果、放行状态	File、Integration	资料版本可追溯；失败可重提；未放行禁止发运完成	P0	迭代 3	待实现
P1-017	装船发运与不可变交接快照	放行状态、航次、柜和文件清单	FirstLegShipmentDeparted.v1 与快照	P1-015、P1-016	仅满足前置条件可发运；重复操作同一结果；快照有版本和摘要	P0	迭代 3	待实现
P1-018	事件信封与兼容性测试	事件目录、字段定义	版本化契约、示例、校验测试	P1-001	必填字段、区域码、版本、摘要校验通过；旧消费者兼容新增字段	P0	迭代 3	基础契约已实现
P1-019	事件桥可靠发送基础	Outbox 事件	签名请求、投递状态、重试和死信	P1-009、P1-018	超时重试有上限；签名失败拒绝；支持人工补投和监控	P0	迭代 4	内部令牌、目标区域和 Inbox 幂等已实现并通过 8 项测试；mTLS、跨区发送、RocketMQ、Outbox 扫描待实现
P1-020	尾程 Inbox 与交接回执	发运交接事件	幂等 Inbox、尾程聚合、接受/拒绝回执	P1-017、P1-019	重复 10 次只创建一次；坏摘要拒绝；旧版本不覆盖新版本	P0	迭代 4	待实现
P1-021	尾程一期最小阶段	已接受交接	到港前、到港、到仓、出仓、签收状态	P1-020	五阶段正常流转；非法逆序拒绝；异常原因和操作者可查	P0	迭代 4	待实现
P1-022	国内统一轨迹投影	订单、头程和尾程里程碑事件	商户订单时间线	P1-018、P1-021	最终一致；乱序不回退；重复不新增；展示最后同步时间	P0	迭代 4	待实现
P1-023	异步订单通知	领域事件、订阅规则、模板	站内通知及发送记录	P1-022	通知失败不回滚业务；可重试、死信、去重；租户隔离	P0	迭代 4	待实现
P1-024	文件对象存储适配	现有本地文件接口	存储抽象、对象键、短期下载授权	对象存储	本地与对象存储实现可切换；SHA-256、大小、类型和下载审计通过	P0	迭代 3	当前本地磁盘，待改造
P1-025	打印最小闭环	模板、订单/仓储数据	打印任务、生成文件、结果历史	File、Print	可创建模板版本和任务；失败可重试；任务关联 file_id	P1	迭代 4	表结构已有，执行待实现
P1-026	关键动作审计覆盖	写接口和领域事件清单	审计记录	Audit、各业务服务	登录、授权、审核、状态推进、交接、补投均记录租户和追踪号	P0	迭代 1-4	采集基础已有，覆盖待核验
P1-027	可观测性和告警	服务、Outbox、Inbox、数据库指标	仪表盘和告警规则	全部核心服务	事件积压、死信、5xx、鉴权失败、数据库连接异常可告警	P0	迭代 4	待实现
P1-028	一期自动化业务验收	测试账号、测试订单和故障场景	验收报告与证据	P1-003 至 P1-027	主链路、重复、乱序、断网 30 分钟、跨租户、回滚场景全部通过	P0	迭代 5	前端联调范围 105 项真实 API 检查通过；完整履约、跨区断网和乱序验收待补
P1-029	国内生产部署与回滚演练	镜像、配置、SQL、备份	国内上线版本和回滚记录	P1-028	标准端口无冲突；密钥不入库；备份恢复和旧版本回滚演练通过	P0	迭代 5	待实现
P1-030	海外迁移准备包	区域配置、数据分类和事件链路	海外资源清单、切流门槛、回滚手册	P1-019 至 P1-029	不依赖国内 MySQL/Redis/Nacos；影子环境可重复部署	P1	迭代 5	结构已拆，生产准备未完成

6. 建议迭代与出口条件

迭代	目标	出口条件
迭代 0：边界冻结	冻结状态机、事件、数据库和部署边界	审核本文及区域方案；契约有负责人和版本
迭代 1：账号权限	完成注册审核、激活、登录和按钮鉴权	两端权限与跨租户自动化通过，关键动作有审计
迭代 2：订单到入仓	订单受理后创建头程任务并完成到仓测量	正常、拒绝、取消、重复事件和差异处理通过
迭代 3：头程发运	完成订舱、装柜、报关、对象存储和发运快照	可稳定生成唯一且可校验的交接事件
迭代 4：尾程回环	在国内打通事件桥、Inbox、尾程五阶段、轨迹和通知	断网恢复、重复、乱序、死信补投和跨租户测试通过
迭代 5：上线准备	自动化验收、容量、安全、备份和回滚	国内一期上线审批通过；海外准备包可审核

7. 一期验收数据与场景

至少准备两个商户租户、一个平台管理员、一个审核员、一个订单运营、两个企业成员、两个国内仓、一条正常订单、一条拒绝订单和一条差异订单。

必须自动化覆盖：

1. 商户甲不能读取或操作商户乙的成员、订单、货物、文件和轨迹。
2. 无按钮权限的用户直接调用写接口返回 403。
3. 未审核、被拒绝、禁用租户不能提交订单。
4. 同一订单事件重复投递 10 次只生成一个头程任务。
5. 同一发运交接事件重复投递 10 次只生成一个尾程聚合。
6. 尾程里程碑乱序到达时，旧版本不能覆盖新状态。
7. 事件通道中断 30 分钟不影响国内订单和头程提交，恢复后自动补投。
8. 通知发送失败不回滚履约状态，并能重试或进入死信。
9. 文件下载必须短期授权、校验租户并写下载审计。
10. 关键状态推进、人工覆盖和人工补投均可按追踪号还原操作链。

8. 当前可复用的验收基线

已有一期管理员、角色、菜单和按钮初始化记录，以及登录、权限查询、跨端隔离等 19 项自动化冒烟记录；根工程曾有 20 个测试通过记录。这些结果可以作为权限基线，但不能替代本方案中的注册审核、仓内作业、头程发运、尾程交接、可靠事件、轨迹和通知验收。

一期在国内同时运行尾程时，应使用已提供的国内兼容 Profile 构建：

cd D:\baiyue\deployments\cn
.\build.ps1 -IncludePhase1Lastleg

默认国内聚合为 18 个 Reactor 模块；上述命令启用 phase1-domestic-lastleg 后为 19 个 Reactor 模块并包含 lastleg。国内和海外聚合均已包含 common-event-contract 与 event-bridge-service，不需要另行手工加入。

执行新一轮验收前，应先清理旧端口进程并以最新代码、正确数据库密码和标准端口重新启动，避免把临时 9001/9301 验收环境当作正式运行配置。

9. 审核后立即执行的 P0 顺序

1. 审核并冻结 P1-001 的业务状态与事件交接点。
2. 完成 P1-004、P1-006，关闭注册审核与后端按钮鉴权缺口。
3. 完成 P1-009、P1-010，先把订单到头程任务的可靠链路跑通。
4. 完成 P1-011 至 P1-017，形成真实发运交接快照。
5. 完成 P1-019 至 P1-023，在国内回环验证尾程、轨迹和通知。
6. 完成 P1-027 至 P1-029，通过故障演练后部署国内一期。

海外服务器、海外数据库和正式切流放在国内回环可靠性验收之后，避免在业务闭环尚未形成时同时引入跨国网络问题。