[文档] 文档更新

docs/frontend-development-guidelines.md

@@ -1,56 +1,36 @@
 # OpenFlare 前端开发规范
 
-## 1. 适用范围
+本文档约束 `openflare_server/web` 的正式前端工程。它描述的是 `1.0.0` 之后仍然有效的结构、请求层、组件、样式、状态管理与测试基线。
 
-本文档约束 `openflare_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。
+## 1. 技术基线
 
-当前状态：
+默认技术栈：
 
-* 前端改造已完成
-* 本文档描述的是现行正式基线，不再维护迁移期约束
-
----
-
-## 2. 技术基线
-
-前端默认技术栈：
-
-* Next.js 15（App Router）
+* Next.js 15 App Router
 * React 19
 * TypeScript 5
 * Tailwind CSS 4
 * TanStack Query
 * React Hook Form + Zod
-* Zustand（仅限轻量客户端状态）
+* 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 体系
+* 默认使用 TypeScript
+* 默认使用函数组件
+* 默认使用 App Router
 * 前端必须支持 `light`、`dark`、`system` 三种主题模式
 
 禁止：
 
-* 新增 Semantic UI 依赖
-* 新增大型 UI 框架，破坏当前组件基线
-* 在新模块中继续使用 jQuery 风格 DOM 操作
-* 将页面逻辑堆积为单个超大组件
+* 引入 Semantic UI
+* 新增大型 UI 框架破坏现有组件基线
+* 使用 jQuery 风格 DOM 操作
 
----
-
-## 3. 目录与分层
+## 2. 目录与分层
 
 推荐目录：
 
@@ -68,28 +48,14 @@ tests/
 
 职责约束：
 
-* `app/`：定义路由、组织布局、组装页面
+* `app/`：路由、布局、页面组装
 * `features/`：按业务域组织模块
 * `components/`：跨 feature 复用组件
 * `lib/`：请求客户端、环境变量、工具函数、常量
 * `store/`：少量跨页面 UI 状态
 * `types/`：共享类型定义
 
-禁止：
-
-* 在 `app/` 页面文件里堆积复杂请求逻辑
-* 把服务端主数据放进 Zustand
-* 将同一业务拆出多套平行结构
-
----
-
-## 4. 路由与页面
-
-路由命名要求：
-
-* 使用英文小写
-* 资源页保持现有单数命名
-* 保持与当前路径结构一致
+## 3. 路由与页面
 
 页面文件只负责：
 
@@ -103,26 +69,16 @@ tests/
 * 编写复杂表单校验逻辑
 * 维护大量彼此耦合的局部状态
 
-后台页面优先采用统一结构：
+## 4. 数据请求与类型
 
-1. 标题区
-2. 操作区
-3. 筛选区
-4. 内容区
-5. 详情区或弹层
-
----
-
-## 5. 数据请求与类型
-
-### 5.1 请求层
+### 4.1 请求层
 
 所有 API 请求必须统一经过 `lib/api/`。
 
 要求：
 
 * 统一处理 `success/message/data` 响应结构
-* 统一处理鉴权失效、网络异常、通用错误消息
+* 统一处理鉴权失效、网络异常和通用错误消息
 * 统一维护资源接口与请求路径
 
 禁止：
@@ -130,101 +86,7 @@ tests/
 * 在页面组件中直接调用 `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 内，确认跨域复用后再上移
-
-状态分类：
+### 4.2 状态分层
 
 * 服务端状态：TanStack Query
 * 页面临时状态：组件内部 `useState`
@@ -232,13 +94,45 @@ tests/
 
 不推荐：
 
-* 用 Zustand 保存服务端列表数据
+* 用 Zustand 保存服务端主数据
 * 用 Context 代替完整数据层方案
-* 页面里堆叠过多耦合本地状态
 
----
+### 4.3 类型
 
-## 9. 反馈、测试与交付
+要求：
+
+* 开启 TypeScript 严格模式
+* 禁止滥用 `any`
+* API 响应、表单输入、业务实体必须有明确类型
+
+## 5. 表单与交互
+
+统一使用：
+
+* React Hook Form
+* Zod
+
+高风险操作必须：
+
+* 二次确认
+* 展示操作对象名称
+* 明确成功与失败反馈
+
+## 6. 样式与主题
+
+样式原则：
+
+* 统一使用 Tailwind CSS 与现有 token 体系
+* 优先复用已有基础组件与布局组件
+* 保持视觉层级、留白与语义颜色一致
+
+主题要求：
+
+* 同时支持 `light`、`dark`、`system`
+* 用户选择必须持久化
+* 首屏尽量避免主题闪烁
+
+## 7. 测试与交付
 
 每个页面至少具备：
 
@@ -256,5 +150,5 @@ tests/
 交付要求：
 
 * 构建产物保持可静态导出
-* 构建结果保持可被 Go Server 托管
-* 新页面与新组件默认同时通过亮色与暗色模式验收
+* 构建结果可被 Go Server 托管
+* 新页面默认通过亮色与暗色模式验收