mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 22:06:38 +08:00
ryan
129 lines
2.4 KiB
Markdown
129 lines
2.4 KiB
Markdown
# OpenFlare 前端开发规范
|
|
|
|
本文档约束 `openflare_server/web` 的正式前端工程。它描述的是 `1.0.0` 之后仍然有效的结构、请求层、组件、样式、状态管理与测试基线。
|
|
|
|
## 1. 技术基线
|
|
|
|
默认技术栈：
|
|
|
|
* Next.js 15 App Router
|
|
* React 19
|
|
* TypeScript 5
|
|
* Tailwind CSS 4
|
|
* TanStack Query
|
|
* React Hook Form + Zod
|
|
* Zustand
|
|
* ESLint + Prettier
|
|
* Vitest + Testing Library + Playwright
|
|
* pnpm
|
|
|
|
要求：
|
|
|
|
* 默认使用 TypeScript
|
|
* 默认使用函数组件
|
|
* 默认使用 App Router
|
|
* 前端必须支持 `light`、`dark`、`system` 三种主题模式
|
|
|
|
|
|
## 2. 目录与分层
|
|
|
|
推荐目录：
|
|
|
|
```text
|
|
app/
|
|
components/
|
|
features/
|
|
lib/
|
|
hooks/
|
|
store/
|
|
types/
|
|
styles/
|
|
tests/
|
|
```
|
|
|
|
职责约束：
|
|
|
|
* `app/`：路由、布局、页面组装
|
|
* `features/`：按业务域组织模块
|
|
* `components/`：跨 feature 复用组件
|
|
* `lib/`：请求客户端、环境变量、工具函数、常量
|
|
* `store/`：少量跨页面 UI 状态
|
|
* `types/`：共享类型定义
|
|
|
|
## 3. 路由与页面
|
|
|
|
页面文件只负责：
|
|
|
|
* 获取路由参数
|
|
* 组织页面结构
|
|
* 调用 feature 组件
|
|
|
|
页面不应负责：
|
|
|
|
* 手写复杂 API 细节
|
|
* 编写复杂表单校验逻辑
|
|
* 维护大量彼此耦合的局部状态
|
|
|
|
## 4. 数据请求与类型
|
|
|
|
### 4.1 请求层
|
|
|
|
所有 API 请求必须统一经过 `lib/api/`。
|
|
|
|
要求：
|
|
|
|
* 统一处理 `success/message/data` 响应结构
|
|
* 统一处理鉴权失效、网络异常和通用错误消息
|
|
* 统一维护资源接口与请求路径
|
|
|
|
禁止：
|
|
|
|
* 在页面组件中直接调用 `fetch('/api/...')`
|
|
* 在多个组件中重复拼接同一接口路径
|
|
|
|
### 4.2 状态分层
|
|
|
|
* 服务端状态：TanStack Query
|
|
* 页面临时状态：组件内部 `useState`
|
|
* 跨页面 UI 状态：Zustand
|
|
|
|
不推荐：
|
|
|
|
* 用 Zustand 保存服务端主数据
|
|
* 用 Context 代替完整数据层方案
|
|
|
|
### 4.3 类型
|
|
|
|
要求：
|
|
|
|
* 开启 TypeScript 严格模式
|
|
* 禁止滥用 `any`
|
|
* API 响应、表单输入、业务实体必须有明确类型
|
|
|
|
## 5. 表单与交互
|
|
|
|
统一使用：
|
|
|
|
* React Hook Form
|
|
* Zod
|
|
|
|
高风险操作必须：
|
|
|
|
* 二次确认
|
|
* 展示操作对象名称
|
|
* 明确成功与失败反馈
|
|
|
|
## 6. 样式与主题
|
|
|
|
样式原则：
|
|
|
|
* 统一使用 Tailwind CSS 与现有 token 体系
|
|
* 优先复用已有基础组件与布局组件
|
|
* 保持视觉层级、留白与语义颜色一致
|
|
|
|
主题要求：
|
|
|
|
* 同时支持 `light`、`dark`、`system`
|
|
* 用户选择必须持久化
|
|
* 首屏尽量避免主题闪烁
|