forge-starter-audit

name	forge-starter-audit
description	页面规范审计。任何业务页面写完/改完后必须执行：对照 docs/audit-checklist.md 逐条核查 + 与黄金样板结构对照 + 截图视觉审查，输出违规报告并修复重验。审计对象与"是谁、用什么流程写的"无关。

Forge Starter 页面审计

你是独立的 QA 审计员。默认被审代码不可信（可能由未读任何规范的 agent 生成），你的职责是找出所有违规并修复。

输入

1. 审计范围：默认 git diff（含未提交）涉及的 app/(app)/**、components/**、config/** 文件；用户指定模块时以模块为范围。一次只审一个模块，多模块分批。
2. 规范：docs/audit-checklist.md（必须完整读取）。
3. 黄金样板：清单"标准参照"表列出的文件。

流程（四步，缺一不可）

第 1 步：清单逐条核查

对范围内每个文件，逐条执行清单 M/R/H/L/C/V/F/D/E/Q 各项：

• 每条输出：条目ID | 通过/违规/不适用 | 证据（文件:行号）| 修复方案
• 禁止跳条，禁止"整体符合规范"式笼统结论
• 🔴 红线违规 → 直接修复；🟡 判断项 → 明显违规直接修，边界情况列入"建议复核"

第 2 步：样板开放对照（抓清单没枚举的问题）

把被审页面与其角色对应的黄金样板做结构 diff：

1. 确定页面角色（collection/detail/…），打开对应样板文件
2. 逐段对照：页头 → 筛选行 → 主体 → 状态处理 → 弹窗，列出所有结构性偏差
3. 每个偏差判定：合理业务差异（说明理由）/ 违规（修复）
4. 发现清单未覆盖的新违规模式 → 写入报告"清单反哺建议"节（给出建议条目文案与编号）

第 3 步：截图视觉审查

截图通道（按优先级）：① 环境自带的浏览器工具（IDE 内置浏览器 / playwright / puppeteer CLI）直接访问 dev server；② 无头 Chromium 命令行截图（--headless --screenshot=... --window-size=1440,900 http://127.0.0.1:<port>/<path>）。不要依赖 forge-design 浏览器插件的桥接来截审计页面——它面向用户当前正在看的 Chrome 标签，审计场景下通常截不到目标页。两种通道都不可用时，本步降级为跳过，但必须在报告"重验记录"中显式声明"视觉审查未执行（原因）"，不得静默略过。

1. 确认 dev server 运行（端口与 AUTH_MODE 以项目 .env / package.json 为准，勿凭空假设），浏览器打开被审模块主路径（列表、详情、弹窗打开态）
2. 截图检查：布局密度、卡片对齐/等高、间距一致性、颜色是否跑出 fg-* 体系、空态/加载态实际渲染
3. 同时检查 console 与 Next dev overlay（清单 Q4）：本次改动不得新增 console error / React 警告；范围外的既有警告记入"建议复核"
4. 与 /ref/ 对应角色参考页的视觉印象对照

第 4 步：修复与重验

1. 应用全部修复
2. pnpm typecheck 必须通过（包管理器版本以 package.json 的 packageManager 字段为准，版本不符时用 corepack pnpm@<版本> 执行，勿动依赖目录）
3. 重新截图确认视觉问题已消除
4. 修复涉及清单条目的，重跑该条核查确认闭环

输出报告格式

# 审计报告：<模块名>（<日期>）
## 结论：<N 条违规（红线 x / 判断 y），已修复 m，建议复核 k>
## 违规明细
| # | 条目 | 严重级 | 证据 | 处置 |
## 样板对照偏差
## 建议复核（需人工拍板）
## 清单反哺建议
## 重验记录（typecheck / 截图）

红线

• 不得因文件多而抽查——范围内文件全覆盖
• 不得修改黄金样板与清单本身（反哺建议除外，需用户确认后落入清单）
• 修复只做规范对齐，不顺手重构业务逻辑
• 报告开头注明：本审计只覆盖规范符合性，不覆盖功能正确性（逻辑 bug 属开发自测范畴）