Files
persionalBrand/docs/adr/0002-template-package-and-plugin-boundary.md
T

3.1 KiB

ADR 0002:模板配置包与功能插件边界

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

背景

平台的核心目标是帮助个人构建品牌、表达信任并获得咨询或合作。餐饮、咨询、设计、摄影等行业存在不同的业务表达和流程,但行业差异不应持续侵入个人品牌核心模型。

当前系统已经支持模板安装、页面模块、字段定义、业务提供项和动态咨询表单。如果继续把行业流程直接加入核心 API,平台会逐渐变成耦合严重的行业 CMS,并增加后续迁移成本。

决策

固定核心

所有品牌固定包含以下五类能力,行业模板不能删除或替代:

  1. 品牌身份:我是谁、经历和定位;
  2. 信任内容:资历、作品、案例、反馈和流程;
  3. 业务提供项:服务、产品、套餐和合作方式;
  4. 联系与咨询:基础联系入口和通用咨询;
  5. 品牌表达:视觉、介绍、合作预期和可用状态。

配置包优先

第一阶段的行业能力以配置包交付。配置包可以声明:

  • 默认页面模块;
  • 行业字段定义;
  • 业务类型和展示结构;
  • 咨询表单字段;
  • 默认文案、图片位和视觉配置。

配置包不得注入任意代码,不得绕过核心认证、品牌隔离、发布状态和数据校验。

功能插件分层

只有需要独立业务流程的能力,才在后续升级为功能插件。功能插件必须通过明确契约提供独立 API、后台页面、小程序页面、数据模型、权限和测试,不能直接修改核心领域规则。

模板版本与安装快照

  • 模板由后端内置模板注册表提供;
  • 每个模板拥有稳定的 templateKey 和版本号;
  • 安装模板时,将模板配置复制为品牌自己的配置快照;
  • 模板升级不会自动覆盖品牌已经修改的内容;
  • 升级必须显式执行,并提供变更预览或可回滚策略;
  • 客户端不能自行提交模板定义。

备选方案

  • 将所有行业字段和流程加入核心模型:实现初期较快,但会造成领域耦合,拒绝采用。
  • 立即开放任意代码插件:扩展自由度高,但会扩大安全、版本兼容和租户隔离风险,拒绝作为第一阶段方案。
  • 仅保留静态页面模板:实现简单,但无法覆盖后台配置和行业业务差异,拒绝采用。

后果

  • 核心品牌模型保持稳定,行业模板可以持续增加;
  • 模板安装后的内容归品牌所有,模板升级不会隐式破坏用户配置;
  • 第一阶段需要定义配置包 schema、版本和安装快照逻辑;
  • 复杂行业流程需要额外的插件契约、权限和自动化测试;
  • 当前餐饮模板应逐步整理为配置包示例,而不是继续增加餐饮专属核心字段。

后续计划

  1. 定义模板配置包的 TypeScript schema 和版本约束;
  2. 将现有 personal、food 模板迁移到注册表;
  3. 区分核心模块与模板模块,并保留安装来源和版本;
  4. 为模板安装、升级和回滚补充 API 测试;
  5. 评估第一个真正需要插件的行业流程,再设计插件契约。