fix: restore deleted content (authentication, structure check, icon rules)

2026-04-15 09:58:31 +00:00
parent 8dac914624
commit 0869464a99
1 changed files with 225 additions and 19 deletions
--- a/.claude/skills/d8d-dev/visual-diff-mode-pencil.md
+++ b/.claude/skills/d8d-dev/visual-diff-mode-pencil.md
@@ -56,7 +56,7 @@ Phase PVD-1: 逐页对比循环
  对每个映射页面：
  ├── A. Pencil MCP 导出设计帧截图
  ├── B. Playwright 截取实际页面
-  ├── C. AI 视觉对比
+  ├── C. 结构校验（.pen节点树）+ AI 视觉对比
  ├── D. 差异分级 + 强制执行计数
  └── E. PAGE GATE-CHECK 门禁检查

@@ -150,7 +150,7 @@ visual_diff_pencil_mapping:
 ```
 原理：代码中存在的页面一定要对比，不能因为自动映射失败就漏掉。
  1. 读取 app/mini-program/src/pages.json
-  2. 提取所有 pages 和 subpackages 中的页面路径
+  2. 提取 all pages 和 subpackages 中的页面路径
  3. 对每个页面路径:
     - 提取页面名 = 路径倒数第二段（"pages/withdraw/index" → "withdraw"）
     - 检查当前映射表中是否已有该页面
@@ -175,6 +175,15 @@ mkdir -p tests/e2e/screenshots/visual-diff-pencil
 - 便于独立追踪每个页面的验证进度
 - 避免单个 agent 上下文过大导致污染或遗漏

+### 分批并行策略
+
+**Anthropic API 配额限制**: 单次 5 小时窗口有请求次数限额，一次性启动全部 agent 容易触发 `429 AccountQuotaExceeded`。
+
+**推荐执行策略**:
+- 每次启动 **5 个页面** 验证
+- 等待全部完成后再启动下一批
+- 如果遇到 429 配额超限，**提示用户更换 API key 或等待配额重置** 后继续（重置时间在错误提示中有说明）
+
 ### 0.8 启动逐个任务验证

 对**每个任务**启动一个**独立的 agent**，按照 Phase PVD-1 流程执行验证。独立 agent 避免上下文污染，执行更精准。
@@ -184,15 +193,15 @@ mkdir -p tests/e2e/screenshots/visual-diff-pencil
 ## Phase PVD-1: 逐页门禁对比循环

 ⛔ **核心原则：逐页执行，每页必须通过门禁才能继续下一页。禁止全量截图后批量对比。**
-**最佳实践：每个页面启动一个独立 agent，避免上下文污染，执行更精准。**
+**最佳实践：每个页面启动一个独立 agent，分批并行执行，避免上下文污染和 Playwright MCP 配额超限，执行更精准。**

-对映射表中每个 `status: active` 的页面，依次执行以下完整循环（每个页面由独立 agent 处理）：
+对映射表中每个 `status: active` 的页面，**分批启动**独立 agent 依次执行以下完整循环（每个页面由独立 agent 处理）：

 ```
 PVD-1 PER-PAGE LOOP:
  A. 导出设计截图
  B. 截取实际页面
-  C. AI 视觉对比
+  C. 结构校验 + AI 视觉对比
  D. 差异分级
  E. PAGE GATE-CHECK ⛔
     ├── 🟢 通过 → G. 记录 → NEXT PAGE
@@ -221,22 +230,199 @@ PVD-1 PER-PAGE LOOP:

 ```
 1. browser_resize → 375x812（移动端）或 1440x900（管理后台）
-2. browser_navigate → {实际 URL}{route}
-3. browser_wait_for → time=3
-4. browser_take_screenshot(fullPage=false)
+2. 处理认证（如需要）→ 见下文
+3. browser_navigate → {实际 URL}{route}
+4. browser_wait_for → time=3
+5. browser_take_screenshot(fullPage=false)
   → tests/e2e/screenshots/visual-diff-pencil/{name}-actual.png
 ```

-### 1.C AI 视觉对比
+### 认证处理（需要登录的页面）

