00文档信息与读者

本文档定义五个核心业务域的数据接口：会员（member）、商品（product）、订单（order）、结算（settlement）、支会（chapter），并增补卖家入驻与审核流（seller / audit，§9，会员中枢已实现）与 Medusa 集成（vendor §9.5 / customer 归组 §9.6，双模式）。所有金额、折扣、分账一律由服务端计算；前端展示层只消费返回值。

01系统架构与职责边界

1.1职责边界（谁负责什么）

02通用技术约定

2.1基础地址

2.2认证与身份

• 请求头 Authorization: Bearer <keycloak_jwt>；JWT subject = Keycloak user_id（uuid），即 members.user_id 预留锚点；SSO 接入（Phase 2 Keycloak）后回填，member_no 保持不变
• 游客购物车：不携带 JWT，服务端签发匿名 cart_id；登录/绑定会员后调 POST /carts/:id/attach 合并
• 运营后台走 Keycloak realm 角色：org-admin / platform-admin（realm_access.roles 声明，会员中枢按此鉴权）；会员中枢另有 AUTH_MODE=off|required 开关——off 放行不解析（Phase 1 演示默认），required 校验 Bearer 令牌 + 角色

2.3语言与国际化

• 请求头 Accept-Language: zh-CN | ja-JP | ko-KR | en-US
• 推荐：多语字段返回全量对象 { "zh": …, "ja": …, "ko": …, "en": … }（字段名后缀 _i18n），前端本地选言（原型已按此实现，切换语言不发请求）
• 错误信息同理：message_i18n 返回全量四语

2.4时间 / 货币 / 精度

• 时间：ISO 8601 带偏移，统一北京时间，如 2026-09-28T14:32:08+08:00；展示层一律北京时间
• 货币：Phase 1 全场景人民币 CNY；金额字段命名 *_cny，JSON number 两位小数；计算精度为"分"（round half-up），多币种为 Phase 2+

2.5分页 / 幂等

• 分页：?page=1&page_size=20（max 100）；响应外层 { items: [...], page, page_size, total }
• 幂等：下单 / 支付 / 退款请求必须携带 Idempotency-Key（uuid）；服务端 24h 内去重，重复请求返回首次结果

2.6错误结构

{
  "error": {
    "code": "MEMBER_TYPE_SCHEMA_INVALID",
    "message_i18n": { "zh": "动态字段校验失败：手机号格式不正确", "ja": "…", "ko": "…", "en": "…" },
    "trace_id": "01J8X9K2M3Q7Z",
    "details": [ { "field": "mobile", "rule": "pattern" } ]
  }
}

03数据模型总览

/* 关系总览（→ 一对多，⇢ 快照冻结） */
MemberType 1 ──✦── Member          入会时冻结 type_snapshot（模板升版不回写）
Chapter    1 ────── Member          会员归属支会（分账路由键）
Chapter    self-ref                 parent_id 组织树：总会 → 双区 → 九支会
Member(ENT)1 ──0..1─ SellerProfile   canSell 类型方可入驻（Hub 实现，§9）；member_id 唯一
SellerProfile1 ────── AuditTask      target_type=0 卖家资质（无外键，target_id 弱引用）
Member     1 ────── AuditTask      reviewer_id 审核人留痕（可空）
Category   1 ──✦── Product        商品（Commerce 侧）
Member     1 ────── Order ──1── OrderItem   OrderItem 冻结 title/price 快照
Order      1 ────── Settlement ── Split[] SplitRule 版本化，尾差由支会吸收

04会员模块（Hub）

4.1实体定义

interface Member {
  member_id: string;      // uuid，内部主键
  member_no: string;      // OKTA-ENT-BJ-2026-00001，对外唯一，不变
  user_id: string | null;// Keycloak subject（SSO 锚点，Phase 2 回填）
  display_name: string;
  email: string | null;  phone: string | null;
  type_code: 'IND'|'STU'|'PRO'|'ENT'|'HON';
  type_version: number; // 快照对应的模板版本
  type_snapshot: TypeSnapshot;  // 入会事务内冻结，见 4.2
  chapter_id: string;    // 归属支会 → 分账路由键
  status: 'active'|'pending'|'expired'|'frozen';
  joined_at: string; valid_until: string; created_at: string; updated_at: string;
}

interface TypeSnapshot {   // 只增不改；模板升版不回写
  type_code: string; version: number; name: string;
  discount_rate: number; benefits_count: number; captured_at: string;
}

