# ADR 0003:行业分叉前的领域边界与运行时契约 - 状态:已采纳 - 日期:2026-09-21 ## 背景 平台主线是帮助已有业务的个人建立品牌、表达信任并获得咨询或合作。模板需要支持餐饮、咨询、摄影、设计、定制产品等行业的差异,但核心模型不能逐渐变成某个行业的系统。 当前模板安装、字段、业务提供项和动态表单已经存在,但在进入更多行业前发现了几个风险:`Service` 与 `Offering` 双轨存在;表单只描述字段,没有描述提交后的业务动作;`Booking` 使用固定的全行业状态;客户端还缺少稳定的运行时工作空间契约。 ## 决策 ### 1. 固定三层边界 ```text Brand Core 品牌身份、信任、业务展示、联系与咨询 Template Package 行业文案、模块、字段、默认表单和展示配置 Capability 预约、排期、报价、库存、支付等独立业务流程 ``` 模板只能提供声明式配置,不能注入任意代码或绕过核心鉴权、品牌隔离、发布状态和数据校验。复杂流程必须作为 capability,由明确的 API、数据模型、权限、后台页面、小程序页面和测试组成。 ### 2. `Offering` 是核心业务提供项的唯一身份 服务、产品、套餐和订阅统一使用 `Offering` 表达。预约、咨询表单、公开详情和历史快照都引用 `Offering`。现有 `Service` 仅作为迁移期间的兼容入口,不能继续成为新的核心关联对象。 任何业务记录都必须保存名称、价格和关键配置的快照,避免业务提供项修改后历史记录失真。 ### 3. 表单必须声明提交语义 动态表单除了字段定义,还必须声明用途和提交动作,例如: ```text 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 的质量;这属于可控的工程成本,换取后续行业分叉时的数据一致性和客户端稳定性。