@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/advanced-ui.md

@@ -0,0 +1,302 @@
+---
+skill: advanced-ui
+description: 规范高级 UI 组件的使用与开发，包括选择器组件（下拉/树/级联）、高级表格（vxe-table）、高级表单、图表（ECharts）、工作流（BPMN）、树形表格等。在开发复杂交互组件时调用。
+scope: project
+tags: [vue3, select, tree, table, vxe-table, echarts, bpmn, cascader, form-advanced]
+---
+
+# 高级 UI 组件规范
+
+## 选择器组件
+
+### ReSelectQuery（下拉查询选择器）
+
+适用于需要搜索、分页、远程加载的下拉选择场景：
+
+```vue
+<script setup lang="ts">
+import { ReSelectQuery } from "@/components/ReSelectQuery";
+
+const value = ref("");
+
+// 远程搜索
+function remoteMethod(query: string) {
+  // 调用 API 获取选项列表
+}
+</script>
+
+<template>
+  <ReSelectQuery
+    v-model="value"
+    :api="getUserListApi"
+    label-key="name"
+    value-key="id"
+    placeholder="请选择用户"
+    :remote="true"
+    :remote-method="remoteMethod"
+  />
+</template>
+```
+
+### el-tree-select（树形下拉选择）
+
+适用于组织架构、分类选择等树形数据场景：
+
+```vue
+<template>
+  <el-tree-select
+    v-model="value"
+    :data="treeData"
+    :props="{ label: 'name', value: 'id', children: 'children' }"
+    check-strictly
+    :render-after-expand="false"
+    placeholder="请选择部门"
+  />
+</template>
+```
+
+### ReCascader（级联选择器）
+
+适用于省市区、多级分类等联动选择场景：
+
+```vue
+<template>
+  <ReCascader
+    v-model="value"
+    :api="getAreaListApi"
+    :props="{ label: 'name', value: 'code', children: 'children' }"
+    placeholder="请选择地区"
+  />
+</template>
+```
+
+### 选择器约定
+
+1. 简单下拉使用 `el-select`，需要搜索+分页用 `ReSelectQuery`。
+2. 树形数据选择使用 `el-tree-select`，不要用 `el-select` 嵌套 `el-tree`。
+3. 级联场景使用 `ReCascader`，支持异步加载子节点。
+4. 移动端选择使用 `RePopupPicker`（基于 Vant）。
+5. 选择器必须设置 `placeholder`，清除按钮默认开启。
+
+## 高级表格
+
+### ReTableBar（表格工具栏）
+
+```vue
+<ReTableBar>
+  <template #left>
+    <el-button type="primary" @click="handleAdd">新增</el-button>
+    <el-button type="danger" :disabled="!selected.length" @click="handleBatchDelete">
+      批量删除
+    </el-button>
+  </template>
+  <template #right>
+    <!-- 右侧默认包含：列配置、密度、全屏按钮 -->
+  </template>
+</ReTableBar>
+```
+
+### ReTableOperate（操作列按钮组）
+
+```vue
+<el-table-column label="操作" width="200" fixed="right">
+  <template #default="{ row }">
+    <ReTableOperate
+      :buttons="[
+        { label: '查看', type: 'primary', link: true, onClick: () => handleView(row) },
+        { label: '编辑', type: 'primary', link: true, onClick: () => handleEdit(row) },
+        {
+          label: '删除',
+          type: 'danger',
+          link: true,
+          confirm: { title: '确认删除？', message: `将删除「${row.name}」` },
+          onClick: () => handleDelete(row),
+        },
+      ]"
+      :max="3"
+    />
+  </template>
+</el-table-column>
+```
+
+### ReGrid（数据表格）
+
+```vue
+<ReGrid
+  v-loading="loading"
+  :data="content"
+  :pagination="pagination"
+  @page-change="handlePageChange"
+  @size-change="handleSizeChange"
+  @selection-change="handleSelectionChange"
+>
+  <el-table-column type="selection" width="55" />
+  <el-table-column prop="name" label="名称" sortable />
+  <el-table-column prop="createTime" label="创建时间" width="180" />
+  <el-table-column label="操作" width="200" fixed="right">
+    <!-- ... -->
+  </el-table-column>
+</ReGrid>
+```
+
+### vxe-table（高性能表格）
+
+当数据量超过 1000 行或需要复杂编辑（行内编辑、单元格合并）时使用 vxe-table：
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+
+const gridRef = ref();
+const tableData = ref([]);
+
+const columns = [
+  { type: "seq", width: 60 },
+  { field: "name", title: "名称", sortable: true },
+  { field: "status", title: "状态", formatter: (v) => (v ? "启用" : "禁用") },
+];
+</script>
+
+<template>
+  <vxe-grid
+    ref="gridRef"
+    :data="tableData"
+    :columns="columns"
+    :pager-config="{ total: 100 }"
+    :edit-config="{ trigger: 'click', mode: 'cell' }"
+  />
+</template>
+```
+
+## 树形表格
+
+### 数据转换
+
+使用 `handleTree` 工具函数将平铺数据转为树形结构：
+
+```typescript
+import { handleTree } from "@/utils/tree";
+
+const flatData = ref<FlatItem[]>([]);
+const treeData = computed(() =>
+  handleTree(flatData.value, "id", "parentId", "children")
+);
+```
+
+### 树形表格渲染
+
+```vue
+<ReGrid :data="treeData" :tree-props="{ children: 'children' }" row-key="id">
+  <el-table-column prop="name" label="名称" />
+  <el-table-column prop="code" label="编码" />
+</ReGrid>
+```
+
+### 树形连线展示
+
+使用 `ReTreeLine` 组件为树形表格添加视觉连线：
+
+```vue
+<template>
+  <ReTreeLine :data="treeData">
+    <template #default="{ row }">
+      <span>{{ row.name }}</span>
+    </template>
+  </ReTreeLine>
+</template>
+```
+
+## 高级表单组件
+
+### ReIconPicker（图标选择器）
+
+```vue
+<el-form-item label="菜单图标">
+  <ReIconPicker v-model="formData.icon" />
+</el-form-item>
+```
+
+### ReSegmented（分段控制器）
+
+```vue
+<ReSegmented
+  v-model="activeTab"
+  :options="[
+    { label: '基本信息', value: 'basic' },
+    { label: '详细配置', value: 'config' },
+    { label: '权限设置', value: 'permission' },
+  ]"
+/>
+```
+
+### ReCheckCard（多选卡片）
+
+```vue
+<ReCheckCard
+  v-model="selectedRoles"
+  :options="roleOptions"
+  multiple
+/>
+```
+
+## 图表 (ECharts)
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import * as echarts from "echarts";
+
+const chartRef = ref<HTMLDivElement>();
+let chartInstance: echarts.ECharts;
+
+onMounted(() => {
+  chartInstance = echarts.init(chartRef.value!);
+  chartInstance.setOption({
+    title: { text: "数据统计" },
+    tooltip: { trigger: "axis" },
+    xAxis: { type: "category", data: ["1月", "2月", "3月"] },
+    yAxis: { type: "value" },
+    series: [{ type: "bar", data: [120, 200, 150] }],
+  });
+});
+
+// 响应式：监听容器大小变化
+const resizeObserver = new ResizeObserver(() => chartInstance?.resize());
+onMounted(() => resizeObserver.observe(chartRef.value!));
+onUnmounted(() => {
+  resizeObserver.disconnect();
+  chartInstance?.dispose();
+});
+</script>
+
+<template>
+  <div ref="chartRef" style="width: 100%; height: 400px;" />
+</template>
+```
+
+### 图表约定
+
+1. 始终在 `onUnmounted` 中 `dispose()` 图表实例，防止内存泄漏。
+2. 使用 `ResizeObserver` 监听容器变化自动调整大小。
+3. 图表配置项抽取为独立变量或函数，不要内联在 `setOption` 中。
+4. 数据大屏场景使用 `ReFlicker` 组件实现闪烁效果。
+
+## 工作流
+
+### BPMN 流程设计器
+
+项目集成 `bpmn-js` 用于流程设计，使用方式参考 `src/views/workflow/` 下的示例页面。
+
+### jsplumb 关系图
+
+用于可视化连线配置场景（如审批流程配置），参考 `src/components/` 下的封装组件。
+
+## 常见反例
+
+- 大数据量表格使用 `el-table` 而不是 `vxe-table`（性能问题）。
+- 树形数据不使用 `handleTree` 转换，手动递归。
+- 图表实例不在组件卸载时销毁，导致内存泄漏。
+- 操作列超过 3 个按钮不使用 `ReTableOperate` 的 `max` 属性折叠。
+- 选择器不设置 `placeholder`。

