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

package/references/code-quality.md

@@ -7,7 +7,22 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 
 # 代码质量审查清单
 
-> **使用说明**：在 AI 生成或修改代码后，逐项对照以下检查点。任何一项不通过，必须修正后再输出。此清单面向"小白"开发者，确保 AI 产出的代码能通过团队 Code Review。
+> **使用说明**：生成或修改代码后逐项对照。不通过必须修正后再输出。  
+> 须按 Skill 模块内示例与本清单审查。
+
+## 〇、项目选型（最高优先级）
+
+- [ ] 已加载 `core-kernel` + `project-inventory`
+- [ ] 复用已有 Re* / Hook / utils；未另起同能力实现
+- [ ] 选型表指定库未擅自替换；新依赖已标注待确认
+- [ ] 命中 addon 时已核对 `package.json`；缺失包已按第九节**精确版本**安装（或已展示命令并征得确认）
+- [ ] Vite 相关插件（FileViewer / vConsole / Vant resolver / Fake Server）版本与接线文件已核对
+- [ ] 未使用 `@latest` 或不带版本号安装选型表内的库
+- [ ] 列表方法名为 **`onSearch` / `reset`**（不是 handleSearch/handleReset）
+- [ ] HTTP 为 `import { http } from '@/utils/http'` + 全局 `Result<T>`
+- [ ] 业务路由未二次挂 Layout
+- [ ] 使用对应 `references/<模块>.md` 示例与约定写法
+
 
 ## 一、TypeScript 类型检查
 
@@ -49,7 +64,6 @@ function getListApi(params: ListQuery): Promise<Result<ListResult>> {
 
 - [ ] 使用 `<script setup lang="ts">`，不使用 Options API。
 - [ ] 使用 `defineOptions({ name: "ComponentName" })` 声明组件名。
-- [ ] `script` 标签第一行是 `import type { ... } from "./type"`。
 - [ ] Props 和 Emits 类型定义在同目录 `type.ts` 文件中。
 - [ ] 样式使用 `<style lang="scss" scoped>`。
 - [ ] 组件 class 名使用 `re-` 前缀（自定义组件）或有意义的业务前缀。
@@ -81,30 +95,44 @@ function increment() { count.value++; }
 ### 必须通过
 
 - [ ] API 调用封装在 `src/api/` 目录的函数中，不在组件中直接写 `http.request`。
-- [ ] 所有接口使用 POST 方法，参数通过 `data` 传递。
-- [ ] 接口函数命名符合 `[动作][模块]Api` 格式。
-- [ ] 接口参数和返回值有完整类型定义。
+- [ ] 请求方法与后端文档一致（**允许 GET / POST**）；POST 用 `data`，GET 用 `params`。
+- [ ] 真实接口 URL 使用 `import.meta.env.VITE_API_BASE_URL` 拼接；未硬编码域名。
+- [ ] 未把 `/mock/...` 或虚构的 `/api/...` 当成前后端标准前缀。
+- [ ] 返回类型为 `Result<T>`（`status` / `statusText` / `data`）；分页用 `content` / `totalCount` / `pageNo` / `pageSize`。
+- [ ] 字段命名为驼峰（如 `userName`），与后端一致；`Long` / `BigDecimal` 用 `string`。
 - [ ] 下载请求设置了 `responseType: "blob"`。
-- [ ] 敏感数据（密码、身份证号）使用了加密请求 `crypto: true`。
+- [ ] 加解密依赖环境变量 `VITE_ENCODE_SWITCH`（无单请求 `crypto: true`）。
 - [ ] 组件中 API 调用有 `try/finally` 或 `try/catch` 处理异常。
 
 ### 常见错误示例
 
 ```typescript
-// ❌ 错误：在组件中直接调用 http
+import { http } from "@/utils/http";
+
+// ❌ 错误：在组件中直接调用 http，且使用虚构 /api 前缀
 const res = await http.request("post", "/api/user/list", { data: params });
 
-// ✅ 正确：封装到 api/ 目录
-// src/api/user.ts
-export function getUserListApi(params: UserQuery) {
-  return http.request<Result<UserListResult>>("post", "/api/user/list", { data: params });
+// ✅ 正确：封装到 api/，真实地址走环境变量
+export function getUserListApi(data: CombinedQueryData) {
+  return http.request<Result<Data>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/console/user/list`,
+    { data },
+  );
 }
 
