OpenFlare/docs/frontend-development-guidelines.md

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 三种主题模式

禁止：

• 引入 Semantic UI
• 新增大型 UI 框架破坏现有组件基线
• 使用 jQuery 风格 DOM 操作

2. 目录与分层

推荐目录：

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
• 用户选择必须持久化
• 首屏尽量避免主题闪烁

7. 测试与交付

每个页面至少具备：

• 加载态
• 空态
• 错误态
• 成功反馈

测试要求：

• 公共工具、类型转换、主题逻辑补单元测试
• 关键页面交互补组件测试
• 核心主链路补 Playwright 或等效联调验证

交付要求：

• 构建产物保持可静态导出
• 构建结果可被 Go Server 托管
• 新页面默认通过亮色与暗色模式验收