Files
persionalBrand/docs/template-completion-rules.md
T
que01 3017e3eb49 fix: 收口依赖兼容与会话撤销
为 miniprogram-ci 和 Jimp 依赖增加兼容 patch 与 smoke test;修复平台模板管理员路由漏配;收紧模板契约校验;为 admin/customer 增加 token 撤销和集中会话存储;同步品牌切换角色、doctor source hash、多屏宽截图证据和 CI 构建门禁。
2026-10-18 23:43:25 +08:00

97 lines
11 KiB
Markdown
Raw 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.
# 模板完成度规则
## 区域与数据层级
直接编辑区域须提供全部展示变量,名称与边界一致。主理人卡片不能只有标签字段。共享姓名、头像等允许多个入口,但指向唯一权威值并说明影响范围。
组合区域仅导航、不承载字段;子区可独立点选,父容器不能吞掉点击。详情页为动态记录预览,选择记录并链接业务编辑入口。访客输入和系统状态只读并说明原因。
列表支持每项编辑、增删和必要排序;数量和布局由模板约束决定,不把四项、两列强加给所有模板。
## 完成门槛
模板可用性必须覆盖真实入口:目录列出、当前品牌行业适配、管理员成员可见、选择保存、安装版本台账和重载预览。目录存在不代表可安装;新增包必须自动具备 Runtime manifest,回归不得仅在数据库预置最终 visualTemplateKey 而绕过选择与安装。用于独立宣传的模板须提供独立品牌的显式创建方法,不得通过更改现有品牌行业或放宽兼容限制解决。
| 层次 | 需要证明 | 历史问题 |
| ---------- | -------------------------------------------------- | ----------------------------------------- |
| 数据来源 | 每个展示变量有真实绑定或只读理由 | description/slogan、未消费的 brandPromise |
| 区域覆盖 | 选中边界内所有变量可修改 | 主理人只剩标签、统计只有介绍标题 |
| 层级与记录 | 最近目标点选,导航与画布一致,页面和 recordId 正确 | 自定义 trust 目标找不到记录 |
| 编辑闭环 | 独特值修改、预览变化、正确请求、重载保留 | 只验证输入框出现 |
| 发布隔离 | 草稿不影响公开内容、发布生效、品牌隔离 | 旧快照、跨品牌污染 |
| 视觉 | 原型对照、行列、宽度、按钮、滚动、多屏宽 | wrapper 使 2×2 变 1×4 |
| 异常 | 空值仍可配置、失败保留输入、重试、切页保护 | 无记录无入口、部分失败仍提示成功 |
## 自动诊断边界
运行 pnpm template:doctor,自动扫描 packages/template-*/template.json 和 Taro renderer;支持 --template packageKey、--output path 输出 JSON。每个问题包含 code、page、target、binding、位置和修复方向。
staticStatus 只代表支持范围内的静态检查。completionStatus 保持 unverified,直到交互、隔离数据库保存发布、视觉证据经过审阅。退出 1 表示存在 blocker、未登记 review 或执行后的登记校验失败,退出 2 表示执行故障。
已逐条完成源码审阅的 review 可登记在 `.codex-tasks/template-audit-execution/raw/manual-review.json`。登记必须使用和诊断报告一致的 `file/page/target/binding/line/message`,并保留结论与证据;doctor 只把精确匹配的 review 标记为 `source-reviewed`,不改变 `completionStatus`。未匹配的新 review 和全部 blocker 仍会让命令失败。
完成证据登记在 `.codex-tasks/template-audit-execution/raw/completion-evidence.json`。每套模板必须提供 `real-manifest-interaction`、`save-reload-publish-isolation`、`visual-reference`、`empty-error-branches` 四类 `passed` 证据;每类证据必须包含实际命令、`exitCode=0`、日志或截图产物及其 SHA-256。registry 还必须记录 source tree hash;doctor 会计算当前仓库源码树(排除 `.codex-tasks/` 证据目录)的 hash,并在不匹配时拒绝完成态。doctor 会校验证据覆盖全部模板、产物存在且哈希一致。全部通过时 `completionStatus=complete`;证据文件缺失时保持 `unverified`;登记不完整或哈希不匹配时对应模板为 `incomplete` 并让命令失败。
AST 解析可追踪 workspace.brand、presentation、object 和局部别名。动态路径、跨组件和间接映射等未知情况标为 review,不能猜测为通过。诊断器包含正反故障注入测试。
## 修复闭环
1. 保留真实 manifest、renderer、原型、失败截图和只读报告。
2. 按 code/page/target/binding 聚合同根问题,先修共享逻辑,再修声明;测试必须使用真实 manifest。
3. 先补失败回归。确定性格式化、catalog 生成可自动执行;业务字段归属、迁移、视觉调整按证据判断,不能自动猜测覆盖用户数据。
4. 小批修复,优先原 DOM 加标记;新增 wrapper 必查 grid/flex 直接子项和 CSS 选择器。
5. 重跑诊断及修改、保存、重载、公开输出;跨来源保存检查部分失败,mock 成功不能替代数据库证据。
6. 保留剩余项;连续 3 次同类失败重新审查原始数据链和测试输入,禁止删断言或弱化规则求绿。
7. 新故障加入诊断规则、测试和文档;skill 引用统一规则,不复制两套标准。
## 验收证据
归档 Git commit/未提交 diff、模板版本、命令结果、页面区域字段覆盖、原型与截图、隔离数据来源、保存重载发布测试定位和剩余项。状态为 pass/fail/unverified/not-applicable,最后一种必须附原因,不记录凭证和客户私密数据。
CI 可执行 pnpm test:template-doctor 和诊断命令。新模板自动扫描。现有缺口或动态证据未验证时不得声称模板全部完成。
## 共享绑定回归补充
同一绑定出现在多个区域时,修改任一入口后其他入口必须同步。未挂载字段不得以 undefined 覆盖已有配置;保存当前区域也不能清空其他区域。回归必须至少覆盖首页修改、主理人页修改、保存及重载,不能只使用单字段 fixture。
## 保存与预览补充
新增模板后,检查实际运行的 Admin renderer 与图片资源模块发现列表,而不只检查新启动的服务;新增包的图片须逐张验证 naturalWidth 大于 0。跨目录新增包可能未使运行中的 Vite glob 缓存失效,须刷新模块或重启本地开发服务。组件画布与备用 iframe 都须按当前 Runtime 的 visualTemplateKey 选择 renderer;未知模板显示不可用,不能静默回落首个模板。多模板 H5 未配置原生 tabBar,导航不得调用 switchTab。回归覆盖所有真实模板来回切换及备用 iframe。
独立 H5 预览须覆盖真实公开数据加载、失败提示及重试恢复;请求成功或失败后都必须退出 loading,不能仅以 tabbar 出现判定页面可用。编辑器预览继续等待 workspaceDraft,不得因公开请求结束而提前显示失败。
H5 开发预览的 `/media` 请求须代理至 API 媒体服务,默认 `http://localhost:3001`,可通过 `MEDIA_API_TARGET` 覆盖,或从绝对地址 `API_BASE_URL` 推导 origin。图片回归检查实际加载尺寸,不能只检查图片节点存在;生产环境仍由部署网关提供 `/media` 路由。
保存请求仅包含允许修改的字段及新配置。禁止在新 config 后展开带旧 config 的完整品牌对象,禁止内容编辑携带 visualTemplateKey 触发模板切换权限。共享表单保存须保留跨区域修改。
Admin 预览读取当前品牌的草稿 Runtime,公开接口读取已发布快照。两者共用投影逻辑;保存后预览、重新加载预览、发布后公开读取必须分别测试。不得用 mock 返回最新数据掩盖真实预览接口仍读旧发布快照。
templateFields 按各自 page 分组;预览同步 templateData。列表审计必须核对 itemFields 的每个实际展示子字段,列表 binding 存在不代表子字段完整。缺少记录的区域仍须提供配置入口。
## 旧配置与标准列优先级
Runtime 合并标准品牌列和模板 config 时,标准列是共享品牌事实的权威值。同名旧 config 不得覆盖标准列;标准列主动清空为 null 时,旧 slogan、phone、wechat、studioAddress 等别名也不能恢复旧内容。回归须注入冲突值及清空值,验证草稿和公开投影一致,不依赖清洗数据库掩盖优先级错误。
画布点选测试必须点击实际区域内部的叶子内容,并验证目标和记录 ID;侧栏定位通过不能代替画布可点击。应避开圆角透明角落,不能用强制点击或 dispatchEvent 掩盖真实命中问题。
预览 renderer 的 React 组件引用必须稳定;鼠标悬浮、选区与草稿更新不得重新创建组件类型并卸载画布。回归需覆盖移动鼠标后点选以及连续输入,确认 DOM、焦点和组件本地状态保留。高亮覆盖层必须穿透指针事件,仅显式选区按钮允许接收点击。
## Taro 小程序视觉一致性
Taro 小程序构建默认会把 CSS 中的 HTML 标签选择器重写为 `.h5-<tag>`,但 React `<Button />` 渲染的是微信原生 `<button>`,不会自动获得 `.h5-button`。本项目关闭小程序 `htmltransform`,保证 `button` 选择器直接命中微信原生 `<button>`;新增共享组件样式时不得再依赖 `.h5-<tag>`。
共享 reset 必须让微信 `<button>` 与 Taro H5 的 `taro-button-core` 一致:默认 flex、全宽、`min-height:var(--brand-button-height)`、文字居中,并重置 `appearance`、间距、边框和背景。局部按钮通过 `--brand-button-height` 或结构化 class 调整;模板样式不得复制基础尺寸,也不得重新声明整套居中规则。
共享令牌必须同时声明在 `page` 与 `body` 上(见 `apps/taro/src/app.css`):微信端根元素是 `page`,H5 渲染树里没有 `page` 元素,只写 `page` 会让 H5 的 `var(--brand-button-height)` 解析失败并退化成 `auto`。两端默认 88rpx(H5 在 375px 视口等于 44px)由浏览器测试守卫,不要把这组声明挪回单一 `page` 选择器。
## Taro 双端验收清单
小程序视觉回归按页面角色和原生控件执行,不按模板名写专用清单。平台新增或修改原生控件时,先更新共享 reset、令牌和产物契约测试,再让所有模板自动受益。每个模板变更至少记录一次:
1. 使用生产参数构建 `weapp` 和 `h5`,保留命令、产物路径和 `project.config.json` 中的 AppID。
2. 产物断言:`API_BASE_URL`、`/media/` 补全、`button` 选择器未被改写为 `.h5-button`、共享 reset 存在。
3. 页面证据:首页媒体、列表卡片、详情主行动按钮、个人页紧凑行动按钮、表单提交按钮、错误与空态。
4. 原生控件必查:显示类型、宽度、高度令牌、文字垂直居中、点击命中、安全区和底部遮挡。
5. 真机必查:request/media 合法域名、登录、拨号、复制、滚动、字体缩放和 iPhone 底部安全区。
6. 修复方式先查共享 reset、令牌和 Taro 运行时,再改模板局部样式;同类问题必须补产物契约测试或视觉清单项,不允许只改单个模板的单个按钮。