# admin-vue

**Repository Path**: xiak/admin-vue

## Basic Information

- **Project Name**: admin-vue
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: UI

## README

# 后台框架 · 管理系统

基于 **Vue 3 + Vite + TypeScript + Element Plus** 的后台管理系统基础框架。当前版本 **v1.16.0**。

内置完整布局、主题色、**24+ 组件演示页**、**10 个业务模块共 70+ 页面**、**10 个总览仪表盘**、系统管理示例，覆盖几乎全部 Element Plus 组件，可作为后续做后台系统的脚手架。

> **v1.15.3 更新**：完成全业务模块（10 个）+ 系统管理 + 数据大屏 + 组件演示页 + 共享组件 + 布局 + 基础设施的深度审计修复，消灭占位 stub，统一数据真实化与类型安全，补充单测至 246 个，`type-check / lint / test / build` 全链路通过。

## 技术栈

- Vue 3 + `<script setup>` + TypeScript
- Vite 5（modern Sass API）
- Element Plus（自动引入 + 自定义主题）
- Vue Router 4
- Pinia 2
- vue-echarts（按需引入折线 / 柱状 / 饼图 / 雷达）
- SCSS 变量化主题
- `unplugin-auto-import` / `unplugin-vue-components` 自动引入
- ESLint 9（flat config）+ Prettier 代码规范
- axios 封装（`utils/request.ts`）

## 主题色

| 用途                                                 | 颜色      |
| ---------------------------------------------------- | --------- |
| 导航黑（头部 + 侧栏底色）                            | `#001529` |
| 主蓝（高亮 / 主按钮 / Element Plus 主题色 / 选中态） | `#2563fc` |

集中在 `src/styles/`：`variables.scss` 定义 SCSS 变量（编译期布局 / 尺寸），`index.scss` 顶部 `:root` 用 CSS 变量覆盖 Element Plus 主题色，改一处全局生效。

## 快速开始

```bash
npm install
npm run dev      # http://localhost:5173
npm run dev:mock # 启用本地 Mock，无需后端服务
npm run build
npm run preview
npm run lint     # 检查代码规范
npm run lint:fix # 自动修复可修复的问题
npm run format   # Prettier 格式化
npm run test     # 跑全部单测（vitest）
npm run test:watch    # 监听模式
npm run test:coverage # 覆盖率报告
```

复制 `.env.example` 为 `.env`（可选，用于自定义标题 / API 地址 / 默认头像 / Mock 开关）。生产环境参考 `.env.production`。

## 登录演示

内置完整登录流程（路由守卫 + Token 持久化 + 用户信息拉取），演示账号：

- **xiaobu / 123456** (管理员，拥有全部权限，可访问所有 10 个业务模块)
- **guest / guest** （访客，仅 3 个菜单：工作台 / 商品 / 文章，可用来验证权限系统）

代码入口：`src/views/login/index.vue`（Spug 风格简洁视觉）。
登录鉴权适配器：`src/utils/auth.ts` —— **这是接入真实后端的唯一改动点**，替换其中的 MOCK_ACCOUNTS 与 `loginApi` / `fetchProfileApi` / `logoutApi` 实现即可，无需改其他文件。

### 角色权限持久化

在「系统管理 → 角色管理」分配的权限会按 `roleCode` 自动写入 `localStorage`（键名 `admin_framework_role_permissions`），下次登录时由 `loginApi` 读取并覆盖默认权限。点击对话框底部「恢复默认」可一键清空。切换真实后端时把 `utils/rolePermissions.ts` 改为 PUT `/role/:id/permissions` 接口即可，其他文件无需改动。

## 组件演示页清单（24 页）

### 基础组件

- **按钮 Button** — 类型 / 尺寸 / 图标 / 加载 / 按钮组
- **图标 Icon** — 全部 Element Plus 图标浏览（点击复制名称）
- **文字 Typography** — 标题 / 段落 / 文本状态 / 引用
- **基础元素 Element** — Color 色彩 / Border 边框 / Shadow 阴影 / Text 文本 / Link 链接 / Divider 分割线
- **布局 Layout** — Row/Col 栅格 / 响应式 / Container / Space / Scrollbar / Affix / Backtop

### 表单组件

