fix(web-admin): 前端全面排查修复——移动端、阅读视图、性能与测试基建

.github/workflows/_tests.yml

@@ -97,6 +97,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Audit production dependencies
+        run: pnpm audit --prod --audit-level=high
+
       - name: Type check
         run: pnpm type-check
 

docs/dev/architecture.md

@@ -149,6 +149,18 @@ src/quickquip/
 
 ---
 
+## `frontend/` — Web 管理后台前端
+
+Web Admin 前端是独立的 pnpm 工程（`quickquip-admin-v2`），技术栈为 Vue 3.5 + TypeScript strict + Vite 8 + vue-router 4（hash 模式，base `/ops/`）。关键约定：
+
+- 路由页面在 `src/config/nav.ts` 登记，路由由其派生；除首页静态引入外，页面组件一律路由级动态 import。
+- 后端接口封装按领域收在 `src/api/`，可复用状态与请求编排收在 `src/composables/`，`src/components/ui/` 是设计系统组件。
+- 构建产物 `frontend/dist/`（gitignore）由 `app/web/` 以 StaticFiles 挂载到 `/ops/`；前端不设路由守卫，鉴权由后端强制。
+
+开发命令、测试双栈与部署形态见 [`../../frontend/README.md`](../../frontend/README.md)。
+
+---
+
 ## `config/` — 配置文件目录
 
 | 文件 | 层 | 说明 |

docs/dev/style.md

@@ -86,6 +86,8 @@ God file、God function、God class、mega-controller、service locator、宽 co
 - `<script setup>` 中的业务状态、请求编排或图表配置形成稳定职责时抽为 composable 或子组件。
 - API 响应类型归属 `api/`；组件局部类型置于 `<script setup>` 顶部。
 - 加载、错误和正常页面是不同的展示职责时，用组件或清晰分支保持主视图可读。
+- 新增路由页面在 `config/nav.ts` 登记并使用路由级动态 import；导航结构与路由路径以 `nav.ts` 为唯一真值源。
+- 新组件与 composable 的测试优先使用 vitest 栈（`tests/unit/`）；存量 `tests/*.test.cjs`（node --test）保持运行。
 
 ## 测试与评审
 

docs/index.md

@@ -51,6 +51,7 @@ QuickQuip 是一个基于 NoneBot2 + OneBot V11 的规则驱动优先 QQ 群聊
 | [docs/dev/branching.md](dev/branching.md) | 开发工作流与发布流程——六级变更分级、评审（含 KHPilot Bot Review 机制与双轨交叉核对）、验证、release 与 hotfix |
 | [docs/dev/versioning.md](dev/versioning.md) | 版本号约定——三段式版本、主题更新系列、dev 批次与发布候选规则 |
 | [docs/dev/architecture.md](dev/architecture.md) | 项目架构与结构——三层架构、依赖方向、组合根、目录用途与数据边界 |
+| [../frontend/README.md](../frontend/README.md) | Web Admin 前端模块入口——技术栈、目录约定、开发命令、测试双栈与部署形态 |
 | [docs/dev/record-identities.md](dev/record-identities.md) | 记录正文与成员身份契约——正文片段结构、身份分层缓存与消费口径 |
 | [docs/dev/game-framework.md](dev/game-framework.md) | 游戏框架开发指南——BaseGame 接口、economy API、Session 模式 vs RPG 模式、扩展新游戏步骤 |
 | [docs/dev/llm-configuration-api.md](dev/llm-configuration-api.md) | LLM 配置 API——修订冲突、任务状态、参数 metadata 与前端接口契约 |

frontend/README.md

