diff --git a/agent.md b/agent.md index cf30556..76cffb3 100644 --- a/agent.md +++ b/agent.md @@ -40,7 +40,7 @@ - Monorepo:`pnpm workspace + Turborepo` - 小程序:原生微信小程序 + TypeScript -- 管理后台:Next.js + TypeScript +- 管理后台:React + TypeScript + Vite;本地使用 Vite proxy,生产使用 Nginx 反向代理 - API:NestJS + TypeScript - 数据库:PostgreSQL - ORM:Prisma @@ -48,6 +48,18 @@ - 后台登录:第一版账号密码,未来可绑定微信身份 - 发布:第一版人工使用微信开发者工具发布 +## 行业分叉前的架构不变量 + +- `Brand Core` 只负责个人身份、信任、业务展示、联系与咨询;行业字段和行业流程不得反向进入核心模型。 +- 模板是声明式配置包,负责行业表达和默认配置;复杂排期、报价、库存、支付和行业状态机属于独立 capability。 +- `Offering` 是服务、产品、套餐和订阅的统一业务身份;`Service` 仅保留为迁移兼容入口,新的核心流程不得建立新的 Service 关联。 +- 动态表单必须声明用途、目标对象和提交动作,不能让客户端根据字段猜测是否创建预约或订单。 +- 订单或预约状态由带版本的 workflow 定义,核心只提供状态、权限、审计和非法跳转保护。 +- 小程序和 Admin 消费后端生成的 runtime workspace contract,不根据 `templateKey` 编写行业分支。 +- 所有扩展 JSON 必须带 schema version,并在 DTO 或 capability validator 边界校验。 + +行业模板扩展前,必须先完成 `docs/adr/0003-industry-fork-readiness.md` 中的 Offering、品牌行业字段、表单动作、workflow 和 runtime workspace 五项收口。 + ## 第一版范围 必须实现: diff --git a/docs/adr/0002-template-package-and-plugin-boundary.md b/docs/adr/0003-template-package-and-plugin-boundary.md similarity index 100% rename from docs/adr/0002-template-package-and-plugin-boundary.md rename to docs/adr/0003-template-package-and-plugin-boundary.md diff --git a/docs/adr/0004-industry-fork-readiness.md b/docs/adr/0004-industry-fork-readiness.md new file mode 100644 index 0000000..84f4e49 --- /dev/null +++ b/docs/adr/0004-industry-fork-readiness.md @@ -0,0 +1,84 @@ +# 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 的质量;这属于可控的工程成本,换取后续行业分叉时的数据一致性和客户端稳定性。