- **输入与选择** — Input / Select / Radio / Checkbox / Switch / Slider / Rate / DatePicker / Transfer / ColorPicker / InputNumber
- **时间日期 Datetime** — DatePicker 全套（日/周/月/年/范围/快捷） / DateTimePicker / TimePicker / TimeSelect
- **高级表单 Advanced** — Autocomplete / Cascader / Mention / Segmented / Slider marks / ColorPicker 预设
- **表单 Form** — 校验 / 行内 / 对齐
- **上传 Upload** — 点击 / 拖拽 / 头像 / 照片墙

### 数据展示

- **表格 Table** — 基础 / 状态 / 排序筛选 / 固定列 / 展开行 / 可选择 + 分页 / 业务表格（含 TableActions）
- **标签 / 徽章** — Tag 类型 / 主题 / 动态 / Badge / Avatar
- **卡片 / 折叠** — Card 多风格 / 带图片 / 折叠面板
- **时间线 / 描述** — Timeline 自定义 / Descriptions 多种风格
- **图片 / 走马灯** — Image 预览 / 懒加载 / 失败占位 / Carousel / Avatar Group
- **日历 / 统计** — Calendar 自定义 / Statistic / Countdown
- **树 Tree** — 基础 / 可勾选 / 懒加载 / 拖拽编辑 / 过滤 / TreeV2 虚拟树（1 万节点）

### 反馈组件

- **消息 / 通知** — Message / Notification / MessageBox（alert/confirm/prompt）
- **弹窗 / 抽屉** — Dialog 多种 / Drawer 四方向
- **警告 / 进度** — Alert / Progress / Skeleton / Loading / Empty / Result
- **气泡 / 提示** — Tooltip / Popover / Popconfirm / Dropdown

### 导航组件

- **标签页 Tabs** — 基础 / 卡片 / 位置 / 可增加关闭
- **步骤条 Steps** — 基础 / 图标 / 简洁 / 垂直
- **分页 Pagination** — 完整功能 / 与表格联动

### 其他组件

- **水印 / 引导** — Watermark / Tour / InfiniteScroll / Image Viewer / Segmented

## 业务模块示例(10 个,70+ 页面)

| 模块     | 路径前缀     | Dashboard 特色                    | 主要内容                                                                   |
| -------- | ------------ | --------------------------------- | -------------------------------------------------------------------------- |
| 告警管理 | `/alarm`     | 3D 态势图 + 实时告警滚动          | 规则（来源系统/通知方式/沉默）/ 联系人组 / 列表 / 详情 / 看板 / 驾驶舱      |
| 电商管理 | `/ecommerce` | 转化漏斗 + 订单流水线             | 商品 / 订单 / 会员 / 营销 / 售后退款 / 物流                                |
| 物业管理 | `/property`  | 缴费进度环形 + 报修 SLA           | 业主 / 房产 / 报修 / 缴费                                                  |
| 新闻 CMS | `/news`      | 内容生产 pipeline + 流量 TOP      | 文章（md 编辑）/ 栏目 / 评论                                               |
| 短剧管理 | `/drama`     | 内容矩阵散点图 + 观看漏斗         | 剧集 / 章节 / 分类（树）/ 演员 / 审核 / 弹幕 / Banner                      |
| 音乐管理 | `/music`     | 版权到期时间线 + 试听漏斗         | 歌曲（试听抽屉）/ 歌手 / 专辑 / 风格（树）/ 歌单 / 评论 / 版权             |
| AI 客服  | `/aiservice` | 转人工原因 treemap + 知识库覆盖率 | 机器人 / 提示词 / 渠道 / 知识库 / 意图 / 训练 / 对话 / 转人工              |
| 工单系统 | `/ticket`    | 4 列看板 + SLA 趋势               | 全部 / 我的 / 看板（拖拽）/ 分类 / SLA / 模板 / 自动化                     |
| 问卷系统 | `/survey`    | 回收 Sankey + NPS 分布            | 问卷 / 模板 / 题库 / 回答 / 规则 / 抽奖（动画）/ 评价                      |
| 文档管理 | `/document`  | 新鲜度饼图 + 活动时间线           | 全部 / 分类 / 知识库（md 预览）/ 共享 / 版本（回滚）/ 回收站 / 日志 / 模板 |
| 系统管理 | `/system`    | 模块使用分布 + 权限审计           | 用户 / 角色 / 菜单 / 操作日志 / 登录日志                                   |

