# 前端开发规范

> 前端开发的总入口，覆盖目录组织、接口设计、类型定义、UI 实现与质量要求。

---

## 概述

本规范用于统一前端项目的开发方式，目标是让代码在以下几个方面保持稳定：

- 可读：目录、命名、职责边界清晰，方便快速定位代码
- 可维护：页面逻辑拆分合理，避免巨型组件和重复实现
- 可复用：公共能力与页面私有能力边界明确，减少污染
- 可演进：接口、类型、页面结构支持逐步扩展，不因小改动造成大面积返工

核心原则：

1. 就近原则：只在当前页面使用的代码，放在当前页面目录下
2. 分层清晰：全局公共层、页面私有层、接口层各司其职
3. 命名统一：文件名、目录名、Hooks、弹窗组件遵循固定规则
4. 类型明确：接口参数、返回值、组件 Props、状态值都应具备清晰类型
5. 优先复用：抽公共前先确认真的复用，抽公共后保持通用而不过度设计

---

## 编码环境

- Vue / React，使用 TypeScript
- Vite、路由库（React Router / Vue Router）、Axios 等常见前端库

---

## 开发前检查清单

开始修改前端代码前，请先确认：

1. 这次改动是否真的属于前端层，而不是后端或其它层
2. 需求影响的是全局公共能力，还是某个页面私有能力
3. 涉及接口时，参数、返回值、错误处理方式是否已经明确
4. 涉及样式、主题或视觉变量时，是否优先使用 `@oppein-react/design-tokens`
5. 新增命名是否使用业务语义，而不是后端表结构或临时术语
6. 是否有现成组件、Hooks、工具函数、类型定义或设计 token 可以复用
7. 改动是否会影响现有页面、公共组件或既有接口调用方式

---

## 规范索引

| 规范 | 作用 | 适用场景 |
|---|---|---|
| [前端结构规范](./frontend-structure-guidelines.md) | 约束 `src` 下各层目录职责、页面私有结构和命名方式 | 新建页面、重构目录、抽离公共能力前必读 |
| [UI 设计规范](飞书用户态接口授权流程（Auth%20->%20Callback%20->%20DataApi）.md) | 规范界面实现方式、视觉一致性和交互呈现 | 新做页面、优化样式、补充组件展示时阅读 |
| [设计变量使用规范](./design-tokens-guidelines.md) | 规范 `@oppein-react/design-tokens` 的接入、变量消费、主题切换与 UnoCSS 使用方式 | 新增样式、主题切换、替换硬编码颜色、接入 UnoCSS token 时必读 |
| [接口契约规范](./api-guidelines.md) | 规范前端接口文件、请求封装、错误处理和兼容性 | 新增接口、调整请求参数、封装请求工具时阅读 |
| [类型定义规范](./dto-guidelines.md) | 规范请求参数、响应数据、页面消费模型和类型边界 | 新增类型、重构数据结构、拆分页面模型时阅读 |
| [质量规范](./quality-guidelines.md) | 规范代码质量、拆分方式、验证要求和评审重点 | 开发中自检、提测前、收尾时阅读 |

---

## 推荐使用方式

可以把这套规范理解成一个简单流程：

1. 先看 `frontend-structure-guidelines.md`
   确认代码该放全局、页面私有，还是接口层
2. 涉及样式、主题和设计变量时看 `design-tokens-guidelines.md` 和 `DESIGN.md`
   确保颜色、间距、圆角、阴影、亮暗主题实现方式一致
3. 涉及请求与数据时看 `api-guidelines.md` 和 `dto-guidelines.md`
   确保接口定义、类型建模、页面消费方式一致
4. 涉及页面与交互时看 `DESIGN.md`
   保证页面结构、交互体验与视觉实现符合要求
5. 提交前看 `quality-guidelines.md`
   做最后的质量自检与风险排查

---

## 完成前自检

完成前端改动前，至少确认以下几点：

- 目录层级是否正确，页面私有代码是否已就近放置
- 接口是否统一从约定目录导出，是否避免了页面内联请求实现
- 类型是否明确，是否避免了新增 `any`
- 样式是否优先使用了 `@oppein-react/design-tokens` 的语义变量或 UnoCSS token class
- 页面是否拆分合理，是否把复杂逻辑从主页面组件下沉
- 公共能力是否真的具备复用价值，而不是过早抽象
- 构建是否通过，关键路径是否完成本地验证

---

## 语言要求

- 所有规范文档、注释、提交信息统一使用**简体中文**
- 代码中的变量名、函数名、类型名可以使用英文
- 命名应优先体现业务语义，避免使用模糊缩写与临时命名