lovife
5b877451eb
旧模板的 193 个文件整体删除，换成纯 Vue 3.5 + Naive UI 2.42 的树。
- 去掉 auto-import（组件与 API 全显式 import）、v-hasPerm（改 user.has('码')，全库 8 处）、
Stylelint；n-tag 的 type 统一过 utils/tag.ts 转换（Arco 色词直接透传会静默变灰）
- 图标改为构建期抽取：scripts/extract-pc-icons.py -> icons/icon-data.ts（37 个），
内网离线部署不会白屏
- 重搭后修掉 6 类"编译 / lint / typecheck 全绿、界面上就是坏的"故障：
① NGrid 的 cols 写成像素值（不是断点名 -> 永远只 1 列，工作台因此错乱）
② n-tab-pane 用 tab 属性（只渲染空注释节点，整排 tab 一个字都不显示）
③ 漏 import 被当未知自定义元素（样式整块丢） ④ .n-card__content 类名不存在
（高度链第一环失效，表格行在 DOM 里但屏幕上没有） ⑤ 填报单状态映射错位一格
⑥ 有标题的卡片没有上内边距（naive 的 padding-top 只给"内容区是长子"的卡片）
- 卡片式版面提成全局基线：styles/index.scss 的 xt-* 令牌 + .page-card / .toolbar /
.section-title，页面只引用、不再各写一套
- 品牌：改名「深学在线」，文字标换成几何标（方 = 卷宗 / 环 = 在线，不用文字字形）；
index.html 的页签图标从 404 的 /favicon.ico 改指真实存在的 /favicon.svg
59 lines
2.5 KiB
Markdown
59 lines
2.5 KiB
Markdown
---
|
||
name: project-api
|
||
description: 接口调用约定（axios 封装、apis/xt 模块、平台代管头、错误处理）。新增或修改接口调用时加载本技能。
|
||
---
|
||
|
||
# 接口调用
|
||
|
||
> ⚠️ **本仓库没有 Mock**：`mock/` 与 `vite-plugin-mock` 都已删除。
|
||
> `pnpm dev` 把 `/api` 代理到 `http://localhost:8080` → **后端不起着就没有数据**。
|
||
> （上一版这份 skill 以 Mock 为主线，那是 Gi 模板的写法，**已不适用**。）
|
||
|
||
## 契约
|
||
|
||
- 响应恒为 `{ code, msg, data }`；**业务错误也用 HTTP 200**，
|
||
只有 `401` / `403` / `429` / `5xx` 用**真实状态码**（别在业务码里找 `40301`）。
|
||
- `code === 0` 是成功。
|
||
|
||
## 封装（`src/utils/http.ts`）
|
||
|
||
它替业务代码做掉三件事，所以页面里几乎不出现 `code`：
|
||
|
||
1. 成功时**直接 resolve `data`** → `const vo = await getTask(id)` 拿到的就是数据；
|
||
2. 失败时**弹一次提示**并 reject 一个带 `bizCode` 的错误（要按码分支也能拿到）；
|
||
3. 自动带 `Authorization: Bearer <token>` 与平台代管头 `X-Tenant-Id`。
|
||
|
||
## 写一个接口模块（`src/apis/xt/<域>.ts`）
|
||
|
||
```ts
|
||
import type { PageResult } from '@/apis/types'
|
||
import http from '@/utils/http'
|
||
|
||
export interface XxxVO { id: number, name: string, status: number }
|
||
|
||
/** 状态映射与接口同处一个文件（别处也要用，改动只有一处） */
|
||
export const XXX_STATUS: Record<number, { text: string, color: string }> = {
|
||
0: { text: '停用', color: 'gray' },
|
||
1: { text: '正常', color: 'green' }
|
||
}
|
||
|
||
export function list(params: { page: number, pageSize: number, keyword?: string }) {
|
||
return http.get<PageResult<XxxVO>>('/xxx', { params })
|
||
}
|
||
```
|
||
|
||
- 新域就**新建一个文件**，并在 `src/apis/xt/index.ts` 里按需导出；
|
||
- 通用类型（`PageResult`、`BizError` 等）在 `src/apis/types.ts`；
|
||
- ⚠️ 展示映射里的 `color` 是**上一版 Arco 的色词**，给 `n-tag` 用之前必须过 `@/utils/tag.ts` 的 `tagOf()`。
|
||
|
||
## 平台代管（`X-Tenant-Id`）
|
||
|
||
平台运营的请求要带"当前学校"：值存在 `src/stores/acting-tenant.ts`，
|
||
由 `http.ts` 统一注入。**页面不要自己拼这个头**；不选学校时**不要发请求**（发了会把各租户数据混在一起）。
|
||
|
||
## 其它
|
||
|
||
- 下载类接口（导出包、整理结果）必须走 `fetch`/axios **取 blob**：接口要鉴权，
|
||
直接 `window.open` 或 `<a href>` 会 401，用户看到的是"下载没反应"。
|
||
- 签名 URL（预览图片等）**每次现取**，不要缓存进本地状态或存库（有有效期）。
|