每个业务模块首页均为「总览」仪表盘，深度业务化设计：4 个独特 KPI + 1 个 HERO 可视化（每个不同）+ 1-2 辅助图 + 1 可操作列表。所有图表用统一的 `<EChart>` 组件，支持折线/柱状/饼图/雷达/散点/漏斗/treemap/Sankey。

工作台另含 5 个数据大屏：驾驶舱 / 运营仪表盘 / 财务仪表盘 / 监控大屏 / 销售大屏。

均基于统一 TableActions + 搜索表单 + 分页模式，**所有表格均带分页条**。

## 系统管理示例

- **用户管理** — 完整 CRUD（搜索 + 表格 + 新增/编辑弹窗 + 删除 + 启停）
- **角色管理** — 角色 CRUD + 权限分配（菜单 / 功能复选框 + 持久化）
- **菜单管理** — 树形表格 + 类型/排序 + 增删改
- **日志管理** — 操作日志 / 登录日志（筛选 + 分页）

## 顶部加载进度条

首次访问新页面（惰性 chunk 加载）时，顶部出现 2px 蓝色光条，加载完毕淡出。已访问过的页面缓存内重访不重复触发。
实现位于 `src/components/LoadingBar.vue` + `src/router/index.ts` 的 `beforeEach` / `afterEach` 钩子。

## 目录结构

```
src/
├── config/
│   ├── menus/               # 菜单系统：index.ts 聚合 menuTree + 工具函数，
│   │                         # <module>.ts 按模块拆分菜单数据（树形，含 permission）
│   └── app.ts               # 功能开关（TagsView / 面包屑等）
├── components/
│   ├── DemoBlock.vue        # 组件演示容器（标题 + 描述 + 内容）
│   ├── PageHeader.vue       # 页面标题
│   ├── EChart.vue           # vue-echarts 封装（折线/柱状/饼图/雷达）
│   ├── LoadingBar.vue       # 顶部加载进度条
│   ├── ImageGallery.vue     # 图片画廊（网格 + 全屏预览）
│   └── TableActions.vue     # 表格行操作按钮（行内 + 溢出下拉）
├── layout/                  # 整体布局
│   ├── index.vue
│   └── components/          # AppHeader / AppLogo / ModuleNav / AppSidebar
│                              AppBreadcrumb / UserAvatar / NotificationBell
├── router/index.ts          # 路由（含登录守卫 + LoadingBar 触发）
├── stores/
│   ├── app.ts               # 侧栏折叠 / 当前模块
│   ├── user.ts              # 用户信息 / 通知 / 权限
│   └── tagsView.ts          # 多标签页状态（visited / cached）
├── styles/
│   ├── variables.scss      # SCSS 变量（颜色 / 尺寸 / 断点，vite 全局注入）
│   └── index.scss          # Element Plus 主题色覆盖（:root CSS 变量）+ 通用样式
├── utils/
│   ├── auth.ts              # 鉴权适配器（接入后端的唯一改动点）
│   ├── rolePermissions.ts   # 角色权限持久化（localStorage）
│   ├── request.ts           # axios 封装（拦截器 / envelope / 401 / 上传 / 下载 / ApiError）
│   ├── mock/                # 本地 Mock 层（VITE_USE_MOCK=true 时启用）
│   └── export.ts            # CSV 导出工具
├── directives/
│   └── permission.ts        # v-permission 按钮级鉴权指令
└── views/
    ├── components/          # 24 个组件演示页
    ├── system/              # 系统管理（含总览 Dashboard）
    ├── business/            # 10 个业务模块（电商/物业/新闻/短剧/音乐/AI 客服/工单/问卷/文档/告警）
    ├── dashboard/           # 工作台 + 5 个数据大屏
    ├── about/               # 关于 / 更新日志
    ├── login/               # 登录页
    └── error/               # 403 / 404 / Redirect（刷新中转）
```

## 扩展指南

### 新增顶部模块

在 `src/config/menus/` 下新建 `<module>.ts` 导出一个顶层 `MenuNode`（含 `id` / `name` / `icon` / `children`，参考 `dashboard.ts`），再把它加入 `index.ts` 的 `menuTree` 数组。
顶部导航自动从 `menuTree` 派生。

### 新增页面 / 路由

1. 在 `src/views/<module>/` 下创建 `.vue` 文件
2. 在 `src/router/index.ts` 添加路由，meta 关键字段：
   - `title`: 页面标题（同时用于浏览器标签 + 面包屑）
   - `breadcrumb`: 面包屑路径数组
