@qilitt-mickey/vue3-temp-skill 1.1.11 → 1.1.13

package/references/api-check.md

@@ -1,331 +1,51 @@
 ---
 skill: api-check
-description: 前后端接口对接检查清单。在对接后端 API 或 AI 生成接口调用代码后，必须对照此清单验证接口契约的正确性，确保前后端数据流通畅。适用于接口联调、AI 生成 API 代码自检、本地 Mock 场景。
+description: 前后端接口联调核对清单。对接后端或生成 API 后对照契约；写法细则见 http-api。
 scope: project
-tags: [api, backend, integration, contract, http, request, response, debug, checklist, mock]
+tags: [api, backend, integration, contract, http, checklist, mock]
 ---
 
-# 前后端接口对接检查清单
+# 前后端接口对接检查
 
-> **使用说明**：在对接后端 API 或 AI 生成接口调用代码后，逐项对照检查。确保前端调用方式与后端接口定义完全匹配，避免联调阶段反复返工。  
-> **权威来源**：以仓库代码为准——`types/global.d.ts`（`Result` / 分页）、`src/utils/http.ts`、`src/api/**`、`mock/**`、`src/hooks/useTableSearch.ts`。
+写法与示例 → **`http-api`**。本文件只做联调核对。权威源：`types/global.d.ts`、`src/utils/http.ts`、`src/api/**`、`mock/**`、`useTableSearch`。
 
-## 一、接口基本信息核对
+## 基本信息
 
-### 必须确认
+- [ ] 业务 path 与后端文档一致；忌把 `/mock/...` 当生产约定
+- [ ] 真实 URL：`VITE_API_BASE_URL` + path；忌硬编码域名 / 虚构 `/api` 前缀
+- [ ] 方法跟文档（允许 GET/POST）；POST→`data`，GET→`params`
+- [ ] Content-Type：默认 JSON；上传 `multipart/form-data`
+- [ ] 认证头：`token` / `userCode`（拦截器注入）
+- [ ] 加解密：`VITE_ENCODE_SWITCH`；无 `crypto: true`；GET 默认不加解密
 
-- [ ] **请求地址**：业务接口路径与后端文档一致；**禁止**把本地 Mock 前缀（如 `/mock/...`）当成前后端约定。
-- [ ] **域名来源**：真实接口使用 `import.meta.env.VITE_API_BASE_URL` 拼接业务 path，禁止硬编码域名。
-- [ ] **请求方法**：与后端接口文档一致即可。**允许 GET / POST**（项目未禁止 GET）；常见业务写操作用 POST，查询/下载/签名等后端要求 GET 时用 GET。
-- [ ] **参数位置**：POST 业务体用 `data`；GET 查询串用 `params`。二者按方法匹配，不要混用错位置。
-- [ ] **Content-Type**：默认 `application/json`，文件上传使用 `multipart/form-data`。
-- [ ] **认证方式**：拦截器自动注入请求头 `token`、`userCode`（不是 `Authorization: Bearer`）。
-- [ ] **加解密**：由环境变量 `VITE_ENCODE_SWITCH` 全局控制（见 `src/utils/http.ts`），**没有**单请求 `crypto: true` 开关；GET 默认不走加解密。
+## 请求参数
 
-### URL 约定（务必区分「真实联调」与「本地 Mock」）
+- [ ] 驼峰字段与文档一致；必填已传
+- [ ] `Long` / `BigDecimal` → `string`；日期格式与后端约定一致
+- [ ] 分页入参：`pageNo`（从 1）/ `pageSize`
 
-```typescript
-// ✅ 真实业务接口：环境变量 + 后端业务 path（示例，path 以接口文档为准）
-`${import.meta.env.VITE_API_BASE_URL}/console/common/attachment/list`
-`${import.meta.env.VITE_API_BASE_URL}/baseCode/search?uuid=${buildUUID()}`
+## 响应
 
-// ✅ 本地 Fake Server（vite-plugin-fake-server，目录 mock/）
-// 仅开发 Mock 使用，不是前后端规范前缀
-"/mock/login"
-"/mock/console/customerPortrait/queryCustomerRelation"
-"/get-table-list"   // 部分 Fake Server 路径也可能不带 /mock 前缀
+- [ ] `Result<T>`：`status === 200` / `statusText` / `data`
+- [ ] 分页：`content` / `totalCount`（非 `list`/`total`）
+- [ ] 可空字段类型含 `| null`；展示用可选链
 
-```
+## 特殊场景
 
