Files
persionalBrand/docs/adr/0015-template-build-time-composition.md
que01 55989a5dfe fix: 修复模板页面跳转并移除无入口的下单页
新增运行时 openPage/takePageQuery,tabBar 页自动使用 switchTab 并传递参数
- 编译器写入 tabPages,并拒绝 navigateTo/redirectTo 到 tabBar 页或 switchTab 带参数
- 阿成首页、套餐、出摊、主理人、详情、记录、成功页跳转统一改用 openPage
- 套餐筛选改用后台业务提供项分类;详情跳咨询时携带业务提供项
- 移除 capability-booking:小程序无入口且依赖已删除的 /public/brand,需求由咨询表单覆盖"
2026-09-27 10:10:23 +08:00

40 lines
3.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ADR 0015:模板采用构建时叠加编译
## 背景
平台需要支持大量行业和视觉风格不同的小程序模板。把所有模板代码放在 `apps/miniapp`,再通过运行时分支选择,会让壳持续膨胀、模板之间互相污染,也无法可靠验证某个品牌最终打开的页面。
## 决策
`template:dev` 采用三层构建时叠加:
1. `apps/miniapp` 只提供品牌无关的运行时、通用 UI、公共页面和 TDesign 依赖。
2. `packages/capability-*` 提供独立业务流程页面,由模板 manifest 的 `requiredCapabilities` 声明引入。
3. `packages/template-*` 提供完整视觉模板页面、组件、资源和 `app.json` 窗口配置。
编译器按运行时 → 能力包 → 模板包的顺序复制,并对同路径文件执行显式冲突校验。模板只能通过 `overrides` 声明替换下层页面或组件目录。最终生成 `app.json`、`project.config.json`、`runtime-config.js` 和 `template.runtime.json`,产物可直接由微信开发者工具打开。
品牌 slug、API 地址和 AppID 是构建参数;开发构建允许通过 storage 覆盖 API 和品牌,生产构建必须显式提供并使用 HTTPS API。模板切换不在小程序运行时完成,而是在构建时选择模板包。
## 替代方案
- 运行时携带全部模板并按 `templateKey` 分支:代码和资源随模板数量线性膨胀,容易混用,放弃。
- 运行时下载 WXML/JS 模板:微信小程序安全和编译模型不支持,放弃。
- 每个模板独立复制完整小程序:公共能力重复、修复无法统一,放弃。
## 与既有 ADR 的关系
本决定只替换"小程序如何选择和渲染模板",不改变业务数据、能力和兼容性声明:
- **ADR 0005**:替换第 3 节中"小程序只消费 Runtime Workspace 的 `modules`/`theme` 并按模块渲染"以及 Phase 2 的"模块顺序、可见性和模块变体"。Runtime Workspace 仍是品牌、Offering、表单、能力的数据契约,但页面结构由模板包在构建时决定。第 4 节 Capability Plugin 保持,并新增小程序页面以 `packages/capability-*` 形式交付。
- **ADR 0008**:替换迁移计划第 3 步"Miniapp 页面按页面 schema 和模块 registry 渲染"。模块 registry 已退役,模板包直接提供页面和组件;manifest 的数据槽位、资源槽位和安装边界保持。
- **ADR 0009**:`supportedIndustryTemplates` 兼容声明保持有效。其中"实际切换"只影响后台记录和 Runtime Workspace,不会改变已构建的小程序。
## 后果
新增模板只需新增 package 和 manifest,不需要改 compiler 或 runtime。模板包需要自行提供 manifest 声明的页面四件套和 tab 资源,编译测试会阻止缺页、缺图标、组件引用或 `require` 路径错误。后台视觉模板切换不会直接改变已构建小程序,后台切换历史和回滚属于后续治理任务。
## 迁移计划
阿成、林境两个模板已迁移。`booking` 下单页曾作为第一个能力包迁入 `packages/capability-booking`,但小程序中没有入口、依赖已删除的 `/public/brand` 接口,且需求已由咨询表单覆盖,因此已移除;能力包层机制保留,后端 Booking 的去留另行决策。`packages/template-compiler/test/fixtures/template-drill-consultant` 是第二行业演练模板,只用模板包自有页面和运行时通用组件,作为"新增行业不改 compiler/runtime"的回归门禁。每个新增模板必须通过 `pnpm template:check`(契约校验、compiler 产物校验、全部模板自动发现编译)后才能进入目录 registry。