@qilitt-mickey/vue3-temp-skill 1.0.12 → 1.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.0.12",
-  "description": "Vue 3 企业级中后台项目开发规范技能包 — 让 AI 编程助手按照团队规范生成代码，并自动审查代码质量",
+  "version": "1.1.2",
+  "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"
   },

package/references/api-check.md

@@ -1,45 +1,54 @@
 ---
 skill: api-check
-description: 前后端接口对接检查清单。在对接后端 API 或 AI 生成接口调用代码后，必须对照此清单验证接口契约的正确性，确保前后端数据流通畅。适用于接口联调、AI 生成 API 代码自检场景。
+description: 前后端接口对接检查清单。在对接后端 API 或 AI 生成接口调用代码后，必须对照此清单验证接口契约的正确性，确保前后端数据流通畅。适用于接口联调、AI 生成 API 代码自检、本地 Mock 场景。
 scope: project
-tags: [api, backend, integration, contract, http, request, response, debug, checklist]
+tags: [api, backend, integration, contract, http, request, response, debug, checklist, mock]
 ---
 
 # 前后端接口对接检查清单
 
-> **使用说明**：在对接后端 API 或 AI 生成接口调用代码后，逐项对照检查。确保前端调用方式与后端接口定义完全匹配，避免联调阶段反复返工。
+> **使用说明**：在对接后端 API 或 AI 生成接口调用代码后，逐项对照检查。确保前端调用方式与后端接口定义完全匹配，避免联调阶段反复返工。  
+> **权威来源**：以仓库代码为准——`types/global.d.ts`（`Result` / 分页）、`src/utils/http.ts`、`src/api/**`、`mock/**`、`src/hooks/useTableSearch.ts`。
 
 ## 一、接口基本信息核对
 
 ### 必须确认
 
-- [ ] **请求地址**：URL 路径与后端接口文档一致，注意前缀 `/api`。
-- [ ] **请求方法**：本项目统一使用 POST，确认后端没有要求 GET/PUT/DELETE。
+- [ ] **请求地址**：业务接口路径与后端文档一致；**禁止**把本地 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 的接口，确认请求头携带了 `Authorization`。
-- [ ] **加密要求**：敏感接口（登录、修改密码等）需要设置 `crypto: true`。
+- [ ] **认证方式**：拦截器自动注入请求头 `token`、`userCode`（不是 `Authorization: Bearer`）。
+- [ ] **加解密**：由环境变量 `VITE_ENCODE_SWITCH` 全局控制（见 `src/utils/http.ts`），**没有**单请求 `crypto: true` 开关；GET 默认不走加解密。
 
-### URL 规范
+### URL 约定（务必区分「真实联调」与「本地 Mock」）
 
 ```typescript
-// ✅ 项目标准 URL 格式
-"/api/system/user/list"      // 列表
-"/api/system/user/detail"    // 详情
-"/api/system/user/save"      // 保存（新增+编辑）
-"/api/system/user/delete"    // 删除
-"/api/system/user/export"    // 导出
-
-// ❌ 避免 RESTful 风格（本项目统一 POST）
-"/api/users"                 // 不对
-"/api/users/:id"             // 不对
+// ✅ 真实业务接口：环境变量 + 后端业务 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 前缀
+
 ```
 
+说明：
+
+1. **`/mock/...`、部分裸路径**：服务本地 `mock/*.ts`（`defineFakeRoute`），用于后端未就绪时的前端开发。
+2. **真实联调**：换成 `VITE_API_BASE_URL` + 后端真实 path；path 形态由后端文档决定，**不是**统一的 `/api` 前缀规范。
+3. **方法以接口文档为准**：允许 GET；不要为了“统一 POST”去改后端已定义的 GET 接口。也勿无依据地套路径参数式 REST（如 `/users/:id`），除非文档就是这样定义。
+
 ## 二、请求参数核对
 
 ### 必须确认
 