3. 在对应模块的 `children` 中加入菜单项（含 `path` / `icon` / `permission`）

### 修改主题色

编辑 `src/styles/`：

- `index.scss` 顶部 `:root` 中的 `--el-color-primary*` 系列 CSS 变量覆盖 Element Plus 主题色（运行时生效）
- `variables.scss` 定义项目自定义 SCSS 变量（导航黑、语义色、布局尺寸、断点），经 vite `additionalData` 全局注入

### 表格行操作按钮

统一使用 `<TableActions>` 组件，避免每个页面重复实现：

```vue
<TableActions
  :actions="[
    { key: 'edit', label: '编辑' },
    { key: 'delete', label: '删除', danger: true },
    { key: 'more', label: '更多', overflow: true }
  ]"
  :max-inline="3"
  @command="onCommand"
/>
```

- 超过 `maxInline` 个或设置 `overflow: true` 的按钮自动收进下拉菜单
- `danger: true` 红色文字，`disabled: true` 禁用

### 导出 CSV

```ts
import { exportCsv } from '@/utils/export'
exportCsv('用户列表.csv', rows, [{ field: 'id', title: 'ID' }, ...])
```

### 发起 HTTP 请求

统一使用 `utils/request.ts` 暴露的 `request`，拦截器已处理 token 注入与 401 跳转：

```ts
import { request } from '@/utils/request'

// GET（自动拆 envelope，直接拿到 data）
const list = await request.get<UserItem[]>('/system/user/list', { params: { keyword: 'foo' } })

// POST / PUT / DELETE 同理
await request.post<void>('/system/user', { name: 'foo' })
await request.put<void>(`/system/user/${id}`, { name: 'bar' })
await request.delete<void>(`/system/user/${id}`)
```

后端 envelope 约定为 `{ code, data, message }`，`code === 0` 视为成功。
若后端结构不同，仅需调整 `utils/request.ts` 中的 `unwrapResponse` / `SUCCESS_CODE`。

### 按钮级权限

菜单 / 用户接口返回的 `permissions` 字段会自动写入 user store。模板里用 `v-permission` 控制按钮显示：

```vue
<!-- 单个权限 -->
<el-button v-permission="'system:user:add'">新增</el-button>

<!-- 多个权限：任一命中即显示 -->
<el-button v-permission="['system:user:edit', 'system:user:reset']">操作</el-button>

<!-- 全部命中才显示 -->
<el-button v-permission.all="['system:user:add', 'system:user:edit']">操作</el-button>
```

代码内判断：

```ts
const user = useUserStore()
if (user.hasPermission('system:user:add')) { ... }
if (user.hasAnyPermission(['a', 'b'])) { ... }
if (user.hasAllPermissions(['a', 'b'])) { ... }
```

约定：admin 角色的 `permissions` 含 `'*'` 通配，拥有全部权限。
也可以使用前缀通配，如 `'system:*'` 命中所有 `system:` 开头的权限。

### 路由级权限

在路由 `meta.permission` 上声明权限，路由守卫会自动检查：

```ts
{
  path: 'system/user',
  component: () => import('@/views/system/User.vue'),
  meta: {
    title: '用户管理',
    permission: 'system:user:list'   // 缺权限访问会跳 /403
  }
}
```

侧栏菜单 / 顶部模块也会按权限自动过滤：

- 叶子菜单有 `permission` 且用户无权限 → 不展示
- 目录所有子项都被过滤掉 → 整个目录隐藏
- 顶部模块所有子项都被过滤掉 → 整个模块隐藏

### 多标签页（TagsView）—— 可选启用

- **默认关闭**，可在「账户设置 → 多标签页」开关中开启（或开发者在 `src/config/app.ts` 改默认值）
- 开启后：自动记录访问过的页面，固定标签（`meta.affix: true`）不可关闭
- 右键标签：刷新 / 关闭 / 关闭其他 / 关闭左侧 / 关闭右侧 / 关闭全部
- 右侧下拉箭头提供等价的快捷菜单
- `<keep-alive :include="cachedViewNames">` 智能缓存
- 关闭模式时：标签条隐藏且不使用 `<keep-alive>`，每次进入菜单都创建新的页面实例
- 标签条持久化到 localStorage（开启模式下有效），刷新后恢复

路由 meta 控制项：

