# 问题诊断与修复规范

> **核心原则**：定位根因，精准修复，避免反复

---

## 🎯 适用场景

- Bug 修复
- 样式问题调整
- 功能异常排查
- 性能问题优化
- 任何需要"修改"而非"新增"的场景

---

## ⚠️ 常见错误模式

### 表面修复陷阱

| 表面现象 | 错误做法 | 真实原因示例 |
|----------|----------|--------------|
| 边框缺失 | 直接加 border | overflow:hidden 裁剪、多文件样式冲突、伪元素被隐藏 |
| 元素错位 | 调整 margin/padding | flex 布局问题、父容器约束、z-index 层级 |
| 点击无效 | 检查事件绑定 | 透明元素遮挡、pointer-events 设置、事件冒泡被阻止 |
| 文字截断 | 增加宽度 | white-space 设置、flex-shrink 压缩、父容器限制 |
| 动画卡顿 | 降低帧率 | 频繁重排重绘、JavaScript 阻塞、内存泄漏 |
| 接口超时 | 延长超时时间 | N+1 查询、缺少索引、死锁、资源竞争 |

---

## 📋 强制诊断流程

### 第一步：复现与观察（必须）

```markdown
1. 完整复现问题，记录：
   - 具体表现是什么？
   - 在什么条件下出现？
   - 是否稳定复现？

2. 收集环境信息：
   - 浏览器/运行环境版本
   - 相关依赖版本
   - 是否仅在特定环境出现？
```

### 第二步：根因分析（核心）

**必须回答的问题**：

1. **谁**定义了这个行为？
   - 哪个文件/哪一行代码？
   - 是否有多处定义？（样式冲突常见原因）

2. **为什么**会这样表现？
   - 这段代码的原始意图是什么？
   - 当前表现与意图的差异在哪？

3. **什么时候**开始出现？
   - 是一直存在还是最近才有？
   - 如果最近才有，什么改动引入的？

4. **还有谁**可能受影响？
   - 修改这里会影响其他地方吗？
   - 是否有依赖这个行为的代码？

### 第三步：验证假设

```markdown
在修改前，必须验证你的假设：

✅ 正确做法：
- 使用浏览器开发者工具检查实际生效的样式
- 搜索全项目相关关键词，确认没有其他定义
- 临时注释可疑代码，观察变化

❌ 错误做法：
- 看一眼代码就下结论
- 不搜索直接修改
- 用 !important 强行覆盖
```

### 第四步：最小化修复

```markdown
修复原则：
1. 修改最少的代码
2. 从源头解决，而非末端补救
3. 不引入新的 hack 或 workaround
4. 保持代码一致性
```

---

## 🔍 诊断工具与方法

### 前端样式问题

```bash
# 必做检查
1. DevTools → Elements → Computed 查看最终生效样式
2. DevTools → Elements → Styles 查看样式来源和覆盖关系
3. 全项目搜索相关选择器，检查是否有冲突定义
4. 检查父元素的 overflow、position、z-index
```

### 后端接口问题

```bash
# 必做检查
1. 查看完整请求/响应日志
2. 检查数据库查询执行计划（EXPLAIN）
3. 检查是否有并发/锁问题
4. 检查资源使用情况（内存、连接池）
```

### 通用代码问题

```bash
# 必做检查
1. 使用 grep/ripgrep 搜索相关函数/变量的所有引用
2. 检查 git blame 了解代码变更历史
3. 查看相关测试用例（如果有）
4. 检查依赖库版本和已知问题
```

---

## 📝 修复报告模板

每次修复问题时，应在心中（或注释中）回答：

```markdown
## 问题描述
[具体表现]

## 根因分析
- 直接原因：[是什么导致了这个表现]
- 根本原因：[为什么会有这个直接原因]
- 影响范围：[这个问题还会影响哪些地方]

## 解决方案
- 修改内容：[具体改了什么]
- 为什么这样改：[而不是其他方案]
- 验证方法：[如何确认修复有效]
```

---

## 🚫 禁止事项

1. **禁止想当然修复**
   - ❌ "边框没了？加个 border"
   - ✅ "边框没了？先查为什么没了"

2. **禁止盲目使用 !important**
   - ❌ 用 !important 强行覆盖
   - ✅ 找到冲突源头，提高选择器优先级或删除冲突

3. **禁止不搜索就修改**
   - ❌ 直接在当前文件修改
   - ✅ 先搜索全项目相关定义