interface MemberType {
  type_code: string; version: number;    // schema 变更自动递增
  name_i18n: I18nText; annual_fee_cny: number; discount_rate: number;
  requires_verification: boolean; invitation_only: boolean;
  status: string;
  benefits: I18nText[];          // 权益文案（四语）
  dynamic_schema: object | null;   // Ajv JSON Schema，注册时校验 dynamic_fields
}

members 字段表

member_types 示例值（与原型 data.js 一致）

4.2接口清单

05支会模块（Hub）

5.1实体定义

interface Chapter {
  chapter_id: string;         // ch-bj / ch-tokyo …
  code: string;               // BJ / SH / HZ / SZ / CD / JP / KR / SG / NA / CN-R / INTL-R / HQ
  parent_id: string | null; // 自引用组织树
  region: 'hq'|'domestic-region'|'overseas-region'|'domestic'|'overseas';
  name_i18n: I18nText;
  country_code: string;      timezone: string;  // 支会活动时间展示用
  member_count: number;     // 冗余计数，定时任务刷新
  status: string; sort_order: number;
}

• 组织树固定三层：OKTA 总会（HQ）→ 国内区 / 海外区 → 九个支会（国内 5：北京/上海/杭州/深圳/成都；海外 4：东京/首尔/新加坡英语区/北美英语区）
• 删除约束：仍有会员挂靠的支会不可删除，必须先迁移会员；海外支会 timezone 用于活动时间换算展示
• 会员的 chapter_id 是分账路由键——买家归属支会收取 4% 支会基金（与卖家支会无关，见 §8.3）

5.2接口清单

06商品模块（Commerce）

6.1卖家 Seller（入驻审核制）

interface Seller {
  seller_id: string;
  member_no: string | null;  // 企业会员编号（ENT）；官方直营 = null
  kind: 'official'|'member';
  shop_name_i18n: I18nText;
  chapter_id: string;         // 店铺归属支会（与买家支会无关）
  status: 'pending_audit'|'active'|'suspended';
  applied_at?: string; approved_at?: string;
}

• 入驻前置校验（双服务协作）：Commerce 调 Hub 校验 member_no 存在且 type_code = 'ENT'、status=active
• 状态机：pending_audit → active →（违规）suspended；suspended 店铺全部商品强制 offline

6.2商品 Product 与类目

interface Product {
  product_id: string; sku: string;      // sku 对外唯一：OKTA-M-101 / YX-T-401 / AL-H-402 …
  seller_id: string; category_id: string;   // cat-merch/周边 · cat-course/课程 · cat-event/活动 · cat-curate/甄选
  title_i18n: I18nText; summary_i18n: I18nText;
  price_cny: number;                // 零售价
  member_pricing: 'type_discount';   // Phase 1：会员价 = price_cny × 会员 type_snapshot.discount_rate
  stock: number;                    // 数字商品用哨兵值 999（不递减）
  status: 'draft'|'pending_audit'|'active'|'offline';
  created_at: string;
}

6.3接口清单

07订单模块（Commerce）

7.1购物车 Cart

interface Cart {
  cart_id: string;
  member_no: string | null;         // 游客 = null；绑定后合并
  items: { product_id: string; qty: number }[];
  updated_at: string;
}

• 金额预计算：GET /carts/:id 响应附带 pricing（每行 unit_price_cny 按会员快照折扣 + 汇总 amounts），前端不再自行计算折扣（原型 Store.totals 为本地替身）
• 加购/改量时服务端校验库存（数字商品哨兵 999 恒通过）

7.2订单 Order 与订单行

interface Order {
  order_no: string;              // OKTA-SO-YYYYMMDD-NNNNN，日序号
  member_no: string | null; chapter_id: string | null;  // 买家归属支会 → 分账路由
  delivery: { name: string; phone: string; region: string; detail: string };
  items: OrderItem[];
  amounts: { goods_subtotal: number;        // 折后商品金额 = 分账基数
             member_discount_cny: number; shipping_cny: number; payable_cny: number };
  status: 'pending'|'paid'|'shipping'|'completed'|'cancelled';
  payment: { channel: 'wechat_pay'; state: 'unpaid'|'paid'|'refunded';
             prepay_id?: string; paid_at?: string };
  created_at: string;
}
interface OrderItem {
  product_id: string; sku: string; qty: number;
  unit_price_cny: number; line_total_cny: number;
  title_snapshot_i18n: I18nText;   // 下单时标题快照：改价/改名/下架不影响历史订单
}

