mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 22:06:38 +08:00
ryan
13 KiB
13 KiB
ATSFlare 前端开发规范（Next.js + Tailwind CSS）
1. 文档定位
本文档用于约束 ATSFlare 新前端的工程结构、编码方式、组件设计、请求层、样式体系与交付标准。
适用范围：
atsf_server/web新版前端工程- 基于 Next.js + Tailwind CSS 的管理端页面、组件、状态、测试与构建代码
说明：
- 本文档为前端专项规范。
- 当改造方案正式落地后，应将其中稳定约束同步回写到 docs/development-guidelines.md。
2. 技术栈规范
前端默认技术基线如下：
- Next.js 15（App Router）
- React 19
- TypeScript 5.x
- Tailwind CSS 4.x
- NextUI
- pnpm
- ESLint + Prettier
- TanStack Query
- React Hook Form + Zod
- Zustand（仅限轻量客户端状态）
- Vitest + Testing Library
要求：
- 默认使用 TypeScript，不再新增 JS 页面模块
- 默认使用函数组件，不新增 class 组件
- 默认使用 App Router，不新建 Pages Router 结构
- 默认使用 Tailwind CSS，不再引入新的大型样式框架
- 默认使用 NextUI 作为统一视觉组件基础
- 前端必须支持亮色 / 暗色模式切换，且主题切换能力应作为基础能力贯穿布局、组件与页面实现
禁止：
- 新增 Semantic UI 依赖
- 混用多套大型组件库造成视觉与交互割裂
- 在新模块中继续使用 jQuery 风格 DOM 操作
- 将页面逻辑继续堆积为单个超大组件
3. 目录与分层规范
推荐目录：
app/
components/
features/
lib/
hooks/
store/
types/
styles/
tests/
3.1 app/
职责：
- 定义路由
- 组织页面级布局
- 组合业务模块
禁止：
- 在
app/中堆积复杂请求逻辑 - 在
app/页面文件内直接写大段业务处理代码
3.2 features/
职责：
- 按业务域组织模块
- 管理该模块的视图、表单、schema、query、action、类型定义
建议：
- 一个核心业务对象对应一个 feature
- feature 内部可包含
components、api、hooks、schema、types
3.3 components/
职责：
- 放置跨 feature 复用组件
分层建议：
components/ui/：基于 NextUI 封装的按钮、表格、对话框、标签、输入框等基础组件components/layout/：侧边栏、导航栏、页面容器、内容区components/feedback/：加载、空态、错误态、确认框、消息提示components/forms/：复用型表单片段
3.4 lib/
职责：
- 公共能力沉淀
建议子目录：
lib/api/：请求客户端、资源接口、错误映射lib/auth/：登录态工具、鉴权辅助lib/env/：环境变量读取与校验lib/utils/：纯工具函数lib/constants/：常量定义
3.5 store/
职责：
- 存储少量需要跨页面共享的客户端 UI 状态
禁止：
- 把服务端资源数据塞进 Zustand 作为主数据源
- 用全局 store 代替正常的 props 或 query 缓存
4. 路由与页面规范
4.1 路由命名
要求：
- 使用英文小写复数资源名
- 使用语义清晰的层级结构
示例：
/nodes/proxy-routes/config-versions/tls-certificates/managed-domains
4.2 页面职责
页面文件应只负责：
- 获取路由参数
- 组织页面结构
- 调用 feature 组件
页面不应负责：
- 编写复杂表单校验逻辑
- 手写 API 细节
- 维护大量局部状态机
4.3 页面结构建议
后台页面优先采用统一结构：
- 页面标题区
- 页面说明区（可选）
- 操作区
- 筛选区
- 内容区（表格 / 卡片 / 表单）
- 详情区或侧栏（可选）
5. Server Component / Client Component 规范
5.1 默认原则
在当前 ATSFlare 管理端场景下，优先使用以下原则：
- 路由层、布局层可优先使用 Server Component
- 表单、交互、列表操作类组件使用 Client Component
- 涉及浏览器 API、事件处理、弹窗状态的模块必须显式声明
'use client'
5.2 使用约束
禁止：
- 为了省事，将整个应用顶层都改成 Client Component
- 将仅用于展示的静态内容一律写成客户端组件
建议：
- 以“最小客户端边界”为目标组织组件
- 明确区分展示组件与交互组件
6. TypeScript 与类型规范
6.1 总体要求
- 开启严格模式
- 禁止滥用
any - 接口响应、表单输入、业务实体必须有明确类型
6.2 命名建议
- 接口返回：
ProxyRoute,NodeItem,ConfigVersionItem - 表单值：
ProxyRouteFormValues - 查询参数：
NodeListQuery - Schema：
proxyRouteSchema
6.3 类型边界
要求：
- API 响应类型定义在资源模块或
types/中 - 组件 props 明确声明，不使用隐式结构
- 日期、状态、枚举类字段应在前端建立明确字面量或枚举类型
7. 数据请求规范
7.1 请求入口
所有 API 请求必须统一经过 lib/api/。
禁止：
- 在页面组件中直接调用
fetch('/api/...') - 在多个组件中重复拼接相同接口路径
7.2 请求封装
要求：
- 提供统一请求客户端
- 统一处理：
success/message/data响应结构- 鉴权失效
- 通用错误提示
- 网络异常
7.3 Query 使用规范
适用场景：
- 列表查询
- 详情查询
- 配置读取
- 依赖后端的分页、筛选、刷新操作
要求：
- 使用稳定的 query key
- 变更操作完成后按资源粒度失效缓存
- 列表刷新不要依赖手工多处 setState
8. 表单规范
8.1 表单栈
统一使用：
- React Hook Form
- Zod
8.2 校验原则
- 输入校验尽量前置
- 与后端约束一致
- 错误信息清晰可读
8.3 交互要求
- 必填项明确标识
- 提交中状态不可重复点击
- 保存成功要有明确反馈
- 服务端错误要映射到表单或全局提示
8.4 高风险表单
适用场景：
- 发布配置
- 激活版本
- 删除节点
- 删除证书
- 重置 Token
要求：
- 必须有二次确认
- 必须展示操作对象名称
- 必须明确成功与失败反馈
9. 样式与 UI 规范
9.1 样式原则
- NextUI 为统一视觉组件基线
- Tailwind CSS 为布局、间距、响应式与业务样式扩展的基础方案
- 样式通过设计 token、NextUI 主题能力与语义类组合实现
- 页面视觉风格统一、留白一致、层级清晰
- 所有新页面与基础组件必须同时兼容亮色与暗色主题，禁止只实现单一主题
- 主题切换必须可由用户主动触发，并在路由切换和刷新后保持一致
9.2 设计 token
至少抽象以下语义：
- 主色、成功色、警告色、危险色
- 边框色、背景色、弱文本色、强文本色
- 圆角、阴影、间距、层级
- 亮色 / 暗色两套语义 token 映射，以及主题切换所需的前景色、表面色、分隔色
9.3 组件外观要求
- 按钮尺寸、输入框高度、表格密度、弹窗圆角保持统一
- 状态标签颜色语义固定，不允许每页自定义一套颜色
- 表格、卡片、表单容器使用统一布局间距
9.4 禁止项
- 大量硬编码颜色值
- 在 JSX 中堆砌不可读的超长类名且不抽组件
- 同一个状态在不同页面使用不同颜色语义
- 仅在暗色或仅在亮色模式下校验视觉效果后直接交付
10. 组件设计规范
10.1 组件分类
组件分为三类：
- 基础组件：基于 NextUI 二次封装的按钮、输入框、表格、对话框、标签
- 业务组件：节点状态卡、版本激活按钮、证书上传表单
- 页面组合组件：页面头部、筛选面板、详情抽屉
10.2 复用原则
- 先抽象稳定结构，再抽象复杂行为
- 不为单次使用过度设计通用组件
- 业务组件优先放在 feature 内，确认跨域复用后再上移
10.3 Props 规范
- props 命名语义化
- 布尔值 props 使用肯定式命名
- 事件 props 使用
onXxx
示例：
isLoadingisDangeronSubmitonConfirm
11. 状态管理规范
11.1 状态分类
- 服务端状态：放 Query
- 页面临时交互状态：放组件内部
useState - 跨页面 UI 状态：放 Zustand
11.2 不推荐做法
- 用 Zustand 保存服务端列表数据
- 用 Context 替代完整的数据层方案
- 页面里堆叠过多彼此耦合的本地状态
11.3 推荐做法
- 将筛选条件、对话框开关、当前编辑对象保持最小化
- 复杂交互优先拆成自定义 hook 或 feature action
12. 反馈与异常处理规范
12.1 基础反馈
每个页面必须具备：
- 加载态
- 空态
- 错误态
- 成功反馈
12.2 错误处理
要求：
- 请求失败时给出用户可理解的信息
- 后端返回
message时优先展示可读消息 - 非预期错误需要统一兜底文案
12.3 长耗时操作
适用场景：
- 发布配置
- 激活版本
- 上传证书
- 节点触发更新
要求：
- 需要展示明确 loading 状态
- 完成后要主动刷新相关资源
13. 可访问性与国际化规范
13.1 可访问性
要求：
- 表单控件必须有关联标签
- 按钮文案清晰，不只依赖图标表达语义
- 弹窗支持键盘关闭与焦点管理
- 状态颜色不能作为唯一信息来源
13.2 国际化
当前管理端以中文为主，但要求：
- 文案集中管理，避免散落硬编码
- 状态、按钮、提示信息尽量收敛到常量或文案文件
14. 测试规范
14.1 单元与组件测试
适用内容：
- 工具函数
- schema 校验
- 基础组件
- 关键业务组件
14.2 集成测试
适用内容：
- 列表加载与筛选
- 表单提交与错误反馈
- 对话框确认流程
14.3 E2E 测试
至少覆盖以下主链路：
- 登录
- 新增反代规则
- 发布并查看配置版本
- 节点列表查看
- 证书导入
- 运维设置修改
15. 性能规范
要求：
- 避免不必要的大型客户端依赖
- 避免页面级重复请求
- 大表格页面优先考虑分页而非一次性全量加载
- 图标、日期格式化、富文本等能力优先按需引入
建议：
- 公共重型组件按需加载
- 详情弹窗、复杂编辑器、Diff 预览支持懒加载
16. 安全规范
要求：
- 不在前端持久化敏感 Token
- 不在日志中输出敏感配置、证书私钥、完整凭证
- 富文本或 Markdown 渲染必须经过安全处理
- 上传、下载、外链跳转必须有明确来源控制
禁止：
- 在本地存储中缓存高敏感服务端数据
- 为图方便绕过后端鉴权逻辑
17. 命名与代码风格规范
17.1 文件命名
- 组件：
PascalCase.tsx - hook：
useXxx.ts - 工具：
camelCase.ts或按职责命名 - schema：
xxx.schema.ts - 类型：
xxx.types.ts
17.2 符号命名
- 组件名使用名词或名词短语
- hook 使用
use前缀 - 布尔值使用
is、has、can前缀 - 事件处理使用
handle前缀
17.3 代码风格
- 保持单文件职责清晰
- 优先早返回减少嵌套
- 删除废弃代码与无意义注释
- 不在 JSX 中堆积复杂表达式，提取到变量或 hook
18. 提交与评审要求
18.1 提交粒度
要求：
- 一次提交聚焦一个明确目标
- 不把样式重构、功能新增、目录调整混在同一提交中
18.2 代码评审关注点
评审时重点检查：
- 是否符合目录分层
- 是否复用了统一请求层
- 是否破坏现有 API 兼容性
- 是否存在过度客户端化问题
- 是否符合 UI 一致性与状态反馈规范
- 是否补充必要测试
19. 文档维护要求
以下内容变化时，必须同步更新本文档：
- 技术栈调整
- 目录结构调整
- 请求层约定变化
- 状态管理方案变化
- 测试基线变化
- 样式体系变化
当专项方案正式实施后，还应同步更新：
20. 最低执行标准
新前端代码提交前，至少满足：
- 通过类型检查
- 通过 lint
- 核心路径具备基础测试
- 页面具备加载态、空态、错误态
- API 请求不散落在页面 JSX 中
- 未新增 Semantic UI 依赖
- 未破坏当前后端主链路和部署约束