- `affix: true` —— 固定标签（如 Dashboard）
- `cache: false` —— 此页面不参与 keep-alive
- `noTagsView: true` —— 此页面不显示在标签条（如详情弹层页）

开发者配置（`src/config/app.ts`）：

```ts
export const appConfig = {
  tagsView: {
    defaultEnabled: false, // 默认关闭
    userToggleable: true // 用户可在设置抽屉中切换；false 则强制使用 defaultEnabled
  }
}
```

### 工作流引擎（状态机）

通用 FSM 引擎 + 审批对话框，已在工单、文档、告警三个模块落地。

**定义状态机**（参考 `src/views/business/ticket/machine.ts`）：

```ts
import { defineMachine } from '@/utils/stateMachine'

export const ticketMachine = defineMachine({
  initial: 'open',
  states: [
    { state: 'open', label: '待处理', color: 'warning' },
    { state: 'pending', label: '处理中', color: 'primary' },
    { state: 'resolved', label: '已解决', color: 'success' },
    { state: 'closed', label: '已关闭', color: 'info', final: true }
  ],
  transitions: [
    { action: 'assign', label: '受理工单', from: 'open', to: 'pending' },
    { action: 'resolve', label: '标记已解决', from: 'pending', to: 'resolved' },
    {
      action: 'close',
      label: '关闭工单',
      from: ['resolved', 'pending'],
      to: 'closed',
      requireComment: true
    },
    {
      action: 'reopen',
      label: '重新打开',
      from: ['resolved', 'closed'],
      to: 'pending',
      requireComment: true
    }
  ]
})
```

**配合 ApprovalDialog**（参考 `ticket/All.vue` / `document/All.vue`）：

```vue
<ApprovalDialog
  v-model="approval.visible"
  :machine="ticketMachine"
  :from="row.status"
  :action="approval.action"
  @confirm="onApprovalConfirm"
/>
```

**查询接口**：

| 方法                                        | 用途                                                   |
| ------------------------------------------- | ------------------------------------------------------ |
| `machine.nextTransitions(state)`            | 查询某状态可执行的所有操作（用于动态按钮）             |
| `machine.canTransition(from, action)`       | from→action 是否合法                                   |
| `machine.findTransition(from, action)`      | 查找具体 transition（含 to/requireComment/permission） |
| `machine.stateOf(state)`                    | 取 label/color/final 等元信息                          |
| `runTransition(machine, from, action, ctx)` | 执行转换，自动跑 before 钩子                           |
| `shortestPath(machine, from, to)`           | BFS 找最短路径（可视化用）                             |

### Schema-driven CRUD（list 页标准范式）

list 页的搜索表单 + 表格 + 分页 + 增删改弹窗样板高度重复。`useCrud` composable + `SchemaSearch` / `SchemaTable` / `SchemaDialog` 三件套把模板从 ~400 行降到 ~150 行。已在 music、ecommerce、property、news、drama、aiservice、survey、alarm 等模块 30+ 页面落地。

**最小用例**（参考 `views/business/music/Artist.vue`）：

```vue
<template>
  <div class="page-fit">
    <SchemaSearch
      :fields="crud.searchFields"
      :query="crud.query"
      :loading="crud.loading.value"
      @search="crud.search"
      @reset="crud.reset"
    >
      <template #extra-right>
        <el-button :icon="Plus" @click="crud.openAdd">新增</el-button>
      </template>
    </SchemaSearch>

    <SchemaTable
      :columns="columns"
      :data="crud.rows.value"
      :loading="crud.loading.value"
      :total="crud.total.value"
      :page="crud.page"
      @update:page="
        (p) => {
          crud.page.current = p.current
          crud.page.size = p.size
        }
      "
    >
      <template #actions="{ row }">
        <TableActions :actions="rowActions(row)" @command="(k) => onAction(k, row)" />
      </template>
    </SchemaTable>

    <SchemaDialog
      :fields="crud.formFields"
      :dialog="crud.dialog"
      @update:dialog="(d) => Object.assign(crud.dialog, d)"
      @submit="crud.submit"
    />
  </div>
</template>

<script setup lang="ts">
const fields: FieldDef<Artist>[] = [
  {
    prop: 'name',
    label: '姓名',
    rules: [{ required: true, message: '请填写姓名', trigger: 'blur' }]
  },
  { prop: 'keyword', label: '关键字', inForm: false }, // 虚拟搜索字段
  { prop: 'region', label: '地区', type: 'select', options: regionOpts },
  { prop: 'bornAt', label: '出生日期', type: 'date' },
  { prop: 'bio', label: '简介', type: 'textarea', span: 24 }
]

const crud = useCrud<Artist>({
  source: () => artists.value,
  filter: (r, q) => !q.keyword || r.name.includes(q.keyword),
  fields,
  create: (f) => artists.value.unshift({ ...(f as Artist), id: nextId() }),
  update: (f, row) => Object.assign(row, f),
  remove: (row) => (artists.value = artists.value.filter((r) => r.id !== row.id))
})
</script>
```

