# miko-frontend

**Repository Path**: oldauntu/miko-frontend

## Basic Information

- **Project Name**: miko-frontend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miko-admin · 前端

> **后端驱动的管理端**——菜单、路由、按钮权限、脱敏口径全部由后端下发，前端不做第二份权限真相。

![Vue](https://img.shields.io/badge/Vue-3.5-42b883)
![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6)
![Vite](https://img.shields.io/badge/Vite-6-646cff)
![AntDesignVue](https://img.shields.io/badge/Ant%20Design%20Vue-4.2-1677ff)
![Pages](https://img.shields.io/badge/pages-40-blue)

后端仓库：[**miko-backend**](https://gitee.com/oldauntu/miko-backend)

---

## 1. 这是什么

一套后台管理端的**前端骨架**：Vue 3 + TypeScript + Ant Design Vue + Vite + Pinia，
**40 个页面**覆盖后端全部业务域——权限管理、账号安全、工作流、代码生成、文件存储、
定时任务、监控、多租户、黑名单……

它不是一个"漂亮的后台模板"，而是**与后端严格对齐的一侧**：
后端 `docs/17-前端设计规范.md` 里定下的每条契约，在这里都有对应实现（并且很多时候是踩坑后才对齐的，见第 6 节）。

| | |
|---|---|
| 框架 | Vue 3.5（`<script setup>` + Composition API）+ TypeScript 5.7（`strict`） |
| UI | Ant Design Vue 4.2 + `@ant-design/icons-vue` |
| 构建 | Vite 6 + pnpm；`vue-tsc --noEmit` 作为类型门禁 |
| 状态 / 路由 | Pinia 2 + vue-router 4（动态路由由后端菜单驱动） |
| 页面 | **40 个** `.vue`，10 个 API 模块 |
| 生产依赖 | **只有 10 个**（见 `package.json`）——没有重型表单库、没有重型流程图库 |

---

## 2. 相较其他 Vue 后台模板，优势在哪

### 2.1 权限是数据，不是前端配置

大多数 Vue 后台模板（vue-vben-admin / soybean-admin 等）的做法是：
**路由表写在前端**，权限码写在前端常量里，后端只是"也校验一遍"。
两侧各维护一份真相，改一处忘一处就是"菜单能看见、点进去 404"或者"受限账号能看见删除按钮"。

本项目的契约是**只有一份真相，在后端**：

```
后端 sys_menu 表 ──┬─► GET /auth/routes    → 菜单树（M 目录 / C 页面）→ 前端 addRoute
                   └─► 登录响应 permissions → 按钮级权限点 → v-auth 指令
```

由此得到几个实际好处：

- **加一个页面不用改前端路由文件**。后端菜单里配 `component` 字符串，前端按
  `import.meta.glob('../views/**/*.vue')` 映射；没命中就渲染占位页而不是白屏。
- **页面级访问控制是"天然"的**：不在菜单里的页面**根本没注册路由**，深链会落到 404 兜底页——
  不需要在每个路由上重复写 `meta.roles`。
- **按钮级权限不需要前端维护常量**：`v-auth="'system:user:add'"` 直接比对登录态里的权限串。

### 2.2 动态路由的三个"反直觉但必要"的设计

这三条都是**实测踩出来的**，[`src/router/index.ts`](./src/router/index.ts) 里有完整注释：

| 设计 | 不这么做会怎样 |
|---|---|
| "路由已注册"由**路由模块自己**持有（`routesOwner` 记录"按哪个**令牌**注册的"），不信 store 的装载标记 | `login()` 会提前拉菜单并把标记置真，守卫若拿它判断，登录后**首次跳转就整段跳过注册**——侧边栏菜单齐全、点进去全是 404。而整页刷新反而正常，所以**只测直链会漏掉这个 bug** |
| 动态路由**扁平注册 + 绝对路径**（不做嵌套 `children`），再挂成布局壳的子路由 | "侧边栏层级"和"路由层级"不是一回事；嵌套写法会让深链、刷新、权限过滤各需要一套规则 |
| 404 兜底路由**不能**标 `meta.public` | 未登录访问 `/system/user` 时动态路由还没注册，该路径首先匹配到兜底路由；它算公开就直接放行，用户看到"页面不存在"而不是被送回登录页 |

再补两条容易忽略的：

- `routesOwner` 用**令牌值**而不是布尔值 → 重新登录 / 换账号拿到新令牌，天然触发重装，上一个账号的页面不会残留。
- 装载完动态路由后必须 `return to.fullPath` **重新解析一次**——此时 `to` 是在路由表尚不完整时解析出来的，
  不重解析会把 404 兜底页渲染出来。

### 2.3 传输加密与脱敏是"必须做对"的，不是可选项

后端对登录 / 改密 / 换绑这类接口是**强制**加密的（明文直接 400），所以前端的加密链路不是装饰：

- **WebCrypto 实现**（`src/utils/transport.ts`），每请求随机会话密钥，AES-256-GCM，AAD 绑 nonce；
- 公钥按 `keyId` 缓存，服务端轮换密钥后自动跟随；
- 响应是否加密**看 `x-transport-encrypted` 标记头**，不靠"猜形态"；
- 加密失败按明文发送，**由服务端裁决**（而不是前端自己降级）——否则等于给降级攻击留了口子；
- 二进制响应（下载 / 上传）与 `rawPassthrough` 端点**跳过信封判定**，
  OpenAPI 规范、健康探测这类非业务信封的响应不会被打成"业务失败"。

脱敏侧对应一条硬约定：**掩码值绝不回填编辑框**。
后端返回的联系方式永远是"按权限脱敏后的值"，把 `138****8000` 塞回表单再提交，等于把掩码存成真实号码——
所以编辑弹窗干脆不回填这几列，并在旁边写明原因。

### 2.4 类型安全加了一道 JS 精度防线

- `vue-tsc --noEmit` 是门禁（`strict` + `noUnusedLocals` + `noImplicitOverride`）。
- **所有 ID 一律 `string`**。后端雪花 ID 是 `i64`，以 JSON 数字出网会被浏览器读成 `Number`——
  `229385820128149504` 变成 `229385820128149500`，后续"删除 / 编辑"带着错 ID 回后端就是 404 或误改。
  后端已统一改成字符串出网，前端类型也一律按 `string` 写。

### 2.5 零重型依赖，包括流程设计器

- **生产依赖只有 10 个**。没有引入 `@vue-flow/core`、没有引入重型表单引擎。
- **流程设计器是自研的**（`src/views/system/flow/designer/`）：DOM + SVG 画布，
  只做"拖 / 连 / 选"三件事。最大的好处不是省依赖，而是——
  **画布模型就是后端 DSL**，`toDsl()` 直出后端能吃的 JSON，不需要中间转换层。
- **前端校验与后端同判据**：`graph.ts` 照抄后端 `miko-flow::validate` 的错误码与规则，
  连线规则在画的时候拦截。验证方式是拿 14 张故意画坏的图**同时喂给两边，逐一比对错误码集合**。
  缺 `approve_type` 时前端保持 `null` 而不替用户挑一个默认值——否则两边口径分叉，
  用户会看到"前端说没问题、后端说审批人为空"。

---

## 3. 已实现的页面

| 域 | 页面 |
|---|---|
| 通用 | 概览、登录、找回密码、个人中心、404、未映射占位页 |
| 权限域 | 用户、部门、岗位、角色、菜单、客户端 |
| 账号安全 | 密码策略、登录锁定、二次因子（MFA）、敏感操作、密钥管理 |
| 系统域 | 字典、参数设置、通知公告、接口文档、（消息中心） |
| 监控 | 在线用户、登录日志、操作日志、服务监控、缓存监控、慢 SQL |
| 框架能力 | 数据源（静态 + 动态）、异步任务、定时任务、文件存储、导入导出、Saga 编排 |
| 工作流 | 流程定义（含可视化设计器）、我的待办 / 我发起的 / 抄送我的 |
| 研发提效 | 代码生成器 |
| 扩展 | 多租户字段、黑名单 |

---

## 4. 架构

```
skills/           项目技能库（前端相关；完整技能集在后端仓库）
src/
├── api/            10 个模块，按后端业务域拆分（auth / system / security / monitor / flow ...）
├── router/
│   ├── index.ts        静态骨架 + 守卫 + 动态路由注册（routesOwner 机制）
│   └── dynamic.ts      菜单树 → 路由记录（component 字符串 → glob 映射，未命中给占位页）
├── stores/         Pinia：user（令牌 / 资料 / 权限）/ menu（菜单树）/ message(未读)
├── layouts/        BasicLayout（侧边栏 + 顶栏由菜单生成）
├── views/          40 个页面；flow/designer 是自研画布
├── directives/     v-auth 按钮级权限指令
├── utils/
│   ├── request.ts     axios 双拦截器：业务信封判定 / 401 处置 / trace_id 透出 / blob 下载
│   ├── transport.ts   传输加密（WebCrypto，请求封装 + 响应解密 + 公钥缓存）
│   └── ws.ts          WebSocket（ticket 换连接 / 25s 心跳 / 指数退避重连 / Toast 去重）
├── components/     SensitiveVerifyModal（敏感操作二次验证弹窗）
└── styles/         全局样式
```

### 请求链路

```
业务调用 api/*.ts
   └─► request.ts 请求拦截器 ── 强制加密路径？→ transport.ts 封装信封（随机会话密钥 + AAD 绑 nonce）
   └─► axios
   └─► request.ts 响应拦截器 ── 带了 x-transport-encrypted？→ 解密
                              ── rawPassthrough / blob？→ 原样返回，不判业务码
                              ── 否则判 code === 'GLOBAL.OK'，失败按错误码分流提示
                              ── 401：带令牌被拒 = 会话失效（清本地状态 + 带原因回登录页）
                                      无令牌 401 = 账号/口令错（把后端原话透给登录页）
```

> `401 ≠ 登录失败` 这条区分很关键：早期实现一律 `logout()`，结果既递归（登出接口本身也吃 401），
> 又因为整页跳转冲掉 toast 而**不给任何提示**。现在失效原因会通过 `/login?expired=...` 带到登录页用 Alert 展示
> ——整页跳转会把页面上的一切清掉，所以原因必须能随 URL 走。

---

## 5. 快速开始

```bash
# 0) 取代码
git clone https://gitee.com/oldauntu/miko-frontend.git
cd miko-frontend

# 1) 安装依赖（Node ≥ 20）
pnpm install

# 2) 起开发服务（:5173，/api 与 /ws 代理到后端 8080）
pnpm dev
```

> 后端需先在 `http://127.0.0.1:8080` 起着（见 [miko-backend](https://gitee.com/oldauntu/miko-backend)）。
> 代理配置在 [`vite.config.ts`](./vite.config.ts)。

```bash
pnpm typecheck    # vue-tsc --noEmit（类型门禁）
pnpm build        # vite build → dist/
pnpm preview      # 本地预览构建产物
```

生产形态下 `dist/` 由**后端静态托管**（配置里的 `server.static_dir`），
或由部署侧的 Nginx 反代（`deploy/nginx.conf`）。

### 环境变量

| 文件 | 变量 | 说明 |
|---|---|---|
| `.env.development` | `VITE_API_BASE_URL=/api` | 接口前缀，交给 Vite 代理 |
| | `VITE_ENABLE_ENCRYPT=true` | 接口传输加密开关 |
| `.env.production` | 同上 | 生产**强制**开启加密 |

> ⚠️ `VITE_ENABLE_ENCRYPT` **不要单方面关掉**：后端对登录 / 改密 / 换绑提交是强制加密的，
> 前端关掉等于这些接口直接 400。要抓包调试请两侧一起关
> （同时把后端 `MIKO_SECURITY__TRANSPORT__ENABLED=false` 与 `REQUIRED_PATHS` 清空）。

这两个文件**只含非敏感开关**，随仓维护；任何带本机地址或凭据的覆盖文件（`.env.local` 等）不进仓。

---

## 6. 工程约定（都是踩坑换来的）

写新页面之前值得先看的几条，完整记录见后端仓库 `docs/20-开发任务清单.md` 的 D 编号：

| 约定 | 原因 |
|---|---|
| **申请 ID 一律 `string`** | 雪花 ID 以 JSON 数字出网被 JS 截断，后续编辑 / 删除 404 或误改 |
| **下拉"不许新选"用选项级 `disabled`，不要 `filter`** | 过滤掉停用项会让已绑定的历史数据显示成裸雪花 ID（`a-select` 拿不到 label 就显示 value），运营看不懂也解不开 |
| **`v-auth` 必须挂在真实元素上** | 挂在 `a-popconfirm` 这类不渲染根元素的组件上会**静默失效**（受限账号仍能看到删除按钮） |
| **表单若校验在后端，不要依赖 `@finish`** | antd `Form` 的 `@finish` 只在有 `name` 字段时触发，纯布局表单永不派发，点按钮毫无反应 |
| **掩码值不回填编辑框** | 把 `138****8000` 提交回去 = 把掩码存成真实号码 |
| **改权限语义才踢人** | 权限串固化在令牌里，改 `perms` / `status` 需重新登录；只改名称 / 图标 / 排序刷新即生效 |
| **必须显式导入 antd 组件** | 否则被当成原生标签渲染：不报错、没样式、点了没反应，`vue-tsc` 也查不出来 |
| **改完前端要绕过浏览器缓存实测** | 页面加载的入口 chunk 在磁盘上可能已不存在，新按钮不出现，容易被误判成权限 bug |
| **二进制响应跳过信封判定** | 上传发原始字节不走 multipart；下载要按 RFC 5987 解析中文文件名 |

### 验证口径

后端项目对前端有两条**强制**要求，改前端时请照做：

1. **两条加载路径都要测**：整页加载与 SPA 菜单跳转的初始化路径不同，只测一种会漏 bug
   （上面"登录后点菜单全 404"就是只在整页刷新下测试才漏掉的）。
2. **前端校验要与后端同判据**：像流程图校验这种两侧都有的规则，验证方式是**同一批坏数据同时喂给两边，
   比对错误码集合**（比条数稳——同类问题在重复节点上会报多条）。

---

## 7. 已知问题

| 项 | 说明 |
|---|---|
| 首屏包偏大 | `ant-design-vue` **全量引入**，首屏三个 chunk gzip 合计约 **683 KB**（其中 antd 601 KB）。尚未做按需引入 / 组件级 tree-shaking |
| 构建有 chunk 体积警告 | 有一个懒加载 chunk 超过 1024 KB（`chunkSizeWarningLimit` 已调到 1024）。Scalar 接口文档相关 chunk 已按需加载，不影响首屏 |
| 类型为手写 | `src/api/*.ts` 的类型是手写的；`openapi-typescript` 已装但**尚未接入**（后端的 `openapi.json` 已就绪，接上即可自动生成） |
| 无 ESLint | `pnpm lint` 目前等价于 `vue-tsc --noEmit`，只做类型门禁；规则集尚未敲定 |
| 无前端单测 / E2E 配置 | 验证目前靠后端仓库里的端到端脚本 + 浏览器实测，仓内没有 `playwright.config.ts` |
| 大文件上传 | 后端未做分片上传，前端也没有分片 / 断点续传 |
| 国际化 | 未做（后端 `docs/18` §5 亦未开工） |

---

## 8. 项目技能库

[`skills/`](./skills/README.md) 放了两个前端专属技能——供 AI 助手（拷到工作区的 `.workbuddy/skills/`
即可自动加载）与新人取用：

| 技能 | 什么时候读 |
|---|---|
| [miko-frontend-dev](./skills/miko-frontend-dev/SKILL.md) | 改任何页面 / 路由 / 请求层 / 组件之前 |
| [miko-browser-testing](./skills/miko-browser-testing/SKILL.md) | 要用浏览器实测、复现交互问题、验收截图时 |

完整技能集（后端约定、安全域、基础设施、工作流、验证规程、仓库发布）在
[后端仓库](https://gitee.com/oldauntu/miko-backend) 工程根的 `skills/` 里。