# 调试指南

核心思想：先定位规范与目标页面，再用自动化完成复现、修复与回归；尽量不要求用户提供技术细节。

## 1. 调试前准备

开始调试前，按顺序确认以下信息：

- 目标目录下的 `spec.md`、`index.tsx`、`style.css`（如有）
- 相关主题文件：`DESIGN.md`、`designToken.json`、`globals.css`（如有）
- 验收规则：`rules/development-guide.md`
- 涉及视觉或布局问题时，额外参考 `rules/design-guide.md`

### 1.1 视觉问题的设计规范优先级

当问题属于样式、布局、层级、字体、配色、组件状态不一致时，按以下顺序判断：

1. **用户提供的设计规范**
2. **主题内设计系统**：`DESIGN.md`
3. **默认设计规范（兜底）**
   - **基础型界面**：`/skills/third-party/interface-design/SKILL.md`
     - 适用：后台、ToB、工具类、设置页、数据工作台
   - **风格化界面**：`/skills/third-party/frontend-design/SKILL.md`
     - 适用：落地页、品牌展示、营销页、ToC 产品页、强视觉 App 页面

## 2. 标准调试流程

### 2.1 先跑验收脚本

优先运行项目验收脚本，拿到真实状态和目标地址：

```bash
node scripts/check-app-ready.mjs /components/[组件目录]
# 或
node scripts/check-app-ready.mjs /prototypes/[原型目录]
```

处理原则：

- `ERROR`：优先修复构建、依赖、运行时报错，再进入浏览器复现
- `READY`：直接进入浏览器自动化验收
- `TIMEOUT`：优先排查启动卡死、接口阻塞、长任务或脚本异常

### 2.2 自动化复现与定位

- **优先使用 Chrome DevTools MCP**；没有时使用 **Playwright MCP**
- 如果当前环境没有可用 MCP：直接提示用户安装并完成配置，再继续自动化验收
- 自动化过程中必须完成：
  - 打开验收脚本返回的 `targetUrl`
  - 检查 Console、Network、页面报错与资源加载状态
  - 复现核心交互链路，而不是只看首屏
  - 必要时截图、快照、记录关键 DOM / 样式状态

## 3. 问题处理顺序

按影响范围由大到小处理：

1. **构建与启动问题**：依赖缺失、编译失败、路径错误、语法错误
2. **运行时问题**：白屏、崩溃、接口异常、状态错误、空数据未兜底
3. **交互问题**：按钮不可点、表单无反馈、弹层错位、路由异常
4. **视觉问题**：尺寸、间距、颜色、字体、层级、响应式、主题不一致

**重要**：一次只修一个明确问题。每次修复后必须重新验收，确认未引入新问题，再继续下一个。

## 4. 视觉与交互调试要求

当页面可访问后，不仅要看“能打开”，还要验证：

- 关键任务路径是否能走通
- 空状态、加载态、错误态是否合理
- 文案、字段、组件层级是否与 `spec.md` 一致
- 响应式布局是否在主要断点下可用
- 颜色、字体、圆角、阴影、边框是否与主题或设计规范一致

如果属于视觉偏差，但用户未提供设计稿：

- **基础型界面**按 `/skills/third-party/interface-design/SKILL.md` 约束修复
- **风格化界面**按 `/skills/third-party/frontend-design/SKILL.md` 约束修复

## 5. 回归验收

每次修复后都必须重复以下动作：

1. 重新运行 `check-app-ready.mjs`
2. 再次打开 `targetUrl`
3. 重跑刚才失败的交互链路
4. 确认 Console 无新增报错
5. 确认页面状态恢复正常

只有当前问题完成回归后，才能进入下一个问题。