# 前端实现自检清单

> 开发者在编写前端代码前后自检使用。确保组件结构合理、样式一致、状态完整、
> 可访问且可测试。分为"实现前"（PRE）和"实现后"（POST）两部分。
> 全部通过后方可提交代码评审。

---

## 使用说明

1. **PRE** 项在开始写组件前检查；
2. **POST** 项在完成编码和所有验证命令后检查；
3. 对"不通过"项必须在代码评审前修复；
4. 无法满足的项标记 `[N/A: <原因>]`。

---

## 实现前（PRE — Pre-Implementation）

### 1. 上下文完备性

| #     | 检查项                                                             | 通过 | 不通过 | N/A | 备注 |
| ----- | ------------------------------------------------------------------ | ---- | ------ | --- | ---- |
| PRE-1 | 已确定项目框架（React / Vue / Svelte / SolidJS / Angular）         | ☐    | ☐      | ☐   |      |
| PRE-2 | 已确定样式方案（Tailwind / CSS Modules / styled-components / ...） | ☐    | ☐      | ☐   |      |
| PRE-3 | 已读取至少 3 个同模块的现有文件（UI 工作同类组件），理解命名、结构和样式模式（共享 brownfield 规则，规范出处：`.octopus/skills/review-code/SKILL.md` §"Greenfield vs. Brownfield"）            | ☐   | ☐     | ☐  |      |
| PRE-4 | 已确认路由模式（file-based / config-based）和新组件路由位置        | ☐    | ☐      | ☐   |      |
| PRE-5 | 已确认项目使用的 UI 基础库（Kobalte / Radix / Headless UI / ...）  | ☐    | ☐      | ☐   |      |
| PRE-6 | 若项目有设计系统（token / theme / spacing），已确认取值方式        | ☐    | ☐      | ☐   |      |
| PRE-7 | Pipeline 模式：已读取设计文档的组件设计、接口设计、NFR 章节（DAG 路由：设计输入解析自冻结 DAG 副本 `{epic-slug}/dag` 节点规格 + 跨 session 边契约，见 `implementation.md` 使用说明第 5 条） | ☐    | ☐      | ☐   |      |

### 2. 组件边界

| #     | 检查项                                                          | 通过 | 不通过 | N/A | 备注 |
| ----- | --------------------------------------------------------------- | ---- | ------ | --- | ---- |
| PRE-8 | 组件职责单一——一个组件只做一件事                                | ☐    | ☐      | ☐   |      |
| PRE-9 | Props 类型已列出（TypeScript 接口 / PropTypes / defineProps）   | ☐    | ☐      | ☐   |      |
| PRE-10| 所有需要的 UI 状态已识别：loading / empty / error / success / edge | ☐    | ☐      | ☐   |      |

---

## 实现后（POST — Post-Implementation）

### 3. 组件结构

| #      | 检查项                                                      | 通过 | 不通过 | N/A | 备注 |
| ------ | ----------------------------------------------------------- | ---- | ------ | --- | ---- |
| POST-1 | 组件命名清晰、遵循项目约定（PascalCase / kebab-case）       | ☐    | ☐      | ☐   |      |
| POST-2 | 所有 Props 有完整类型，无 `any` 类型                         | ☐    | ☐      | ☐   |      |
| POST-3 | 组件文件结构符合项目约定（单文件 / 目录+index / co-located） | ☐    | ☐      | ☐   |      |
| POST-4 | 无巨型组件（> 200 行）——必要时已拆分为子组件                 | ☐    | ☐      | ☐   |      |
| POST-5 | 事件处理器和回调遵循项目命名规范（`on*` / `handle*`）        | ☐    | ☐      | ☐   |      |

### 4. 样式与设计系统

| #      | 检查项                                                         | 通过 | 不通过 | N/A | 备注 |
| ------ | -------------------------------------------------------------- | ---- | ------ | --- | ---- |
| POST-6 | 使用项目统一的样式方案，未引入新的样式库                       | ☐    | ☐      | ☐   |      |
| POST-7 | 若使用 Tailwind：无冗余类名堆积，复杂样式已提取为 `@apply` 或组件 | ☐    | ☐      | ☐   |      |
| POST-8 | 响应式断点已处理（移动端/平板/桌面），无横向溢出               | ☐    | ☐      | ☐   |      |
| POST-9 | 若项目有暗色模式：组件在亮/暗主题下均可正常显示                | ☐    | ☐      | ☐   |      |
| POST-10| 使用项目设计 token（颜色/间距/字体），无硬编码魔法数值         | ☐    | ☐      | ☐   |      |
| POST-11| 动画/过渡遵循项目约定（`motion` / CSS transition / ...），无突兀跳动 | ☐    | ☐      | ☐   |      |

### 5. 状态覆盖

