为 miniprogram-ci 和 Jimp 依赖增加兼容 patch 与 smoke test;修复平台模板管理员路由漏配;收紧模板契约校验;为 admin/customer 增加 token 撤销和集中会话存储;同步品牌切换角色、doctor source hash、多屏宽截图证据和 CI 构建门禁。
97 lines
11 KiB
Markdown
97 lines
11 KiB
Markdown
# 模板完成度规则
|
||
|
||
## 区域与数据层级
|
||
|
||
直接编辑区域须提供全部展示变量,名称与边界一致。主理人卡片不能只有标签字段。共享姓名、头像等允许多个入口,但指向唯一权威值并说明影响范围。
|
||
|
||
组合区域仅导航、不承载字段;子区可独立点选,父容器不能吞掉点击。详情页为动态记录预览,选择记录并链接业务编辑入口。访客输入和系统状态只读并说明原因。
|
||
|
||
列表支持每项编辑、增删和必要排序;数量和布局由模板约束决定,不把四项、两列强加给所有模板。
|
||
|
||
## 完成门槛
|
||
|
||
模板可用性必须覆盖真实入口:目录列出、当前品牌行业适配、管理员成员可见、选择保存、安装版本台账和重载预览。目录存在不代表可安装;新增包必须自动具备 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 运行时,再改模板局部样式;同类问题必须补产物契约测试或视觉清单项,不允许只改单个模板的单个按钮。
|