a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# 调试指南
|
||
|
||
核心思想：先定位规范与目标页面，再用自动化完成复现、修复与回归；尽量不要求用户提供技术细节。
|
||
|
||
## 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. 确认页面状态恢复正常
|
||
|
||
只有当前问题完成回归后，才能进入下一个问题。
|