116 lines
9.2 KiB
Markdown
116 lines
9.2 KiB
Markdown
|
# 前端实现自检清单
|
|||
|
|
|
|||
|
|
> 开发者在编写前端代码前后自检使用。确保组件结构合理、样式一致、状态完整、
|
|||
|
|
> 可访问且可测试。分为"实现前"（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`（或项目等效命令）全部通过 | ☐ | ☐ | ☐ | |
|