mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 14:06:36 +08:00
ryan
261 lines
5.3 KiB
Markdown
261 lines
5.3 KiB
Markdown
# ATSFlare 前端开发规范
|
||
|
||
## 1. 适用范围
|
||
|
||
本文档约束 `atsf_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。
|
||
|
||
当前状态：
|
||
|
||
* 前端改造已完成
|
||
* 本文档描述的是现行正式基线，不再维护迁移期约束
|
||
|
||
---
|
||
|
||
## 2. 技术基线
|
||
|
||
前端默认技术栈：
|
||
|
||
* 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
|
||
|
||
本地开发模式：
|
||
|
||
* `pnpm start`：启动独立前端开发服务器，默认监听 `3001`，支持热更新
|
||
* 开发服务器默认把 `/api/*` 反向代理到 `http://127.0.0.1:3000`
|
||
* 如需改后端地址，可设置 `NEXT_DEV_BACKEND_URL`
|
||
* `pnpm build`：继续用于静态导出，产物交给 Go Server 托管
|
||
|
||
要求：
|
||
|
||
* 默认使用 TypeScript，不新增 JS 页面模块
|
||
* 默认使用函数组件，不新增 class 组件
|
||
* 默认使用 App Router，不新建 Pages Router 结构
|
||
* 默认使用 Tailwind CSS 与现有设计 token 体系
|
||
* 前端必须支持 `light`、`dark`、`system` 三种主题模式
|
||
|
||
禁止：
|
||
|
||
* 新增 Semantic UI 依赖
|
||
* 新增大型 UI 框架，破坏当前组件基线
|
||
* 在新模块中继续使用 jQuery 风格 DOM 操作
|
||
* 将页面逻辑堆积为单个超大组件
|
||
|
||
---
|
||
|
||
## 3. 目录与分层
|
||
|
||
推荐目录：
|
||
|
||
```text
|
||
app/
|
||
components/
|
||
features/
|
||
lib/
|
||
hooks/
|
||
store/
|
||
types/
|
||
styles/
|
||
tests/
|
||
```
|
||
|
||
职责约束：
|
||
|
||
* `app/`：定义路由、组织布局、组装页面
|
||
* `features/`：按业务域组织模块
|
||
* `components/`：跨 feature 复用组件
|
||
* `lib/`：请求客户端、环境变量、工具函数、常量
|
||
* `store/`：少量跨页面 UI 状态
|
||
* `types/`：共享类型定义
|
||
|
||
禁止：
|
||
|
||
* 在 `app/` 页面文件里堆积复杂请求逻辑
|
||
* 把服务端主数据放进 Zustand
|
||
* 将同一业务拆出多套平行结构
|
||
|
||
---
|
||
|
||
## 4. 路由与页面
|
||
|
||
路由命名要求：
|
||
|
||
* 使用英文小写
|
||
* 资源页保持现有单数命名
|
||
* 保持与当前路径结构一致
|
||
|
||
页面文件只负责：
|
||
|
||
* 获取路由参数
|
||
* 组织页面结构
|
||
* 调用 feature 组件
|
||
|
||
页面不应负责：
|
||
|
||
* 手写复杂 API 细节
|
||
* 编写复杂表单校验逻辑
|
||
* 维护大量彼此耦合的局部状态
|
||
|
||
后台页面优先采用统一结构：
|
||
|
||
1. 标题区
|
||
2. 操作区
|
||
3. 筛选区
|
||
4. 内容区
|
||
5. 详情区或弹层
|
||
|
||
---
|
||
|
||
## 5. 数据请求与类型
|
||
|
||
### 5.1 请求层
|
||
|
||
所有 API 请求必须统一经过 `lib/api/`。
|
||
|
||
要求：
|
||
|
||
* 统一处理 `success/message/data` 响应结构
|
||
* 统一处理鉴权失效、网络异常、通用错误消息
|
||
* 统一维护资源接口与请求路径
|
||
|
||
禁止：
|
||
|
||
* 在页面组件中直接调用 `fetch('/api/...')`
|
||
* 在多个组件中重复拼接同一接口路径
|
||
|
||
### 5.2 Query
|
||
|
||
适用场景：
|
||
|
||
* 列表查询
|
||
* 详情查询
|
||
* 配置读取
|
||
* 依赖后端的分页、筛选、刷新操作
|
||
|
||
要求：
|
||
|
||
* 使用稳定的 query key
|
||
* 变更成功后按资源粒度失效缓存
|
||
* 列表刷新不要依赖分散的手工 `setState`
|
||
|
||
### 5.3 类型
|
||
|
||
要求：
|
||
|
||
* 开启 TypeScript 严格模式
|
||
* 禁止滥用 `any`
|
||
* API 响应、表单输入、业务实体必须有明确类型
|
||
* 枚举、状态、日期字段建立明确类型边界
|
||
|
||
---
|
||
|
||
## 6. 表单与交互
|
||
|
||
统一使用：
|
||
|
||
* React Hook Form
|
||
* Zod
|
||
|
||
交互要求：
|
||
|
||
* 必填项明确标识
|
||
* 提交中不可重复点击
|
||
* 保存成功有明确反馈
|
||
* 服务端错误映射到表单或全局提示
|
||
|
||
高风险操作适用场景：
|
||
|
||
* 发布配置
|
||
* 激活版本
|
||
* 删除节点
|
||
* 删除证书
|
||
* 重置 Token
|
||
* 触发更新
|
||
|
||
要求：
|
||
|
||
* 必须有二次确认
|
||
* 必须展示操作对象名称
|
||
* 必须明确成功与失败反馈
|
||
|
||
---
|
||
|
||
## 7. 样式与主题
|
||
|
||
样式原则：
|
||
|
||
* 统一使用 Tailwind CSS 与现有 token 体系
|
||
* 优先复用已有基础组件与布局组件
|
||
* 页面视觉风格统一、层级清晰、留白一致
|
||
|
||
主题要求：
|
||
|
||
* 同时支持 `light`、`dark`、`system`
|
||
* 用户手动选择后必须持久化
|
||
* 刷新、重新进入页面、路由切换后保持一致
|
||
* 首屏尽量避免主题闪烁
|
||
* 布局层、导航层、基础卡片、表单容器必须先满足双主题
|
||
|
||
禁止：
|
||
|
||
* 大量硬编码颜色值
|
||
* 同一状态在不同页面使用不同颜色语义
|
||
* 仅验证单一主题后直接交付
|
||
|
||
---
|
||
|
||
## 8. 组件与状态管理
|
||
|
||
组件分层：
|
||
|
||
* 基础组件：按钮、输入框、表格、对话框、标签、卡片
|
||
* 业务组件：节点状态卡、版本激活按钮、证书上传表单
|
||
* 页面组合组件：页面头部、筛选面板、详情弹层
|
||
|
||
复用原则：
|
||
|
||
* 先抽象稳定结构，再抽象复杂行为
|
||
* 业务组件优先放在 feature 内，确认跨域复用后再上移
|
||
|
||
状态分类：
|
||
|
||
* 服务端状态：TanStack Query
|
||
* 页面临时状态：组件内部 `useState`
|
||
* 跨页面 UI 状态：Zustand
|
||
|
||
不推荐：
|
||
|
||
* 用 Zustand 保存服务端列表数据
|
||
* 用 Context 代替完整数据层方案
|
||
* 页面里堆叠过多耦合本地状态
|
||
|
||
---
|
||
|
||
## 9. 反馈、测试与交付
|
||
|
||
每个页面至少具备：
|
||
|
||
* 加载态
|
||
* 空态
|
||
* 错误态
|
||
* 成功反馈
|
||
|
||
测试要求：
|
||
|
||
* 公共工具、类型转换、主题逻辑补单元测试
|
||
* 关键页面交互补组件测试
|
||
* 核心主链路补 Playwright 或等效联调验证
|
||
|
||
交付要求：
|
||
|
||
* 构建产物保持可静态导出
|
||
* 构建结果保持可被 Go Server 托管
|
||
* 新页面与新组件默认同时通过亮色与暗色模式验收
|