feat(frontend): 管理端改用 Gi Admin Pro 框架 + 腾讯云主题
前端此前只有本地实现、从未入库，本次首次纳入版本管理。
框架切换
· 以 Gi Admin Pro（Vue3 + Vite + TS + Arco Design Vue + Pinia）为底
· 剥离 14 个演示页面目录 / 121 个文件（demo 28、file 20、form 19、system 18…）
· 依赖 dependencies 35 → 19，devDependencies 31 → 27
· 保留框架核心：layout、Gi* 组件库、hooks、权限指令、错误页、登录页
主题：腾讯云 / TDesign 官方色板
· 主色 #0052D9（腾讯蓝）、成功 #00A870、警告 #ED7B2F、危险 #E34D59
· 页面底色 #f3f3f3、文字 rgba(0,0,0,90/60/40/26%)
· 覆盖 Arco 底层色板 + 显式语义别名（primary/success/warning/danger/link/neutral）
· 三个改了不生效也不报错的坑已记入注释：
1) Arco 色值是逗号分隔 RGB 三元组，不是 #RRGGBB
2) Arco 把色板定义在 body 而非 :root，必须写 `:root, body`
3) setting.json 的 themeColor 会以内联样式写进 body，优先级高于样式表
对接后端（三处契约差异在 @/utils/http 统一适配）
· 响应信封 {code,msg,data} → {code,success,message,data}
· Token 头 token → Authorization: Bearer
· 分页 {list,total} → 补一份 records，list 原样保留
· 40101 → 登录页；登录密码 RSA 加密（公钥走 /auth/public-key，轮换无需重建前端）
· 路由：后端只下发菜单键，前端在本地路由表上过滤（有哪些页面归代码，谁能看归后端）
已实现页面（浏览器实测通过）
· 登录：RSA 加密 + 自适应验证码/租户码 + 账号锁定提示
· 工作台：真实数据（组织 6 个 / 角色 1 个 / 权限 25 项）
· 组织架构：三级树 + CRUD + 占用校验
· 租户管理：开通租户 + 初始密码只显示一次的强确认
· 待建页：未实现菜单显示所属里程碑
· 权限菜单：学校管理员看不到「租户管理」
视觉资产按腾讯云主题重做
· logo.svg（渐变圆角方 + 填）、favicon.svg（小尺寸做减法）、login-hero.svg（材料归集）
· 登录页点阵纹理走主题变量，换主色自动跟随
· 文案改为产品实际能力：自动改名 / 强制压缩 / 隐私保护
清理模板遗留（约 17MB + 三处外部依赖）
· 百度统计脚本（上报到 gi-demo 作者的统计账号）
· 用户菜单「项目地址」（跳转模板作者的 Gitee 仓库）
· 两份 8.8MB mp3、388KB favicon.ico、57KB 模板插画、未引用字体与 loading.gif
· 「个人中心」指向已删除的 /system/account（点了 404）
· 头部头像在无 avatarUrl 时渲染成裂图 → 改为姓名首字兜底
后端修复
· 新增 GET /auth/public-key（前端加密登录密码用）
· DataSeeder.ancestor_path 生成错误：子节点本该是 /16/17/ 却写成 /17/
该字段是「按院系统计」的索引，错了会漏人/多人且不报错 —— 改为从库里读父节点路径
· seedDemoOrgs 曾放在租户作用域外 + admin 早退分支之后，导致启动失败 / 永不执行
· 示范租户补一套三级组织树（1 学校 / 2 院系 / 3 班级），供界面演示
This commit is contained in:
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: project-api
|
||||
description: 在本模板项目中新增或修改 API 接口、类型定义与 vite-plugin-mock 模拟数据。涉及 getBaseApi、http、baseAPI、mock 目录、分页响应格式时使用。
|
||||
---
|
||||
|
||||
# API 与 Mock
|
||||
|
||||
## 接口层结构
|
||||
|
||||
每个业务模块一个文件，例如 `src/apis/system/user.ts`：
|
||||
|
||||
```ts
|
||||
import { getBaseApi } from '@/apis/base'
|
||||
import http from '@/utils/http'
|
||||
|
||||
export interface ListItem {
|
||||
id: string
|
||||
name: string
|
||||
status: Status
|
||||
createTime: string
|
||||
// ...
|
||||
}
|
||||
|
||||
/** 标准 CRUD */
|
||||
export const baseAPI = getBaseApi<ListItem>({ baseUrl: '/system/user' })
|
||||
|
||||
/** 非标准接口单独声明 */
|
||||
export function getDictDataList(params: { code: string } & Pagination) {
|
||||
return http.get<PageRes<DictDataItem[]>>('/system/dict/getDictDataList', params)
|
||||
}
|
||||
```
|
||||
|
||||
## getBaseApi 约定路径
|
||||
|
||||
| 方法 | HTTP | 路径 |
|
||||
|------|------|------|
|
||||
| getList | GET | `{baseUrl}/getList` |
|
||||
| getDetail | GET | `{baseUrl}/getDetail` |
|
||||
| add | POST | `{baseUrl}/add` |
|
||||
| update | POST | `{baseUrl}/update` |
|
||||
| delete | POST | `{baseUrl}/delete` |
|
||||
|
||||
列表参数：`{ page, size, ...filters }`
|
||||
删除参数：`{ ids: string[] }`
|
||||
|
||||
## 响应格式
|
||||
|
||||
```ts
|
||||
// 单条/布尔
|
||||
interface ApiRes<T> {
|
||||
code: number
|
||||
data: T
|
||||
message: string
|
||||
success: boolean
|
||||
}
|
||||
|
||||
// 分页列表 data 结构
|
||||
interface PageRes<T> {
|
||||
records: T
|
||||
total: number
|
||||
}
|
||||
```
|
||||
|
||||
`useTable` 同时兼容 `data` 为数组或 `PageRes` 两种形态。
|
||||
|
||||
## http 封装
|
||||
|
||||
- 实例：`src/utils/http.ts`，`baseURL` = `import.meta.env.VITE_API_PREFIX`
|
||||
- 开发环境 `.env.development`：`VITE_API_PREFIX = '/mock'`
|
||||
- Token：请求头 `token` 字段（`getToken()`）
|
||||
- 业务失败：`success === false` 时 Message/Notification 提示并 reject
|
||||
- 401：跳转 `/login`
|
||||
|
||||
```ts
|
||||
import http from '@/utils/http'
|
||||
|
||||
http.get<PageRes<Item[]>>('/path', { page: 1, size: 10 })
|
||||
http.post<boolean>('/path', { ids: ['1'] })
|
||||
```
|
||||
|
||||
## Mock 开发流程
|
||||
|
||||
### 1. 静态数据
|
||||
|
||||
在 `mock/_data/` 下维护 JSON/TS 数据，如 `system_dict.ts`。
|
||||
|
||||
### 2. 路由 Mock
|
||||
|
||||
在 `mock/system/`（或对应模块）新建文件：
|
||||
|
||||
```ts
|
||||
import { defineMock } from '../_base'
|
||||
import { getBaseApi, getDelayTime, resultError, resultSuccess } from '../_utils'
|
||||
|
||||
export default defineMock([
|
||||
...getBaseApi({
|
||||
baseUrl: '/system/xxx',
|
||||
getListData: () => resultSuccess({ total: list.length, records: list }),
|
||||
getDetailData: (query) => {
|
||||
const obj = list.find((i) => i.id === query.id)
|
||||
return obj ? resultSuccess(obj) : resultError(null, '未找到', 400)
|
||||
}
|
||||
}),
|
||||
{
|
||||
url: '/system/xxx/customAction',
|
||||
method: 'get',
|
||||
timeout: getDelayTime(),
|
||||
response: ({ query }) => {
|
||||
// 筛选、分页后返回
|
||||
return resultSuccess({ total, records })
|
||||
}
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
### 3. 工具函数
|
||||
|
||||
| 函数 | 用途 |
|
||||
|------|------|
|
||||
| `resultSuccess(data)` | `{ code:200, success:true, data, message }` |
|
||||
| `resultError(data, message, code?)` | 失败响应 |
|
||||
| `getDelayTime()` | 50–300ms 随机延迟 |
|
||||
| `getBaseApi({ baseUrl, getListData, ... })` | 生成标准 CRUD mock |
|
||||
|
||||
`defineMock` 会自动给 url 加前缀 `/mock`，与 `VITE_API_PREFIX` 对应。
|
||||
|
||||
### 4. 注册
|
||||
|
||||
确保 mock 文件被 `mock/index` 或同级聚合引入（遵循现有 `mock/system/*.ts` 模式）。
|
||||
|
||||
## 新增模块检查清单
|
||||
|
||||
- [ ] `src/apis/{module}/{name}.ts`：类型 + `baseAPI` 或自定义方法
|
||||
- [ ] `mock/{module}/{name}.ts`：与接口路径一致
|
||||
- [ ] 列表 Mock 返回 `{ total, records }`
|
||||
- [ ] 字段类型与 `Status`、`Gender` 等全局类型对齐
|
||||
- [ ] 在页面通过 `useTable({ listAPI, deleteAPI })` 接入
|
||||
|
||||
## 自定义 listAPI 示例
|
||||
|
||||
```ts
|
||||
useTable({
|
||||
listAPI: (page) => getDictDataList({
|
||||
...page,
|
||||
code: dictCode.value,
|
||||
name: query.name || undefined,
|
||||
status: query.status === '' ? undefined : query.status
|
||||
}),
|
||||
immediate: false
|
||||
})
|
||||
```
|
||||
|
||||
`immediate: false` 用于依赖左侧选中项后再 `search()` 的场景。
|
||||
Reference in New Issue
Block a user