-使用 Read 工具分别查看设计截图和实际截图，AI 综合分析视觉差异:
- 布局结构（网格/弹性/定位、对齐方式）
- 组件排列（导航栏、卡片、按钮、图标）
- 颜色（Neon Pulse 规范：#000000 背景、#ffb3b5 粉色、#e8b3ff 紫色、#00dce5 青色）
- 间距（内边距、外边距、元素间距）
- 字体（大小、粗细、颜色、对齐方式）
- 图标（是否存在、形状是否正确、是否 emoji 替代）
- 设计规范（是否违反 Neon Pulse 原则：如存在不必要的 1px 边框）
+大多数功能页面需要登录才能访问，未登录会自动跳转到登录页。正确流程：
+
+1. **生成测试 token**（需要组织者权限的页面必须）：
+   项目已提供预先生成 token 的脚本，直接运行：
+   ```bash
+   node tests/generate-test-token.cjs
+   ```
+   输出一个已认证组织者身份的 JWT token，复制备用。
+
+   > 脚本会使用 `api/.env` 中的 `JWT_SECRET` 生成签名，确保与后端验证一致。
+
+2. 如果已有测试 token，在 `browser_navigate` **之前** 注入 token 到 `localStorage`:
+   ```javascript
+   await page.evaluate((token, userInfo) => {
+     localStorage.setItem('token', token);
+     localStorage.setItem('user', JSON.stringify(userInfo));
+   }, token, userInfo);
+   ```
+   其中 `userInfo` 是：
+   ```javascript
+   {
+     id: "test-organizer-user-id",
+     nickname: "Test Organizer",
+     role: "organizer",
+     organizer: { id: "test-organizer-id", status: "APPROVED" }
+   }
+   ```
+
+3. 再导航到目标 URL
+4. 如果需要组织者权限，确保测试账号已通过局头认证（状态 `APPROVED`）
+
+### 常见问题排查
+
+| 问题现象 | 可能原因 | 解决方案 |
+|------|------|---------|
+| 截图黑屏 / 内容空白 | 缺少必要 URL 参数（如 `eventId`），页面无法获取数据 | 从 API 获取有效测试 ID，访问时带上查询参数 `?id=xxx` |
+| 始终显示登录页（即使应该已登录） | 缺少 token 或 token 无效 | 重新登录获取有效 token 注入 `localStorage` |
+| API 返回 401 即使有 token | **服务端环境变量 `JWT_SECRET` 与本地不匹配** | 修改 `api/.env` 后执行 `pm2 restart api` 重启加载 |
+| 页面白屏 / JavaScript 报错 | API 返回 `null` 时代码直接访问属性 | 添加可选链操作符 `?.` 做防御性编程 |
+
+### 1.C 结构校验 + AI 视觉对比
+
+**分两步：先做结构校验，再做视觉对比**
+
+```
+步骤:
+  1. 从 Pencil MCP batch_get 获取当前设计帧的完整节点树
+  2. **递归提取所有层级命名节点**（任意层级只要 name 属性存在的节点）→ 得到"必须存在的组件列表"
+     **递归算法**:
+       function collectNamedNodes(node, path, resultList):
+         if node.name != null && node.name != "":
+           resultList.push({path: path + node.name, node: node})
+         for each child in node.children:
+           collectNamedNodes(child, path + node.name + ".", result);
+     
+     **强制要求**: **任何层级**只要节点有 name 属性，都必须提取并检查。**不允许只检查顶层不检查深层**。
+     
+     结果包含所有层级：topBar, topBar.topLeft, topBar.topRight, tabSection, tabSection.tabLeft, barCard1, barCard1.ratingBadge, barCard1.activitySnippet 等等（深度嵌套没问题，全部提取）。
+     示例: topBar.topLeft / tabSection.tabLeft / availableCard / amountInput / ...
+  3. **检查全局配置关联**: 如果设计帧包含 name=bottomNav/BottomNav 且是 ref 组件
+       - 读取 app/mini-program/src/pages.json → 获取当前 tabBar 配置
+       - 对比设计中 bottomNav.children.length vs 实际 tabBar.list.length
+       - 对比每个 item 文字描述是否匹配（如果可匹配）
+       - 数量不匹配 → critical_count += 1（底部导航结构错误是严重差异）
+  4. 读取实际页面源码（app/mini-program/src/pages/{page}/index.vue），双向检查每个必需组件:
+     - **必需组件检查**: 按路径节点整个区块缺失 → 直接判定为 🔴 严重差异 → critical_count += 1
+       **强制规则**: 无论层级多深，**只要设计节点有 name 就必须存在**，缺失必须计数
+     - **多余组件检查**: 实际页面存在设计稿中没有的顶层区块 → 🟡 中等差异 → moderate_count += 1
+     - **组件类型一致性检查**: 设计是 `icon_font` 但实现用纯文本字符 → 🟡 中等差异 → moderate_count += 1
+     - **文字样式一致性检查**: **任意设计节点 type=text 且有 name** → 检查 fill 颜色 + fontSize + fontWeight 与实际CSS不符 → 🟡 中等差异 → moderate_count += 1
+     - **布局对齐检查**: 设计节点声明 `justifyContent: space_between` → 检查实际CSS是否正确设置 `display: flex; justify-content: space-between;` → 如果右侧元素未靠右对齐 → 🟡 中等差异 → moderate_count += 1
+  5. 结构校验通过后，使用 Read 工具分别查看设计截图和实际截图，AI 综合分析视觉差异:
+     - 布局结构（网格/弹性/定位、对齐方式）
+     - 组件排列（导航栏、卡片、按钮、图标）
+     - 颜色（Neon Pulse 规范：#000000 背景、#ffb3b5 粉色、#e8b3ff 紫色、#00dce5 青色）
+     - 间距（内边距、外边距、元素间距）
+     - 字体（大小、粗细、颜色、对齐方式）
+     - 图标（是否存在、形状是否正确、是否 emoji 替代）
+     - 设计规范（是否违反 Neon Pulse 原则：如存在不必要的 1px 边框）
+```
+
+### 可复用组件检查（通用规则）
+
+设计稿 (.pen) 中标记 `reusable: true` 的组件为**全局可复用组件**，必须抽取为 Vue 全局组件在 `app/mini-program/src/components/` 目录，所有页面使用 import 导入，禁止在每个页面重复手写完整实现。
+
+**检查规则**：
+  1. 先通过 Pencil MCP `batch_get` 扫描 `.pen` 中所有标记 `reusable: true` 的节点 → 获取全局可复用组件列表
+  2. 对每个需要使用该组件的页面：
+     - 如果页面**完整手写实现了可复用组件代码**（未 import 使用全局组件）→ 🟡 中等差异 `moderate_count += 1`
+     - 如果使用了全局组件但样式（背景色/尺寸）不符合设计规范 → 🟡 中等差异 `moderate_count += 1`
+     - 正确使用了全局组件且样式符合规范 → 不计数
+
+**当前已识别可复用组件**：
+  - `NavigationBarPrimary` (一级页面通用导航栏) → 要求：背景 `#000000` 不透明
+  - `NavigationBarWithBack` (二级页面带返回导航栏) → 要求：背景 `#000000cc` 半透明 + `backdrop-filter: blur(20px)`
+
+**修复要求**：发现重复手写实现必须抽取为全局组件，并更新所有页面使用。
+
+### 图标检查特别规则（@egoist/tailwindcss-icons）
+
+**设计要求**：设计节点 `type=icon_font` 必须用 tailwindcss-icons 实现，禁止使用 emoji 或纯文本占位。
+
+**正确 HTML 结构：**
+```vue
+<!-- ✅ 正确：容器嵌套独立图标元素 -->
+<view class="action-icon pink">
+  <view class="i-lucide-flame"></view>
+</view>
+
+<!-- ❌ 错误：图标类直接放在容器 -->
+<view class="action-icon pink i-lucide-flame"></view>
+```
+
+**正确 CSS 规则：**
+```css
+/* 必须添加确保SVG继承颜色 */
+.action-icon > view svg {
+  width: 100%;
+  height: 100%;
+  fill: currentColor;
+}
+```
+
+**图标命名规则：**
+
+项目 tailwind.config.js 已启用三个图标集合：
+```js
+collections: getIconCollections(["mdi", "lucide", "material-symbols"]);
+```
+
+| 图标库 | 类名前缀 | 适用场景 |
+|---------|----------|----------|
+| Material Symbols | `i-material-symbols-*` | 直接使用设计中的原始名称，不需要转换 |
+| Material Design Icons | `i-mdi-*` | 常用 material 图标 |
+| Lucide | `i-lucide-*` | 设计中 Material Symbols 不存在时使用 |
+
+**Material Symbols → Lucide 名称映射表**（当设计使用 Material Symbols 但需要用 Lucide 替代时参考）：
+
+| Material 名称 | Lucide 对应名称 | 示例场景 |
+|---------------|-----------------|------------|
+| `local_fire_department` | `flame` | 热门推荐/火焰 |
+| `near_me` | `navigation` | 附近/定位 |
+| `military_tech` | `trophy` | 排行/奖杯 |
+| `wine_bar` | `wine` | 酒吧/酒杯 |
+| `location_on` | `map-pin` | 位置 |
+| `star` | `star` | 评分/星星 |
+| `chevron_right` | `chevron-right` | 向右箭头 |
+
+**差异定级规则：**
+- 结构错误（图标类在容器上）→ 🟡 中等差异 `moderate_count += 1`
+- 缺少 `fill: currentColor` → 🟡 中等差异 `moderate_count += 1`
+- 图标名称不匹配（按上表）→ 🟡 中等差异 `moderate_count += 1`
+- **使用 emoji 替代图标** → 🔴 严重差异 `critical_count += 1` **(微信小程序不兼容emoji，强制修复)**
+
+### 布局对齐检查
+
+对于设计节点使用 `justifyContent: space_between` 的水平排列容器：
+- 检查实际CSS是否正确设置 `display: flex; justify-content: space-between; align-items: flex-start;`
+- 如果左侧元素挤在一起，右侧元素没有靠右对齐 → 🟡 中等差异 `moderate_count += 1`
+
+对于设计节点声明的对齐方式：
+- 实际实现对齐方式不符 → 🟡 中等差异 `moderate_count += 1`
+
+### 防御性编程提醒
+
+当 API 数据可能返回 `null` 时（未登录/加载失败），确保代码使用**可选链操作符 `?.`**访问属性避免渲染崩溃：
+
+```vue
+<!-- 正确 -->
+<template>{{ earnings?.totalAmount }}</template>
+
+<!-- 错误 -> 页面渲染崩溃 -->
+<template>{{ earnings.totalAmount }}</template>
+```
+
+如果发现源码缺少可选链，在 AUTO-FIX 阶段应当添加。
+
+**优势**:
+- 利用设计文件本身的结构信息，比纯视觉分析更可靠
+- **递归检查所有层级** → 确保不会漏检顶层存在但内部子区块缺失（如 topBar 存在但 topLeft 缺失）
+- **自动检查全局 tabBar 配置** → 设计稿显示的 bottomNav 结构必须与实际配置一致
+- **所有文字节点都检查** → 正文/meta/操作计数等颜色不符不会漏检
+- 确保不会漏检"整个区块缺失"（如支付结果页订单信息卡片整个不见了）
+- 帮助 AI 聚焦到每个具体组件，差异分析更准确

 ### 1.D 差异分级