| #      | 检查项                                                          | 通过 | 不通过 | N/A | 备注 |
| ------ | ----------------------------------------------------------------| ---- | ------ | --- | ---- |
| POST-12| **Loading 状态**：数据加载时有骨架屏/加载指示器，布局不跳动     | ☐    | ☐      | ☐   |      |
| POST-13| **Empty 状态**：无数据时有友好提示和操作引导（非空白页）        | ☐    | ☐      | ☐   |      |
| POST-14| **Error 状态**：请求失败时显示错误信息和重试/恢复操作           | ☐    | ☐      | ☐   |      |
| POST-15| **Edge cases**：超长文本截断、特殊字符、空数组、`null`/`undefined` 值均已处理 | ☐    | ☐      | ☐   |      |
| POST-16| 数据更新后 UI 正确反映最新状态（无过期数据残留）                | ☐    | ☐      | ☐   |      |

### 6. 可访问性（a11y）

| #      | 检查项                                                              | 通过 | 不通过 | N/A | 备注 |
| ------ | ------------------------------------------------------------------- | ---- | ------ | --- | ---- |
| POST-17| 使用语义化 HTML 元素（`<button>` 而非 `<div onclick>`）             | ☐    | ☐      | ☐   |      |
| POST-18| 图片/图标有有意义的 `alt` 文本（纯装饰性图片使用 `alt=""`）        | ☐    | ☐      | ☐   |      |
| POST-19| 表单控件有关联的 `<label>`（非仅 placeholder）                     | ☐    | ☐      | ☐   |      |
| POST-20| 所有交互元素可通过键盘访问（Tab 导航，Enter/Space 激活）           | ☐    | ☐      | ☐   |      |
| POST-21| 弹窗/模态框：打开时焦点移入，关闭时焦点回退，ESC 可关闭            | ☐    | ☐      | ☐   |      |
| POST-22| 动态内容更新（加载完成/错误提示/列表变化）有适当的 `aria-live` 通知 | ☐    | ☐      | ☐   |      |
| POST-23| 色彩对比度：正文 ≥ 4.5:1，大文本 ≥ 3:1，非仅靠颜色传达信息        | ☐    | ☐      | ☐   |      |
| POST-24| 页面有逻辑的标题层级（`h1` → `h2` → `h3`），无跳级                 | ☐    | ☐      | ☐   |      |

### 7. 性能

| #      | 检查项                                                         | 通过 | 不通过 | N/A | 备注 |
| ------ | -------------------------------------------------------------- | ---- | ------ | --- | ---- |
| POST-25| 无不必要的重渲染——列表子项 key 稳定、事件处理器引用稳定       | ☐    | ☐      | ☐   |      |
| POST-26| 大列表使用虚拟滚动或分页（非一次性渲染全部）                   | ☐    | ☐      | ☐   |      |
| POST-27| 图片使用懒加载（`loading="lazy"`），有合适的 `width`/`height` 防止布局偏移 | ☐    | ☐      | ☐   |      |
| POST-28| 非首屏组件考虑代码分割（`lazy()` / `defineAsyncComponent`）    | ☐    | ☐      | ☐   |      |

### 8. 代码质量

| #      | 检查项                                                      | 通过 | 不通过 | N/A | 备注 |
| ------ | ----------------------------------------------------------- | ---- | ------ | --- | ---- |
| POST-29| `bun typecheck`（或项目等效命令）通过，无类型错误           | ☐    | ☐      | ☐   |      |
| POST-30| `bun lint`（或项目等效命令）通过，无错误或警告              | ☐    | ☐      | ☐   |      |
| POST-31| 无注释掉的代码块或 `console.log` 调试语句                   | ☐    | ☐      | ☐   |      |
| POST-32| 无硬编码的 API 地址、密钥或环境特定值——使用环境变量或配置   | ☐    | ☐      | ☐   |      |
| POST-33| 没有因 UI 改动导致的不相关组件样式错乱                       | ☐    | ☐      | ☐   |      |

### 9. 前端测试

| #      | 检查项                                                             | 通过 | 不通过 | N/A | 备注 |
| ------ | ------------------------------------------------------------------ | ---- | ------ | --- | ---- |
| POST-34| 新组件有基础渲染测试（"does it render without crashing"）          | ☐    | ☐      | ☐   |      |
| POST-35| 关键交互有行为测试（点击/输入/提交触发预期回调或状态变化）        | ☐    | ☐      | ☐   |      |
| POST-36| 至少覆盖 loading / error / empty 其中一种边界状态的测试             | ☐    | ☐      | ☐   |      |
| POST-37| 若项目使用 Storybook：新组件有至少一个 story                       | ☐    | ☐      | ☐   |      |
| POST-38| `bun run test:parallel`（或项目等效命令）全部通过                   | ☐    | ☐      | ☐   |      |