# 模板管理与分发交付计划 > 任务 ID:TMP-PLATFORM-001 > > 状态:Phase 0/1/2/3/4/5/6/7 实现已收口;Phase 8 待外部验证 > > 唯一任务入口:本文档 > > 架构决策:ADR 0029:模板管理、导入与分发边界 本文档把模板从本地开发、导出、线上导入、校验、预览、安装到小程序发布的完整工作固化为一个可追踪任务。后续代码、迁移、接口、后台页面、测试证据和已知缺口都必须回到本文登记。本文描述的是目标和实施门禁;没有对应代码、测试和运行证据的条目不能标记为完成。 ## 1. 背景和目标 过去的模板交付把多个层次混在了一起: - 本地分支的代码、线上 release 目录、数据库中的品牌内容、发布快照和微信开发者工具中的代码不是同一份状态; - 行业模板和视觉模板同时存在,但安装、选择和展示依赖分散的注册表与默认值; - 模板有 manifest 和 sample content,却没有完整的导出、线上导入、版本校验和独立预览闭环; - 示例数据只在一次性 seed 或脚本里出现,老品牌升级时不会自动补齐新字段; - 构建、上传、发布的状态被压缩成一个状态,依赖缺失、产物路径错误、日志乱序和重启恢复都可能让后台永久轮询; - 静态 doctor、页面能打开或 mock 成功不能证明真实字段可编辑、保存可重载、发布可见和小程序可上传。 本任务的目标是让平台具备以下稳定流程: 本地模板包开发 -> 确定性校验与导出 -> 线上导入与 checksum 去重 -> 兼容性校验与诊断 -> 按行业选择的独立预览 -> 发布到模板目录 -> 创建或选择品牌 -> 安装精确版本 -> 显式导入起始内容 -> 编辑、保存、重载、发布 -> 使用真实品牌参数构建和上传小程序 -> 升级、冲突处理和回滚 完成标准不是“以后绝不出 bug”,而是每个状态转换都有明确契约、失败路径、可恢复操作和自动化证据;外部微信审核或上传结果必须单独记录,不能用本地 mock 代替。 ## 2. 范围和非目标 ### 2.1 本任务范围 - 建立平台级模板管理页面,和单品牌的内容配置、配置发布页面分离; - 支持从仓库中的模板包生成可校验、可复现的导出包; - 在线导入模板包,进行文件安全检查、manifest/schema 校验、运行时和 renderer 兼容性校验; - 按行业选择可预览的模板组合,并使用模板包内演示数据通过真实 Runtime 投影; - 管理模板版本的导入、校验、目录发布、撤回和审计; - 在品牌上下文安装精确的行业模板和视觉模板版本; - 将预览演示数据和品牌起始内容分开,支持显式、可追踪、缺失字段优先的 bootstrap 导入; - 支持升级预览、冲突报告、用户内容保护和回滚; - 将构建、上传、发布的任务状态、依赖、产物、重试和重启恢复纳入同一交付门禁; - 为上述行为建立 API integration test、client contract test、Admin 关键交互测试、构建产物检查和最终 E2E 证据。 ### 2.2 非目标 - 不允许 API 进程直接执行上传包中的任意 JavaScript、TypeScript、shell 或安装脚本; - 不把所有模板 sample content 复制进 Prisma seed,也不把 seed 当成模板目录; - 不把品牌 owner 的权限扩展为平台模板管理员权限; - 不把一次性的线上修复脚本当成模板安装能力; - 不建设模板兼容层:运行时只读唯一正式 manifest/runtime contract;历史数据通过失败即停止的一次性迁移转换,不能保留双读、双写、默认映射或旧格式 fallback; - 不在同一阶段长期维护两套业务 renderer。Taro 是统一的双端业务 renderer,旧原生实现只作为迁移和回滚基线; - 不承诺第一阶段可以导入任意全新 renderer 源码后立即运行。第一阶段只接收声明式 manifest、资源、演示数据和已部署的受信 renderer 引用; - 不把生成一张预览图、静态文件存在或页面能打开当成模板交付完成。 如果产品最终要求“线上导入任何全新 renderer 源码即可运行”,必须另行完成可信第一方源码包、隔离构建 Worker、依赖 allow-list、签名、产物扫描和 H5/weapp 版本化发布;不能把平台重新部署伪装成导入闭环。 ## 3. 当前状态和目标状态 | 领域 | 当前状态 | 目标状态 | 进入目标状态的证据 | | ------------ | ------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------ | | 模板发现 | packages/config 有生成注册表,文档注册表仍是手工清单 | 所有可用版本由可校验包 manifest 发现,生成注册表只作为构建产物 | 包发现测试、目录接口测试、无手工重复定义 | | 版本 | 当前模板包 metadata 已与 manifest 对齐,导入 checksum 闭环尚未实现 | key + version + checksum 唯一且不可变 | 导出 checksum、重复导入、冲突导入测试 | | 行业与视觉 | 行业安装和视觉选择已有部分能力,但没有完整版本化目录 | 行业兼容性、视觉包版本、renderer contract 一起校验 | 组合矩阵、安装快照和跨行业测试 | | 示例内容 | 包内 sample 可用于部分预览和显式导入 | preview fixture、bootstrap 内容、品牌真实数据严格分离 | 预览无品牌写入、显式导入审计、缺失值规则测试 | | 模板管理页面 | 现有工作台可以选择部分已注册模板 | 独立 /admin/templates 管理导入、校验、预览、发布和版本 | 页面状态测试、API 权限测试、错误重试测试 | | 安装和升级 | 品牌配置、行业安装和视觉选择存在重复来源 | 唯一安装记录锁定行业模型与精确视觉包版本 | 一次性数据转换、唯一性约束、升级/回滚 integration test | | 构建发布 | 构建、上传和发布曾共用状态,容易死锁或误报 | build、upload、review、publish 分层,attempt/lease/产物隔离 | 并发、重启、超时、错误收敛、真实参数产物测试 | | 版本事实 | atelier-solopreneur 的 manifest 和 package metadata 已统一为 1.1.0 | 包内版本字段和导出元数据在导出前强一致 | validate:templates 的版本一致性检查 | 当前存在的 Runtime Workspace、模板 manifest、样例导入和 Taro 构建能力是基础组件,不代表本任务已完成。实施进度必须引用本文的阶段和证据。 ## 4. 领域边界和术语 | 名称 | 责任 | 不负责的事情 | | ------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------- | | 行业模板(industry template) | 定义行业字段、Offering schema、表单用途和能力依赖 | 不定义视觉包的完整页面代码和样例内容 | | 视觉模板包(visual template package) | 定义页面结构、模块变体、theme token、资源槽位、编辑绑定和演示内容 | 不把品牌真实数据写进平台全局 seed | | Capability | 定义咨询、上传、排期等可复用业务能力及其 API/Admin/小程序契约 | 不通过页面分支偷偷引入行业专属字段 | | Template package version | 一个不可变的 manifest、资源、fixture、bootstrap 声明和兼容性声明 | 不在导入时执行任意包脚本 | | Preview session | 对某个已校验版本和行业组合的临时演示上下文 | 不创建品牌、咨询提交、发布快照或真实客户记录 | | Bootstrap import | 管理员明确触发的起始内容导入 | 不覆盖品牌主动设置的值,不等同于模板注册 | | Brand installation | 某品牌使用的精确行业/视觉包版本快照 | 不修改历史发布快照,不代表样例已导入 | | Release snapshot | 某次品牌发布时冻结的全部运行时定义和品牌内容 | 不随着模板目录更新而隐式变化 | 平台要维护两种唯一性: 1. 模板包的事实唯一性由包 manifest 和 checksum 决定; 2. 品牌公开内容的事实唯一性由品牌数据库草稿和发布快照决定。 模板包不能成为品牌运行时的隐式 fallback。模板 renderer 读取的品牌事实必须来自 Runtime contract;缺失内容要显示空态、降级或阻止发布,不能自动填充未经管理员确认的假身份、经验、背书或接单状态。 ## 5. 用户流程和页面职责 ### 5.1 平台模板管理员流程 1. 在本地开发模板包,运行 schema、编辑绑定、资源、renderer 和构建检查; 2. 导出确定性包,生成 manifest 摘要、文件清单和 checksum; 3. 在 /admin/templates 导入包,看到导入进度、大小、文件数量和失败原因; 4. 打开版本详情,查看兼容行业、runtime contract、renderer、能力、页面区域、编辑绑定、sample 和阻断诊断; 5. 为某个行业启动独立预览,预览只消费包内演示数据,不写入品牌数据库; 6. 通过所有门禁后发布到模板目录;未发布版本只对平台模板管理员可见; 7. 发布后仍保留版本和资源,撤回只影响可选目录,不删除已安装品牌和历史发布快照; 8. 查看导入、校验、预览、发布和撤回审计。 ### 5.2 品牌管理员流程 1. 在品牌工作台选择已发布且和当前行业兼容的模板版本; 2. 查看安装前差异、能力依赖和是否已有品牌内容; 3. 安装精确版本,记录安装快照; 4. 独立点击“导入起始内容”,先查看 dry-run 的新增、保留和冲突; 5. 编辑模板声明的字段,保存后刷新页面验证重载; 6. 通过结构完整性校验后发布品牌内容; 7. 使用真实品牌 slug、模板 key、版本和 API 地址构建小程序; 8. 上传、审核、上线状态单独展示,失败可以重试同一 attempt 或创建新 attempt; 9. 新版本升级前查看差异,发生冲突时逐项处理;回滚时明确恢复配置基线还是撤销尚未采用的新内容。 ### 5.3 页面分工 | 页面 | 面向对象 | 核心职责 | 必须具备的状态 | | ---------------- | ---------------------------- | -------------------------------------------- | ---------------------------------------------------------------- | | /admin/templates | 平台模板管理员 | 模板包导入、版本列表、校验、目录发布和审计 | loading、empty、importing、invalid、ready、published、retry | | 模板版本详情 | 平台模板管理员 | manifest、兼容矩阵、诊断、资源、能力、历史 | schema error、renderer incompatible、missing asset、audit | | 模板预览 | 平台模板管理员或受控内部用户 | 选择行业、使用 sample 渲染真实 Runtime | preview loading、组合不兼容、空值、错误、禁止提交 | | 品牌模板安装 | 品牌管理员 | 选择已发布版本、查看差异、安装快照 | unauthorized、incompatible、already installed、conflict、success | | 品牌起始内容导入 | 品牌管理员 | dry-run、确认导入、显示来源和保留规则 | no-op、new records、preserved values、conflict、failure | | 品牌配置与发布 | 品牌管理员 | 编辑、保存、重载、发布 | field error、save failure、stale version、publish blocked | | 构建与上传记录 | 品牌管理员/平台运维 | 展示 build、upload、review、release 分层状态 | queued、running、retryable failure、terminal failure、recovered | 模板管理页面不能代替品牌内容页面。平台管理员发布的是目录版本,品牌管理员发布的是某个品牌的内容快照。 ## 6. 模板包契约 ### 6.1 版本和兼容性字段 实施时应扩展 packages/template-contract,并让 manifest 成为唯一输入。字段名称可以在实现阶段经过类型审查调整,但必须保留以下语义: | 字段 | 规则 | | -------------------------- | ------------------------------------------------------------------- | | packageKey | 稳定标识,只允许小写、数字和短横线;发布后不能复用给另一个产品 | | version | 模板包版本,遵循明确的 semver 规则;同 key + version 不允许内容变化 | | packageSchemaVersion | 包格式版本,和模板业务版本分开 | | runtimeContract | 所需 Runtime Workspace contract,必须通过兼容矩阵 | | renderer | renderer key、版本、支持端和最小兼容版本 | | supportedIndustryTemplates | 行业 allow-list,不能由客户端任意修改 | | capabilities | 能力 key、版本、必选/可选及配置 schema | | pages / modules | 页面入口、区域、模块顺序、变体和公开数据槽位 | | admin.sections | 编辑区、真实 binding、输入类型、必填规则和预览目标 | | assetSlots | 资源 binding、类型、尺寸约束和是否必需 | | previewFixture | 只读预览用演示内容,声明敏感字段和提交禁用策略 | | bootstrap | 可显式导入的起始内容、映射、稳定 key 和导入策略 | | compatibility | renderer、capability、API 和 toolchain 的兼容范围 | admin.sections 和 renderer 必须互相校验:每个可见、可编辑的品牌事实都有可追踪 binding,每个 binding 都有真实 renderer 消费点。字段出现在 mock 输入框、静态文件或隐藏 fallback 中,不能算作完成。 ### 6.2 推荐包结构 template-package/ template.json assets/ fixtures/ preview/ bootstrap/ checksums.json README.md 仓库内的模板包可以额外包含 taro/ 源码和迁移用的旧 miniapp/;线上导入器第一阶段只接受 allow-list 中的声明式文件、资源和已部署 renderer 引用。包中发现新的 renderer 源码时必须明确返回“需要平台 renderer release”,不能静默忽略。 ### 6.3 导出和导入规则 - 导出使用排序稳定的文件清单、规范化 JSON、固定压缩参数和 UTF-8 编码; - checksum 覆盖 manifest、资源、fixture、schema 和允许的元数据; - 导入先写入临时对象存储或临时目录,完成 path traversal、绝对路径、symlink、压缩炸弹、大小、文件数量、扩展名、MIME 和 checksum 检查后才进入版本表; - 不解析或执行 postinstall、prepare、构建脚本和包内任意代码; - 同一 packageKey + version + checksum 重试必须幂等; - 同一 packageKey + version 但 checksum 不同必须拒绝并生成稳定错误 code; - 导入失败不能留下可被目录接口读取的半版本; - 旧已发布版本的资源必须可继续读取,不能因为目录撤回或新版本导入而删除。 ## 7. 版本、数据来源和状态机 ### 7.1 版本维度 以下版本必须分开记录: 1. 模板包业务版本,例如 atelier-solopreneur@1.1.0; 2. package schema version,表示包格式; 3. Runtime contract version,表示数据投影契约; 4. renderer version,表示预部署的 Taro renderer; 5. capability version,表示能力 API 和配置; 6. toolchain version,表示 Taro、React、Node 和构建依赖; 7. brand release version,表示某品牌的一次发布; 8. miniapp build/upload attempt,表示某次构建和上传尝试。 不能因为包格式升级就自动把 Runtime contract 从 1.x 升到 2.0;每次 breaking change 都必须有兼容策略、迁移和回滚说明。 ### 7.2 模板版本状态 importing -> rejected importing -> imported -> validating -> invalid validating -> previewable -> published -> retired retired -> published - imported 表示文件入库,不表示可使用; - previewable 表示 manifest、资源、renderer、行业兼容性和 preview fixture 通过; - published 才能被品牌管理员选择; - retired 不影响已有安装、历史快照和预览证据;平台管理员可显式重新发布,恢复目录可见性; - 任意状态迁移都写审计,重复请求使用 operation/idempotency key。 ### 7.3 品牌模板和内容状态 安装、起始内容导入、品牌内容发布分别记录: installation: requested -> installed -> upgrade_pending -> conflicted bootstrap: previewed -> confirmed -> imported | failed brand content: draft -> publish_validating -> published | blocked 模板安装成功不能自动代表 sample 已导入,sample 导入成功也不能自动代表品牌内容已发布。 ### 7.4 构建和上传状态 build: queued -> running -> built | failed | timed_out upload: queued -> running -> uploaded | failed | timed_out review: pending -> approved | rejected release: pending -> released | rolled_back 后台 UI 不得只轮询一个“发布”状态。每个 job 有 attemptId、lease、开始和结束时间、最后心跳、版本、产物路径、错误 code 和可重试性。日志按 sequence 写入,终态使用 compare-and-set 或事务状态迁移;禁止多个异步日志写入同时覆盖任务终态。 ## 8. 数据模型和迁移策略 以下是目标模型,最终字段名以 Prisma schema、shared client 和 integration test 一起确定: | 目标模型 | 主要内容 | 设计要求 | | ------------------------------- | --------------------------------------------------------------------------- | ------------------------------------ | | TemplatePackage | 稳定 key、名称、所有者和描述 | 不保存某个品牌的内容 | | TemplatePackageVersion | manifest snapshot、版本、checksum、兼容性、renderer、artifact ref、校验状态 | 版本不可变,checksum 唯一 | | TemplateValidationRun | 校验器版本、issue code、语义指纹、结果和日志 | issue identity 不能依赖行号 | | TemplatePreviewSession | package version、行业、fixture、过期时间、权限和 origin | 不关联真实品牌数据,不持久化真实提交 | | BrandVisualTemplateInstallation | 品牌使用的精确视觉包版本和快照 | 和行业安装区分,保留历史 | | TemplateBootstrapImport | 来源包、版本、checksum、actor、策略、结果和审计 | 记录每条记录的来源和稳定 key | | TemplateUpgradePlan | from/to、差异、冲突、用户确认和执行结果 | 支持 dry-run、重试和回滚 | | TemplateOperationJob | 导入、校验、资源处理、build/upload 的 attempt 和 lease | 支持重启恢复和终态收敛 | BrandTemplateInstallation 必须收敛为品牌唯一的当前模板安装,记录行业模型及精确视觉包版本。先只读盘点数据,再以一次性事务迁移完成无歧义映射;迁移后删除重复状态和旧字段,不保留兼容读取窗口。发布历史通过不可变 release snapshot 保留,不依赖旧安装形状。 数据库迁移必须遵循以下顺序: 1. 备份并记录当前 schema、模板安装、品牌配置和发布快照数量; 2. 先增加可为空的新字段或新表,不改变旧读路径; 3. 回填只写可从旧数据确定推导出的值,不能猜测版本、checksum 或样例来源; 4. 生成新旧数据的只读差异报告;有歧义时停止迁移并修正数据; 5. 执行一次性事务迁移,校验唯一安装及 package/version/checksum/industry 一致后删除旧表示; 6. 清理旧字段前提供备份、回滚脚本和历史快照验证; 7. 重复执行迁移和导入不得生成重复安装、重复 offering、重复 inquiry form 或重复审计。 模板 sample 永远来自包。开发 demo 可以保留少量显式 fixture,但新模板不能要求在 apps/api/prisma/seed.ts 增加一套全局注册和样例记录。 ### 8.1 Bootstrap 的保留规则 导入前必须生成 dry-run: - missing:数据库中没有该 binding 或稳定业务 key,可以创建; - existing:已有值,保留并显示来源; - explicit-empty:管理员主动保存的空字符串、null 或空数组,视为已有值,不能被样例覆盖; - conflict:同一稳定 key 的结构或类型不兼容,必须人工处理; - removed-in-target:新版本不再声明旧字段,不能隐式删除用户数据。 导入记录保存 sourcePackageKey、sourceVersion、sourceChecksum、sourcePath、targetRecordId、operationId 和导入时的值摘要。不会为了通过 ready check 自动导入假姓名、十年经验、虚构背书、营业状态或公开案例。 ## 9. API、权限和客户端契约 接口命名和资源路径在实现阶段通过 shared client 固化;以下是必须覆盖的接口族: | 接口族 | 作用 | 权限和隔离 | 必测路径 | | ----------------------- | ---------------------- | ---------------------------- | --------------------------------------------------- | | template package import | 上传、导入、查询 job | 独立平台模板管理权限 | 无凭证、错误角色、包非法、成功、重复、checksum 冲突 | | template validation | 运行或查询校验、诊断 | 平台模板管理权限 | 未导入版本、未授权、兼容失败、重试幂等 | | template catalog | 查询已校验/已发布版本 | 未发布版本仅平台权限 | 目录隔离、撤回、分页、版本排序 | | template preview | 按版本和行业创建预览 | 平台权限或受控 preview token | 行业不兼容、资源缺失、过期、真实提交被拒 | | brand installation | 安装已发布精确版本 | 由服务端确定当前品牌 | 跨品牌、未发布、错误行业、重复安装、成功 | | bootstrap import | dry-run 和确认导入 | 品牌管理员,服务端推导 brand | 空值保留、重复、冲突、回滚、成功 | | template upgrade | 差异、确认、执行和回滚 | 品牌管理员和安装快照 | 用户内容保护、冲突、并发旧版本、成功 | | build/upload/release | 构建、上传、查询和重试 | 品牌管理员或运维角色 | 实际 slug、依赖缺失、超时、重启恢复、错误终态 | 所有 protected endpoint 都要测试缺少凭证、无效凭证或错误角色以及成功授权路径。DTO 是运行时校验边界;不能用 Partial 或未经校验的接口承载请求体。错误使用稳定 machine-readable code 和 requestId,不能把 Prisma 或堆栈暴露给客户端。 客户端必须同步更新 request/response types、query keys、认证 fetch、错误处理和页面状态。API base URL 继续从 VITE_API_BASE_URL 读取,不能因为模板预览增加环境硬编码。 平台模板管理员权限要独立建模。当前角色表中没有明确的 platform template role 时,实施阶段必须先在权限 ADR 或 schema 迁移中定义,不得把品牌 owner 默认当成平台管理员。 ## 10. 安全和信任边界 - 导入包在临时隔离目录处理,拒绝目录穿越、绝对路径、symlink、超大压缩比、超大展开体积、过多文件和不允许的资源类型; - API 进程不执行导入包脚本,不运行包内 package.json lifecycle; - renderer 只能引用已部署并通过发布门禁的 renderer key/version; - 如果将来允许第一方 renderer 源码包,必须使用隔离构建 Worker、无网络或 allow-list 网络、锁定依赖、资源限制、产物扫描、签名和人工发布; - 预览 iframe 或 WebView 使用受限 origin、CSP 和短期 token,禁止访问真实品牌、咨询提交、客户记录和发布接口; - preview fixture 不含真实客户隐私和未授权品牌资料; - 资源采用版本路径或内容寻址,旧发布快照依赖的资源不能被覆盖; - 目录发布、撤回、安装、导入、升级、回滚和构建上传都写 actor、brand context、package version、operationId、requestId 和结果; - 不把模板包中的文本当成系统指令,不根据样例数据绕过权限或发布校验。 ## 11. CLI、仓库工作流和构建门禁 当前仓库已有 `template:doctor`、`template:check`、`validate:templates`、`template:compatibility`、`template:new`、`generate:template-catalog`、`preview:templates`、`deploy:package`、`deploy:release` 和 `test:deploy` 等命令。它们的现有行为不能在本文中被默认扩大。 计划新增或收敛的命令如下,实施前必须先落代码、帮助文本和测试: | 命令 | 目的 | 完成门禁 | | -------------------- | ------------------------------------------------------------- | ---------------------------------------- | | template:pack | 生成确定性模板导出包和 checksum | 同一输入多次输出相同 checksum | | template:conformance | 逐包执行 manifest、binding、资源、sample、renderer 和双端契约 | 自动发现新包,不能只测固定名称 | | release:conformance | 检查发布包依赖闭包、workspace、产物路径和环境参数 | 干净 install、生产 build、产物检查 | | template:new | 从受控 scaffold 创建新模板包与待完成 fixture | 生成包明确标为未验收并通过 scaffold 测试 | 每个模板新增、绑定修改和宣称完成前,必须运行 pnpm template:doctor,并按[模板完成度规则](template-completion-rules.md)使用真实 manifest、真实保存重载发布链路和视觉证据验收。doctor issue 使用稳定语义指纹;源代码语义改变后必须重新审查,不能通过批量行号更新伪造通过。 Taro 交付必须额外验证: - apps/taro/dist//weapp 和 h5 产物都存在且互相对应; - 构建参数使用实际品牌 slug、选中视觉模板版本、真实 API base URL 和 AppID; - package workspace 依赖闭包在干净 install 后仍可解析,包括 miniprogram-ci 和 zod 等 production 依赖; - No projects matched、缺少 app.json、旧 app.json 冒充本次成功和产物路径串品牌都被视为失败; - 日志终态、上传启动、上传失败、超时和重启恢复都有测试; - 真实微信开发者工具或真机负责 request、media、登录、拨号、复制、滚动、安全区和最终视觉证据。 ## 12. 分阶段实施清单 阶段按依赖顺序执行。每个阶段都要在本文的进度区补充 commit、测试命令、证据路径和未解决问题;阶段未过门禁不得进入下一阶段。 ### Phase 0:任务固化和现状盘点 - [x] 建立本文档和 ADR 0029,并将其设为唯一任务入口; - [x] 盘点所有模板包的 manifest/package metadata、renderer、fixture、资源和版本差异; - [x] 盘点现有行业安装、视觉选择、发布快照和 Admin 页面调用关系,见 [Phase 0 现状盘点](template-management-phase0-inventory.md); - [x] 为历史事故建立可执行回归清单,见 [Phase 0 现状盘点](template-management-phase0-inventory.md#8-phase-0-历史事故回归清单); - [x] 解决 atelier-solopreneur manifest/package metadata 版本漂移; - [x] 明确平台模板管理员角色缺口和线上隔离边界,见 [Phase 0 现状盘点](template-management-phase0-inventory.md#6-权限与租户现状) 与 [Phase 0 现状盘点](template-management-phase0-inventory.md#7-部署-release-与运行环境隔离); 退出门禁:模板目录、版本事实、现有数据模型和已知失败路径有可审阅清单;没有“默认值能猜出来”的隐含项。 Phase 0 执行记录(2026-10-16): - 已将三个仓库模板的 package metadata 与 manifest 对照,并修复 atelier-solopreneur 的 1.0.0/1.1.0 漂移; - validate:templates 新增 package name 和 version 一致性阻断; - template-doctor 生成 after 报告:三个模板 staticStatus 均为 pass,completionStatus 保持 unverified,112 个 review 均有登记; - template:check、template-doctor 测试和 typecheck 通过;完整证据保存在本次工作区的 Phase 0 运行记录中; - 行业安装、视觉选择、发布快照和 Admin 调用链已完成盘点,证据见 `docs/template-management-phase0-inventory.md`; - 已确认平台模板管理员不能复用品牌 membership 字符串,线上模板 artifact、版本目录和小程序构建 attempt 仍需后续阶段实现; ### Phase 1:包契约和确定性导出 - [ ] 扩展 packages/template-contract,定义 package schema、rendererRef、preview/bootstrap、资源和兼容矩阵; - [x] 实现 `template:pack`,生成稳定清单和 checksum;当前覆盖 3 个仓库模板,测试重复导出目录和 archive checksum 一致; - [x] 实现 package-discovered `template:conformance`,自动发现模板并串联真实 compiler、doctor 和产物契约; - [ ] 为每个当前模板补齐真实 manifest、可见字段、编辑绑定、空态和 fixture; - [ ] 把版本漂移、缺资源、未知 binding、未消费字段和不兼容 renderer 变成阻断 issue; - [ ] 记录旧原生 miniapp 和 Taro 目录的迁移边界。 退出门禁:干净 checkout 中所有模板包可被发现、导出、校验;相同输入 checksum 稳定;不执行包脚本;每个页面的可见品牌事实都有 renderer 和 editor 证据。 ### Phase 2:线上导入、校验和模板目录 - [x] 增加 TemplatePackage、TemplatePackageVersion、生命周期审计和 artifact 引用; - [x] 实现临时存储、安全检查、checksum 幂等和冲突拒绝; - [ ] 完成 manifest、runtime、renderer、industry、capability、资源和 fixture 诊断; - [x] 实现目录发布、撤回、分页、审计和旧资源保留; - [x] 增加独立平台模板权限; - [x] API、DTO、shared client 和 integration test 一起交付。 退出门禁:非法包不会进入可用目录;重复导入不重复建版本;同版本不同 checksum 明确失败;未发布版本不能被品牌管理员安装。 Phase 2 当前进度(2026-10-16): - 已增加 `TemplatePackage`、`TemplatePackageVersion`、版本状态和 `AdminUser.platformTemplateRole`,artifact 路径独立于 release 目录; - 已实现平台模板管理员 guard、`GET /admin/templates` 和 `POST /admin/templates/import`;普通品牌管理员和 customer 均不能访问; - 已实现临时文件导入、archive 路径/链接/重复项检查、文件数和解压体积限制、manifest/package metadata/checksum 校验、幂等和版本冲突拒绝;不执行包内脚本; - 已同步 shared client 和 Admin `/admin/templates` 的导入、版本列表、loading/empty/error/retry/success 状态; - 已通过 `51/51` API HTTP integration tests 和 `2/2` upload tests; - 已补充 `imported -> published -> retired` 生命周期、重复操作幂等、状态竞争保护、分页、审计查询和 Admin 页面发布/撤回/审计操作; - 已将模板包和版本及审计写入同一数据库事务,数据库失败时清理已落盘 artifact,避免留下半版本; - 已通过 `51/51` API HTTP integration tests、`2/2` upload tests 和 `6/6` API client tests; - 尚未完成:独立 validation run / renderer / capability / fixture 诊断、独立 preview session、品牌精确版本安装;因此 Phase 2 目录基础闭环已完成,完整任务继续进入 Phase 3/4。 ### Phase 3:独立预览和模板管理页面 - [x] 增加 preview session 或同等短期隔离上下文; - [x] 按行业选择兼容组合,使用 preview fixture 通过真实 Runtime projection 渲染; - [x] 页面展示模块顺序、字段来源、资源缺失、能力依赖和诊断; - [x] 预览禁止真实咨询、客户记录、品牌发布和上传; - [x] /admin/templates 完成导入、详情、校验、预览、发布、撤回和审计交互; - [x] 覆盖 loading、empty、error、retry、success 和权限失败状态。 退出门禁:预览不创建品牌和业务数据;不同版本、行业和资源组合不会串数据;页面失败时保留上传和选择上下文;真实 Runtime 和预览数据映射有测试。 Phase 3 初版实现(提交 `6edde5a`,2026-10-16): - 增加 `GET /admin/templates/:id/preview?industry=`,只允许平台模板管理员;DTO 校验查询,服务读取数据库版本的 `manifestSnapshot.sampleContent`,不读取当前品牌内容,不创建品牌或业务记录。 - `imported` 和 `published` 可预览;`retired` 和其他不可用状态返回 `409`。不存在的版本、非法行业组合、Runtime/renderer/capability/sample 校验失败返回 `400`,沿用统一错误 envelope。 - 使用 `assemblePublicWorkspace` 投影演示快照,Client 和 Admin 同步接入;模板管理页按行业选择,并可查看首页、我的、业务详情和咨询等内页,失败保留选择并支持重试。 - 当前 renderer 兼容策略保守地要求部署 registry 的 package key、visual key 和版本一致;这只是第一步兼容门禁,尚未引入独立 renderer version/hash。API 不执行导入包源码,Admin 只挂载已部署 renderer。 - 当前预览为请求内存上下文,模拟 ID 使用 `template-preview:` 前缀,咨询组件使用 `preview` 模式并禁用提交;客户记录组件沿用不读取客户 API 的预览模式。 - 自动化:API 集成测试覆盖缺少/无效凭证、普通品牌管理员和 customer 拒绝、真实 atelier 包预览、行业不兼容、无 renderer、无 capability、缺 sample、撤回状态及全局业务表计数不变。浏览器交互使用真实 manifest 和同一生产投影生成 fixture,HTTP mock 仅证明页面交互,不代替 API 授权/数据库证据。 - 预览入口增加嵌套声明结构门禁;集成测试覆盖 `dataSlots`、`navigation`、`templateFields`、`trustContentTypes` 和 Admin section 的畸形输入,返回可操作的 `400` 错误。 - 本轮验证:API HTTP integration `52/52`、upload `2/2`、API unit `49/49`、Client `6/6`、Admin unit `6/6`、Playwright 预览交互 `1/1`;全仓 typecheck、Admin production build、变更范围 lint、format、`template:check` 通过。`template:doctor` 未解决项为 `0`,模板完成度仍为 `unverified`。Playwright 运行前需构建 API/config 并启动 Admin:`ADMIN_PORT=3016 pnpm --filter @personal-brand/admin dev`,随后在 `apps/taro` 运行 `pnpm exec playwright test test/browser/template-management.spec.ts`。 - 咨询按钮改动另行完成 atelier 的 `weapp` 和 `h5` 构建,参数为 `TEMPLATE_KEY=atelier-solopreneur API_BASE_URL=https://wechat.app.que01.top/api WEAPP_APP_ID=wxd75d946d6978d183 pnpm --filter @personal-brand/taro build:`;产物包含对应 AppID/API 地址并通过 masking 检查。本轮不作为微信真机视觉验收。 - 初版剩余项(以下续进展为准):独立 `previewFixture` 与 bootstrap sample 的拆分、包内完整身份和媒体 fixture、按 checksum 提供导入资源、逐资源缺失诊断、画布内 CTA 导航、预览审计、短期 session/origin/CSP 隔离、跨模板/行业/版本矩阵及最终视觉验收。因此以上阶段清单仍保留未完成状态。 Phase 3 独立 fixture 与资源进展(2026-10-16): - 新增 `previewFixture.`:`schemaVersion: "1"`、身份白名单 `brand`、独立 `content` 和固定禁用策略 `safety`;使用 `packages/validation` 的同一 Zod 规则校验本地包和线上导入,不引入新校验体系。声明 fixture 的包必须覆盖全部兼容行业;无效声明不能回退到 `sampleContent`。 - atelier 升为 `1.2.0`,保持不可变版本;预览主理人和品牌身份单独声明,`sampleContent` 只用于显式品牌起始内容。所有可发布包必须满足同一 manifest 契约;不提供旧包运行兼容路径。 - 管理页展示当前页面的 Admin 模块声明顺序、字段 binding、资源配置数量和缺失状态。这是声明诊断,不代表已经验证 renderer 的实际视觉顺序或全部字段消费。 - 预览读取已导入 archive,核对 archive/content checksum 及逐图片 SHA-256,校验实际图片格式后以内嵌 data URL 提供给画布;不执行源码、不解压到公共目录、不回退到当前部署的同名图片。每图最多 2 MiB、总图片最多 8 MiB、最多 128 张,超出限额返回明确诊断;外链图片仍为待验证。 - 同一预览响应同时包含版本 checksum、Runtime 和图片映射,切换版本/行业不会复用另一份图片;当前实现尚不包含可公开访问的资源 URL、远程资源探测或 CDN 缓存。 - 本轮不涉及编辑 binding 或 renderer 布局变更;真实品牌编辑/保存/发布闭环及微信视觉验收仍按模板完成度规则独立验收。 - 预览成功会写平台模板审计:操作者、版本 checksum、行业、fixture 来源及 requestId;不记录演示内容、不创建业务数据,关闭预览后刷新审计缓存。 - 自动化新增独立 fixture 与 bootstrap 解耦、无效安全策略导入拒绝、敏感身份字段拒绝、兼容来源标识、archive 漂移阻断及图片类型/体积/摘要故障回归。API HTTP integration `52/52`、upload `2/2`、API unit `51/51`、Client/Admin unit 各 `6/6`、真实包图片浏览器交互 `1/1` 通过;typecheck、Admin production build、变更范围 lint 和 `template:check` 通过。 - 仍待推进:预览上下文与 origin/CSP 隔离、画布内 CTA 导航、跨模板/行业/版本完整矩阵和最终视觉验收。前述初版实现记录中的 fixture 与包内资源缺口由本段更新,其余阶段门禁不变。 Phase 3 短期隔离 session 进展(2026-10-16): - 预览响应新增 `preview.session`;首次预览生成 64 位十六进制短期 token,有效期 15 分钟。`GET /admin/templates/:id/preview` 支持 `session` 查询参数,DTO 仅接受预期格式。 - 服务端 session 只在 API 进程内存中保存已构建投影,上限 20 个并主动清理过期项;每次复用必须匹配同一平台模板管理员、版本 ID 和行业。因此 token 不是跨管理员可重放凭据,不同版本/行业/管理员不会串数据。 - 带 session 的成功复用不重复读取 archive,也不重复写 `previewed` 审计;不存在、过期或绑定不匹配返回可操作的 `400`,管理员可重新创建预览。 - Admin 预览按版本和行业保留短期 token 供失败重试复用;请求失败时删除对应 token,行业/版本选择和业务记录选择仍保留。 - 自动化覆盖 session 成功复用、复用不新增审计、跨管理员拒绝、未知 token 拒绝、版本/行业绑定、shared client URL 和 Admin 重试上下文。本轮 API HTTP integration `52/52`、upload `2/2`、Client `6/6`、Admin unit `3/3` 和全仓 typecheck 通过;origin/CSP 隔离与最终矩阵验收仍待完成。 Phase 3 现场验收纠偏(2026-10-16): - 现场核对发现 `retired` 曾是终态,但页面仍展示“发布”操作,状态机与 UI 矛盾。已允许平台模板管理员执行 `retired -> published`,只恢复目录可见性,不改动 immutable 包和历史快照;integration test 覆盖撤回、不可预览、重新发布、重新可预览。 - 现场核对发现旧模板 `sampleContent` 只有少量业务数据,`brandConfig` 和媒体槽位为空,导致 food/linjing 预览像缺数据。已为 `acheng-campus-food@1.0.1`、`linjing-editorial@1.0.3` 补齐包内演示主图、头像、封面和视觉文案;旧版本保持 immutable 并撤回。 - atelier 独立 fixture 也没有头像。已升为 `atelier-solopreneur@1.3.0`,在 `previewFixture.personal.brand` 中加入包内头像,继续保持预览数据与 bootstrap sample 分离。 - 修复 Admin 导入包预览中 food renderer 的资源 key 前缀映射:包内 `/assets/service/*.png` 等图标现在可从 archive 校验后的 data URL 渲染,不回退到本地部署资源。 - 矩阵 API 回归新增断言:每个支持行业的主理人身份非空、头像指向包内资源、所有 asset slot 都是 `ready`、没有诊断。 - 新增 Playwright 媒体矩阵:覆盖 `acheng/food`、`atelier/personal`、`linjing/doors`,使用真实 `template:pack` 产物和 API preview service;验证失败重试、founder 可见、所有 `data:` 图像 `naturalWidth > 0`、无“内容缺失”、无真实写入请求。四张截图已人工检查。 - 本轮本地目录以最新已发布版本为准:`acheng-campus-food@1.0.1`、`atelier-solopreneur@1.3.0`、`linjing-editorial@1.0.3`;被取代的旧演示版本进入 retired。 Phase 3 隔离、导航和矩阵收口(2026-10-16): - Admin dev/preview 响应增加 CSP、`Referrer-Policy: no-referrer` 和 `X-Content-Type-Options: nosniff`。preview/生产 CSP 为 `default-src 'self'`、`script-src 'self'`、`object-src 'none'`、`base-uri 'none'`、`frame-ancestors 'self'`、`form-action 'self'`;图片和媒体允许 `self/data/blob` 以读取通过 checksum 校验的包内资源,样式保留 `unsafe-inline` 以支持现有 React UI。生产构建同时保留 CSP meta 作为静态托管防线。 - Vite dev 为 React refresh preamble 单独允许 inline script;这是开发服务器例外,不是 preview/生产契约。Playwright 校验响应中存在 CSP 的 `default-src 'self'`、包内资源所需的 `img-src data:` 和 `frame-ancestors 'self'`。 - Admin 画布监听 Taro web preview runtime 发出的导航事件,把 renderer 内真实 CTA 转成画布内切换;`detail` 路由同步选择对应 offering。Playwright 覆盖“首页案例 -> 详情 CTA -> 禁止提交的咨询表单”。 - 新增真实包矩阵回归:`acheng-campus-food/food`、`atelier-solopreneur/personal`、`linjing-editorial/doors`,每个组合各 2 个版本,共 6 个模拟品牌。测试校验行业兼容、Runtime/renderer 声明、模拟品牌 ID、包内资源逐项 checksum、禁用提交和跨版本隔离。 - 矩阵回归发现 linjing doors 起始内容声明了未注册 capability `doors`。已将其修正为 `inquiry`,模板包升为 `linjing-editorial@1.0.1`,生成目录、release build 配置和模板注册表同步更新;旧 `1.0.0` 不在本轮改写。 - Playwright 支持通过 `TEMPLATE_PREVIEW_VISUAL_EVIDENCE` 输出 `home/detail/inquiry/profile` 截图。本轮已生成并人工检查:独立 fixture 身份、包内图片、详情 CTA、咨询禁用和我的页面正常。该证据覆盖本地 Admin/H5 预览,不替代微信真机视觉验收或审核上传。 - 本轮回归:API HTTP integration `52/52`、upload `2/2`、API unit `52/52`、Client `6/6`、Admin unit `6/6`、Playwright `1/1`;全仓 typecheck、变更范围 ESLint、format、Admin production build 和 `template:check` 通过。全仓 `pnpm lint` 仍有先前记录的 Admin 既有 error,非本轮阻塞。 - Phase 3 本地预览门禁完成;微信真机/审核上传、品牌精确版本安装、bootstrap 导入和真实编辑发布仍归 Phase 4/5。 ### Phase 4:品牌安装、bootstrap 和发布 - [x] 区分行业安装和视觉包安装,保存精确版本与 checksum 快照; - [x] 实现 sample dry-run、显式确认、missing-only、空值保留、冲突和来源审计; - [x] 建立模板驱动的 Admin editor binding,保存后重载仍能看到相同值; - [x] 发布校验基于当前安装版本和真实品牌 manifest; - [x] 通过 shared client、Admin 页面和 API integration test 验证跨品牌隔离; - [x] 验证模板安装不自动导入未确认的身份、背书、案例和咨询数据。 当前进展:安装台账只引用精确的 `templatePackageVersionId` 并记录 `contentChecksum`;renderer key 只从该版本的 package manifest 读取。bootstrap 只读取已发布 package version 的 `manifestSnapshot.sampleContent`,preview 只 dry-run,import 必须显式传入 `strategy: "missing_only"` 和 `confirm: true`。已有品牌值(包括显式空值)、同名 offering、相同 `type + title` 的 trust content、相同 inquiry field,以及已启用表单都会被保留;重复导入按品牌、版本和 checksum 幂等返回,并写入 `TemplateBootstrapImport` 和 capability audit。 seed 边界已收口:`ensureRuntimeContent` 写入的 offerings、trust content、inquiry fields、表单名称和模板品牌样例均来自对应 package 的 `sampleContent`,food、doors 的媒体和结构化展示字段已通过真实公开 workspace 验证;`runtimeSeedTemplates` 仅保留明确的开发演示品牌 profile,不作为模板目录或业务样例来源。新增模板不需要修改全局 seed;每个运行品牌都必须有精确已发布 package version 安装,缺失时启动/操作明确失败,不走 registry fallback。 退出门禁:干净品牌可以通过安装和显式导入完成编辑发布;已有用户值、主动清空值和历史发布快照均不被覆盖;错误请求不会改变表单。 ### Phase 5:构建、上传和线上发布闭环 - [x] 将 build、upload、review 状态拆分,并为构建/上传增加持久化 attempt 和 lease; - [x] 产物路径包含品牌 slug、模板 key、模板包精确版本和 build attempt id; - [x] 生产依赖闭包通过 Node 24 release package、干净 `--prod --frozen-lockfile` 安装、Prisma Client generate、API runtime import 和 production API health check 验证;API app 重建后的 attempt 恢复由真实 Prisma integration 覆盖; - [x] 构建失败、上传失败、超时、进程退出、重试和恢复有自动化测试;覆盖 build worker 非零退出/watchdog kill、失败构建、上传子进程超时、attempt lease 竞争/接管、真实 Prisma/API app 重建恢复;本机 Node 24 production bundle 已启动、停止并重启验证;生产机 PM2/主机重启仍属于部署环境验收; - [x] 自定义产物目录纳入 Taro 构建和 masking 检查;缺少 `app.json` 会阻止上传; - [x] 使用实际品牌参数完成 production weapp build 并尝试微信上传,保存产物检查和外部结果;`linjing-doors` 的真实 AppID/API 地址构建通过,修复了 worker 漏掉 `/weapp` 输出层级的问题;同一 release task 的两次真实微信上传均返回工具链 `timeout`,attempt 持久化为 failed 且无 upload id,未提交审核或发布。 退出门禁:API 不会因为 fire-and-forget 日志或并行重试永久轮询;任何终态都可查询;构建成功不再隐含上传成功;上传结果有真实 weappUploadId 或明确外部失败证据。 Phase 5 首轮实现记录(2026-10-17): - 新增 `MiniAppReleaseAttempt`,分别记录 build/upload attempt、单调 attempt 序号、随机 lease token、过期时间、heartbeat、日志、产物路径、external id 和 terminal status;并发操作拒绝,过期 attempt 收敛为 `timed_out` 后可重试。 - MiniAppReleaseTask 新增独立 `uploadStatus`、`reviewStatus`;旧 `status` 仍作为兼容聚合状态供现有客户端读取。新增 migration 对历史 uploaded/review 状态做可推导回填。 - 构建输出按 `releases//@//weapp` 隔离;每次 build 不复用其他品牌、版本或 attempt 的目录。成功产物可用于当前任务上传;失败状态不允许旧产物冒充本次 build。 - Taro 支持受控 `MINIAPP_OUTPUT_ROOT`,masking 会检查同一自定义目录;构建进程增加明确 timeout。Admin 发布卡片显示 build/upload/review 阶段状态。 - 本地验证:API unit `60/60`、API HTTP integration `52/52`、upload integration `2/2`、Taro tests `16/16`、Admin/API/API Client/Taro typecheck、Admin production build、`format:check` 通过;migration 在主本地数据库及隔离 integration schema 均成功应用。Taro `weapp` 使用测试 AppID 的自定义输出路径 smoke build 已通过,不作为生产参数证据。 - 本轮补充:`deploy:package` 首次暴露 Admin production asset base 错误,已统一 Vite `base` 并重跑通过;最新 929 文件 release 在 Node 24.16.0 下完成干净 production-only 冻结安装、Prisma Client generate 和 API runtime import;production API 启动、停止、重启及 `/health` 检查通过。新增真实 Prisma integration:关闭并重建 Nest app 后接管过期持久化 build attempt;最近全套 integration `53/53`、upload `2/2` 通过。该本机验证不替代生产机 PM2/主机重启演练。 - 本轮实际发布尝试:`linjing-doors` 页面的凭据状态为已加密保存,解密后 PEM 校验通过。为避免改写历史 version 13 上传任务,先基于当前已发布且 readiness 通过的品牌内容生成 version 14,并创建独立 MiniAppReleaseTask。首次构建因 worker 输出目录缺少 `/weapp` 而失败;修复后 build attempt 2 成功,产物包含 `app.json`。两次 miniprogram-ci 上传均返回 `timeout`,task 当前为 `buildStatus=success`、`uploadStatus=failed`、`reviewStatus=not_submitted`,没有 `weappUploadId`。任务、attempt 和失败原因已保存在本地数据库;没有提交微信审核,也没有发布小程序线上版本。 - 收口说明:按当前交付范围,Phase 5 的实现、自动化测试、本地 production bundle 验证及实际品牌构建/上传尝试均已完成,故阶段标记为已收口。真实微信上传仍以 `timeout` 失败且无 upload id;未提交审核或发布,生产机 PM2/主机重启演练也未执行。这些是明确记录的外部/部署环境限制,不代表微信发布成功;若后续需要线上发布或出现相关问题,再核查上传链路及部署环境。 ### Phase 6:升级、冲突、回滚和恢复 - [x] 生成旧版本到新版本的字段 binding、页面入口、包文件、资源槽位和能力差异;视觉模块与 renderer 标记为平台视觉 manifest 所有,不随模板包升级; - [x] 升级支持 dry-run、显式确认、逐项保留现有 binding 冲突和用户内容保护;同一预览并发执行时 compare-and-set 保证最多一个成功; - [x] 回滚要求显式确认并校验当前版本,只恢复安装配置快照及不可变包关联,不恢复已删除的用户数据,也不删除当前用户数据; - [x] 验证旧模板版本、品牌历史发布快照和客户咨询提交在升级/回滚后持续可读;新旧包文件清单分别从验证报告或已验证归档读取; - [x] API / Prisma Client 重建后读取持久化安装状态;该升级操作是同步数据库事务,没有独立 worker job,Admin 页面重载后由查询重新读取 preview,陈旧操作会被版本校验拒绝。 退出门禁:升级冲突/陈旧预览不改变安装状态;回滚不会删除用户历史数据;并发重试和 API 重建不会重复升级或覆盖终态。 Phase 6 收口记录(2026-10-17): - 升级目标切换为当前视觉模板最新已发布的不可变 `TemplatePackageVersion`;preview 比较模板配置 binding、页面入口、语义资源槽位、能力和校验报告中的逐文件 SHA-256。视觉模块/renderer 明确标为平台视觉 manifest 管理,包升级不替换 renderer;未有历史文件清单的旧包会明确报告不可比较。 - 升级 API 要求 DTO 显式确认并携带目标 package id/checksum、来源 package id/版本及每个冲突 binding 的 `preserve` 选择;执行时再次验证包状态、行业兼容性和冲突集合,数据库 compare-and-set 防止并发重复升级。品牌现有值不被改写,升级不删除数据。 - 回滚要求显式确认和预期当前版本,compare-and-set 防止覆盖并发升级;回滚恢复配置快照和对应不可变包关联,不删除品牌内容、历史发布或客户提交。升级/回滚写入 package audit log,记录 actor、brand、版本、checksum、保留选择与 requestId。 - 归档兼容:新导入包的 checksum 文件清单保存于 `validationReport`;旧记录在 preview 时从隔离存储中的已导入 archive 只读提取 `checksums.json`,缺失/损坏时返回明确不可比较,不执行包内脚本。 - 自动化验证:无凭据/错误角色、DTO 校验、目标版本 preview、冲突未确认拒绝、同一预览并发一胜一冲突、升级与回滚审计、Prisma Client 断开重连、Nest app 重建后读取版本、历史发布与咨询内容保留;API HTTP integration `53/53`、upload integration `2/2`、API unit `64/64`、API Client `7/7`、Admin `6/6`、API/API Client/Admin typecheck、Admin production build、格式检查通过。全仓 lint 仍有本阶段之外的既有错误,本次变更文件的 lint 单独通过。 - `pnpm template:doctor` completionStatus 仍为 `unverified`,因为真实 manifest 的品牌编辑保存/重载/发布和视觉证据未提供;这是模板完成度独立门禁,不由本阶段升级 API 测试替代。 ### Phase 7:规模化模板生产和持续回归 - [x] 新模板可通过 `pnpm template:new ` scaffold、package-discovered conformance 和模板管理页面进入目录;生成包明确保留待填写的 industry/fixture 占位,不能误当成已验收模板; - [x] 行业、视觉、能力、renderer 和 Taro/React toolchain 组合有自动兼容矩阵,未知 renderer、未知 capability、行业不兼容和依赖版本漂移都会阻断; - [x] 固定页面角色的浏览器视觉 smoke 与真实 package fixture 已由 CI browser job 执行;原型对照、真实编辑保存重载发布证据仍遵循模板完成度规则单独验收; - [x] CI 在新增模板时自动发现并执行契约、API 预览矩阵、compatibility、包构建 conformance 和 browser smoke; - [x] 统一统计导入失败、预览失败、安装失败/冲突、升级/回滚失败、构建失败和上传失败;平台模板管理员可查询窗口聚合,且不暴露错误正文;定期审阅流程仍需运营安排; - [ ] 删除或迁移旧注册表、默认行业映射和重复 renderer 分支。 Phase 7 进展记录(2026-10-17): - 新增 `pnpm template:new `,生成 package metadata、manifest、Taro renderer 和明确未完成的 README;重复 key 会拒绝,不生成可伪装完成的空样例数据。 - 新增 `pnpm template:compatibility`,通过 TypeScript AST 读取行业、能力和视觉注册表,自动发现所有 package manifest;比较平台视觉 renderer、Admin glob、Taro renderer 导出、行业 capability 和 package/platform Taro/React 依赖主次版本,支持 JSON 报告。 - API 模板预览矩阵自动扫描真实 manifest,逐个验证声明行业、版本隔离、品牌隔离和归档资源;CI 静态 job 显式执行 package validation、compatibility、API matrix 和 conformance。CI browser job 已执行真实包 fixture 的页面/资源/编辑回归截图。 - 自动化验证:`pnpm template:check` 通过(contract `22/22`、scaffold/compatibility `3/3`、pack `3/3`、conformance `1/1`、compiler `10/10`、miniapp fixture `3/3`);API matrix `2/2`;compatibility 报告有 4 个支持组合;API unit `65/65`、HTTP integration `54/54`、upload integration `2/2`、API Client `8/8`、Admin `6/6`;API/API Client/Admin typecheck、Admin production build、Prettier 和 `git diff --check` 通过。 - 剩余:指标已有统一持久化和平台管理员查询接口,但定期审阅流程仍需运营安排;模板运行时仍有旧 renderer/默认行业映射等兼容路径待移除。模板 doctor 的真实品牌编辑保存重载发布与原型视觉证据仍为 `unverified`,不能以 CI smoke 代替;因此 Phase 7 整体继续进行。 运营指标说明:新增 `TemplateOperationFailureEvent` 记录导入、预览、安装/冲突、升级和回滚失败;构建/上传从已有 release attempt 聚合。事件只保留 action、稳定 `HTTP_*` resultCode、可选实体标识和 requestId,查询只返回类别/数量;按 180 天 best-effort 清理,不回填历史失败数。定期审阅仍需运营流程和负责人。 退出门禁:增加一个新模板不需要修改全局 seed 才能被发现,不需要在 Controller 写行业分支,不需要手工改线上数据库才能选择、预览、安装和发布。 ### Phase 8:真实品牌与外部验收 - [ ] 使用隔离测试品牌,按真实 manifest 完成首页、个人页、业务详情和咨询入口的字段编辑、保存、重载和发布验证;记录草稿与公开快照隔离证据; - [ ] 对 3 个真实模板完成多页面视觉对照,覆盖媒体、图标、空态、错误态、按钮命中、滚动和移动端安全区; - [ ] 使用真实部署参数完成 H5 和 weapp 构建,检查 AppID、API 地址、媒体地址、模板版本和产物路径; - [ ] 在微信开发者工具或真机完成 request、media、拨号、复制、表单提交和安全区验证;外部上传、审核、发布结果单独归档; - [ ] 由平台模板管理员执行一次失败指标审阅,确认高频问题、负责人和后续动作,形成审阅记录; - [ ] 完成一次性品牌安装与 package version 数据转换,之后删除旧 registry/default mapping 和所有模板兼容读写;迁移歧义必须阻断,不得延长兼容窗口。 Phase 8 启动记录(2026-10-17): - Phase 7 实现 commit:`71c528d feat: 收口模板升级与阶段七持续回归`; - 自动化模板、API、Client、Admin 和构建门禁已通过;`template:doctor` 的 `completionStatus` 仍为 `unverified`; - 当前阶段需要真实品牌、真实部署参数、微信开发者工具/真机和运营审阅证据,不能仅由本地自动化继续替代。 Phase 8 本地证据(2026-10-17): - `node scripts/template-doctor.mjs --output .codex-tasks/template-audit-execution/raw/phase8-after.json` 通过;三个模板均为 `staticStatus=pass`、`unresolvedIssues=0`,但 `completionStatus=unverified`,报告保留 112 条已登记 source review; - `node --test apps/taro/test/build-contract.test.mjs` 通过 `3/3`,已检查三个模板的 weapp 页面入口、导航、`project.config.json`、button reset 和 H5 module 入口; - 以上证据只证明静态诊断和已生成产物契约,尚未证明真实品牌保存重载发布、视觉对照或微信真机行为。 Phase 8 自动化持久化与兼容审查(2026-10-17): - API unit `65/65`、API Client `8/8`、Admin `6/6`、发布验证/部署测试 `8/8` 通过;隔离 PostgreSQL schema 中执行完整 `pnpm --filter @personal-brand/api test:integration`,HTTP integration `54/54`、upload integration `2/2` 通过,schema migration 与重复 seed 幂等性通过; - 隔离 integration 中真实 manifest bindings 经数据库持久化、草稿预览和发布快照测试通过(193 个 manifest bindings);这证明自动化数据链,不等价于人工在 Admin 实际点选编辑,也不替代独立模板视觉审查; - 旧默认视觉映射仍被 seed、草稿/公开 Runtime、release snapshot 和显式 bootstrap 调用,违反单一契约决策。必须先输出只读迁移报告,将每个运行品牌明确绑定到已发布 visual package version/checksum;无法唯一映射时阻断。完成一次性转换后删除所有 fallback,不提供双读或兼容窗口。 退出门禁:真实品牌保存重载发布、视觉证据、双端外部验证和运营审阅记录全部归档;历史品牌通过一次性迁移满足唯一模板契约,所有兼容层和旧字段已删除。 Phase 8 编辑闭环回归(2026-10-18): - 用户反馈模板预览初步认可,尚不视为逐区域、双端视觉验收完成。 - 修复 Admin renderer 解析每次返回新 React 组件导致悬浮更新卸载画布、点击和输入焦点丢失的问题;同一模板复用稳定组件引用。高亮覆盖层穿透指针,仅组合选区按钮接收点击。 - 修复页面内容保存成功后仍保留未保存标记、切页被错误拦截的问题;失败时继续保留草稿与原有离页保护。 - 修复餐饮菜单底部按钮全宽叠加左右外边距造成的窄屏溢出;包递增为 `acheng-campus-food@1.0.2`,同步 package metadata、生成目录与发布构建清单。 - 编辑器浏览器测试使用真实 manifest,修正 Runtime plugin fixture、列表字段与页面控件定位;新增悬浮后 DOM 保留、覆盖层穿透及保存后切页无确认弹窗断言。数据库 integration 补充全部品牌/业务/信任字段修改后、发布前公开快照不变的断言。 - 浏览器编辑器 `2/2`、模板管理预览 `1/1`、业务弹窗跨入口编辑 `1/1` 通过;隔离数据库 HTTP integration `54/54`、upload `2/2` 通过;Admin unit `6/6`、typecheck、production build、变更 TypeScript ESLint、模板总门禁、format 与 diff 检查通过;餐饮 H5/weapp 本地 smoke 构建及三模板产物契约 `3/3` 通过。餐饮品牌未配置真实 AppID,本次构建不作为真实部署参数或微信发布证据。 - 浏览器 fixture 与数据库 integration 是分别验证的证据,尚未执行连接隔离数据库的完整浏览器发布流程;`template:doctor` 仍为 `completionStatus=unverified`,三个模板静态通过且未解决项为 `0`。 ## 13. 历史问题到自动化验收的映射 | 已发生问题 | 必须新增的验收 | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | 代码部署了但线上没有品牌数据库内容 | 部署 smoke test 明确代码、migration、seed fixture 和品牌内容;模板样例只通过显式 bootstrap 进入品牌 | | 线上选择不到新品牌模板 | 目录接口返回版本、行业兼容矩阵和发布状态;Admin 有创建/选择兼容品牌的路径;跨行业组合被明确拒绝 | | 新模板没有基础数据 | preview fixture 可独立预览;bootstrap 有 dry-run、来源记录和缺失字段测试;不依赖一次性 seed | | 老品牌没有新字段 | 升级测试验证 missing-only、显式空值保留、冲突和重复执行 | | 首页/我的页面缺主理人内容 | manifest 的页面区域、renderer 消费、editor binding 和固定 fixture 同时验收;个人页不是由记录数量决定是否出现 | | 咨询、关于、我的的页面角色混乱 | 导航 manifest、CTA 目标、页面责任和端到端点击路径测试;第三个 tab 的角色由模板声明驱动 | | 修改 tab 名称但实际页面未梳理 | 导航 label、route、页面标题、CTA 和截图 fixture 一致性测试 | | Taro、原生、theme、文档多套漂移 | package-discovered renderer/conformance、双端产物检查和唯一默认 renderer 门禁 | | release 包漏 apps/taro 或模板源码 | release:conformance 在干净安装中检查 workspace、文件清单、构建入口和缺失产物 | | production 使用 devDependencies 缺 CLI | production install + build + runtime import test,明确依赖分类 | | 分次安装丢 miniprogram-ci 或 zod | 依赖闭包测试、lockfile 复现、API/回滚路径实际 import | | No projects matched 但命令退出 0 | 构建命令必须检查 project count 和 app.json,无匹配返回非零并记录诊断 | | 每行日志并发写导致 P2034、状态永久轮询 | attempt/lease、顺序日志、原子状态迁移、终态收敛、超时和进程重启测试 | | 使用默认 brand slug 或旧 app.json 冒充成功 | 产物读取 app.json、请求 URL、品牌 slug、模板版本和 release id 的一致性检查 | | doctor 只按 file/line 机械更新 | issue 采用稳定语义指纹,源代码变化使 review 失效;静态通过仍需真实编辑、保存、重载、发布和视觉证据 | | 用 mock/API 成功宣称微信上线 | 自动化证据和真实微信开发者工具/真机上传证据分栏记录;没有外部结果就标记未完成 | ## 14. 最终端到端验收 验收在独立环境完成,使用干净 checkout、隔离数据库、隔离对象存储前缀和专用测试品牌。步骤和证据必须按顺序保存: 1. 从干净分支导出一个新模板包,记录 commit、包版本、package schema、runtime contract、renderer、文件清单和 checksum; 2. 重复导出并证明 checksum 相同;修改一个文件后证明 checksum 改变; 3. 将包导入隔离线上环境,确认非法路径、超限文件、symlink、未知 binding 和版本冲突被拒绝; 4. 用有效包完成导入、校验和目录发布,记录 job、validation report 和审计; 5. 选择 personal、food、doors 中至少两个行业分别预览,确认兼容矩阵正确; 6. 确认预览能看到主理人/身份、信任、业务内容、咨询入口和第三个 tab 的完整页面角色; 7. 确认预览不会创建品牌、写入 TrustContent、创建 inquiry form、保存咨询提交或生成 release; 8. 创建兼容测试品牌,安装精确模板版本,记录安装快照; 9. 对 bootstrap 执行 dry-run,确认新增、保留、显式空值和冲突,确认来源包含 key/version/checksum; 10. 编辑一个字段、主动清空一个字段、增加一条业务内容,保存后刷新页面确认值仍在; 11. 发布品牌内容,确认 public workspace 只读发布快照,未发布草稿不会公开; 12. 用真实品牌 slug、模板版本、API 地址和 AppID 构建 H5/weapp,检查产物路径、app.json、请求地址、媒体资源和模板版本; 13. 上传并分别记录 build、upload、review、release 的状态、日志、attempt 和外部返回 id; 14. 同一品牌安装新模板版本,执行差异预览、冲突处理和成功升级;注入失败后重试和重启 worker,确认不会重复导入或永久轮询; 15. 回滚并确认用户数据、历史 release、咨询提交和旧资源仍可读取; 16. 并行对第二个品牌执行构建、上传和发布,确认路径、日志、状态和内容不串品牌; 17. 重复执行导入、bootstrap、升级和重试,确认所有幂等约束成立; 18. 归档 API、Admin、构建、数据库、预览截图和微信外部结果,更新本文进度。 自动化可以覆盖 1 至 12、14 至 17 的大部分行为,但微信开发者工具、真机、审核和线上代码上传结果必须在验收记录中明确标为“真实外部验证”。没有这部分证据时,只能说自动化链路通过,不能说小程序已上线。 ## 15. 进度登记模板 每个阶段完成时追加一条记录,不覆盖历史: 日期: 阶段: 实现 commit: 数据库 migration: 接口和页面: 测试命令: 测试结果: 真实环境: 外部证据: 未解决问题: 风险负责人和后续动作: 阶段状态只使用: - 未开始:尚未实现; - 进行中:有代码但未通过全部退出门禁; - 待外部验证:自动化和内部证据通过,仍缺真实微信或线上环境结果; - 已完成:退出门禁和所需外部证据都已归档; - 阻断:明确阻断原因、影响阶段和恢复动作。 ## 16. 未决决策 以下问题必须在对应阶段开始前作出可审阅决定,不允许用临时默认值带过: | 问题 | 推荐方向 | 最晚决定阶段 | | ----------------------------------------------- | ------------------------------------------------------------------------ | ------------ | | 平台模板管理员角色名称和权限来源 | 独立于品牌 owner 的平台级权限,所有操作审计 | Phase 0 | | artifact 存储 | 版本化对象存储或受控 release 目录,按 checksum/版本寻址 | Phase 2 | | preview session 存储 | 第一阶段使用短期 token + 服务端受控数据;需要审计时再持久化 session | Phase 3 | | 视觉安装模型 | 唯一品牌安装记录锁定行业模型和精确视觉包版本,完成一次性迁移并删除旧状态 | Phase 4 | | renderer 分发 | 第一阶段只引用预部署 renderer;任意新 renderer 走独立可信构建方案 | Phase 1 | | 包签名 | 内网 MVP 先 checksum,跨环境或第三方来源前增加签名和信任根 | Phase 2 | | 目录可见性 | 未发布版本只给平台管理员,已发布版本才给品牌管理员 | Phase 2 | | template package version 与 npm package version | 导出前强制一致,若不一致直接阻断 | Phase 1 | ## 17. 可观察性和风险 必须记录并可查询: - 模板包 key、version、checksum、schema、runtime、renderer 和 capability; - import/validation/preview/install/bootstrap/upgrade/build/upload/release 的 operationId、attemptId、requestId、actor 和 brand context; - job 的开始、心跳、重试、lease 过期、终态和外部返回 id; - 诊断 issue code、稳定语义指纹、文件/manifest 路径和修复建议; - 预览创建量、预览失败量、安装冲突、bootstrap no-op、构建失败、上传失败和永久轮询告警。 重点风险: - 如果仍把模板代码作为线上任意上传内容执行,平台会引入供应链和租户隔离风险; - 如果行业安装和视觉安装继续共用不清晰的字段,升级和回滚会误改品牌; - 如果 sample 和 bootstrap 不分离,预览数据会污染品牌内容或产生虚假公开背书; - 如果 renderer、runtime、toolchain 版本没有分别记录,新模板会在部署后才暴露兼容问题; - 如果只测试 happy path,依赖丢失、进程重启和并行构建仍会回到永久轮询; - 如果视觉验收继续依赖静态源码匹配,首页、关于/我的、咨询和 CTA 的逻辑问题仍会漏掉。 风险的接受条件是有明确 owner、触发指标和恢复动作;“暂时没复现”不能作为关闭依据。 ## 18. 相关文档 - [ADR 0029:模板管理、导入与分发边界](adr/0029-template-management-and-distribution.md) - [模板注册表](template-registry.md) - [模板运行时实施进度](template-runtime-progress.md) - [模板完成度规则](template-completion-rules.md) - [模板数据流](template-data-flow.md) - [工程交付清单](engineering-delivery-checklist.md) - [ADR 0008:视觉模板包契约](adr/0008-visual-template-package-contract.md) - [ADR 0019:Taro 模板双端运行时](adr/0019-taro-template-runtime.md) - [ADR 0022:模板完成度诊断](adr/0022-template-completion-diagnostics.md) - [ADR 0028:按当前视觉模板显式导入示例](adr/0028-template-selected-sample-import.md)