4. **禁止只看表面不查根因**
   - ❌ 改了能跑就行
   - ✅ 理解为什么会出问题

---

## 📚 真实案例

### 案例：Element Plus 表格边框问题

**表面现象**：表格边框显示不全，左边粗右边细

**错误修复路径**：
1. 加 `border: 1px solid` → 左边更粗了
2. 改 `overflow: hidden` → 右边消失了
3. 加伪元素边框 → 还是不对

**正确诊断**：
1. 搜索全项目 `.el-table--border` 相关样式
2. 发现 **两个文件** 都定义了表格边框：
   - `table.css`: `border: 1px solid` + `::before { display: none }`
   - `element-overrides.css`: `::before { background-color }`
3. 两套互相冲突的边框机制导致渲染异常

**正确修复**：
- 删除一处定义，保持单一来源
- 让 Element Plus 使用默认边框机制

**教训**：样式问题必须搜索全项目，确认没有冲突定义

---

## 🎨 设计稿还原专项规范

> ⚠️ **此章节基于真实案例：一个输入框居中问题反复 15+ 轮对话才修复**

### 设计稿工具使用规范（Sketch/Figma）

#### 强制要求：完整读取选中元素及其所有子集

**问题根源**：
- 只读取了容器属性，忽略了内部文本的精确位置
- 每次只查询一个属性，导致信息不完整
- 假设而非验证具体数值

**正确做法**：

```javascript
// 示例：读取输入框完整信息（包含所有子集）
function extractInputFieldComplete(inputGroup) {
  console.log('=== 容器信息 ===');
  console.log(`宽度: ${inputGroup.frame.width}px`);
  console.log(`高度: ${inputGroup.frame.height}px`);
  
  console.log('=== 内部文本（子集）===');
  const text = inputGroup.layers.find(l => l.type === 'Text');
  console.log(`文本 Y 坐标: ${text.frame.y}px`);  // 关键：距容器顶部距离
  console.log(`文本高度: ${text.frame.height}px`); // 关键：计算行高
  console.log(`字号: ${text.style.fontSize}px`);
  
  console.log('=== 计算结果 ===');
  const topSpace = text.frame.y;
  const bottomSpace = inputGroup.frame.height - text.frame.y - text.frame.height;
  console.log(`上边距: ${topSpace}px`);
  console.log(`下边距: ${bottomSpace}px`);
  console.log(`行高倍数: ${(text.frame.height / text.style.fontSize).toFixed(2)}`);
}
```

#### 必须获取的信息清单

| 元素类型 | 必须获取 | 用途 |
|----------|----------|------|
| 容器 | width, height, padding | 外层尺寸 |
| 文本 | fontSize, Y坐标, height, fontWeight | 计算行高和边距 |
| 图标/SVG | viewBox, path, fill-opacity | 完整导出 |
| 渐变 | stops（所有节点）, from, to | 精确还原 |
| 阴影 | x, y, blur, spread, color | 全部5个参数 |

### 反复修复问题的根因分析

| 导致反复的原因 | 正确做法 |
|----------------|----------|
| 只读取容器高度，不读内部文本 Y 坐标 | 一次性获取容器+所有子元素的完整信息 |
| 用"试错法"调整参数 | 先计算精确值（如行高=文本高度÷字号） |
| 修改 A 属性引发 B 问题 | 理解属性之间的相互作用关系 |
| 假设"差不多居中" | 从设计稿获取精确像素值验证 |

### 设计稿还原检查清单

修复任何设计还原问题前：

- [ ] 已获取目标元素的**完整信息**（容器+所有子集）
- [ ] 已计算精确数值（行高、边距、颜色透明度）
- [ ] 已理解框架渲染机制（如 Flutter TextField 的多属性相互作用）
- [ ] 一次性配置完整方案，而非逐个属性调整
- [ ] 验证所有相关元素（placeholder、光标、输入内容）都符合预期

---

## ✅ 检查清单

修复任何问题前，确认以下检查项：

- [ ] 已搜索全项目相关代码
- [ ] 已确认没有其他文件定义相同/冲突的逻辑
- [ ] 已理解原代码的意图
- [ ] 修改方案从源头解决问题
- [ ] 修改不会影响其他功能
- [ ] 有明确的验证方法

---

**维护者**: MTA工作室  
**创建日期**: 2025-01-04  
**版本**: v1.0