package/references/api-check.md

@@ -0,0 +1,272 @@
+---
+skill: api-check
+description: 前后端接口对接检查清单。在对接后端 API 或 AI 生成接口调用代码后，必须对照此清单验证接口契约的正确性，确保前后端数据流通畅。适用于接口联调、AI 生成 API 代码自检场景。
+scope: project
+tags: [api, backend, integration, contract, http, request, response, debug, checklist]
+---
+
+# 前后端接口对接检查清单
+
+> **使用说明**：在对接后端 API 或 AI 生成接口调用代码后，逐项对照检查。确保前端调用方式与后端接口定义完全匹配，避免联调阶段反复返工。
+
+## 一、接口基本信息核对
+
+### 必须确认
+
+- [ ] **请求地址**：URL 路径与后端接口文档一致，注意前缀 `/api`。
+- [ ] **请求方法**：本项目统一使用 POST，确认后端没有要求 GET/PUT/DELETE。
+- [ ] **Content-Type**：默认 `application/json`，文件上传使用 `multipart/form-data`。
+- [ ] **认证方式**：需要 Token 的接口，确认请求头携带了 `Authorization`。
+- [ ] **加密要求**：敏感接口（登录、修改密码等）需要设置 `crypto: true`。
+
+### URL 规范
+
+```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"             // 不对
+```
+
+## 二、请求参数核对
+
+### 必须确认
+
+- [ ] **参数位置**：本项目统一通过 `data` 传递（POST body），不是 `params`（query string）。
+- [ ] **字段名称**：与后端接口文档的字段名完全一致，注意大小写。
+- [ ] **字段类型**：字符串/数字/布尔/数组/对象，与后端定义匹配。
+- [ ] **必填字段**：所有后端标记为必填的字段，前端必须传递。
+- [ ] **默认值**：后端有默认值的字段，前端不传时使用后端默认值。
+- [ ] **枚举值**：状态码、类型码等枚举值与后端定义一致。
+
+### 参数格式对照表
+
+| 后端 Java 类型 | 前端 TypeScript 类型 | 注意事项 |
+|---------------|---------------------|---------|
+| `String` | `string` | 空字符串 `""` 与 `null` 不同 |
+| `Integer` / `Long` | `number` | 注意 `Long` 精度问题（超过 `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>` | 尽量避免，要求后端定义明确结构 |
+
+### 常见参数错误
+
+```typescript
+// ❌ 错误：参数放在 params 中（query string）
+http.request("post", "/api/user/list", { params: { page: 1, pageSize: 10 } });
+
+// ✅ 正确：参数放在 data 中（request body）
+http.request("post", "/api/user/list", { data: { page: 1, pageSize: 10 } });
+
+// ❌ 错误：字段名不匹配
+{ userName: "张三" }   // 后端期望 username
+
+// ✅ 正确：与后端字段名一致
+{ username: "张三" }
+
+// ❌ 错误：金额使用 number（精度丢失）
+{ amount: 99999999.99 }  // 可能变成 99999999.989999999
+
+// ✅ 正确：金额使用 string
+{ amount: "99999999.99" }
+```
+
+## 三、响应数据核对
+
+### 必须确认
+
+- [ ] **响应结构**：后端返回 `Result<T>` 包装结构 `{ success, data, message, code }`。
+- [ ] **数据类型**：`data` 字段的类型与前端声明的泛型 `T` 一致。
+- [ ] **列表结构**：列表接口返回 `{ list: T[], total: number }` 还是直接返回数组。
+- [ ] **分页字段**：确认分页字段名（`total` vs `totalCount`，`page` vs `pageNum`）。
+- [ ] **空值处理**：后端可能返回 `null` 的字段，前端类型要包含 `| null`。
+- [ ] **嵌套结构**：复杂对象的嵌套层级与后端返回一致。
+- [ ] **日期格式**：后端返回的日期字符串格式，前端展示时是否需要格式化。
+
+### 响应类型定义
+
+```typescript
+// ✅ 正确：定义完整的响应类型
+interface UserListResult {
+  list: UserInfo[];
+  total: number;
+}
+
+interface UserInfo {
+  id: string;
+  username: string;
+  phone: string | null;      // 可能为空
+  createTime: string;        // "2024-01-15 10:30:00"
+  department: {              // 嵌套对象
+    id: string;
+    name: string;
+  };
+  roles: string[];           // 角色编码数组
+}
+
+// API 调用
+function getUserListApi(params: UserQuery) {
+  return http.request<Result<UserListResult>>(
+    "post", "/api/system/user/list", { data: params }
+  );
+}
+
+// 组件中使用
+const { data } = await getUserListApi(query);
+// data.list — 用户列表
+// data.total — 总条数
+// data.list[0].department.name — 部门名称
+```
+
+### 常见响应处理错误
+
+```typescript
+// ❌ 错误：没有解构 Result 包装
+const list = await getUserListApi(params);  // 这是 Promise<Result<T>>
+
+// ✅ 正确：解构 data 字段
+const { data } = await getUserListApi(params);
+const list = data.list;
+const total = data.total;
+
+// ❌ 错误：没有处理 null 值
+<span>{{ user.phone.length }}</span>  // phone 为 null 时报错
+
+// ✅ 正确：可选链
+<span>{{ user.phone?.length ?? "-" }}</span>
+
+// ❌ 错误：日期直接展示原始格式
+<span>{{ row.createTime }}</span>  // "2024-01-15T10:30:00.000+08:00"
+
+// ✅ 正确：格式化日期
+<span>{{ formatDate(row.createTime, "YYYY-MM-DD") }}</span>
+```
+
+## 四、特殊场景检查
+
+### 文件上传
+
+- [ ] `Content-Type` 设置为 `multipart/form-data`。
+- [ ] 使用 `FormData` 对象传递文件。
+- [ ] 文件大小限制与后端配置一致。
+- [ ] 上传进度有 UI 反馈。
+
+```typescript
+// ✅ 文件上传标准写法
+function uploadFileApi(file: File) {
+  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" } }
+  );
+}
+```
+
+### 文件下载/导出
+
+- [ ] `responseType` 设置为 `"blob"`。
+- [ ] 使用 `blobDown()` 工具函数处理下载。
+- [ ] 文件名从响应头 `Content-Disposition` 获取或使用默认名。
+- [ ] 下载过程有 Loading 状态。
+
+```typescript
+// ✅ 文件下载标准写法
+async function handleExport() {
+  loading.value = true;
+  try {
+    const res = await exportApi(queryParams);
+    blobDown(res, "导出数据.xlsx");
+  } catch {
+    ElMessage.error("导出失败");
+  } finally {
+    loading.value = false;
+  }
+}
+```
+
+### 加密接口
+
+- [ ] 登录、修改密码等敏感接口设置了 `crypto: true`。
+- [ ] 加密字段与后端约定一致（哪些字段需要加密）。
+- [ ] 加密请求的响应数据也需要解密处理。
+
+### 分页接口
+
+- [ ] 前端分页参数名与后端一致（`page` vs `pageNum`，`pageSize` vs `size`）。
+- [ ] 首页页码从 1 开始（不是从 0）。
+- [ ] 空列表时 `total` 返回 0，`list` 返回空数组 `[]`（不是 `null`）。
+
+## 五、联调常见问题排查
+
+### 请求发出去了但后端收不到参数
+
+- 检查参数是否放在了 `data` 中（不是 `params`）。
+- 检查 `Content-Type` 是否为 `application/json`。
+- 检查字段名是否与后端 `@RequestBody` 对象的字段名一致（驼峰 vs 下划线）。
+
+### 后端返回数据但前端取不到
+
+- 检查是否解构了 `Result` 包装：`const { data } = await api()`。
+- 检查 `data` 的结构是否与类型定义一致。
+- 检查数组字段是否直接返回了数组，还是包裹在 `{ list: [] }` 中。
+
+### 跨域问题
+
+- 开发环境：检查 `vite.config.ts` 的 `server.proxy` 配置。
+- 生产环境：确认 Nginx 反向代理配置正确。
+- 确认后端 CORS 配置允许前端域名。
+
+### Token 过期
+
+- 检查 http 拦截器是否处理了 `401` 状态码。
+- 401 时应自动跳转登录页或刷新 Token。
+- 刷新 Token 后重试失败的请求。
+
+## 六、接口 Mock 规范
+
+在后端接口未就绪时，前端可以先 Mock 数据开发：
+
+```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,
+    },
+    message: "success",
+    code: 200,
+  });
+}
+```
+
+### Mock 约定
+
+1. Mock 数据必须严格符合 `Result<T>` 响应结构。
+2. Mock 数据的字段名、类型必须与后端接口文档一致。
+3. 后端接口就绪后，只需替换 API 函数，组件代码不需要修改。
+4. Mock 文件放在 `src/api/mock/` 目录下，按模块对应。
+
+## 快速自检流程
+
+1. **拿到后端接口文档后**：先核对 URL、方法、参数结构、响应结构。
+2. **编写 API 函数时**：声明完整类型，参数放 `data`，返回 `Result<T>`。
+3. **组件中调用时**：解构 `{ data }`，处理 loading/error，做好空值防护。
+4. **联调时**：打开浏览器 Network 面板，对比请求/响应与接口文档是否一致。
+5. **有问题时**：参照「联调常见问题排查」逐项检查。

package/references/base-code-dict.md

@@ -0,0 +1,48 @@
+# 基础代码（字典）
+
+规范基础代码（字典）的获取、缓存、映射与使用。在页面需要码表、枚举、下拉数据时参照。
+
+## 获取基础代码
+
+通过 `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`。