• 状态机：pending → paid → shipping → completed；pending → cancelled（用户取消或超时 2 小时未支付自动关闭）；paid → refunded 走退款流程（Phase 2）
• 运费规则（参数化存储，禁止硬编码）：满 ¥199 免运费（游客）/ 满 ¥99 免运费（会员），未满收 ¥12；运费不参与分账
• 下单即快照：unit_price、title、分账规则版本全部写入订单行/结算单，后续模板或规则调整不影响存量订单

7.3接口清单

08结算模块（Commerce · 分账）

8.1分账规则 SplitRule（版本化）

interface SplitRule {
  rule_id: string;                      // 当前生效：rule-global-v3
  scope: 'global'|'chapter'|'seller';    // Phase 1 仅 global；预留支会/卖家级覆盖
  seller_ratio: number;                 // 0.90
  platform_ratio: number;               // 0.06
  chapter_ratio: number;                // 0.04
  version: number; effective_from: string; status: string;
  // 约束：三 ratio 之和必须 = 1.00（服务端校验）；生效中规则不可改，只能新建更高 version
}

8.2结算单 Settlement 与分账明细

interface Settlement {
  settlement_id: string; order_no: string;
  base_amount_cny: number;       // = order.amounts.goods_subtotal（运费不分账）
  rule_version: number;           // 成单时冻结的规则版本
  status: 'preview'|'pending'|'settled'|'partial_refunded';
  splits: SettlementSplit[];
}
interface SettlementSplit {
  payee_type: 'seller'|'platform'|'chapter';
  payee_id: string;              // seller_id | 'okta-platform' | chapter_id
  ratio: number; amount_cny: number;
}

8.3计算规则（与原型 DB.split / settlementPreview 严格一致）

8.4接口清单

09卖家入驻与人审工作台（会员中枢 · Phase 1 已实现）

本章节与会员中枢实际代码一一对应（services/member-hub/src/seller / src/audit / src/vendor），前端原型 seller.html / admin.html 已按此接线。与 v1.0 初版「卖家归 Commerce」的设想相比，Phase 1 将入驻档案与审核流整体落位 Hub；v1.2 起 vendor 对接双模式亦已实现（§9.5）：审核通过自动创建 Medusa vendor 并回填 medusa_vendor_id，闭环「通过 → 开店」。

9.1实体定义（seller_profiles / audit_tasks）

interface SellerProfile {          // 表 seller_profiles（Hub 库）
  id: string;                        // bigint → JSON 字符串
  memberId: string;                  // member_id 唯一：一名会员仅一份店铺档案
  storeNameI18n: { zh: string; ja?; ko?; en? };  // zh 必填非空（服务端校验）
  credentials?: Record<string, unknown>;      // 资质材料 JSON（营业执照 / 授权书等）
  medusaVendorId: string | null;     // Medusa vendor 唯一键（varchar 64；审核通过自动回填，§9.5）
  rating: number;                     // decimal(3,2)，默认 0
  auditStatus: 0 | 1 | 2 | 3;         // 0 待审 1 通过 2 驳回 3 冻结
  createdAt: string; updatedAt: string;
}
interface AuditTask {               // 表 audit_tasks（Hub 库）
  id: string;
  targetType: 0 | 1 | 2;               // 0 卖家资质 1 商品 2 内容
  targetId: string;                    // 目标主键（无外键，弱引用；卖家任务= seller_profile.id）
  lang: 'zh'|'ja'|'ko'|'en';           // 审核语言上下文，默认 zh
  machineFlags?: object;               // 机审输出；Phase 1 = { machine:'skipped', note:'未接内容安全 API，直通人审' }
  status: 0|1|2|3|4|5;                // 0 草稿 1 机审中 2 人审队列 3 已通过 4 已驳回 5 已冻结
  result: 1 | 2 | null;                // 1 通过 2 驳回（未裁决为 null）
  reason: string | null;               // 驳回理由 ≤500 字
  reviewerId: string | null;           // 按 token sub 回查 member 留痕；查不到留空不阻塞
  createdAt: string; updatedAt: string;
}

• 开店资格：以入会时 type_snapshot.canSell 为准（快照缺省回退类型模板 can_sell）——与会员价同规则，运营改模板不影响存量会员资格
• 事务不变量：档案 + 任务在同一事务内创建；裁决与档案联动也在同一事务内，失败整体回滚
• 索引：audit_tasks(status, lang, target_type)（idx_audit_queue）支撑队列过滤；seller_profiles.member_id、medusa_vendor_id 唯一

9.2双状态机与迁移规则（audit-flow.ts 纯函数，前端同构复刻）