-- [ ] **参数位置**：本项目统一通过 `data` 传递（POST body），不是 `params`（query string）。
-- [ ] **字段名称**：与后端接口文档的字段名完全一致，注意大小写。
+- [ ] **参数位置**：POST → `data`（body）；GET → `params`（query）。与方法匹配即可。
+- [ ] **字段命名**：前后端统一 **驼峰 camelCase**（如 `userName`、`userCode`、`pageNo`），与接口文档一致。
 - [ ] **字段类型**：字符串/数字/布尔/数组/对象，与后端定义匹配。
 - [ ] **必填字段**：所有后端标记为必填的字段，前端必须传递。
 - [ ] **默认值**：后端有默认值的字段，前端不传时使用后端默认值。
@@ -50,104 +59,134 @@ tags: [api, backend, integration, contract, http, request, response, debug, chec
 | 后端 Java 类型 | 前端 TypeScript 类型 | 注意事项 |
 |---------------|---------------------|---------|
 | `String` | `string` | 空字符串 `""` 与 `null` 不同 |
-| `Integer` / `Long` | `number` | 注意 `Long` 精度问题（超过 `Number.MAX_SAFE_INTEGER` 需用 `string`） |
+| `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, any>` | 尽量避免，要求后端定义明确结构 |
+| `Map<String, Object>` | `Record<string, unknown>` | 尽量避免，要求后端定义明确结构 |
 
 ### 常见参数错误
 
 ```typescript
-// ❌ 错误：参数放在 params 中（query string）
-http.request("post", "/api/user/list", { params: { page: 1, pageSize: 10 } });
+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 } });
 
-// ✅ 正确：参数放在 data 中（request body）
-http.request("post", "/api/user/list", { data: { page: 1, pageSize: 10 } });
+// ✅ 正确：POST 业务参数放 data
+http.request("post", `${base}/console/user/list`, { data: { pageNo: 1, pageSize: 10 } });
 
-// ❌ 错误：字段名不匹配
-{ userName: "张三" }   // 后端期望 username
+// ✅ 正确：后端约定 GET 时使用 get + params（项目允许）
+http.request("get", `${base}/console/common/downLoadTemplate`, {
+  params: { fileName: "模板.xlsx" },
+  responseType: "blob",
+});
 
-// ✅ 正确：与后端字段名一致
+// ❌ 错误：写成全小写 username（本项目前后端约定驼峰）
 { username: "张三" }
 
+// ✅ 正确：驼峰命名，与后端字段一致
+{ userName: "张三", userCode: "zhangsan" }
+
 // ❌ 错误：金额使用 number（精度丢失）
-{ amount: 99999999.99 }  // 可能变成 99999999.989999999
+{ amount: 99999999.99 }
 
 // ✅ 正确：金额使用 string
 { amount: "99999999.99" }
+
+// ❌ 错误：分页字段名套用通用脚手架习惯
+{ page: 1, pageSize: 10 }   // 或 pageNum
+
+// ✅ 正确：本项目分页入参（见 QueryData / useTableSearch）
+{ pageNo: 1, pageSize: 10 }
 ```
 
 ## 三、响应数据核对
 
 ### 必须确认
 
-- [ ] **响应结构**：后端返回 `Result<T>` 包装结构 `{ success, data, message, code }`。
-- [ ] **数据类型**：`data` 字段的类型与前端声明的泛型 `T` 一致。
-- [ ] **列表结构**：列表接口返回 `{ list: T[], total: number }` 还是直接返回数组。
-- [ ] **分页字段**：确认分页字段名（`total` vs `totalCount`，`page` vs `pageNum`）。
-- [ ] **空值处理**：后端可能返回 `null` 的字段，前端类型要包含 `| null`。
+- [ ] **响应结构**：后端返回全局 `Result<T>`（`types/global.d.ts`），成功判断用 **`status === 200`**，文案用 **`statusText`**。
+- [ ] **数据类型**：`data` 字段的类型与前端声明的泛型 `T` 一致（`data` 可能为 `null`）。
+- [ ] **列表结构**：分页列表标准为 `{ content, totalCount, pageNo, pageSize, pageCount? }`，**不是** `{ list, total }`。
+- [ ] **空值处理**：后端可能返回 `null` 的字段，前端类型要包含 `| null`，展示用可选链。
 - [ ] **嵌套结构**：复杂对象的嵌套层级与后端返回一致。
 - [ ] **日期格式**：后端返回的日期字符串格式，前端展示时是否需要格式化。
 
-### 响应类型定义
+### 响应类型定义（与仓库一致）
 
 ```typescript
-// ✅ 正确：定义完整的响应类型
-interface UserListResult {
-  list: UserInfo[];
-  total: number;
+// 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;
-  phone: string | null;      // 可能为空
-  createTime: string;        // "2024-01-15 10:30:00"
-  department: {              // 嵌套对象
-    id: string;
-    name: string;
-  };
-  roles: string[];           // 角色编码数组
+  userName: string;          // 驼峰
+  userCode: string;
+  phone: string | null;
+  createTime: string;
 }
 
-// API 调用
-function getUserListApi(params: UserQuery) {
-  return http.request<Result<UserListResult>>(
-    "post", "/api/system/user/list", { data: params }
+function getUserListApi(data: CombinedQueryData) {
+  return http.request<Result<Data>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/console/user/list`,
+    { data },
   );
 }
 
 // 组件中使用
