feat: 收口多品牌与模板构建基础
This commit is contained in:
1 parent
0425a1c672
commit
77224ea51f
317 files changed
+11290
-1158
No files matched your search
@@ -0,0 +1,26 @@
|
||||
# ADR 0009:视觉模板兼容性由 manifest 声明
|
||||
|
||||
## Context
|
||||
|
||||
行业模板负责业务表达,视觉模板负责页面结构与视觉呈现。同一行业会拥有多套视觉模板,但并非每套模板都具备对应的页面变体、资源槽位和能力依赖。此前后台无条件展示全部视觉模板,API 也允许任意行业与视觉组合,无法渲染的组合只能依赖运行时兜底。
|
||||
|
||||
## Decision
|
||||
|
||||
在视觉模板 definition 与 manifest 中增加 `supportedIndustryTemplates`。目录、组合预览和实际切换均通过共享 `isVisualTemplateCompatible` 校验。当前林境模板支持 `personal`、`doors`;极简模板支持 `personal`、`food`、`doors`。
|
||||
|
||||
## Alternatives
|
||||
|
||||
- 在 Admin 前端写行业判断:拒绝,无法约束其他客户端和 API 调用。
|
||||
- 在 Controller 中写 `if (templateKey === ...)`:拒绝,新增模板仍需修改业务代码。
|
||||
- 所有组合都允许并在 Miniapp 运行时降级:拒绝,会把模板设计缺口推迟到用户验收阶段。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 新增视觉模板时必须声明支持的行业模板,后台会自动过滤,API 会自动校验。
|
||||
- 兼容关系是模板包元数据的一部分,可随版本快照记录。
|
||||
- 后续若出现更细粒度的能力差异,可在 manifest 增加槽位或 capability 约束,而无需回到行业分支。
|
||||
|
||||
## Migration
|
||||
|
||||
- 现有两个视觉模板已补齐兼容声明。
|
||||
- 现有品牌配置无需迁移;当前不兼容配置会在下一次保存时被拒绝。
|
||||
@@ -0,0 +1,15 @@
|
||||
# ADR 0010:模板示例内容使用注册表
|
||||
|
||||
## Context
|
||||
|
||||
示例内容导入接口曾直接在 Controller 中写入门窗名称、行业分类、信任内容和咨询字段。新增行业必须修改接口代码,模板声明驱动因此不完整。
|
||||
|
||||
## Decision
|
||||
|
||||
将示例业务项、信任内容、字段和能力归属定义在 `@personal-brand/config` 的 `TemplateSampleContent` 注册表中。Controller 只执行权限、幂等检查、事务和审计。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 新行业只需注册模板示例内容,不需要修改 API Controller。
|
||||
- 示例内容类型在共享配置包中可被 API、后台预览和测试复用。
|
||||
- 当前样例导入接口仍固定迁移门窗示例;后续可将模板 key 纳入请求或从当前安装快照解析。
|
||||
@@ -0,0 +1,15 @@
|
||||
# ADR 0011:示例内容按品牌行业模板选择
|
||||
|
||||
## Context
|
||||
|
||||
示例内容注册表初版已移除 Controller 内的内容硬编码,但接口仍固定读取门窗示例包,个人品牌和餐饮品牌会得到错误的初始化内容。
|
||||
|
||||
## Decision
|
||||
|
||||
示例预览和导入先读取当前品牌的 `templateKey`,再从 `getTemplateSampleContent` 选择对应注册表内容。个人品牌、餐饮、门窗均提供基础示例包。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 新建品牌导入示例时不会跨行业混入文案、字段或能力。
|
||||
- 示例包仍是开发期初始化内容,用户导入后可继续编辑。
|
||||
- 后续模板版本可在注册表中增加版本字段,不需要修改 Controller。
|
||||
@@ -0,0 +1,37 @@
|
||||
# ADR 0012:品牌内容发布生命周期
|
||||
|
||||
## 背景
|
||||
|
||||
当前后台直接修改品牌、业务提供项、信任内容和咨询表单,公开接口会读取这些实时记录。这样无法区分“正在编辑的草稿”和“用户已经看到的版本”,也无法在模板导入、批量修改或误操作后安全预览、发布和撤回。多品牌场景下还必须保证发布版本按 `brandId` 隔离。
|
||||
|
||||
## 决策
|
||||
|
||||
引入品牌级发布版本(`BrandRelease`)作为公开内容的唯一读取边界:
|
||||
|
||||
1. 后台编辑继续写入品牌工作区的草稿数据;草稿不直接影响公开接口。
|
||||
2. 发布时由服务端在事务中校验必填身份、视觉模板兼容性、已启用模块、公开业务项、表单字段和模板能力,然后生成不可变的运行时快照。
|
||||
3. `public/*` 和 `public/workspace` 只读取当前品牌的已发布快照;没有发布版本时返回明确的“尚未发布”状态,不回退到草稿或静态示例数据。
|
||||
4. 每个品牌最多一个当前发布版本,但保留历史版本用于审计和显式回滚。回滚是将历史快照重新发布为新版本,不直接修改草稿数据。
|
||||
5. 模板安装快照与发布快照分别负责不同职责:安装快照记录模板基线,发布快照记录用户可见的完整运行时投影;发布不能覆盖用户草稿。
|
||||
6. 发布、回滚和撤回都必须记录操作者、品牌、版本号、校验结果和时间;公开缓存按品牌发布版本失效。
|
||||
7. 发布前检查、快照读取和版本写入在同一个 Serializable 事务内完成;并发版本冲突有限重试。撤回单独记录 `revokedBy`,不覆盖原发布者。客户提交使用发布快照中的表单字段、业务项名称与报价,同时实时拦截已禁用业务。
|
||||
|
||||
## 不采用的方案
|
||||
|
||||
- 仅在现有表上增加 `published` 布尔字段:无法保证跨表一致性,也不能恢复一组完整内容。
|
||||
- 公开接口继续读取实时表,同时由前端自行判断:客户端无法提供可靠的发布边界,并会造成不同页面读到不同版本。
|
||||
- 复制整套业务表作为发布表:数据重复、迁移成本高,且难以支持模板扩展字段。
|
||||
|
||||
## 后果
|
||||
|
||||
- 需要新增发布版本表、生成快照的应用服务、发布/回滚 API 及集成测试。
|
||||
- 公开接口的响应需要增加 `publication` 元数据和未发布状态;小程序必须展示明确的空状态,而不是静默使用示例数据。
|
||||
- 后台首次配置流程可以围绕“选择模板 → 导入或空白 → 完善内容 → 预览 → 发布”组织,普通用户不需要理解模板内部结构。
|
||||
- 后台目前提供发布前的内容核对,不将其称作小程序视觉预览;最终视觉仍应通过小程序开发者工具验收。小程序不使用本地旧 workspace 兜底,以免撤回后离线缓存继续展示过期内容。
|
||||
|
||||
## 迁移计划
|
||||
|
||||
1. 新增 `BrandRelease` 数据模型和可逆 migration;为现有 demo 品牌生成一次基线发布版本。
|
||||
2. 抽取运行时投影生成器,保证发布快照与当前 `public/workspace` 契约一致。
|
||||
3. 增加发布、回滚、撤回和未发布状态的授权与集成测试,再切换公开接口读取发布快照。
|
||||
4. 后台增加首次配置引导和发布检查清单;通过后再移除公开接口对草稿表的直接读取。
|
||||
@@ -0,0 +1,20 @@
|
||||
# 0013 模板包与构建期生成
|
||||
|
||||
## Context
|
||||
|
||||
视觉模板可能扩展到数百个。将每个模板直接写入 `apps/miniapp` 会造成主工程膨胀、依赖耦合和无法独立回归。
|
||||
|
||||
## Decision
|
||||
|
||||
每个视觉模板是独立 pnpm workspace/npm package。模板包声明 runtime contract、页面入口、导航和能力依赖。构建期由 `template-compiler` 选择一个模板包,生成微信小程序目录;运行时不下载或执行模板代码。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 单次小程序构建只包含一个模板包,控制包体和维护范围。
|
||||
- 本地开发使用 pnpm workspace,不需要先发布私服。
|
||||
- CI/生产构建使用锁定的模板包版本。
|
||||
- Runtime Contract 必须版本化,破坏性变更进入新主版本。
|
||||
|
||||
## Migration plan
|
||||
|
||||
先迁移林境和阿成,再删除 `apps/miniapp` 中模板专属 renderer;公共 runtime 保留在 shell 包中,模板包只消费 Runtime Workspace。
|
||||
@@ -7,6 +7,7 @@
|
||||
- 明确接口的认证要求、角色、品牌隔离和状态转换;
|
||||
- 测试缺少凭证、凭证无效或角色错误,以及成功授权路径;
|
||||
- 测试成功响应、业务校验失败和资源不存在;
|
||||
- 发布与撤回类端点还需覆盖并发版本分配、发布快照与客户提交的一致性;
|
||||
- API Client 方法、请求类型、响应类型和调用页面同步更新;
|
||||
- 状态码、错误 code、错误 message 和 `requestId` 符合统一响应约定。
|
||||
|
||||
@@ -37,6 +38,7 @@
|
||||
## 交付门槛
|
||||
|
||||
- 运行相关 API integration tests;
|
||||
- 集成测试须使用独立 schema 或数据库;不得在默认测试命令中重建开发品牌数据;
|
||||
- 运行 API Client、API 和 Admin typecheck;
|
||||
- 运行 Admin production build;
|
||||
- 运行 `pnpm format:check` 和 `git diff --check`;
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
### 视觉模板
|
||||
|
||||
- `linjing-editorial@1.0.0`:林境建筑画册,适合高端定制和项目型业务。
|
||||
- `minimal-neutral@1.0.0`:极简留白,适合咨询、设计和专业服务。
|
||||
- 当前正式视觉模板包:`linjing-editorial@1.0.0`。个人、餐饮和门窗属于行业数据模板,不是独立视觉模板。
|
||||
|
||||
## 组合规则
|
||||
|
||||
|
||||
Reference in new issue
Block a user