LokiStack/docs/web-ui-guide/00-目录与概览.md

打造高质量 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 仅作功能对照。