-const { data } = await getUserListApi(query);
-// data.list — 用户列表
-// data.total — 总条数
-// data.list[0].department.name — 部门名称
+const res = await getUserListApi(query);
+if (res.status === 200) {
+  const list = res.data?.content ?? [];
+  const total = res.data?.totalCount ?? 0;
+}
 ```
 
 ### 常见响应处理错误
 
 ```typescript
-// ❌ 错误：没有解构 Result 包装
-const list = await getUserListApi(params);  // 这是 Promise<Result<T>>
+// ❌ 错误：按 success / message / code 解构（本项目没有这些字段）
+const { success, message } = await getUserListApi(params);
 
-// ✅ 正确：解构 data 字段
-const { data } = await getUserListApi(params);
-const list = data.list;
-const total = data.total;
+// ✅ 正确：按 status / statusText / data 处理
+const res = await getUserListApi(params);
+if (res.status === 200) {
+  const list = res.data?.content ?? [];
+}
 
-// ❌ 错误：没有处理 null 值
-<span>{{ user.phone.length }}</span>  // phone 为 null 时报错
+// ❌ 错误：当成 { list, total }
+const list = res.data.list;
+const total = res.data.total;
 
-// ✅ 正确：可选链
-<span>{{ user.phone?.length ?? "-" }}</span>
+// ✅ 正确：content + totalCount（useTableSearch 已按此约定解析）
+const list = res.data?.content ?? [];
+const total = res.data?.totalCount ?? 0;
 
-// ❌ 错误：日期直接展示原始格式
-<span>{{ row.createTime }}</span>  // "2024-01-15T10:30:00.000+08:00"
+// ❌ 错误：没有处理 null
+<span>{{ user.phone.length }}</span>
 
-// ✅ 正确：格式化日期
-<span>{{ formatDate(row.createTime, "YYYY-MM-DD") }}</span>
+// ✅ 正确：可选链
+<span>{{ user.phone?.length ?? "-" }}</span>
 ```
 
 ## 四、特殊场景检查
@@ -157,16 +196,21 @@ const total = data.total;
 - [ ] `Content-Type` 设置为 `multipart/form-data`。
 - [ ] 使用 `FormData` 对象传递文件。
 - [ ] 文件大小限制与后端配置一致。
-- [ ] 上传进度有 UI 反馈。
+- [ ] 上传进度有 UI 反馈（如有）。
 
 ```typescript