@@ -0,0 +1,49 @@
+# QuickQuip Web Admin 前端
+
+Web 管理后台（`quickquip-admin-v2`）的前端工程，一个 Vue 3 单页应用。构建产物由后端 FastAPI 以 StaticFiles 挂在 `/ops/` 下，随 `python web_api.py` 一同提供。
+
+## 技术栈
+
+Vue 3.5（`<script setup>`）+ TypeScript strict + Vite 8 + vue-router 4（hash 模式，base `/ops/`）。图表用 echarts 6，Markdown 渲染用 marked + dompurify，图标用 @lucide/vue。包管理使用 pnpm（Node 24）。
+
+## 目录约定
+
+```
+src/
+├── views/        # 路由页面（29 个，由 config/nav.ts 派生；登录门 LoginView 由 App.vue 静态引入）
+├── components/   # ui/ 设计系统组件 + llm-config 等业务域子目录
+├── api/          # 后端接口封装，每个领域一个模块；API 响应类型归属此处
+├── composables/  # 可复用状态与请求编排
+├── config/       # nav.ts：导航唯一真值源
+├── charts/  lib/  styles/
+tests/            # 测试双栈（见下文）
+```
+
+路由由 `config/nav.ts` 派生：新增页面在此登记，路由路径与名称按 `key` 生成。除首页静态引入外，页面组件一律路由级动态 import，按路由分包（首屏 gzip 约 69 KB）。
+
+鉴权不依赖前端路由守卫：`App.vue` 呈现登录门，API 返回 401 时重置登录态，会话与同源检查由后端强制。鉴权结构与反向代理配置见 [docs/admin/web-admin.md](../docs/admin/web-admin.md)。
+
+## 开发命令
+
+```bash
+pnpm install
+pnpm dev          # vite 开发服务器，/ops/api 代理到 127.0.0.1:5104（需后端在跑）
+pnpm build        # 产出 dist/
+pnpm type-check   # vue-tsc 严格类型检查
+```
+
+## 测试双栈
+
+| 栈 | 位置 | 运行器 | 适用场景 |
+|---|---|---|---|
+| 存量 harness | `tests/*.test.cjs`（59 例） | `node --test`，自建 vm harness 执行 `<script setup>` 编译产物 | 既有视图与 store 逻辑回归 |
+| vitest | `tests/unit/*.test.ts`（26 例） | vitest + @vue/test-utils + happy-dom，配置在 `vite.config.ts` 的 `test` 字段 | 新组件、composable 与路由测试优先写在这里 |
+
+```bash
+pnpm test         # 依次跑两套
+pnpm test:unit    # 只跑 vitest
+```
+
+## 部署
+
+`pnpm build` 产出 `frontend/dist/`（gitignore），由后端挂载到 `/ops/`；服务器上的构建与反代流程见 [docs/admin/deployment.md](../docs/admin/deployment.md)。LLM 配置页的页面任务、字段语义与接口接线契约见 [docs/dev/llm-configuration-frontend.md](../docs/dev/llm-configuration-frontend.md)。

frontend/package.json

@@ -2,28 +2,33 @@
   "name": "quickquip-admin-v2",
   "private": true,
   "version": "0.1.0",
+  "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "vite build",
     "type-check": "vue-tsc --noEmit -p tsconfig.app.json",
-    "test": "node --test tests/*.test.cjs"
+    "test": "node --test tests/*.test.cjs && vitest run",
+    "test:unit": "vitest run"
   },
   "dependencies": {
+    "@lucide/vue": "^1.59.0",
     "@vuepic/vue-datepicker": "^14.0.0",
     "date-fns": "^4.4.0",
-    "dompurify": "^3.4.2",
+    "dompurify": "^3.4.17",
     "echarts": "^6.1.0",
-    "lucide-vue-next": "^1.0.0",
-    "marked": "^18.0.3",
-    "vue": "^3.5.0",
+    "marked": "^18.1.1",
+    "vue": "^3.5.44",
     "vue-router": "^4.6.4"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^5.0.0",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "@vue/test-utils": "^2.5.1",
     "@vue/tsconfig": "^0.9.1",
+    "happy-dom": "^21.0.3",
     "typescript": "^6.0.3",
-    "vite": "^5.0.0",
-    "vue-tsc": "^3.2.7"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5",
+    "vue-tsc": "^3.3.13"
   },
   "packageManager": "pnpm@10.31.0",
   "pnpm": {