• 终态锁定：任务 3 / 4 不可再裁决、不可冻结（409 状态机锁定）——裁决不可撤回，申诉走新任务
• 档案互斥：待审（0）重复申请 → 409；已通过（1）重复申请 → 409；已冻结（3）申请 → 403（联系运营）
• Phase 2 商品 / 内容送审接入后，target_type=1/2 走 机审（1）→ 人审队列（2）同套状态机

9.3接口清单 · 卖家端（4 个）

9.4接口清单 · 人审工作台（5 个，全部 org-admin / platform-admin）

9.5Medusa vendor 对接（双模式 · v1.2 已实现）

审核通过后由中枢事务外自动创建 Medusa vendor 并回填 seller_profiles.medusa_vendor_id，闭环「通过 → 开店」。实现位于 src/vendor（vendor-flow.ts 纯函数 + medusa.service.ts 适配器 + vendor.service.ts 编排），运营后台 admin-web 已提供重试与手动绑定操作。

• 幂等语义：medusa_vendor_id 已回填时同步直接返回 skipped:'already-synced'，不重复创建；演示 id 由 member_no 派生，天然幂等
• 失败不阻塞裁决：live 网络失败抛 503，但裁决已落库不回滚，错误经 review 响应的 vendorSync:{ ok:false, error } 返回；后台可重试同步或手动绑定真实 id
• 状态机守卫：仅档案 auditStatus=1（已通过）可同步 / 绑定；其余状态 409
• 来源判定（前端徽标同构）：vendor_local_ 前缀 → 演示回填；其余 → Medusa 真实。手动绑定校验拒绝演示前缀（由系统生成，运营须粘贴 Medusa 后台真实 id，≤64 字符）
• vendor 显示名：store_name_i18n zh → en → OKTA Store <member_no> 逐级回退

9.6Medusa customer 归组同步（双模式 · v1.3 已实现）

会员注册事务提交后，由中枢事务外自动创建 Medusa customer 并按会员类型归入 customer group（会员价定价分组依据），回填 member.medusa_customer_id，结果随注册响应的 customerSync 字段返回。实现位于 src/customer（customer-flow.ts 纯函数 + customer.service.ts 编排，复用 medusa.service.ts 同一双模式实例），运营后台「会员名册」页已提供重试同步与手动绑定操作。

• 幂等语义：medusa_customer_id 已回填时同步直接返回 skipped:'already-synced'，不重复创建；演示 id 由 member_no 派生，天然幂等
• email 解析（逐级回退）：extData.email → extData.contact_email → 登录令牌 email → <user_id>@member.okta.local 派生占位；公司名 extData.company_name 优先，回退 OKTA 会员 <member_no>
• 归组约定（双端锚点）：分组 metadata { source:'okta-hub', typeCode }，显示名 = 类型中文名（zh → en → 类型编码回退）；同类型会员共享一个分组；local 模式归组无网络语义，跳过
• 失败不阻塞入会：live 网络失败抛 503，但注册已落库不回滚，错误经注册响应的 customerSync:{ ok:false, error } 返回；后台可重试同步或手动绑定真实 id
• 来源判定（前端徽标同构）：customer_local_ 前缀 → 演示回填；其余 → Medusa 真实。手动绑定校验拒绝演示前缀（由系统生成，运营须粘贴 Medusa 后台真实 customer id，≤64 字符）

10前端 Mock ↔ 真实接口映射（交接核心表）

原型的每个本地替身函数对应唯一真实接口；替换顺序建议自上而下（价格/折扣最先，支付最后）。

11对接注意事项与遗留项

A附录 · 演示数据与变更记录

A.1演示数据说明（assets/js/data.js）

• 会员 2 名（ENT 星阑科技 / IND 林晓）+ 类型 5 种（四语模板）；11 件商品（4 类目、3 店铺）；支会树 12 节点（总会 + 双区 + 9 支会）；演示订单 3 笔（shipping / completed / pending 各一）
• 演示订单的金额与分账数字均按 §8.3 规则计算，可直接作为单元测试断言用例（如 base 391.02 → 351.92 / 23.46 / 15.64）
• 原型身份切换器（游客 / IND / ENT）用于验收「折扣随身份变化」的定价链路
• 演示审核任务：内置 4 条只读样例（覆盖已通过 / 已驳回 / 已冻结等终态）+ 本机申请镜像任务（可裁决），与 seller.html 八态渲染、admin.html 六状态看板联动，可直接作为审核流验收用例

A.2变更记录