**两种数据模式**（自动判定）：

```ts
// 客户端模式（mock 阶段）：传 source + filter
useCrud({ source: () => rows.value, filter: (r, q) => ..., fields, create, update, remove })

// 服务端模式（接后端）：传 fetch，模板零改动
useCrud({
  fetch: async ({ page, size, query }) => {
    const { data } = await request.get('/artist', { params: { page, size, ...query } })
    return { list: data.list, total: data.total }
  },
  fields,
  create: (f) => request.post('/artist', f),
  update: (f, row) => request.put(`/artist/${row.id}`, f),
  remove: (row) => request.delete(`/artist/${row.id}`)
})
```

**FieldDef 字段类型**：

| type        | 控件              | 默认值  |
| ----------- | ----------------- | ------- |
| `input`     | el-input          | `''`    |
| `textarea`  | el-input textarea | `''`    |
| `number`    | el-input-number   | `0`     |
| `select`    | el-select         | `''`    |
| `switch`    | el-switch         | `false` |
| `radio`     | el-radio-group    | `''`    |
| `date`      | el-date-picker    | `null`  |
| `datetime`  | el-date-picker    | `null`  |
| `daterange` | el-date-picker    | `[]`    |

**三类自定义插槽**：

- `#col-{prop}="{ row }"` — SchemaTable 单元格自定义渲染（el-tag / el-switch / 图片预览）
- `#field-{prop}="{ form, mode }"` — SchemaDialog 表单控件替换（MdEditor / Upload / 自定义组件）
- `#search-{prop}="{ query }"` — SchemaSearch 搜索控件替换

**内置约束**（迁移时不需要每个页面各自实现）：

- `reset()` 自动重新搜索（避免「重置后没刷新」bug），`reset({ refetch: false })` 逃生舱
- `page.size` 变化自动回第一页（旧代码普遍漏掉）
- `submitting` 期间 `openAdd` / `openEdit` 被拦截，防双创建
- 客户端模式有 200ms loading 延迟，让用户感知「加载」
- 服务端模式用 seq 计数器忽略过期响应（搜索连点 / 快速翻页不会闪内容）

**和 FSM 的关系**：FSM 状态流转类页面（Order / Refund / Copyright）useCrud 只托管搜索 / 分页 / 行选择，状态流转仍走 ApprovalDialog。`#actions` slot 是 CRUD 与 FSM 的接缝，详见 `views/business/ecommerce/Order.vue`。

### 接入真实后端

**5 分钟接入清单**（详见 [`docs/BACKEND_INTEGRATION.md`](docs/BACKEND_INTEGRATION.md)）：

1. `cp .env.example .env.development`，按需修改 `VITE_API_BASE_URL`
2. 在 `vite.config.ts` 的 `server.proxy` 配置后端地址（默认 `/api -> http://localhost:8080`）
3. 在 `src/utils/auth.ts` 删除 `MOCK_ACCOUNTS`，把 `loginApi` / `fetchProfileApi` / `logoutApi` 改为真实接口；`refreshApi` 必须使用不带刷新拦截器的独立 axios 实例
4. 若需角色权限持久化：把 `utils/rolePermissions.ts` 中的 `saveRolePermissions` 改为 `PUT /role/:id/permissions`，`loadRolePermissions` 改为登录接口直接返回权限数组
5. 路由守卫、Pinia store、登录页、Role.vue 都无需改动

**边界说明**：路由表（`router/modules/`）是前端静态的，后端菜单接口只驱动导航展示与权限过滤——新增页面仍需前端发版，菜单数据从后端下发也无法动态挂载新组件。

