总体业务设计与技术架构

00前置约束：本设计建立在以下客观事实之上

这一节是整份文档的地基。后面每一处设计决策都能追溯到这里的某一条。 凡标注「已核实」的来自官方文档或公开判例；标注「量级」的是估算。 如果某一条将来发生变化，对应的设计需要重新评估——这是本表存在的意义。

00.1 市场与行业惯例（决定业务设计）

00.2 监管红线（决定资金与渠道设计）

00.3 开源件真实边界（决定技术架构）

说明：EspoCRM/Chatwoot「收运维部署费」在 AGPL/MIT 下合法（Red Hat 模式）——自由≠免费， 许可证禁止的是不给源码，不是禁止收费。前一版文档中"建议弃用 EspoCRM"的判断已在本版撤回。

00.4 平台 API 能力现状（决定哪些能自动化）

01业务设计

1.1 定位与价值主张

这一定位把四件事统一成一句：客户价值（不花钱）= 独特能力（摊位对冲）= 系统价值（全链路可视）= 收入来源（摊位抽成）。 它同时也是销售话术——竞品（会小二这类）能帮你找场地、砍价，但不管你的成本怎么收回来。

1.2 角色图谱

1.3 业务全景

1.4 业务域划分（收敛后 6 个）

1.5 核心业务流程：培训会全生命周期

这是 D1 的主干状态机。你要求的"每个节点客户在 Web 和手机端都能看到状态和进度"， 就是由这一条状态机 + 一个统一进度接口实现的（技术方案见 2.7）。

1.6 渠道体系

1.7 结算与分佣

承办方是交付方不是销售方，行业惯例拿"管理费/成本加成"而非"佣金"。三个组成部分：

平台侧收入参数

1.8 合规内建（不是上线前检查，是设计约束）

02技术架构

2.1 相对前一版的 6 处实质调整

2.2 总体分层架构

2.3 技术栈与开源件边界

2.4 部署形态与版本治理

你要同时支撑 SaaS 多租户和给客户私有化部署。必须同一套代码，否则版本必然分裂。

2.5 模块边界规则（业务线长的唯一解法）

你有 6 个业务域，业务线确实长。但长不等于要拆微服务——5~8 人团队拆开， 首年精力会耗在分布式事务上，而真正的难点在状态机和结算。正确解法是在单体内部划死边界。

// 目录结构（模块内自洽，模块间靠接口与事件）
src/
  platform/          // 横切能力：iam, workflow, rule, verification_code, notify
  modules/
    event/           // D1 活动：controller / service / repository / state-machine
    booth/           // D2 摊位招商
    resource/        // D3 资源与核销
    channel/         // D4 渠道与派单
    settlement/      // D5 结算与分账
    growth/          // D6 AI 与获客
  adapters/          // 外部依赖：dida, wechat-pay, amap, sms, oss
  shared/            // 通用工具

// ESLint 边界规则（CI 强制）
"no-restricted-imports": {
  "patterns": [{
    "group": ["**/modules/*/repository/**"],
    "message": "禁止跨模块直接访问 Repository，请通过模块 Service 接口"
  }]
}

2.6 多租户与数据分级

2.7 工作流引擎与统一进度接口

你要的"Web 和手机端都能看到每个节点状态和进度"，靠一套引擎 + 一个接口实现，不做五套。 这是整个产品体验一致性的前提，也是渠道管控的实现方式（节点的时效与质量被记录并计分）。

// 状态机用数据定义，不写死在代码里 —— 流程会变，改配置不改代码
{
  "flow": "training_event",
  "nodes": [
    { "id": "requirement",  "name": "需求提交", "owner_role": "customer",   "sla_hours": 24 },
    { "id": "proposal",     "name": "方案与报价", "owner_role": "platform",   "sla_hours": 72 },
    { "id": "booth_sales",  "name": "摊位招商", "owner_role": "contractor", "sla_hours": 336 },
    { "id": "resource_lock","name": "资源锁定", "owner_role": "contractor", "sla_hours": 120 },
    { "id": "enrollment",   "name": "学员报名", "owner_role": "customer",   "sla_hours": 168 },
    { "id": "on_site",      "name": "现场执行", "owner_role": "contractor", "sla_hours": 48 },
    { "id": "settlement",   "name": "结算复盘", "owner_role": "platform",   "sla_hours": 168 }
  ]
}

