OpenFlare/docs/frontend-development-guidelines.md

OpenFlare 前端开发规范

1. 适用范围

本文档约束 openflare_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. 目录与分层

推荐目录：

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 托管
• 新页面与新组件默认同时通过亮色与暗色模式验收