# 前端质量规范

> 前端代码质量、可维护性与交付前检查规范。

---

## 必须遵守

- 页面主文件聚焦页面组装,复杂逻辑下沉到 `components/`、`hooks/`、`utils/`
- 目录与命名遵循 `frontend-structure-guidelines.md` 约定
- 接口层、页面层、公共层职责明确,不交叉污染
- 新增类型、常量、工具函数前先搜索是否已有可复用实现
- 公共组件保持通用,页面私有组件就近放置

---

## 禁止行为

- 页面直接内联大段请求逻辑,绕过 `api/` 或页面私有接口文件
- 本应页面私有的组件、Hooks、工具函数被随意放进全局公共目录
- 组件 Props、接口返回值、Hook 返回值大量使用 `any`
- 在组件渲染过程中执行复杂计算、重复格式化、重复创建临时对象而不做整理
- 一个页面目录里同时堆放列表、详情、弹窗、表单等多种耦合逻辑却不拆分
- 把样式、请求、副作用、状态管理全部写进一个超大组件

---

## GIT提交规范

-  所有AI生成的代码提交必须在Git commit message中标识AI模型名称,格式为 `[AI-{模型名称}]`,例如 `[AI-Qoder] 添加用户列表页面`

---

## 测试要求

至少需要验证:

- 页面能正常渲染,关键交互路径不报错
- 新增或修改的接口调用参数、返回值与页面消费逻辑一致
- 条件渲染、空态、加载态、异常态至少人工验证一遍
- 抽取出的工具函数、格式化函数、状态转换函数应补单元测试(如果项目已具备测试设施)
- 改动公共组件或公共 Hook 时,要确认现有调用方未被破坏

如果项目暂时没有完整测试设施,至少保证能通过构建,并完成核心路径的本地人工验证。

---

## 代码审查清单

- 这个改动是否放在了正确目录,而不是图省事塞进页面主文件?
- 新增公共能力之前,是否确认过它不是页面私有逻辑?
- 是否存在命名模糊、职责混乱、目录层级不清的问题?
- 接口、类型、组件、Hooks 之间的数据流是否清晰可读?
- 是否引入了重复实现,本可以复用已有工具或组件?
- 构建、类型检查、本地页面验证是否已经完成?