// 统一进度接口 —— H5 与 Web 共用，响应结构完全一致
GET /api/v1/progress/:aggregate_id
{
  "aggregate_type": "training_event",
  "overall": { "percent": 62, "status": "doing", "next_node": "resource_lock" },
  "nodes": [{
    "id": "resource_lock",
    "status": "blocked",
    "owner": { "type": "contractor", "name": "XX会展" },
    "sla_due_at": "2026-10-02T18:00:00+08:00",
    "blockers": [{ "code": "VENUE_DEPOSIT_UNPAID", "desc": "场馆定金未付", "resolver": "customer" }],
    "evidence": [{ "type": "contract", "url": "..." }]
  }]
}

2.8 结算引擎

// 参数覆盖优先级：单向覆盖，禁止多级相乘（连乘算出来的数没人看得懂，对账必吵架）
resolve_rate(contractor_id, city_code, event_id) {
  if (r = rule.find(event_id))           return r   // 单场特批
  if (r = rule.find(contractor.grade))   return r   // 承办方等级
  if (r = rule.find(city_code))          return r   // 城市
  return GLOBAL_DEFAULT                          // 全局默认 15%
}

// 快照结构（订单创建时冻结，之后永不随配置变化）
settlement_snapshot = {
  "service_rate":      0.15,   // cost-plus
  "saving_share":      0.30,   // 成本节约奖励
  "resource_share":    0.015,  // 资源引入分成
  "platform_fee":      0.10,
  "booth_commission":  0.20,
  "rule_version":      "2026-09-17T10:00:00Z",
  "resolved_by":       "city:GZ"
}

2.9 外部依赖 Adapter 与人工兜底

你对接的外部能力有一半不可靠或不存在（00.4）。核心原则是：每一个外部调用都必须有一条人工通道。

// 统一 Adapter 契约：每个外部依赖实现同样五个方法
interface SupplierAdapter {
  search(req):       Promise<Offer[]>   // 查询
  confirm(ref):      Promise<Hold>      // 锁价/锁库存
  book(hold):        Promise<Order>     // 下单
  cancel(orderId):   Promise<void>      // 取消
  query(orderId):    Promise<Status>    // 查单（含补查）
}

// 履约双通道：API 失败或超时 → 自动降级为工单，客户看到"处理中"而不是"系统错误"
fulfil_mode: 'API' | 'MANUAL'

try   { return await adapter.book(hold) }
catch(e) {
  await ticket.create({ type:'MANUAL_FULFIL', payload:hold, reason:e.code })
  return { status:'processing', fulfil_mode:'MANUAL' }   // 业务不中断
}

2.10 AI 侧架构

两条产品线必须分开命名、分开定价（S5）：

2.11 可观测性与运维

03核心数据模型

04交付路线图

05成本量级

以下均为量级估算，用于判断结构是否合理，不可直接用于预算。 实际数字随城市、薪资水平、谈判结果变化很大。

判断公式（决定是否自建 GPU）：「每月 API 账单 × 18~24 个月」 vs 「GPU 整机价 + 电费」。 前者大则自建划算。大多数办公场景在单客户规模下API 更划算——真私有化的价值在数据合规而非省钱，这两件事要分开算。

06红线清单（上线前逐条复核）

07待你拍板

07.1 本件未能验证的部分（不掩饰）

• 「二线城市全年约 50 场百人级付费培训会」是量级推算，没有可靠公开来源， 按"场地数 × 使用频次 × 品类占比"推得，误差可能 ±50%。它只用于说明量级关系，不能用于预算。 真实数字只能靠 P1 在目标城市实地问出来。
• 微信分账限额突破的实际成功率与周期未核实。我确认了默认上限的存在， 但能否突破、需要什么条件取决于商户资质与谈判——直接问支付服务商经理比查文档快。
• EspoCRM 商业授权无公开报价，需联系官方。若你决定深度使用，这是必问项。
• 行业惯例数字来自海外与第三方评测（活动公司毛利/净利、DMC 收费、SaaS 渠道分成）， 国内实际水平可能有偏差，建议找 2~3 家本地活动公司聊一次验证。
• 涉及监管的判断（二清、特许经营、数据合规）是风险提示，不是法律意见， 协议文本仍需律师审阅。