-说明：
+- [ ] 上传：`FormData` + `repeatRequest: true`（见 `http-api`）
+- [ ] 下载：`responseType: "blob"` + `blobDown`
+- [ ] 列表优先 `useTableSearch`；空列表 `content=[]`、`totalCount=0`
 
-1. **`/mock/...`、部分裸路径**：服务本地 `mock/*.ts`（`defineFakeRoute`），用于后端未就绪时的前端开发。
-2. **真实联调**：换成 `VITE_API_BASE_URL` + 后端真实 path；path 形态由后端文档决定，**不是**统一的 `/api` 前缀规范。
-3. **方法以接口文档为准**：允许 GET；不要为了“统一 POST”去改后端已定义的 GET 接口。也勿无依据地套路径参数式 REST（如 `/users/:id`），除非文档就是这样定义。
+## Mock
 
-## 二、请求参数核对
+- [ ] 用根目录 `mock/` + `vite-plugin-fake-server`；回包符合 `Result<T>`
+- [ ] 后端就绪后 API 改为真实 path，组件调用尽量不变
 
-### 必须确认
+## 联调排查（短）
 
-- [ ] **参数位置**：POST → `data`（body）；GET → `params`（query）。与方法匹配即可。
-- [ ] **字段命名**：前后端统一 **驼峰 camelCase**（如 `userName`、`userCode`、`pageNo`），与接口文档一致。
-- [ ] **字段类型**：字符串/数字/布尔/数组/对象，与后端定义匹配。
-- [ ] **必填字段**：所有后端标记为必填的字段，前端必须传递。
-- [ ] **默认值**：后端有默认值的字段，前端不传时使用后端默认值。
-- [ ] **枚举值**：状态码、类型码等枚举值与后端定义一致。
-
-### 参数格式对照表
-
-| 后端 Java 类型 | 前端 TypeScript 类型 | 注意事项 |
-|---------------|---------------------|---------|
-| `String` | `string` | 空字符串 `""` 与 `null` 不同 |
-| `Integer` | `number` | 普通整型可用 number |
-| `Long` | `string` | 超过 `Number.MAX_SAFE_INTEGER` 会丢精度，统一用 `string` |
-| `Boolean` | `boolean` | `0/1` 与 `true/false` 需确认后端用哪种 |
-| `BigDecimal` | `string` | 金额类字段必须用 `string` 避免精度丢失 |
-| `Date` / `LocalDateTime` | `string` | 确认格式：`yyyy-MM-dd` 还是 `yyyy-MM-dd HH:mm:ss` |
-| `List<T>` | `T[]` | 确认数组元素的类型 |
-| `Map<String, Object>` | `Record<string, unknown>` | 尽量避免，要求后端定义明确结构 |
-
-### 常见参数错误
-
-```typescript
-import { http } from "@/utils/http";
-
-const base = import.meta.env.VITE_API_BASE_URL;
-
-// ❌ 错误：POST 却把业务参数放在 params
-http.request("post", `${base}/console/user/list`, { params: { pageNo: 1, pageSize: 10 } });
-
-// ✅ 正确：POST 业务参数放 data
-http.request("post", `${base}/console/user/list`, { data: { pageNo: 1, pageSize: 10 } });
-
-// ✅ 正确：后端约定 GET 时使用 get + params（项目允许）
-http.request("get", `${base}/console/common/downLoadTemplate`, {
-  params: { fileName: "模板.xlsx" },
-  responseType: "blob",
-});
-
-// ❌ 错误：写成全小写 username（本项目前后端约定驼峰）
-{ username: "张三" }
-
-// ✅ 正确：驼峰命名，与后端字段一致
-{ userName: "张三", userCode: "zhangsan" }
-
-// ❌ 错误：金额使用 number（精度丢失）
-{ amount: 99999999.99 }
-
-// ✅ 正确：金额使用 string
-{ amount: "99999999.99" }
-
-// ❌ 错误：分页字段名套用通用脚手架习惯
-{ page: 1, pageSize: 10 }   // 或 pageNum
-
-// ✅ 正确：本项目分页入参（见 QueryData / useTableSearch）
-{ pageNo: 1, pageSize: 10 }
-```
-
-## 三、响应数据核对
-
-### 必须确认
-
-- [ ] **响应结构**：后端返回全局 `Result<T>`（`types/global.d.ts`），成功判断用 **`status === 200`**，文案用 **`statusText`**。
-- [ ] **数据类型**：`data` 字段的类型与前端声明的泛型 `T` 一致（`data` 可能为 `null`）。
-- [ ] **列表结构**：分页列表标准为 `{ content, totalCount, pageNo, pageSize, pageCount? }`，**不是** `{ list, total }`。
-- [ ] **空值处理**：后端可能返回 `null` 的字段，前端类型要包含 `| null`，展示用可选链。
-- [ ] **嵌套结构**：复杂对象的嵌套层级与后端返回一致。
-- [ ] **日期格式**：后端返回的日期字符串格式，前端展示时是否需要格式化。
-
-### 响应类型定义（与仓库一致）
-
-```typescript
-// types/global.d.ts（权威定义，勿另造 success/code/message 结构）
-interface Result<T = unknown> {
-  att?: unknown[];
-  data?: T | null;
-  exceptionName?: null;
-  status?: number;
-  statusText?: string;
-  name?: string; // blob 下载等场景可能附带文件名
-}
-
-interface Data {
-  pageNo?: number;
-  pageSize?: number;
-  pageCount?: number;
-  totalCount?: number;
-  content?: Content[];
-}
-
-// 业务示例
-interface UserInfo {
-  id: string;
-  userName: string;          // 驼峰
-  userCode: string;
-  phone: string | null;
-  createTime: string;
-}
-
-function getUserListApi(data: CombinedQueryData) {
-  return http.request<Result<Data>>(
-    "post",
-    `${import.meta.env.VITE_API_BASE_URL}/console/user/list`,
-    { data },
-  );
-}
-
-// 组件中使用
-const res = await getUserListApi(query);
-if (res.status === 200) {
-  const list = res.data?.content ?? [];
-  const total = res.data?.totalCount ?? 0;
-}
-```
-
-### 常见响应处理错误
-
-```typescript
-// ❌ 错误：按 success / message / code 解构（本项目没有这些字段）
-const { success, message } = await getUserListApi(params);
-
-// ✅ 正确：按 status / statusText / data 处理
-const res = await getUserListApi(params);
-if (res.status === 200) {
-  const list = res.data?.content ?? [];
-}
-
-// ❌ 错误：当成 { list, total }
-const list = res.data.list;
-const total = res.data.total;
-
-// ✅ 正确：content + totalCount（useTableSearch 已按此约定解析）
-const list = res.data?.content ?? [];
-const total = res.data?.totalCount ?? 0;
-
-// ❌ 错误：没有处理 null
-<span>{{ user.phone.length }}</span>
-
-// ✅ 正确：可选链
-<span>{{ user.phone?.length ?? "-" }}</span>
-```
-
-## 四、特殊场景检查
-
-### 文件上传
-
-- [ ] `Content-Type` 设置为 `multipart/form-data`。
-- [ ] 使用 `FormData` 对象传递文件。
-- [ ] 文件大小限制与后端配置一致。
-- [ ] 上传进度有 UI 反馈（如有）。
-
-```typescript
-// ✅ 参考 src/api/common/index.ts getUploadUrl
-function uploadFileApi(file: File, path = "/documentInfo/uploadFile") {
-  const formData = new FormData();
-  formData.append("file", file);
-  return http.request<Result<UploadFileResult>>(
-    "post",
-    `${import.meta.env.VITE_API_BASE_URL}${path}`,
-    {
-      data: formData,
-      headers: { "Content-Type": "multipart/form-data" },
-    },
-    { repeatRequest: true },
-  );
-}
-```
-
-### 文件下载/导出
-
-- [ ] `responseType` 设置为 `"blob"`。
-- [ ] 使用 `blobDown(data, name, response)`（`src/utils/utils.ts`）处理下载。
-- [ ] 文件名优先从响应头 `Content-Disposition` 解析；http 封装对 Blob 可能返回 `{ data, name }`。
-- [ ] 下载过程有 Loading 状态。
-
-```typescript
-import { blobDown } from "@/utils/utils";
-
-async function handleExport() {
-  loading.value = true;
-  try {
-    const res = await exportApi(queryParams); // responseType: "blob"
-    blobDown(res.data, res.name || "导出数据.xlsx", res);
-  } finally {
-    loading.value = false;
-  }
-}
-```
-
-### 加解密接口
-
-- [ ] 确认当前环境 `VITE_ENCODE_SWITCH`、`VITE_ENCODE_PUBKEY` / `VITE_ENCODE_PRIKEY` 已按对接要求配置。
-- [ ] 开关开启后，非 GET、非 FormData、非白名单接口由拦截器统一加解密；业务 API **不要**写不存在的 `crypto: true`。
-- [ ] 联调时注意：加密开启后控制台可能打印入参/回参明文，正式包需关闭调试输出。
-
-### 分页接口
-
-- [ ] 入参：`pageNo`（从 **1** 开始）、`pageSize`。
-- [ ] 出参：`content`、`totalCount`、`pageNo`、`pageSize`（可选 `pageCount`）。
-- [ ] 列表页优先用 `useTableSearch`（内部已按上述字段对接）。
-- [ ] 空列表时 `totalCount` 为 0，`content` 为空数组 `[]`（不是 `null`）。
-
-## 五、联调常见问题排查
-
-### 请求发出去了但后端收不到参数
-
-- 检查参数是否放在了 `data` 中（不是 `params`）。
-- 检查 `Content-Type` 是否为 `application/json`。
-- 检查字段是否为驼峰，且与后端 `@RequestBody` 字段名一致。
-- 若开启了加解密，确认前后端密钥与开关一致。
-
-### 后端返回数据但前端取不到
-
-- 检查是否按 `Result` 处理：`status` / `data` / `statusText`。
-- 检查分页是否用了 `content` / `totalCount`（不是 `list` / `total`）。
-- 检查是否误把 Mock 路径当成了真实地址（或反过来）。
-
-### 跨域问题
-
-- 开发环境：检查 `build/server.ts` / Vite `server.proxy` 配置。
-- 生产环境：确认 Nginx 反向代理与 `VITE_API_BASE_URL` 一致。
-- 确认后端 CORS 允许前端域名。
-
-### Token 相关
-
-- 请求头字段为 `token`、`userCode`（见 `src/utils/http.ts` 拦截器）。
-- 业务页按项目既有登录态逻辑处理失效场景，勿擅自改成 Bearer 方案。
-
-## 六、接口 Mock 规范
-
-后端未就绪时，使用项目根目录 **`mock/`** + `vite-plugin-fake-server`（`build/plugins/ViteMockServe.ts`），**不要**在 `src/api/mock/` 手写假 Promise 充当标准方案。
-
-```typescript
-// mock/login.ts（权威写法）
-import { defineFakeRoute } from "vite-plugin-fake-server/client";
-
-export default defineFakeRoute([
-  {
-    url: "/mock/login",
-    method: "post",
-    response: ({ body }) => {
-      // POST：从 body 取入参；GET：从 query 取入参
-      return {
-        att: [],
-        data: {
-          accessToken: "demo-token",
-          userCode: body.userCode,
-          userName: "系统默认管理员", // 驼峰
-        },
-        exceptionName: null,
-        status: 200,
-        statusText: "Success",
-      };
-    },
-  },
-]);
-```
-
-对应 API：
-
-```typescript
-// src/api/login/index.ts
-export const getLogin = (data: LoginParams) => {
-  return http.request<Result<UserData>>("post", "/mock/login", { data });
-};
-```
-
-### Mock 约定
-
-1. Mock 回包必须符合 `Result<T>`：`status` / `statusText` / `data`（不是 `success` / `code` / `message`）。
-2. 字段名、类型与真实后端契约一致（驼峰；分页用 `content` / `totalCount`）。
-3. API 函数路径可先指向 Mock；后端就绪后改为 `VITE_API_BASE_URL` + 真实 path，组件调用尽量不变。
-4. Mock 文件放在项目根 `mock/`，按模块拆分（如 `mock/login.ts`、`mock/table.ts`）。
-5. 开关与插件：`VITE_USE_MOCK` + `ViteFakeServerPlugin`（`include: 'mock'`）。
-
-## 快速自检流程
-
-1. **拿到后端接口文档后**：核对真实 path、方法、参数/响应结构；确认不是 Mock 专用路径。
-2. **编写 API 函数时**：`import { http } from "@/utils/http"`；参数放 `data`；返回 `Result<T>`；URL 用 `VITE_API_BASE_URL`（或明确的 Mock 路径）。
-3. **字段与分页**：驼峰命名；列表用 `pageNo`/`pageSize` → `content`/`totalCount`。
-4. **组件中调用时**：判断 `status === 200`，取 `data`，做好空值防护；列表优先 `useTableSearch`。
-5. **联调时**：打开 Network，对比请求 URL/Body/响应与文档；有问题按第五节排查。
+| 现象 | 检查 |
+|------|------|
+| 后端收不到参 | `data` vs `params`；Content-Type；驼峰；加解密密钥 |
+| 前端取不到数 | `status`/`data`；分页字段名；Mock vs 真实 URL |
+| 跨域 | Vite proxy / Nginx / CORS |
+| Token | 请求头是否为 `token`、`userCode` |