@@ -253,8 +439,8 @@ PVD-1 PER-PAGE LOOP:

 | 情况 | 级别 | 是否计数 |
 |------|------|----------|
-| 布局结构不同、关键组件缺失 | 🔴 严重 | `critical_count += 1` |
-| 颜色/间距偏差、图标不一致、文本对齐方式不符、圆角尺寸差异、多余顶层区块、违反Neon Pulse设计规范、组件类型不匹配、文字标签颜色/字体大小不符 | 🟡 中等 | `moderate_count += 1` |
+| 布局结构不同、**任意层级**关键组件缺失、bottomNav 配置与设计不匹配 (Tab数量/文字) | 🔴 严重 | `critical_count += 1` |
+| 颜色/间距偏差、图标不一致、文本对齐方式不符、圆角尺寸差异、多余顶层区块、违反Neon Pulse设计规范、组件类型不匹配、**任意命名文字节点颜色/字体大小不符** | 🟡 中等 | `moderate_count += 1` |
 | 微小像素差异 (1-2px 偏移) | 🟢 轻微 | `minor_count += 1` |

 **门禁规则再强调**：
@@ -294,6 +480,10 @@ FIX LOOP (最多 3 轮):
  F2. 修改代码（CSS/组件/布局/颜色）
      - 使用 Edit 工具修改对应文件
      - 参照设计稿的 Neon Pulse 设计规范