**Mock 模式**：`npm run dev:mock` 启动内置 Mock，无需后端服务即可跑通登录 → 列表 → 详情 → 登出闭环。property/news/drama/aiservice/survey/alarm/music 六个模块的业务 CRUD 列表页已接入 mock 工厂（服务端分页 + 关键字/状态筛选），可直接在浏览器验证搜索 / 新增 / 编辑 / 删除 / 翻页；music 模块为全模块迁移模板（Genre 树形页除外）。未命中的请求仍走真实后端，方便渐进式接入。

### 生产部署约束

- `.env.production` 默认使用同源 `/api`；CI/CD 可覆盖为真实 HTTPS 地址。生产构建会拒绝 `example.com`、localhost、127.0.0.1 或空地址。
- 路由使用 History 模式，Web 服务器必须把不存在的前端路径回退到 `index.html`。Nginx 根路径部署示例：`try_files $uri $uri/ /index.html;`。
- 子路径部署时同时设置 Vite `base`，路由与登录恢复逻辑会使用 `import.meta.env.BASE_URL`。
- 发布新版本后建议保留上一版本静态资源一段时间；即使旧 Chunk 已删除，客户端也只会自动刷新一次，随后进入可恢复错误页，不会无限刷新。

**请求层能力**（`src/utils/request.ts`）：

- 自动拆 envelope `{ code, data, message }`，调用方直接拿 `data`
- 自动注入 `Authorization` 头 + `X-Request-Id`（后端日志联查）
- 错误归一化为 `ApiError`，含 `code` / `status` / `isNetworkError` / `isTimeout` / `isUnauthorized`
- 文件上传 `request.upload()` 支持 multipart + 进度回调
- 文件下载 `request.download()` 自动解析 `Content-Disposition` 文件名
- 全局 `ElMessage` 错误提示，调用方无需重复处理

### 单元测试

基于 **Vitest 4 + happy-dom + @vue/test-utils**，覆盖工具函数、Pinia store、关键组件：

```bash
npm run test           # 一次性跑全部用例
npm run test:watch     # 监听模式（开发期即时反馈）
npm run test:coverage  # v8 覆盖率报告（输出到 coverage/ 目录）
```

测试文件与源码同目录命名 `*.test.ts`，配置在 `vitest.config.ts`。已覆盖：

- `utils/stateMachine.test.ts` — FSM 多源转换 / requireComment / before-after 钩子 / shortestPath
- `utils/rolePermissions.test.ts` — 角色权限的 save/load/clear 与损坏数据兜底
- `utils/export.test.ts` — CSV BOM / 逗号 / 引号 / 换行转义、DOM 下载触发
- `utils/mock/handlers.test.ts` — Mock 路由匹配、用户增删改查、登录闭环、业务 CRUD 工厂（property/news/drama/aiservice/survey/alarm/music，含服务端分页）

### 端到端测试（E2E）

基于 **Playwright**（`@playwright/test`，真实浏览器 chromium），用例在 `e2e/` 目录，配置在 `playwright.config.ts`：

```bash
npm run test:e2e        # 全部 E2E（自动拉起 dev server，已运行则复用）
npx playwright show-report  # 查看 HTML 报告
```

约定：`e2e/auth.setup.ts` 预登录管理员并保存 storageState，业务用例直接以登录态启动；登录类用例自行清空 storageState。当前覆盖登录流程（成功/失败/访客权限/重定向回跳）、核心页面冒烟（工作台 / Schema 列表 / 富文本 / 图片裁剪，含 pageerror 与 console.error 收集断言）、菜单导航与 SchemaSearch 下拉回归、Schema CRUD 全旅程（搜索/重置/新增/编辑/删除）。CI（`.github/workflows/ci.yml`）在 push / PR 时自动跑 type-check / lint / test / build 与 E2E。
- `stores/user.test.ts` — `hasPermission` 三类语义（精确 / `*` / 前缀通配）+ login/logout/fetchProfile
- `components/ApprovalDialog.test.ts` — 转换查找、requireComment 校验、onConfirm 异步等待、cancel

- `views/business/**/*.test.ts` — 代表性 useCrud 列表页（Owner/Article/Channel/Series/List）初始化拉取与搜索触发

约定：纯函数工具用 `describe` + 多 `it`，组件测试用 `mount` + `attachTo: document.body`（Element Plus dialog teleport 到 body）。新增工具函数时强烈建议同步补单测，CI 阶段 `npm run test` 可一次性回归。

## License

MIT