mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 05:56:38 +08:00
[文档] 文档更新
This commit is contained in:
ryan
@@ -1,589 +1,253 @@
|
||||
# ATSFlare 前端开发规范（Next.js + Tailwind CSS）
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
本文档用于约束 ATSFlare 新前端的工程结构、编码方式、组件设计、请求层、样式体系与交付标准。
|
||||
|
||||
适用范围：
|
||||
|
||||
* `atsf_server/web` 新版前端工程
|
||||
* 基于 Next.js + Tailwind CSS 的管理端页面、组件、状态、测试与构建代码
|
||||
|
||||
说明：
|
||||
|
||||
* 本文档为前端专项规范。
|
||||
* 当改造方案正式落地后，应将其中稳定约束同步回写到 [docs/development-guidelines.md](./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. 目录与分层规范
|
||||
|
||||
推荐目录：
|
||||
|
||||
```text
|
||||
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 路由命名
|
||||
|
||||
# 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
|
||||
|
||||
要求：
|
||||
|
||||
* 使用英文小写单数资源名
|
||||
* 使用语义清晰的层级结构
|
||||
* 默认使用 TypeScript，不新增 JS 页面模块
|
||||
* 默认使用函数组件，不新增 class 组件
|
||||
* 默认使用 App Router，不新建 Pages Router 结构
|
||||
* 默认使用 Tailwind CSS 与现有设计 token 体系
|
||||
* 前端必须支持 `light`、`dark`、`system` 三种主题模式
|
||||
|
||||
示例：
|
||||
禁止：
|
||||
|
||||
* `/node`
|
||||
* `/proxy-route`
|
||||
* `/config-version`
|
||||
* `/tls-certificate`
|
||||
* `/managed-domain`
|
||||
|
||||
### 4.2 页面职责
|
||||
|
||||
页面文件应只负责：
|
||||
|
||||
* 获取路由参数
|
||||
* 组织页面结构
|
||||
* 调用 feature 组件
|
||||
|
||||
页面不应负责：
|
||||
|
||||
* 编写复杂表单校验逻辑
|
||||
* 手写 API 细节
|
||||
* 维护大量局部状态机
|
||||
|
||||
### 4.3 页面结构建议
|
||||
|
||||
后台页面优先采用统一结构：
|
||||
|
||||
1. 页面标题区
|
||||
2. 页面说明区（可选）
|
||||
3. 操作区
|
||||
4. 筛选区
|
||||
5. 内容区（表格 / 卡片 / 表单）
|
||||
6. 详情区或侧栏（可选）
|
||||
|
||||
---
|
||||
|
||||
## 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 组件分类
|
||||
|
||||
组件分为三类：
|
||||
|
||||
1. 基础组件：基于 NextUI 二次封装的按钮、输入框、表格、对话框、标签
|
||||
2. 业务组件：节点状态卡、版本激活按钮、证书上传表单
|
||||
3. 页面组合组件：页面头部、筛选面板、详情抽屉
|
||||
|
||||
### 10.2 复用原则
|
||||
|
||||
* 先抽象稳定结构，再抽象复杂行为
|
||||
* 不为单次使用过度设计通用组件
|
||||
* 业务组件优先放在 feature 内，确认跨域复用后再上移
|
||||
|
||||
### 10.3 Props 规范
|
||||
|
||||
* props 命名语义化
|
||||
* 布尔值 props 使用肯定式命名
|
||||
* 事件 props 使用 `onXxx`
|
||||
|
||||
示例：
|
||||
|
||||
* `isLoading`
|
||||
* `isDanger`
|
||||
* `onSubmit`
|
||||
* `onConfirm`
|
||||
|
||||
---
|
||||
|
||||
## 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 代码评审关注点
|
||||
|
||||
评审时重点检查：
|
||||
|
||||
1. 是否符合目录分层
|
||||
2. 是否复用了统一请求层
|
||||
3. 是否破坏现有 API 兼容性
|
||||
4. 是否存在过度客户端化问题
|
||||
5. 是否符合 UI 一致性与状态反馈规范
|
||||
6. 是否补充必要测试
|
||||
|
||||
---
|
||||
|
||||
## 19. 文档维护要求
|
||||
|
||||
以下内容变化时，必须同步更新本文档：
|
||||
|
||||
* 技术栈调整
|
||||
* 目录结构调整
|
||||
* 请求层约定变化
|
||||
* 状态管理方案变化
|
||||
* 测试基线变化
|
||||
* 样式体系变化
|
||||
|
||||
当专项方案正式实施后，还应同步更新：
|
||||
|
||||
* [docs/design.md](./design.md)
|
||||
* [docs/development-guidelines.md](./development-guidelines.md)
|
||||
* [docs/deployment.md](./deployment.md)
|
||||
|
||||
---
|
||||
|
||||
## 20. 最低执行标准
|
||||
|
||||
新前端代码提交前，至少满足：
|
||||
|
||||
1. 通过类型检查
|
||||
2. 通过 lint
|
||||
3. 核心路径具备基础测试
|
||||
4. 页面具备加载态、空态、错误态
|
||||
5. API 请求不散落在页面 JSX 中
|
||||
6. 未新增 Semantic UI 依赖
|
||||
7. 未破坏当前后端主链路和部署约束
|
||||
* 新增 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 托管
|
||||
* 新页面与新组件默认同时通过亮色与暗色模式验收
|
||||
|
||||
Reference in New Issue
Block a user