+      - **图标问题修复优先顺序**:
+        1. 修正结构 → 将图标类从容器移出，嵌套独立 `<view>`
+        2. 修正名称 → 按 Material → Lucide 映射表修改正确名称
+        3. 添加CSS → 确保 `svg { fill: currentColor; }` 让颜色正确继承
  F3. 重启服务（如修改了后端或需要刷新构建）
      - Bash: pm2 restart mini-h5（移动端）或 pm2 restart admin（管理后台）
  F4. 重截实际页面
@@ -332,6 +522,22 @@ visual_diff_pencil:

 ---

+## 复查阶段（必须）
+
+> **第一轮 PVD-1 验证完成成后，必须启动一轮专门的复查阶段**
+
+原因：
+- 初始验证时，很多需要登录/参数的页面因未登录/缺少参数导致截图不正确，但代码对齐检查已通过
+- 必须逐个页面确认**截图内容实际正确**
+- 只有**所有页面截图都正确**，整个验证任务才算完成
+
+操作：
+1. 为每个 `status: active` 页面创建独立的**复查 Task**
+2. 逐个检查：截图文件存在 → 内容显示正确目标页面 → 布局与设计对齐
+3. 如果不正确：修复问题（注入token/添加URL参数/修复代码bug）→ 重新截图
+
+---
+
 ## Phase PVD-2: 汇总报告

 ### 2.1 生成报告