Files
persionalBrand/docs/adr/0004-industry-fork-readiness.md

5.2 KiB

ADR 0003:行业分叉前的领域边界与运行时契约

  • 状态:已采纳
  • 日期:2026-09-21

背景

平台主线是帮助已有业务的个人建立品牌、表达信任并获得咨询或合作。模板需要支持餐饮、咨询、摄影、设计、定制产品等行业的差异,但核心模型不能逐渐变成某个行业的系统。

当前模板安装、字段、业务提供项和动态表单已经存在,但在进入更多行业前发现了几个风险:Service 与 Offering 双轨存在;表单只描述字段,没有描述提交后的业务动作;Booking 使用固定的全行业状态;客户端还缺少稳定的运行时工作空间契约。

决策

1. 固定三层边界

Brand Core       品牌身份、信任、业务展示、联系与咨询
Template Package 行业文案、模块、字段、默认表单和展示配置
Capability       预约、排期、报价、库存、支付等独立业务流程

模板只能提供声明式配置,不能注入任意代码或绕过核心鉴权、品牌隔离、发布状态和数据校验。复杂流程必须作为 capability,由明确的 API、数据模型、权限、后台页面、小程序页面和测试组成。

2. Offering 是核心业务提供项的唯一身份

服务、产品、套餐和订阅统一使用 Offering 表达。预约、咨询表单、公开详情和历史快照都引用 Offering。现有 Service 仅作为迁移期间的兼容入口,不能继续成为新的核心关联对象。

任何业务记录都必须保存名称、价格和关键配置的快照,避免业务提供项修改后历史记录失真。

3. 表单必须声明提交语义

动态表单除了字段定义,还必须声明用途和提交动作,例如:

purpose: inquiry | booking | quote-request
target: brand | offering
submissionAction: create-inquiry | create-booking | create-quote

字段渲染是通用能力,提交后的业务转换由 capability 决定。普通咨询不能隐式变成订单,预约申请也不能依赖客户端自行猜测。

4. 工作流由能力定义,核心只负责生命周期基础设施

核心保留状态、状态变更、权限、审计和非法跳转保护。具体状态集合和转换规则由 workflow/capability 声明,并带有稳定的 workflowKey 与 workflowVersion。

餐饮预约、摄影档期、定制生产可以拥有不同状态机,不把所有行业状态合并为一个全局 enum。现有 Booking 状态作为默认基础 workflow 迁移,不继续扩展为跨行业状态大杂烩。

5. 后端输出运行时工作空间契约

客户端不根据 templateKey 编写行业分支。后端将品牌实际配置编译为稳定的 runtime workspace view,至少包含模块 key、模块类型、schema version、展示配置、数据来源和已启用能力。客户端只依赖该契约渲染页面和行动入口。

模板 key 只用于安装、版本管理和后台管理,不作为小程序业务逻辑的分支条件。

6. 可扩展 JSON 必须有版本和校验边界

Offering.config、模块配置、表单字段快照和 workflow 扩展数据必须有 schema version,并由对应模板或 capability 的 validator 校验。条件显示只能使用受限的声明式规则,禁止执行任意表达式。

7. 核心品牌模型不得包含行业字段

营业时间、配送说明、服务区域、拍摄档期等字段归入模板字段或 capability 配置。BrandProfile 只保留跨行业的身份、定位、表达和联系信息。迁移旧字段时必须保留读取兼容和明确的默认映射。

实施顺序

  1. 盘点 Service 与 Offering 的读写路径,建立 Offering 兼容适配并迁移核心关联;
  2. 从品牌核心模型识别并迁移行业字段;
  3. 为 InquiryForm 增加用途、目标对象和提交动作,补齐历史快照与授权测试;
  4. 建立 workflow 定义、状态转换和状态历史的最小契约,保留现有基础预约行为;
  5. 定义 runtime workspace response schema,并让 Admin 与小程序只消费该契约;
  6. 为模板和 capability 增加 schema version、validator、预览、升级和回滚测试;
  7. 以第二个真实行业模板做验收,验证不修改核心模型、不增加模板判断分支即可完成展示和表单接入。

验收标准

  • 新增一个行业模板不需要修改个人品牌核心表;
  • 同一个 Offering 在公开展示、表单、预约和历史记录中保持一致身份;
  • 同一个表单可以明确产生咨询、预约或报价请求;
  • 两个行业可以使用不同 workflow,且核心 API 不增加行业专属状态;
  • 小程序不出现基于行业 key 的业务分支;
  • 模板升级不会覆盖用户内容,旧快照仍可解释历史数据;
  • 每个新增 endpoint 都覆盖未授权、错误角色、成功、校验失败和品牌隔离测试。

后果

这会增加一次兼容迁移和运行时契约设计成本,但能阻止 Service、餐饮字段和固定订单状态继续侵入核心。模板扩展速度会依赖 schema 和 validator 的质量;这属于可控的工程成本,换取后续行业分叉时的数据一致性和客户端稳定性。