-// ✅ 文件上传标准写法
-function uploadFileApi(file: File) {
+// ✅ 参考 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<UploadResult>>(
-    "post", "/api/common/upload",
-    { data: formData, headers: { "Content-Type": "multipart/form-data" } }
+  return http.request<Result<UploadFileResult>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}${path}`,
+    {
+      data: formData,
+      headers: { "Content-Type": "multipart/form-data" },
+    },
+    { repeatRequest: true },
   );
 }
 ```
@@ -174,36 +218,36 @@ function uploadFileApi(file: File) {
 ### 文件下载/导出
 
 - [ ] `responseType` 设置为 `"blob"`。
-- [ ] 使用 `blobDown()` 工具函数处理下载。
-- [ ] 文件名从响应头 `Content-Disposition` 获取或使用默认名。
+- [ ] 使用 `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);
-    blobDown(res, "导出数据.xlsx");
-  } catch {
-    ElMessage.error("导出失败");
+    const res = await exportApi(queryParams); // responseType: "blob"
+    blobDown(res.data, res.name || "导出数据.xlsx", res);
   } finally {
     loading.value = false;
   }
 }
 ```
 
-### 加密接口
+### 加解密接口
 
-- [ ] 登录、修改密码等敏感接口设置了 `crypto: true`。
-- [ ] 加密字段与后端约定一致（哪些字段需要加密）。
-- [ ] 加密请求的响应数据也需要解密处理。
+- [ ] 确认当前环境 `VITE_ENCODE_SWITCH`、`VITE_ENCODE_PUBKEY` / `VITE_ENCODE_PRIKEY` 已按对接要求配置。
+- [ ] 开关开启后，非 GET、非 FormData、非白名单接口由拦截器统一加解密；业务 API **不要**写不存在的 `crypto: true`。
+- [ ] 联调时注意：加密开启后控制台可能打印入参/回参明文，正式包需关闭调试输出。
 
 ### 分页接口
 
-- [ ] 前端分页参数名与后端一致（`page` vs `pageNum`，`pageSize` vs `size`）。
-- [ ] 首页页码从 1 开始（不是从 0）。
-- [ ] 空列表时 `total` 返回 0，`list` 返回空数组 `[]`（不是 `null`）。
+- [ ] 入参：`pageNo`（从 **1** 开始）、`pageSize`。
+- [ ] 出参：`content`、`totalCount`、`pageNo`、`pageSize`（可选 `pageCount`）。
+- [ ] 列表页优先用 `useTableSearch`（内部已按上述字段对接）。
+- [ ] 空列表时 `totalCount` 为 0，`content` 为空数组 `[]`（不是 `null`）。
 
 ## 五、联调常见问题排查
 
@@ -211,62 +255,77 @@ async function handleExport() {
 
 - 检查参数是否放在了 `data` 中（不是 `params`）。
 - 检查 `Content-Type` 是否为 `application/json`。
-- 检查字段名是否与后端 `@RequestBody` 对象的字段名一致（驼峰 vs 下划线）。
+- 检查字段是否为驼峰，且与后端 `@RequestBody` 字段名一致。
+- 若开启了加解密，确认前后端密钥与开关一致。
 
 ### 后端返回数据但前端取不到
 
-- 检查是否解构了 `Result` 包装：`const { data } = await api()`。
-- 检查 `data` 的结构是否与类型定义一致。
-- 检查数组字段是否直接返回了数组，还是包裹在 `{ list: [] }` 中。
+- 检查是否按 `Result` 处理：`status` / `data` / `statusText`。
+- 检查分页是否用了 `content` / `totalCount`（不是 `list` / `total`）。
+- 检查是否误把 Mock 路径当成了真实地址（或反过来）。
 
 ### 跨域问题
 
-- 开发环境：检查 `vite.config.ts` 的 `server.proxy` 配置。
-- 生产环境：确认 Nginx 反向代理配置正确。
-- 确认后端 CORS 配置允许前端域名。
+- 开发环境：检查 `build/server.ts` / Vite `server.proxy` 配置。
+- 生产环境：确认 Nginx 反向代理与 `VITE_API_BASE_URL` 一致。
+- 确认后端 CORS 允许前端域名。
 
-### Token 过期
+### Token 相关
 
-- 检查 http 拦截器是否处理了 `401` 状态码。
-- 401 时应自动跳转登录页或刷新 Token。
-- 刷新 Token 后重试失败的请求。
+- 请求头字段为 `token`、`userCode`（见 `src/utils/http.ts` 拦截器）。
+- 业务页按项目既有登录态逻辑处理失效场景，勿擅自改成 Bearer 方案。
 
 ## 六、接口 Mock 规范
 
-在后端接口未就绪时，前端可以先 Mock 数据开发：
+后端未就绪时，使用项目根目录 **`mock/`** + `vite-plugin-fake-server`（`build/plugins/ViteMockServe.ts`），**不要**在 `src/api/mock/` 手写假 Promise 充当标准方案。
 
 ```typescript
-// src/api/mock/user.ts
-import type { Result } from "@/utils/http/types";
-import type { UserListResult } from "../types/system";
-
-export function mockGetUserListApi(params: UserQuery): Promise<Result<UserListResult>> {
-  return Promise.resolve({
-    success: true,
-    data: {
-      list: [
-        { id: "1", username: "张三", phone: "13800138000", createTime: "2024-01-15 10:30:00", department: { id: "d1", name: "技术部" }, roles: ["admin"] },
-        { id: "2", username: "李四", phone: "13900139000", createTime: "2024-02-20 14:00:00", department: { id: "d2", name: "产品部" }, roles: ["editor"] },
-      ],
-      total: 2,
+// 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",
+      };
     },
-    message: "success",
-    code: 200,
-  });
-}
+  },
+]);
+```
+
+对应 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>` 响应结构。
-2. Mock 数据的字段名、类型必须与后端接口文档一致。
-3. 后端接口就绪后，只需替换 API 函数，组件代码不需要修改。
-4. Mock 文件放在 `src/api/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. **拿到后端接口文档后**：先核对 URL、方法、参数结构、响应结构。
-2. **编写 API 函数时**：声明完整类型，参数放 `data`，返回 `Result<T>`。
-3. **组件中调用时**：解构 `{ data }`，处理 loading/error，做好空值防护。
-4. **联调时**：打开浏览器 Network 面板，对比请求/响应与接口文档是否一致。
-5. **有问题时**：参照「联调常见问题排查」逐项检查。
+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/响应与文档；有问题按第五节排查。

package/references/base-code-dict.md

@@ -1,48 +1,49 @@
-# 基础代码（字典）
-
-规范基础代码（字典）的获取、缓存、映射与使用。在页面需要码表、枚举、下拉数据时参照。
-
-## 获取基础代码
-
-通过 `useApp().baseCodeGet(codeType)` 获取：
-
-```typescript
-import { useApp } from "@/hooks/useApp";
-
-const { baseCodeGet, filterValue } = useApp();
-const statusList = baseCodeGet("status");
-```
-
-## 特点
-
-- 首次调用会自动发起请求并缓存到 `BaseCode` Store。
-- 后续调用直接返回缓存数据。
-- 如需刷新缓存，在 `params` 中传 `refresh: true`。
-
-## 映射显示
-
-```typescript
-const label = filterValue(code, list, "code", "value");
-```
-
-- 将 `code` 映射为 `value`。
-- 默认字段名：`code` / `value`。
-
-## 在模板中使用
-
-```vue
-<template>
-  <span>{{ filterValue(row.status, statusList) }}</span>
-</template>
-```
-
-## Store 底层
-
-- `src/store/modules/baseCode.ts` 维护 `baseCodeCache`。
-- 接口：`getBaseCode({ codeType })`。
-
-## 关键约定
-
-1. 码表数据优先使用 `baseCodeGet`，避免重复请求。
-2. 列表中码表回写统一使用 `filterValue`。
-3. 不同模块相同码表使用相同 `codeType`。
+# 基础代码（字典）
+
+> 按本文件示例编写，复用 `useApp().baseCodeGet` / `filterValue` 等已有码表能力，勿另起一套字典请求与缓存。
+
+规范基础代码（字典）的获取、缓存、映射与使用。在页面需要码表、枚举、下拉数据时参照。
+
+## 获取基础代码
+
+通过 `useApp().baseCodeGet(codeType)` 获取：
+
+```typescript
+import { useApp } from "@/hooks/useApp";
+
+const { baseCodeGet, filterValue } = useApp();
+const statusList = baseCodeGet("status");
+```
+
+## 特点
+
+- 首次调用会自动发起请求并缓存到 `BaseCode` Store。
+- 后续调用直接返回缓存数据。
+- 如需刷新缓存，在 `params` 中传 `refresh: true`。
+
+## 映射显示
+
+```typescript
+const label = filterValue(code, list, "code", "value");
+```
+
+- 默认字段名：`code` / `value`。
+
+## 在模板中使用
+
+```vue
+<template>
+  <span>{{ filterValue(row.status, statusList) }}</span>
+</template>
+```
+
+## Store 底层
+
+- `src/store/modules/baseCode.ts` 维护 `baseCodeCache`。
+- 接口：`getBaseCode({ codeType })`。
+
+## 关键约定
+
+1. 码表数据优先使用 `baseCodeGet`，避免重复请求。
+2. 列表中码表回写统一使用 `filterValue`。
+3. 不同模块相同码表使用相同 `codeType`。

package/references/chart-echarts.md

@@ -0,0 +1,61 @@
+---
+skill: chart-echarts
+description: ECharts 图表与 ReEchart 封装。词云等扩展按项目依赖。
+scope: project
+tags: [echarts, ReEchart, chart, wordcloud]
+---
+
+# 图表（ECharts）
+
+> **选型**：`echarts` + 项目 `ReEchart`（有则复用）。勿改用 Chart.js / D3 / Plotly 等同类库。  
+> 大屏场景叠加 `data-screen`。
+
+## 依赖（缺则先装）
+
+| 包 | 版本 | 何时需要 |
+|---|---|---|
+| `echarts` | `6.1.0` | 图表必装 |
+| `echarts-wordcloud` | `2.1.0` | 仅词云 |
+
+```bash
+pnpm add echarts@6.1.0
+# 词云时追加：
+pnpm add echarts-wordcloud@2.1.0
+```
+
+## 必须复用
+
+| 资产 | 说明 |
+|------|------|
+| `ReEchart` | `src/components/ReEchart` |
+
+
+## 完整示例（ReEchart）
+
+```vue
+<script setup lang="ts">
+import type { EChartsOption } from "echarts";
+import { ReEchart } from "@/components/ReEchart";
+
+defineOptions({ name: "SalesChart" });
+
+const option = computed<EChartsOption>(() => ({
+  tooltip: { trigger: "axis" },
+  xAxis: { type: "category", data: ["1月", "2月", "3月"] },
+  yAxis: { type: "value" },
+  series: [{ type: "bar", data: [120, 200, 150], name: "销量" }],
+}));
+</script>
+
+<template>
+  <div class="h-400px w-full">
+    <ReEchart :option="option" />
+  </div>
+</template>
+```
+
+## 额外审查
+
+- [ ] 使用 echarts 而非其它图表库
+- [ ] 实例已销毁
+- [ ] 颜色优先 CSS 变量 / 主题色，避免大面积硬编码