From 3524a6f322e1e6028b62f1d0a94659aec324a931 Mon Sep 17 00:00:00 2001 From: que01 Date: Sun, 20 Sep 2026 17:33:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=E6=A8=A1=E6=9D=BF?= =?UTF-8?q?=E9=85=8D=E7=BD=AE=E5=8C=85=E4=B8=8E=E6=8F=92=E4=BB=B6=E8=BE=B9?= =?UTF-8?q?=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...02-template-package-and-plugin-boundary.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/adr/0002-template-package-and-plugin-boundary.md diff --git a/docs/adr/0002-template-package-and-plugin-boundary.md b/docs/adr/0002-template-package-and-plugin-boundary.md new file mode 100644 index 0000000..57f4199 --- /dev/null +++ b/docs/adr/0002-template-package-and-plugin-boundary.md @@ -0,0 +1,69 @@ +# 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. 评估第一个真正需要插件的行业流程,再设计插件契约。