-// ❌ 错误：使用 GET 方法
-http.request("get", "/api/user/list", { params });
+// ❌ 错误：方法与参数位置错配（POST 却用 params）
+http.request("post", `${import.meta.env.VITE_API_BASE_URL}/console/user/list`, { params });
+
+// ✅ 正确：POST → data；后端约定 GET → params（项目允许）
+http.request("post", `${import.meta.env.VITE_API_BASE_URL}/console/user/list`, { data: params });
+http.request("get", `${import.meta.env.VITE_API_BASE_URL}/console/common/downLoadTemplate`, {
+  params: { fileName: name },
+  responseType: "blob",
+});
 
-// ✅ 正确：统一 POST
-http.request("post", "/api/user/list", { data: params });
+// ❌ 错误：不存在的单请求加密开关
+http.request("post", url, { data: params, crypto: true });
 ```
 
 ## 四、安全规范检查
@@ -175,6 +203,7 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 - [ ] 样式使用 `scoped`，不会污染全局。
 - [ ] 颜色使用 CSS 变量（`var(--el-color-primary)`），不硬编码。
 - [ ] 优先使用 UnoCSS 原子类（`flex-center`、`mb-4`）。
+- [ ] 业务图标优先 `<svg-icon name="..." />`（本地无冒号 / Iconify 含 `:`）；菜单 `meta.icon` 为 string；细则见 `icons`。
 - [ ] 不使用 `!important`，除非覆盖第三方组件样式且有注释说明。
 - [ ] 不使用深层嵌套选择器（不超过 3 层）。
 - [ ] 移动端不使用固定 `px` 宽度，使用 `rem` 或百分比。

package/references/core-kernel.md

@@ -0,0 +1,305 @@
+---
+skill: core-kernel
+description: 始终加载的架构内核。硬约束、应用壳、CRUD 积木、工程摘要、核心/附加资产分层。业务开发前必读；不因「改 Vite/入口」单独命中。
+scope: project
+tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
+---
+
+# 核心内核（core-kernel）
+
+> **始终加载。** 覆盖「中后台默认骨架」。  
+> Vite / 包管理 / 入口启动链 **不是**独立 Skill，仅在本文件做只读摘要。  
+> 完整库与组件清单见同目录 `project-inventory.md`（一并查阅）。  
+
+
+---
+
+## 一、硬约束（违反即不合格）
+
+| # | 约定 |
+|---|------|
+| 1 | HTTP 只用 `import { http } from '@/utils/http'`，禁止页面内直接 axios/fetch |
+| 2 | 响应类型用全局 **`Result<T>`**（`types/global.d.ts`）：常用 `status` / `statusText` / `data` |
+| 3 | 默认 **POST**，参数放 **`data`** |
+| 4 | 列表用 `useTableSearch`，方法名 **`onSearch` / `reset`** |
+| 5 | 业务路由模块 **禁止** 再次 `component: Layout` |
+| 6 | 页面权限 `meta.roles`；按钮 `v-auth` / `ReAuth` |
+| 7 | 环境只用 `import.meta.env.VITE_*`，禁止硬编码域名 |
+| 8 | i18n：`$t('中文key')`，key 即中文文案 |
+| 9 | 禁止用 `v-html` 渲染不可信内容 |
+| 10 | 新三方依赖必须用户确认；已有封装须复用，选型表指定库勿擅自替换 |
+| 11 | addon 缺失时按 `project-inventory` 第九节**精确版本**安装；禁止 `@latest` / 无版本号；Vite 插件与 `build/plugins/*` 成套核对 |
+
+---
+
+## 二、应用壳（架构整体）
+
+### 路由
+
+```typescript
+// src/router/modules/xxx.ts
+export default {
+  path: "/xxx",
+  redirect: "/xxx/list",
+  meta: { title: "客户管理", icon: "ep:user", rank: 10 }, // 图标约定见 references/icons.md
+  children: [
+    {
+      path: "/xxx/list",
+      name: "XxxList",
+      component: () => import("@/views/xxx/list/index.vue"),
+      meta: { title: "客户列表", roles: ["admin", "common"] },
+    },
+  ],
+} satisfies RouteConfigsTable;
+// ❌ 不要在业务模块根上再挂 Layout
+```
+
+### 权限
+
+```vue
+<el-button v-auth="['admin']">{{ $t('删除') }}</el-button>
+<ReAuth :value="['admin']"><!-- 区域 --></ReAuth>
+```
+
+### Store / 多标签 / 主题
+
+- 核心 Store：`user` / `app` / `setting` / `theme` / `lang` / `router` / `multiTags` / `baseCode`
+- 详情跳转写标签：`useDetail`（见 `detail-page`）
+- 主题：`useTheme` + `--vts-*` / `--vts-theme-*`（详见 `layout-theme`）
+
+---
+
+## 三、数据通道
+
+```typescript
+import { http } from "@/utils/http";
+
+/** 分页列表 — 可被 useTableSearch 作为 searchFn */
+export function getCustomerList(data: CustomerQuery, url: string) {
+  return http.request<Result<CustomerPage>>("post", url, { data });
+}
+
+/** 详情 */
+export function getCustomerDetail(data: { id: string }) {
+  return http.request<Result<Customer>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/console/customer/detail`,
+    { data },
+  );
+}
+```
+
+- 方法以后端为准，允许 GET/POST；POST→`data`，GET→`params`。细节见 `http-api` / `api-check`
+- 加解密由 `VITE_ENCODE_SWITCH` 全局控制（**无**单请求 `crypto: true`），细节见 `http-api`
+- 字典：`useApp().baseCodeGet` / `filterValue`，见 `base-code-dict`
+- 提示：`import { message } from '@/utils/message'`
+
+---
+
+## 四、CRUD 积木（核心组件 / Hook）
+
+### 核心 Hook
+
+| Hook | 用途 |
+|------|------|
+| `useApp` | headerHeight、字典、svgLoading 等 |
+| `useTableSearch` | 列表查询分页（`onSearch`/`reset`） |
+| `useDetail` | 详情跳转与参数 |
+| `useFormCheck` | 多表单校验聚合 |
+| `useTags` / `useTheme` | 标签 / 主题 |
+
+### 核心 Re*（默认应存在于模板）
+
+ReAuth、ReDialog、ReGrid、ReGridItem、RePagination、ReTableBar、ReTableOperate、ReHeaderPage、ReSvgIcon（图标细则见 `icons`）、ReText、ReLanguageSwitch、ReSegmented、ReSelectQuery、ReCascader、ReDatePicker、ReDateRangePicker、ReCollapsible
+
+> **弹窗写法**：`ReDialog` / `ReDialogResize` 完整示例见 `form-advanced`（关键词「弹窗」即命中），勿业务页直接裸写 `el-dialog`。
+
+### 列表黄金样板
+
+```vue
+<script setup lang="ts">
+import type { Customer, CustomerQuery } from "@/api/customer";
+import { getCustomerList } from "@/api/customer";
+import { ReGrid } from "@/components/ReGrid";
+import { ReGridItem } from "@/components/ReGridItem";
+import { RePagination } from "@/components/RePagination";
+import { ReTableBar } from "@/components/ReTableBar";
+import { ReTableOperate } from "@/components/ReTableOperate";
+import { useApp } from "@/hooks/useApp";
+import { useTableSearch } from "@/hooks/useTableSearch";
+import { message } from "@/utils/message";
+
+defineOptions({ name: "CustomerList" });
+
+const { headerHeight, svgLoading } = useApp();
+const formQuery = reactive<CustomerQuery>({ keyword: "", status: undefined });
+
+const {
+  content,
+  tableHeight,
+  paginationRef,
+  loading,
+  formRef,
+  multipleTableRef,
+  pagination,
+  onSearch,
+  tableData,
+  gridRef,
+  showCollapse,
+  collapsed,
+  collapsedToggle,
+  upBold,
+  downBold,
+  reset,
+} = useTableSearch(
+  formQuery,
+  getCustomerList,
+  `${import.meta.env.VITE_API_BASE_URL}/console/customer/list`,
+);
+
+const tableList = computed(() => tableData.value.tableList as Customer[]);
+
+onMounted(() => {
+  onSearch();
+});
+
+function handleDelete(row: Customer) {
+  message($t("删除成功"), { type: "success" });
+  onSearch();
+}
+</script>
+
+<template>
+  <div
+    ref="content"
+    :style="{ minHeight: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
+    class="bg-[var(--el-bg-color)] p-2"
+  >
+    <el-form ref="formRef" :model="formQuery" @keyup.enter="onSearch">
+      <ReGrid ref="gridRef" :collapsed="collapsed" @show-collapse="showCollapse = $event">
+        <ReGridItem :index="0">
+          <el-form-item :label="$t('关键词')" prop="keyword">
+            <el-input v-model="formQuery.keyword" clearable :placeholder="$t('请输入')" />
+          </el-form-item>
+        </ReGridItem>
+        <ReGridItem :index="1">
+          <el-form-item :label="$t('状态')" prop="status">
+            <el-select v-model="formQuery.status" clearable :placeholder="$t('请选择')">
+              <el-option :label="$t('启用')" :value="1" />
+              <el-option :label="$t('禁用')" :value="0" />
+            </el-select>
+          </el-form-item>
+        </ReGridItem>
+        <ReGridItem :index="99" :collapsed="false">
+          <el-form-item>
+            <el-button type="primary" :loading="loading" @click="onSearch">{{ $t("查询") }}</el-button>
+            <el-button @click="reset()">{{ $t("重置") }}</el-button>
+            <el-button
+              v-if="showCollapse"
+              text
+              type="primary"
+              @click="collapsedToggle"
+            >
+              {{ collapsed ? $t("展开") : $t("收起") }}
+              <component :is="collapsed ? downBold : upBold" class="ml-1" />
+            </el-button>
+          </el-form-item>
+        </ReGridItem>
+      </ReGrid>
+    </el-form>
+
+    <ReTableBar
+      :columns="[]"
+      @refresh="onSearch"
+    >
+      <template #buttons>
+        <el-button type="primary" v-auth="['admin']">{{ $t("新增") }}</el-button>
+      </template>
+    </ReTableBar>
+
+    <el-table
+      ref="multipleTableRef"
+      v-loading="loading"
+      :element-loading-svg="svgLoading"
+      :data="tableList"
+      :height="tableHeight"
+      border
+      row-key="id"
+    >
+      <el-table-column prop="code" :label="$t('编号')" min-width="120" />
+      <el-table-column prop="name" :label="$t('名称')" min-width="140" />
+      <el-table-column :label="$t('操作')" width="160" fixed="right">
+        <template #default="{ row }">
+          <ReTableOperate
+            :buttons="[
+              { label: $t('编辑'), onClick: () => {} },
+              { label: $t('删除'), type: 'danger', onClick: () => handleDelete(row) },
+            ]"
+          />
+        </template>
+      </el-table-column>
+    </el-table>
+
+    <RePagination
+      ref="paginationRef"
+      v-model:current-page="pagination.currentPage"
+      v-model:page-size="pagination.pageSize"
+      :total="pagination.total"
+      @change="onSearch"
+    />
+  </div>
+</template>
+```
+
+`useTableSearch(formQuery, searchFn, url)`：`searchFn` 签名为 `(query, url) => Promise<Result<T>>`，分页字段为 `pageNo` / `pageSize`，列表数据取 `data.content`，总数 `data.totalCount`。
+
+---
+
+## 五、资产分层（核心 vs 附加）
+
+### 附加 Hook（按功能模块加载，勿塞进每个 CRUD）
+
+| Hook | 模块 |
+|------|------|
+| `useWebSocket` | websocket-realtime |
+| `useWechat` | wechat-js / mobile-h5 |
+
+### 附加组件（示例）
+
+附件/预览、ECharts、富文本、验证码、码、图谱、工作流、移动选择器、反馈展示类等 → 见各专项模块与 `project-inventory.md`。
+
+### 附加 Utils
+
+`uploadManager` / `imageCompression` → file；`changeSummaryService` → data-compare；`websocket/**` / `wechat/**` / `vantRules` → 对应专项；`particles` / `particlesOptions` → **particles**；`motion` → feedback-ui / 登录页入场动画。
+
+---
+
+## 六、工程摘要（只读，非日常生成目标）
+
+| 项 | 说明 |
+|----|------|
+| 包管理 | pnpm；脚本 `dev` / `build` / `type-check` / `lint` |
+| 默认插件 | Vue/JSX、AutoImport、SVG、UnoCSS、Favicon、Mock(`VITE_USE_MOCK`)、Gzip、Visualizer、混淆、DevTools |
+| 去 console | `build/build.ts`：非 `VITE_DEBUGGER` 时 Terser `drop_console`（**无** vite-plugin-remove-console） |
+| 功能附属插件 | FileViewer → `file-management`；vConsole → `mobile-h5`；精确版本与 `pnpm` 命令见 `project-inventory` 第九节 |
+| addon 安装 | 裁剪项目缺依赖时：查 `package.json` → 按第九节精确版本征得确认后 `pnpm add` / `pnpm add -D` |
+
+除非用户明确要求改构建配置，否则生成业务代码时**不要**改 `vite.config.ts` / `build/**`。
+
+---
+
+## 七、环境变量（骨架）
+
+`VITE_TITLE` / `VITE_PUBLIC_PATH` / `VITE_USE_MOCK` / `VITE_API_BASE_URL` / `VITE_ENCODE_*` / `VITE_SSO` / `VITE_NO_CUS_LOGO` / `VITE_GZIP` / `VITE_VSUALIZER` / `VITE_BUNDLE_OBFUSCATOR` / `VITE_DEBUGGER`  
+
+附加：`VITE_WS_URL`、`VITE_VCONSOLE`（随专项模块）。
+
+---
+
+## 八、与其它模块的衔接
+
+- 写接口细节 → `http-api`
+- 完整 CRUD 变体、表单页 → `crud-pages`
+- 详情跳转 → `detail-page`
+- 主题布局深挖 → `layout-theme`
+- 选型对照与全量组件表 → `project-inventory.md`