logan
f9c6c1d826
基于 WEB-UI-Development-Guide 标准的整体升级,并更名 LokiDeploy → opsx-loki。 前端(Gin+React+shadcn/ui): - 按 02/07 章重构:页面域化拆分(无超 400 行文件)、PageContainer/ListQuery、 反馈分级(成功静默/失败 toast/危险确认)、401 单飞刷新+队列重放 - 暗色模式(next-themes)+ 语义 Token(--primary 品牌色/success/warning/info) - 部署向导(状态推导四步:环境→存储→Loki→采集,内嵌表单闭环) - 日志查询页:LogQL 标签构建器/拖拽直方图/日志上下文/Live Tail/查询历史 - 按用户+标签策略的查询授权(服务端强制合并策略) 后端(Go+Gin+JSON DB): - 简单用户管理(仅 admin,无 RBAC)+ TokenVersion 会话吊销 + 登录 IP 限流 - LDAP 接入:配置(AES 加密存储/hasPassword 脱敏)/测试连接/批量导入/登录 - 存储配置测试连接(SigV4 零依赖)+ 桶不存在自动创建 - Loki 三模式部署修复:SSH 密钥认证、3.x 配置模板、ruler 对象存储嵌套块、 凭证解密、孤儿 deploying 状态恢复、Grafana 部署(可选默认关)+面板导入 - DaemonSet 采集纯 YAML(去 helm 依赖)+ DNS 自愈回退 ClusterIP + 集群名标签 - 日志查询代理:cluster-svc 经 kube-apiserver proxy/url 直连 + cursor 翻页 - 统一 log 命名空间;部署就绪探活;Grafana 访问地址自动记录 修复:run.sh 增量编译检测、Sanitized 脱敏补全、LokiDeployment Update 白名单、 健康检查 CreatedAt 零值等 10+ 存量 bug。 数据兼容:DB 沿用旧 lokideploy.json(新名优先);localStorage 一次性迁移; HKDF 加密前缀保留(已加密凭证不受影响)。
170 lines
14 KiB
Markdown
170 lines
14 KiB
Markdown
# 打造高质量 Web 管理端前端 — 开发标准
|
||
|
||
> 基于 vue-vben-admin（v5，★★★★★ Vue 标准标杆）、ant-design-pro（v6，★★★★★ React 标准标杆）、
|
||
> soybean-admin（v2.3，★★★★☆ 强烈推荐）、vue-pure-admin（v7，★★★★☆ 推荐）四大纯前端标杆提炼，
|
||
> gin-vue-admin（★★☆☆☆ 仅作全栈功能对照）。
|
||
>
|
||
> 生成时间：2026-10-22 ｜ 修订：2026-10-22 定位为通用开发标准（去项目化）
|
||
|
||
---
|
||
|
||
## 📖 文档定位（先读这一段）
|
||
|
||
本文件是一份**前端开发标准**（Standard），不是教程：
|
||
|
||
1. **用途**：放入新项目仓库（如 `docs/`，并被 AGENTS.md / CLAUDE.md 引用），供 **AI 编程助手与开发者**阅读——AI 在编码、Review、重构时以此为基准**对比并优化**目标代码；与本文冲突的既有代码即为待改进项。
|
||
2. **范围**：Vue 3 与 React 的管理端 / 中后台 Web 前端（新项目优先）；后端为 Gin / FastAPI 等任意 REST 服务均可——本标准只约定前端结构与 HTTP 契约，不绑定后端框架。
|
||
3. **效力**：条款分「必须 / 禁止」「推荐 / 避免」「可选」三级（见规范用语约定）。
|
||
4. **证据**：所有规范条目均标注出处（五项目的具体文件路径），不是凭空偏好。
|
||
5. **用法**：每章末尾有「AI 检查清单」——对比目标工程时逐项核对，不合格项即为优化任务。
|
||
|
||
---
|
||
|
||
## 📚 文档目录
|
||
|
||
| 序号 | 文件名 | 主题 | 核心内容 |
|
||
| -- | ----------------- | ---- | -------------------------------------------- |
|
||
| 01 | `01-框架选型与技术栈.md` | 框架选型 | 默认技术栈、UI 库对比、TS 采用策略、何时允许偏离 |
|
||
| 02 | `02-项目架构与目录结构.md` | 项目架构 | 按功能域组织、页面 co-location、可裁剪分层、命名规范 |
|
||
| 03 | `03-请求层与数据流.md` | 通信架构 | 统一响应契约、拦截器链、refresh 单飞队列、401 三范式、状态分层 |
|
||
| 04 | `04-路由与权限控制.md` | 路由权限 | meta 规范、动态路由三模式、守卫链、RBAC 三粒度、菜单生成 |
|
||
| 05 | `05-布局系统与导航设计.md` | 布局导航 | 布局分层、侧栏/标签页/面包屑、Keep-Alive 链路、页面模板 |
|
||
| 06 | `06-主题系统与视觉设计.md` | 主题视觉 | 设计 Token、暗色模式、CSS 变量换肤、品牌定制、死 CSS 治理 |
|
||
| 07 | `07-组件设计与交互反馈.md` | 组件交互 | 组件分层与晋升、命令式弹层、表单/表格范式、反馈分级、巨型文件拆分 |
|
||
| 08 | `08-工程化与质量保障.md` | 工程实践 | Vite 配置、env 分层、lint 流水线、测试金字塔、性能、双端一致性、CI/CD |
|
||
|
||
---
|
||
|
||
## 🏆 核心结论速览
|
||
|
||
### 默认技术栈（新项目从这里开始）
|
||
|
||
| 端 | 默认栈 | 参照 |
|
||
| --------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
||
| **Vue 3** | Vue 3 + Vite + TypeScript（允许渐进）+ Element Plus + Pinia + Vue Router | 同栈实操对照 vue-pure-admin；架构对照 vben；规范写法对照 soybean |
|
||
| **React** | React + Vite + TypeScript strict + antd（重 CRUD 加 ProComponents）或 shadcn/ui + Zustand + TanStack Query | 工程与组件对照 ant-design-pro |
|
||
|
||
包管理器一律 **pnpm**（`preinstall: only-allow pnpm`）。偏离默认栈的条件与程序见 01 章 1.4。
|
||
|
||
### 单栈优先与双栈迁移策略
|
||
|
||
```
|
||
新项目 ──▶ 必须单栈（Vue 或 React 二选一）
|
||
|
||
迁移期（存量重构）──▶ 允许双栈并存，但必须遵守三条纪律：
|
||
1. 功能以主端为准，副端只做「对齐」同步，不抢先实现新功能
|
||
2. 契约先统一命名：token key / 主题 key / 权限码 / 响应格式，两端同名
|
||
（推荐命名空间：<app>.auth.token / <app>.theme.mode）
|
||
3. 不共享代码，只共享一份契约文档——不为双栈引入 monorepo
|
||
```
|
||
|
||
（monorepo 的适用性判断见 01 章 1.3；双端一致性细则见 08 章第五节）
|
||
|
||
### 参考项目定位（五项目三级）
|
||
|
||
**首选参考 ★★★★★ —— Vue 看 vben，React 看 adp**
|
||
|
||
| 项目 | 技术栈 | 定位 | 主要借鉴点 |
|
||
| ------------------ | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
|
||
| **vue-vben-admin** | Vue 3 + TS monorepo（pnpm + Turbo） | **Vue 标准标杆** | RequestClient + 预设拦截器、refresh 单飞队列、HSL Token + Tailwind 桥接、Preferences 偏好系统、三层布局架构、Vite 配置工厂、VITE_GLOB 运行时配置 |
|
||
| **ant-design-pro** | Umi Max + React 19 + antd v6 + ProComponents | **React 标准标杆** | 响应契约与错误分级（ErrorShowType）、access 权限纯函数、页面 co-location 五件套、React Query 数据流、Biome + commitlint 工程底线、测试范式 |
|
||
|
||
**强烈推荐 / 推荐 ★★★★☆ —— Vue 侧第二、第三参考**
|
||
|
||
| 项目 | 技术栈 | 定位 | 主要借鉴点 |
|
||
| ------------------ | ----------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||
| **soybean-admin** | Vue 3.5 + Naive UI + UnoCSS + Vite（轻 workspace） | 强烈推荐：**代码规范与架构清晰** | @elegant-router 文件路由（目录即路由、类型即生成物）、请求五钩子契约 + flat 返回、store「index + shared」纯函数分离、hasAuth 极简权限、主题三端同步、最严格的 Lint/Commit 体系 |
|
||
| **vue-pure-admin** | Vue 3.5 + Element Plus + Tailwind v4（单包） | 推荐：**干净轻量，有官方精简版 thin** | 页面内聚五件套（index + form + utils/hook）、PureHttp 196 行请求类、ReDialog 命令式弹窗、EP↔Tailwind 变量桥接、两级按钮权限（v-auth/v-perms）、中文注释密度极高 |
|
||
|
||
**仅作对照 ★★☆☆☆ —— 功能参考，不作前端标准**
|
||
|
||
| 项目 | 技术栈 | 定位 | 可借鉴的模式 |
|
||
| ----------------- | ------------------------------------------- | ----------------- | ------------------------------------------------------------------------------- |
|
||
| **gin-vue-admin** | Vue 3 + Element Plus + Pinia + Vite（Gin 全栈） | Gin 全栈闭环 / 后端对接示例 | 后端菜单→`import.meta.glob` 动态路由、`defineOptions name` 与 keep-alive 链路、loading 防抖计数器 |
|
||
|
||
> gva 的价值在于「Gin 后端 + Vue 前端」同仓配套的全栈闭环，适合做整体功能对照；
|
||
> 其前端工程化、代码规范整体弱于上面 4 个纯前端项目（拦截器 `return error` 未 reject、EP 全量引入、无测试）。
|
||
> **前端实现分歧时以 vben（架构）/ soybean（规范）/ pure（同栈 EP 实操）为准，gva 只当功能实现方式对照，前端写法不照搬。**
|
||
|
||
### 按维度查哪个项目
|
||
|
||
| 维度 | 优先看 | 说明 |
|
||
| ---------------- | --------------------- | ----------------------------------------------------------------------- |
|
||
| 目录结构与分层 | vben > soybean > pure | vben monorepo 分层最值得学；soybean 文件路由清晰；pure 传统但干净 |
|
||
| 请求封装 | vben / soybean / pure | 错误处理、Token 刷新、类型定义三家都成熟，见 03 章对照 |
|
||
| 权限系统 | vben > soybean > pure | vben 动态路由 + 细粒度最完整；soybean 静态/动态一键切换；pure 两级按钮权限 |
|
||
| Lint / Commit 规范 | vben / soybean | 配置最严格完整，直接抄它们的配置文件 |
|
||
| 组件二次封装 | vben / pure / adp | vben schema 驱动且多 UI；pure hook + 命令式弹窗实用；adp ProTable/ProForm 是 React 标杆 |
|
||
| TypeScript 类型组织 | vben / soybean / adp | 类型集中、接口返回类型完整；soybean 的全局 namespace + 键级类型最易迁移到 JS 工程 |
|
||
|
||
### 管理端前端十大黄金法则
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────┐
|
||
│ 01. 一切 IO 走统一请求层 —— 组件不直接碰 axios/fetch │
|
||
│ 02. 响应契约全局唯一 —— code/data/msg + 错误分级 │
|
||
│ 03. 401 只有一个入口 —— 单飞刷新 + 队列重放，不竞态 │
|
||
│ 04. meta 驱动一切 UI 行为 —— 菜单/缓存/权限/标题单源维护 │
|
||
│ 05. 权限三态 —— 不可见 / 可见但 403 / 放行 │
|
||
│ 06. 页面私有代码不出页面目录 —— 复用第三次才晋升公共组件 │
|
||
│ 07. 反馈分级、少弹框 —— 成功静默、失败必现、危险确认 │
|
||
│ 08. 换肤只改 CSS 变量 —— 不重编译、不引第二套样式系统 │
|
||
│ 09. 列表/表单/详情有模板 —— 新页面从模板起步，不自由发挥 │
|
||
│ 10. 双栈契约优先 —— 同产品双端实现时 key、权限码、 │
|
||
│ 响应格式两端同名 │
|
||
└────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 质量红线（违反即技术债）
|
||
|
||
- 单文件组件 ≤ **400 行**（视图）/ ≤ **300 行**（工具、请求层），超限必须拆分
|
||
- 样式必须有唯一入口引用链，**无入口的 CSS 一律删除**（存量工程常见 2000+ 行死 CSS 的考古层）
|
||
- 生产构建**零 console.log**，尤其禁止打印 token 片段
|
||
- 组件不绕过 API 层直接调用请求实例
|
||
- 文档与实现同 PR 更新，禁止「描述已删除组件」的漂移文档
|
||
|
||
### 规范用语约定（必须遵守 vs 推荐）
|
||
|
||
| 标记 | 含义 | 违反后果 |
|
||
| ----------- | ------------------------------------ | --------------------- |
|
||
| **必须 / 禁止** | 强制规范（MUST / MUST NOT） | Code review 拒绝，视同 bug |
|
||
| **推荐 / 避免** | 默认采纳（SHOULD / SHOULD NOT），允许有充分理由的例外 | 例外需在 PR 描述中说明原因 |
|
||
| **可选** | 按需采用（MAY） | 无 |
|
||
|
||
正文中加粗的「必须 / 禁止」条款为强制项；各章「AI 检查清单」是带优先级（P0/P1/P2）的对比执行队列。
|
||
|
||
### 文档维护与更新规则
|
||
|
||
1. 实现与文档不一致 = 文档 bug，同一 PR 修复（详见 08 章文档治理）
|
||
2. 参考项目大版本升级（vben / soybean / pure / adp）后，复核对应章节引用的证据文件路径
|
||
3. 新增规范先以「推荐」落地，被 ≥2 个模块实际验证后再升级为「必须」
|
||
4. 修订历史以 git commit 为准
|
||
|
||
---
|
||
|
||
## 🎯 适用场景
|
||
|
||
- 🏗️ **可裁剪底座 / 脚手架** — 壳 / 系统 / 示例三层，fork 即用
|
||
- 🖥️ **管理后台 / 中台** — 用户、RBAC、审计、系统设置等系统级页面
|
||
- 📊 **运维监控平台** — 仪表盘、指标图表、实时日志（WebSocket/SSE）
|
||
- ⏰ **任务调度控制台** — 定时任务 CRUD、执行历史、手动触发
|
||
- 🔄 **双栈迁移工程** — Vue→React 或反向迁移期间的对照参照
|
||
|
||
---
|
||
|
||
## 📐 与兄弟指南的关系
|
||
|
||
| 指南 | 领域 | 分界 |
|
||
| ----------------------- | -------------------- | ---------------------- |
|
||
| `GUI-Development-Guide` | Electron/Tauri 桌面端 | 窗口、标题栏、IPC、自动更新 |
|
||
| `CLI-Development-Guide` | Go 命令行 / TUI / Agent | Cobra、Bubble Tea、审批流 |
|
||
| **本指南** | **浏览器 Web 管理端** | **请求层、路由权限、布局主题、组件工程** |
|
||
|
||
三份指南共享同一套写作范式：每个专题按「原理 → 标杆代码 → 最佳实践 → AI 检查清单」四层展开。
|
||
|
||
---
|
||
|
||
> 💡 **阅读建议**：开发者先通读本文件，写新页面前读 05（页面模板）和 07（组件规范）；搭新模块前读 02（架构）和 04（路由权限）；排查线上问题读 03（请求层）和 08（工程化）。
|
||
> **AI 助手**：编码前读 02/04/05/07；Review 与重构时按各章末「AI 检查清单」逐项对比目标代码，不合格项即输出为优化建议。
|
||
> 查阅标杆实现时：**Vue 架构问题对照 vben、规范写法对照 soybean、同栈（Element Plus）实操对照 pure、React 问题对照 adp，gva 仅作功能对照。**
|