fix: 完善模板可视化编辑闭环与通用验收
This commit is contained in:
1 parent
fa6b492bce
commit
22a82dbfba
39 files changed
+7773
-443
No files matched your search
@@ -0,0 +1,25 @@
|
||||
# 0022 模板完成度诊断与修复闭环
|
||||
|
||||
## 背景
|
||||
|
||||
可点击但变量不全、数据来源错位、编辑标记破坏网格反复出现。旧检查只证明字段存在;简化 manifest 的 fixture 不能验证真实层级。
|
||||
|
||||
## 决策
|
||||
|
||||
以视觉区域为验收单位,连接 renderer 数据读取、manifest 绑定、编辑交互、保存重载发布、视觉证据。静态诊断自动发现模板,输出问题码及位置;未验证不能当作通过。规则见 [模板完成度规则](../template-completion-rules.md)。
|
||||
|
||||
## 替代方案
|
||||
|
||||
增加点选标记不能判断字段完整性;模板特判不能覆盖新模板;静态分析不能证明浏览器布局和持久化。采用静态诊断加真实 manifest 驱动交互验证。
|
||||
|
||||
## 后果
|
||||
|
||||
编译通过的模板也可能未完成。诊断器测试通过不代表模板通过。同一事实的多个入口必须写回同一值;单记录编辑器不能静默承接跨来源保存。
|
||||
|
||||
## 迁移计划
|
||||
|
||||
先提供独立只读命令和 skill,生成现有缺口报告,逐项修复补证据。不修改数据库、seed 或旧发布快照。不将现有缺口隐藏在绿色旧校验中;所有模板交付必须执行新诊断并归档剩余项。
|
||||
|
||||
## 草稿预览修正
|
||||
|
||||
Admin 的 /admin/workspace/preview 从当前品牌记录构建内存快照,并使用公开 Runtime 的同一投影服务,返回 publication.status=draft。公开路由仍只读取发布快照。此更改解决保存后预览退回发布旧值、未发布品牌无法预览的问题,不创建数据库发布记录。原有客户端 Runtime 类型增加 draft 状态,集成测试同时验证授权、品牌范围、草稿重载和发布隔离。
|
||||
@@ -21,6 +21,8 @@
|
||||
|
||||
## 模板与配置包
|
||||
|
||||
- 执行 pnpm template:doctor 并遵循 [模板完成度规则](template-completion-rules.md),诊断未解决项和未验证项不能视为完成;
|
||||
|
||||
- 模板声明必须真正驱动安装和升级,不能只增加类型而保留 Controller 硬编码;
|
||||
- 每个页面上的品牌事实、信任资料、业务详情和可编辑文案都必须来自 Runtime 数据,并在同一页面声明对应 Admin editor binding;`pnpm validate:templates` 的逐页 renderer / editor 契约测试通过后才能判定模板完成;
|
||||
- 每种模板信任内容必须声明实际展示页面,逐页测试要同时验证“声明的类型有 renderer 消费”和“renderer 使用的类型已声明”;
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: template-completion-audit
|
||||
description: Diagnose and repair personal-brand template editability, region selection, field bindings, persistence and visual regressions. Use for new template acceptance or recurring template editor defects; distinguish static coverage from complete delivery.
|
||||
---
|
||||
|
||||
# Template completion audit
|
||||
|
||||
在目标仓库运行;先读取 AGENTS.md、docs/template-completion-rules.md 和 docs/engineering-delivery-checklist.md。此 skill 的版本化来源位于 docs/skills/template-completion-audit/SKILL.md;仓库规则是唯一标准。
|
||||
|
||||
## 执行
|
||||
|
||||
1. 确认当前分支、已有修改、真实模板包与原始视觉参考。使用真实 manifest,禁止为方便测试重新写简化声明。
|
||||
2. 运行 pnpm template:doctor --output <task-dir>/before.json;按需加 --template <packageKey>。退出 1 是发现问题,退出 2 是工具错误;完整保留两者,不吞掉失败。
|
||||
3. 检查每个区域的全部展示变量、来源、绑定、页面和记录 ID;特别核查共享事实、fallback 优先级、组合选区对子区的拦截、列表项和未消费字段。未知映射标 review,不猜测为通过。
|
||||
4. 优先修同根公共逻辑,补失败回归后小批修改。诊断命令只读,不提供猜测式 --fix。catalog 和格式化可以自动运行;不以清报告为由复制数据库字段、修改 seed、删除显示内容或放宽检查。用户授权编辑不等于授权破坏性迁移。
|
||||
5. 对每个修改的字段使用独特值执行点选、预览、正确请求、保存、重载、发布验证;真实数据库测试必须隔离。mock PATCH 只能证明前端请求;必须说明缺失的持久化证据。
|
||||
6. 比较原型与多屏宽截图,特别核查新增 DOM wrapper 对 grid/flex 直接子项的影响。未见原型时记录视觉基线待核实。
|
||||
7. 重跑诊断、相关测试、类型与构建门槛;保存 after.json、命令结果、截图及剩余项。连续 3 次同类失败时重新审查数据链和测试输入,不能继续堆补丁。
|
||||
8. 将新的故障模式写入通用规则和故障注入测试。报告工具交付与模板完成两种状态,不能用静态绿色或单条 fixture 成功代替完整验收。
|
||||
|
||||
## 验收证据
|
||||
|
||||
记录模板/代码版本、真实 manifest 来源、page/target/binding 覆盖、失败与修复、保存重载发布证据、视觉对照、未验证项。对静态分析无法处理的跨组件、动态路径和布局问题保留人工审查及浏览器测试,不自动免责。
|
||||
|
||||
已有案例:整张主理人卡片只编辑标签;统计块绑定到介绍标题;额外 wrapper 将 2×2 变成 1×4;trust 子目标缺页面或导航无法解析记录;两套简介导致保存值不是渲染值。将这些作为复现模式,不把具体模板布局写成所有模板的规则。
|
||||
|
||||
新增共享字段入口时,检查同一 binding 多个表单名的同步;未挂载字段必须保留原值。真实 manifest 的多入口修改、保存、重载是必测项,单入口 fixture 不能替代。
|
||||
|
||||
保存回归必须检查请求 payload 中的新 config 不被旧对象覆盖,内容修改不携带模板选择字段。验证真实 Admin 草稿预览刷新后仍为新值,同时公开 Runtime 保持旧值直至发布。模板专属字段须按 page 分组并同步 templateData;列表逐个核对 itemFields,空区域必须有配置入口。
|
||||
|
||||
检查标准品牌列与旧 config 同名冲突和清空优先级;主动清空后旧别名不得恢复。除侧栏逐页字段覆盖外,从画布内部叶子内容实际点击并核对选区;不能使用强制点击伪造可用性证据。
|
||||
@@ -0,0 +1,57 @@
|
||||
# 两套模板编辑闭环验收(2026-10-10)
|
||||
|
||||
范围为餐饮 acheng-campus-food 和林境 linjing-editorial 的可编辑区域、实际字段、草稿与发布数据链。基线 commit 为 fa6b492,分支 feat/admin-component-preview;结果对应当前未提交 diff。两个模板 manifest 均为包内 template.json,版本 1.0.0,测试直接读取真实声明,没有重写简化 manifest。
|
||||
|
||||
## 本轮修复
|
||||
|
||||
- 主理人区域展示的姓名、身份、简介、头像和标签提供完整入口;多个入口同步共享值。
|
||||
- 组合区域只导航,子区域优先点选;信任内容按页面定位真实记录,列表每个子字段可编辑并支持排序。
|
||||
- 林境信任数据在原 stats 容器加标记,保持 2×2;专业方法、合作流程及主理人页范围/说明独立编辑。
|
||||
- 餐饮日程的工作日和周末各自对应 4 个配置字段;配送方式对应自取/配送标题和说明;流程对应结构化步骤及附注。
|
||||
- 首页业务卡片声明补齐实际显示的地点、类别、系列、关键词、优先图片;移除该卡不消费的字段入口。
|
||||
- 详情仅选择业务记录预览,并提供业务管理入口;详情正文公共文案与底部咨询入口分为两个可编辑区域。
|
||||
- 保存仅发送真正修改的标准字段和新 config,防止旧 config 覆盖新值;跨区域未挂载修改保留,普通内容保存不携带切换模板字段。
|
||||
- 模板专属字段按各自 page 分组,预览同步 templateData。
|
||||
- Admin 预览改用当前品牌草稿的内存快照;公开 Runtime 仍只读取发布快照。未发布品牌也能预览,不产生发布记录。
|
||||
- 标准品牌列优先于旧 config 同名残留;主动清空后旧别名也不能恢复旧联系方式或简介。
|
||||
- 无记录的区域仍可定位,并显示进入相应内容管理页面的配置入口。
|
||||
|
||||
## 验证证据
|
||||
|
||||
原始证据目录为 .codex-tasks/template-audit-execution/raw/。
|
||||
|
||||
| 范围 | 证据与结果 |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 数据持久化 | integration-final.log:41 项通过;其中 generic manifest 回归对 193 个 distinct binding 写入独特值,验证 Admin 重载、草稿 Runtime、发布后公开输出 |
|
||||
| 草稿与公开隔离 | 同一集成套件覆盖草稿改变而公开保持旧值、发布后更新、未发布品牌、授权及品牌范围 |
|
||||
| 授权 | Admin preview 无凭证、无效凭证、customer 错误角色和授权成功路径均有自动化验证 |
|
||||
| 实际编辑器 | browser-current.log:使用两套真实 manifest;逐页侧栏字段、实际画布区域内部点击、共享字段与业务记录修改重载、保存失败保留、切页保护 |
|
||||
| 列表 | 林境统计值、排序、专业方法名称、流程说明修改预览及保存重载;数据库回归覆盖所有声明列表 itemFields |
|
||||
| 详情/表单 | 动态业务内容不在详情编辑;公共底部按钮独立点选、修改、保存重载;咨询字段预览、成功页和记录页可显示 |
|
||||
| 布局 | 每个页面在 320/390 像素画布验证无横向溢出,并归档对应截图;统计检查两列四项;详情按钮限制在画布范围 |
|
||||
| 契约与诊断器 | contracts-final.log:19 项;doctor-tests-final.log:19 项,含故障注入 |
|
||||
| 客户端与纯函数 | api-client-final.log:3 项;types 标准列冲突及清空回归、Admin binding 单元测试通过 |
|
||||
| 工程门槛 | API/Admin/Taro 类型检查,API/Admin lint,Admin build,food/linjing 各自 H5 和 weapp 构建,format:check 与 git diff --check |
|
||||
|
||||
集成测试使用随机隔离 schema,迁移并 seed 后运行,最后删除测试 schema;临时发布记录和 fixture 有清理。没有修改生产数据、Prisma schema、migration 或 seed。
|
||||
|
||||
## 动态映射与原型审阅
|
||||
|
||||
原始诊断 after.json 保留餐饮 55 条、林境 23 条 review,blocker 均为 0。命令仍退出 1,completionStatus 保持 unverified。manual-review.json 为全部 78 条记录保存来源审查结论与证据,不修改原报告,也不把人工审查当自动豁免。
|
||||
|
||||
主要审查结论:动态 trust 目标用 type 和实际 id 定位;formTargets 分别提供咨询/成功/记录页目标;工作日/周末和 pickup/delivery 动态字段都有实际声明;作品副标题由 series 与 keywords 派生;餐品数量和分类由业务列表派生,无独立重复字段;图标轮换仅为固定视觉资源。
|
||||
|
||||
对照原始 React 参考:餐饮位于 /home/que01/下载/阿成校园餐---微信小程序原型/,林境位于 /home/que01/下载/林境门作-·-别墅门系统高级工坊.zip。检查本次编辑标记保持统计、日程、配送及合作流程的原布局结构;没有通过 CSS 改写视觉来迁就数据。截图使用确定性本地图片 fixture,林境借用本地餐饮照片,证明布局与图片加载,不代表原型照片或像素级一致。
|
||||
|
||||
条件项逐行核对了可选文字/联系方式、列表、详情记录、附注分隔符等显示逻辑。浏览器验证完整内容和代表性的空区域/失败分支,未穷举所有字段为空的排列组合,也没有验证每个字段在真实微信 IDE 中的交互。当前证据不应解释为永久保证全部模板或所有未来分支无缺陷。
|
||||
|
||||
## 后续模板的固定验收方式
|
||||
|
||||
1. package manifest 自动发现,运行 template:doctor 保存基线和退出码。
|
||||
2. 以视觉选区核对全部数据来源、页作用域、列表子字段和只读理由。
|
||||
3. 对真实 manifest 执行画布点选及编辑器检查,不能只点侧栏。
|
||||
4. 隔离数据库对 distinct binding 验证保存、草稿、发布输出及授权,不能用 mock PATCH 替代。
|
||||
5. 对照原型与多宽截图,新增 wrapper 必须核查 grid/flex 直接子项。
|
||||
6. 归档人工动态审查与未验证范围;新故障加入诊断器/回归与 skill。
|
||||
|
||||
Admin 构建的既有大于 500 kB chunk 警告仍存在。后续由 Admin 前端维护工作处理分包,本轮不提高阈值掩盖警告。浏览器 NO_COLOR/FORCE_COLOR 冲突提示来自运行环境,不影响测试结果。
|
||||
@@ -0,0 +1,63 @@
|
||||
# 模板完成度规则
|
||||
|
||||
## 区域与数据层级
|
||||
|
||||
直接编辑区域须提供全部展示变量,名称与边界一致。主理人卡片不能只有标签字段。共享姓名、头像等允许多个入口,但指向唯一权威值并说明影响范围。
|
||||
|
||||
组合区域仅导航、不承载字段;子区可独立点选,父容器不能吞掉点击。详情页为动态记录预览,选择记录并链接业务编辑入口。访客输入和系统状态只读并说明原因。
|
||||
|
||||
列表支持每项编辑、增删和必要排序;数量和布局由模板约束决定,不把四项、两列强加给所有模板。
|
||||
|
||||
## 完成门槛
|
||||
|
||||
| 层次 | 需要证明 | 历史问题 |
|
||||
| ---------- | -------------------------------------------------- | ----------------------------------------- |
|
||||
| 数据来源 | 每个展示变量有真实绑定或只读理由 | 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,直到交互、隔离数据库保存发布、视觉证据经过审阅。退出 0 仅表示静态通过,1 表示 blocker/review,2 表示执行故障。
|
||||
|
||||
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。
|
||||
|
||||
## 保存与预览补充
|
||||
|
||||
保存请求仅包含允许修改的字段及新配置。禁止在新 config 后展开带旧 config 的完整品牌对象,禁止内容编辑携带 visualTemplateKey 触发模板切换权限。共享表单保存须保留跨区域修改。
|
||||
|
||||
Admin 预览读取当前品牌的草稿 Runtime,公开接口读取已发布快照。两者共用投影逻辑;保存后预览、重新加载预览、发布后公开读取必须分别测试。不得用 mock 返回最新数据掩盖真实预览接口仍读旧发布快照。
|
||||
|
||||
templateFields 按各自 page 分组;预览同步 templateData。列表审计必须核对 itemFields 的每个实际展示子字段,列表 binding 存在不代表子字段完整。缺少记录的区域仍须提供配置入口。
|
||||
|
||||
## 旧配置与标准列优先级
|
||||
|
||||
Runtime 合并标准品牌列和模板 config 时,标准列是共享品牌事实的权威值。同名旧 config 不得覆盖标准列;标准列主动清空为 null 时,旧 slogan、phone、wechat、studioAddress 等别名也不能恢复旧内容。回归须注入冲突值及清空值,验证草稿和公开投影一致,不依赖清洗数据库掩盖优先级错误。
|
||||
|
||||
画布点选测试必须点击实际区域内部的叶子内容,并验证目标和记录 ID;侧栏定位通过不能代替画布可点击。应避开圆角透明角落,不能用强制点击或 dispatchEvent 掩盖真实命中问题。
|
||||
@@ -15,16 +15,17 @@ This document records where template-controlled content is stored and how it rea
|
||||
|
||||
## Food Schedule Example
|
||||
|
||||
The food template declares the schedule type for the `home` and `service` pages. Its Admin fields map directly to existing database columns:
|
||||
餐饮模板的日程在 service 页展示,使用 TrustContent.config 的浅层字段:
|
||||
|
||||
- `adminFields.title` edits `TrustContent.title`.
|
||||
- `adminFields.summary` edits the primary weekday schedule in `TrustContent.summary`.
|
||||
- `adminFields.content` edits the weekend and supplementary schedule in `TrustContent.content`.
|
||||
- The public workspace returns those values as a `RuntimeTrustItem`; the home and service page renderers read `item.summary` and `item.content`.
|
||||
- title 编辑日程区块标题。
|
||||
- weekdayLabel、weekdayTag、weekdayDetail、weekdayHours 编辑工作日卡片。
|
||||
- weekendLabel、weekendTag、weekendDetail、weekendHours 编辑周末卡片。
|
||||
- status 编辑日程状态。summary 和 content 已在该类型声明中隐藏,不参与日程渲染。
|
||||
- 配送范围与流程分别使用 coverage 和 process 类型的配置字段,不能把摘要或正文作为第二套结构化数据入口。
|
||||
|
||||
No schedule-specific Prisma migration is needed. Different templates can choose different field labels while retaining the shared trust-content storage contract.
|
||||
编辑器区域列表和 renderer 的 slot 均优先使用带结构化配置的记录。页面点选传递真实 recordId;没有记录时提供内容管理入口。保存只影响品牌草稿,发布后公开 Runtime 才更新。模板样例仍属于包,不作为数据库注册目录。
|
||||
|
||||
The Admin editor lists the selected template's declared trust types and uses their `adminFields` labels, help, and placeholders. In the food workspace, the service page links directly to the trust-content editor, so the schedule is configured under **内容管理 → 信任内容 → 出摊安排**. Saving changes the brand's draft content; the Mini Program sees the new values after the next publication.
|
||||
详情页中的业务记录只提供选择预览;公共标题和按钮文案通过品牌配置区域编辑,影响全部详情页,不复制到每条业务记录。
|
||||
|
||||
## Inquiry Field Runtime Mapping
|
||||
|
||||
|
||||
Reference in new issue
Block a user