NEXAAI / STM
V2 · 2026.07.13
System & Technical Milestone · 第二版

最新架构蓝图，代码闭环已完成。

本报告汇总最近两轮开发：第一轮完成平台蓝图的核心交易、资格、合规、结算与多端闭环； 第二轮补齐按经销商独立控制商品发布审核。截至提交 629c354b，数据库迁移、Backend Workflow、Admin、Vendor 和自动化质量门禁已贯通。

代码与自动化门禁：通过 基线提交：6d0c9361 增量提交：629c354b 分支：dev
Verification Evidence

最终验证证据

最终重新执行根目录 pnpm run verify:local，覆盖 lint、typecheck、应用测试、Backend 单元测试、脚本测试和生产构建。

Backend SuitesPASS
209全部通过
Backend TestsPASS
1,4300 failed
Script TestsPASS
13Node TAP 全通过
Workspace BuildPASS
8生产构建完成
Blueprint Closure

蓝图闭环矩阵

保持“核心能力模块化、业务变化由 Policy 决策、数据变更进入 Workflow、后端为单一数据源”的架构边界。

01

渠道与资格

统一账号底座，H2B、BTOB、BTOC 的资格与能力按渠道独立判断。

  • H2B 采购商审核门禁
  • 经销商能力和销售渠道约束
02

H2B 交易闭环

封闭采购、五项商品合规、交易状态机与订单关联已经落入独立模块和 Workflow。

  • Licensed custody provider 抽象
  • 交易创建与状态迁移
03

商品发布治理

发布前统一校验图片、变体、库存、配送与 H2B 合规，并增加经销商级管理员审核开关。

  • 开启：proposed → 审核
  • 关闭：直接 published
04

价格口径

阶梯价格不删除，统一关闭执行与展示入口，基础价格继续作为当前单一有效口径。

  • API 与计算开关关闭
  • Admin 编辑入口隐藏
05

增长与结算

推荐人和网红推广保持独立归因；推荐人提现、手工/自动打款与 Finance 账本安全链闭环。

  • 余额与提现校验
  • 支付执行和审计记录
06

多端体验

Admin、Vendor、H2B、BTOB、BTOC 对应功能、状态反馈与三语 i18n 同步落地。

  • SDK + React Query
  • 状态、错误与加载反馈
Two Delivery Rounds

两轮修改总结

第一轮建立平台主闭环，第二轮把商品发布治理下沉到每个经销商，补齐最后一个可运营控制点。

第一轮 · 平台蓝图闭环

6d0c9361 · feat(platform)
CORE
  1. 完成 H2B Trade 模块、状态机、订单/客户/商家关联与后台管理。
  2. 完成商品五项合规、到期门禁、经销商发布前完整性校验。
  3. 完成推荐人结算、提款、打款执行、Finance 账本与安全校验。
  4. 关闭阶梯价格实际执行和 UI，不删除历史模型与代码。
  5. 统一修复 Admin、Vendor、三 Storefront、E2E 和 i18n 链路。

第二轮 · 经销商独立审核

629c354b · feat(product)
CONTROL
  1. 复用 Store Distribution Policy 作为每个经销商的审核开关。
  2. 新增 Listing Review 独立状态，避免覆盖 H2B Compliance。
  3. Vendor 提交、Admin 批准/退回、拒绝意见和重新提交形成闭环。
  4. 审核 Mutation 全部进入可补偿 Workflow，并增加并发条件更新。
  5. 生成并应用数据库迁移，补齐 7 个专项状态机测试和三语 UI。
Dealer Review Flow

经销商商品发布审核流程

开关按 Seller 隔离；关闭审核不会删除记录，而是把 Listing Review 归一为 not_required。

管理员配置在经销商详情页设置是否需要审核。
经销商提交发布前先通过配送、图片、库存与合规校验。
Policy 决策关闭则 published；开启则 proposed / submitted。
管理员审核批准后 published；退回必须填写审核意见。
经销商反馈可查看状态与意见，rejected 商品修改后重新提交。
Architecture Decisions

关键架构决策

Workflow 承载 Mutation
Route 只做 HTTP 适配，业务变更通过 Step、补偿和状态机完成。
Policy 决定业务差异
经销商审核开关位于 Distribution Policy，不把易变玩法写进 Product 核心模块。
Listing 与 Compliance 分离
普通发布审核不复用 H2B 五项合规状态，避免一个流程覆盖另一个流程的审批结果。
后端单一数据源
Admin/Vendor 使用 Medusa JS SDK 访问后端，并通过 React Query 管理缓存刷新。
阶梯价格保留但关闭
相关模型和历史代码仍在；Backend、计算、Storefront 展示和 Admin 编辑入口均由常量关闭。
Acceptance Boundary

“跑通”的准确含义

已经确认

代码已实现、数据库迁移已应用、专项测试已通过、完整 L0 门禁最终退出码为 0；Backend、Admin、Vendor 与各 Storefront 均能通过类型检查和生产构建。因此，从代码集成与自动化质量门禁角度，最新蓝图已形成闭环。

仍需上线前执行

自动化通过不等同于生产环境真人验收。正式上线前仍建议用真实角色和第三方沙箱完成 UAT：经销商 A/B 不同审核策略、管理员退回意见、H2B 合规、真实支付/退款/打款及权限边界。