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

package/references/code-quality.md

@@ -1,319 +1,105 @@
 ---
 skill: code-quality
-description: 生成后强制质量闸门。写完/改完 Vue/TS 代码后必须重读本清单、对照落盘文件自查、必跑 lint:fix 与 type-check，并在最终回复输出「代码质量审查」结果块。仅把本模块列入命中模块不算完成。
+description: 生成后强制质量闸门。写完/改完代码后重读本清单、对照落盘文件、必跑 lint:fix 与 type-check，最终回复含「代码质量审查」结果块。
 scope: project
 tags: [code-review, quality, checklist, lint, typescript, vue3, security, performance, gate]
 ---
 
-# 代码质量审查清单（生成后强制闸门）
+# 代码质量审查（生成后闸门）
 
-> **何时执行**：任意 `/vue3-temp-skill` 任务在**文件已写入或修改之后**，结束对话前必须执行本闸门。  
-> **不算完成**：只在「命中模块」里写 `code-quality`；或只跑了 type-check / 未跑 `lint:fix`；或未对照本清单；或最终回复无「代码质量审查」结果块。  
-> **须按** Skill 功能模块示例 + 本清单审查；不通过必须修正后再收工。
+写完/改完 Vue/TS 后执行。最终回复须含结果块；只把本模块写入「命中模块」不算完成。
 
-## 强制执行协议（AI 必须按序做）
+## 协议（按序）
 
-1. **重读本文件**（生成后再读，禁止仅凭开场记忆勾选）。
-2. **列出本轮改动文件路径**，逐文件对照下方清单相关项。
-3. **执行命令**（业务项目根目录，**两项均必跑，缺一不可**）：
-   - 必跑：`pnpm lint:fix`（自动修复可修问题；若无该脚本则用 `pnpm lint`，再无则 `pnpm exec eslint . --fix`）
-   - 必跑：`pnpm type-check`（若无该脚本则用 `pnpm exec vue-tsc --noEmit`）
-   - 顺序建议：先 `lint:fix`，再 `type-check`（lint 可能改写文件，须以最终落盘结果过类型检查）
-4. **失败则修代码 → 重跑上述两条命令**，直到全部通过或写出明确阻塞（缺依赖、环境等）。`lint:fix` 后仍有无法自动修复的报错，必须手改后再跑，禁止跳过。
-5. **在最终回复追加结果块**（缺此块 = 未完成）：
+1. 重读本文件
+2. 列出本轮改动路径，对照下方清单
+3. 业务项目根目录必跑：`pnpm lint:fix` → `pnpm type-check`（无脚本则 `pnpm lint` / `pnpm exec eslint . --fix`；`pnpm exec vue-tsc --noEmit`）
+4. 失败则修代码并重跑，直至通过或写明阻塞
+5. 最终回复追加：
 
 ```markdown
 ## 代码质量审查
 - 闸门：已执行 code-quality（生成后）
 - 改动文件：`path/a`、`path/b`、…
-- 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表布局 ✅或N/A / 风格 ✅
+- 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表→详情 ✅或N/A / 列表布局 ✅或N/A / 风格 ✅
 - 已修正：…（无则写「无」）
-- 命令：`pnpm lint:fix` → 通过 | 失败：…；`pnpm type-check` → 通过 | 失败：…
+- 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
 ```
 
----
-
-## 〇、项目选型（最高优先级）
+## 选型与硬约束
 
-- [ ] 已加载 `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>`
+- [ ] 已读 `core-kernel`；addon/缺依赖时已读 `project-inventory`
+- [ ] 复用已有 Re* / Hook / utils；选型库未擅自替换；新依赖已待确认
+- [ ] addon 缺包按 inventory 第九节精确版本（禁止 `@latest`）
+- [ ] 列表方法名 `onSearch` / `reset`；HTTP 用 `@/utils/http` + `Result<T>`
 - [ ] 业务路由未二次挂 Layout
-- [ ] 使用对应 `references/<模块>.md` 示例与约定写法
-- [ ] **查询列表布局**：`el-card ref="content"` + 固定 `height`（含 `headerHeight`）；查询区 `bg-bg_color p-5` + `ReGrid` `gap`/`cols`；表格绑 `tableHeight`；分页在 `ReTableBar` 内；卡片内查询条件以外的模块包根元素绑 `otherRef`
-
-
-## 一、TypeScript 类型检查
-
-### 必须通过
-
-- [ ] 所有 `props` 有明确的类型定义，不使用 `any`。
-- [ ] 所有 API 返回值声明了泛型类型 `Result<T>`。
-- [ ] `ref()` 和 `reactive()` 声明了类型：`ref<string>("")`、`reactive<FormType>({})`。
-- [ ] 事件处理函数声明了参数类型：`(e: Event)`、`(row: UserInfo)`。
-- [ ] 组件 `defineProps` 使用泛型方式 `defineProps<Props>()`，不使用运行时声明。
-- [ ] 不使用 `@ts-ignore` 或 `@ts-nocheck`，除非有注释说明原因。
-- [ ] 类型定义放在 `type.ts` 或 `types/` 目录，不内联在组件中。
-
-### 常见错误示例
-
-```typescript
-// ❌ 错误：使用 any
-const data = ref<any>(null);
-const list = ref([]);  // 推断为 any[]
-
-// ✅ 正确：明确类型
-const data = ref<UserInfo | null>(null);
-const list = ref<UserListItem[]>([]);
-
-// ❌ 错误：API 无返回类型
-function getList(params) {
-  return http.request("post", url, { data: params });
-}
-
-// ✅ 正确：声明完整类型
-function getListApi(params: ListQuery): Promise<Result<ListResult>> {
-  return http.request<Result<ListResult>>("post", url, { data: params });
-}
-```
-
-## 二、Vue 组件规范检查
-
-### 必须通过
-
-- [ ] 使用 `<script setup lang="ts">`，不使用 Options API。
-- [ ] 使用 `defineOptions({ name: "ComponentName" })` 声明组件名。
-- [ ] Props 和 Emits 类型定义在同目录 `type.ts` 文件中。
-- [ ] 样式使用 `<style lang="scss" scoped>`。
-- [ ] 组件 class 名使用 `re-` 前缀（自定义组件）或有意义的业务前缀。
-- [ ] 没有硬编码中文文案（应使用 `$t()` 或配置化）。
-
-### 常见错误示例
-
-```vue
-<!-- ❌ 错误：Options API -->
-<script>
-export default {
-  data() { return { count: 0 } },
-  methods: { increment() { this.count++ } }
-}
-</script>
-
-<!-- ✅ 正确：Composition API + script setup -->
-<script setup lang="ts">
-import type { MyComponentProps } from "./type";
-defineOptions({ name: "MyComponent" });
-const props = defineProps<MyComponentProps>();
-const count = ref(0);
-function increment() { count.value++; }
-</script>
-```
-
-## 三、API 调用规范检查
-
-### 必须通过
-
-- [ ] API 调用封装在 `src/api/` 目录的函数中，不在组件中直接写 `http.request`。
-- [ ] 请求方法与后端文档一致（**允许 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"`。
-- [ ] 加解密依赖环境变量 `VITE_ENCODE_SWITCH`（无单请求 `crypto: true`）。
-- [ ] 组件中 API 调用有 `try/finally` 或 `try/catch` 处理异常。
-
-### 常见错误示例
-
-```typescript
-import { http } from "@/utils/http";
+- [ ] 独立详情：`showLink:false` + `activePath` + `toDetail` + `initToDetail`（细则 `detail-page`）
+- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
 
-// ❌ 错误：在组件中直接调用 http，且使用虚构 /api 前缀
-const res = await http.request("post", "/api/user/list", { data: params });
+## TypeScript
 
-// ✅ 正确：封装到 api/，真实地址走环境变量
-export function getUserListApi(data: CombinedQueryData) {
-  return http.request<Result<Data>>(
-    "post",
-    `${import.meta.env.VITE_API_BASE_URL}/console/user/list`,
-    { data },
-  );
-}
+- [ ] props / API / `ref` / `reactive` / 事件参数有明确类型，忌 `any`
+- [ ] `defineProps<Props>()`；忌 `@ts-ignore` / `@ts-nocheck`（除非注释原因）
+- [ ] 类型放 `type.ts` 或 `types/`
 
-// ❌ 错误：方法与参数位置错配（POST 却用 params）
-http.request("post", `${import.meta.env.VITE_API_BASE_URL}/console/user/list`, { params });
+## Vue 组件
 
-// ✅ 正确：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",
-});
+- [ ] `<script setup lang="ts">` + `defineOptions({ name })`
+- [ ] Props/Emits 在同目录 `type.ts`；`<style lang="scss" scoped>`
+- [ ] 文案用 `$t('中文')`
 
-// ❌ 错误：不存在的单请求加密开关
-http.request("post", url, { data: params, crypto: true });
-```
-
-## 四、安全规范检查
-
-### 必须通过
-
-- [ ] 不在前端代码中硬编码密钥、Token、密码。
-- [ ] 用户输入在提交前做了前端校验（必填、格式、长度）。
-- [ ] XSS 防护：用户输入展示使用 `v-text` 而非 `v-html`，除非已做消毒处理。
-- [ ] 权限按钮使用 `v-auth` 指令控制，不手动判断角色。
-- [ ] 敏感操作（删除、提交）有二次确认弹窗。
-- [ ] 不在前端做安全校验（前端校验仅为体验优化，后端必须同步校验）。
-
-### 安全检查清单
-
-```typescript
-// ❌ 危险：v-html 直接渲染用户输入
-<div v-html="userInput" />
-
-// ✅ 安全：使用 v-text 或 {{ }} 插值
-<span v-text="userInput" />
-<span>{{ userInput }}</span>
-
-// ❌ 危险：硬编码密钥
-const apiKey = "sk-abc123456";
-
-// ✅ 安全：从环境变量或后端获取
-const apiKey = import.meta.env.VITE_API_KEY;
-```
-
-## 五、性能检查
-
-### 必须通过
+## API
 
-- [ ] 页面组件使用 `() => import()` 懒加载。
-- [ ] 列表数据量超过 100 行时使用了分页或虚拟滚动。
-- [ ] 图表组件在 `onUnmounted` 中调用了 `dispose()`。
-- [ ] 没有不必要的 `watch`（能用 `computed` 的场景不用 `watch`）。
-- [ ] `v-for` 循环使用了唯一且稳定的 `:key`，不使用 `index` 作为 key（列表会变动时）。
-- [ ] 大数组操作使用 `computed` 缓存结果，不在 template 中直接调用方法。
-- [ ] 图片使用了懒加载（移动端 `van-image lazy-load`）。
-- [ ] 事件监听器在组件卸载时正确移除（`onUnmounted` 中 `removeEventListener`）。
+- [ ] 调用在 `src/api/`；方法跟后端；POST→`data`，GET→`params`
+- [ ] URL：`VITE_API_BASE_URL` + path；忌硬编码域名 / 虚构 `/api` 前缀
+- [ ] `Result<T>`；分页 `content` / `totalCount` / `pageNo` / `pageSize`
+- [ ] 驼峰字段；`Long`/`BigDecimal`→`string`；下载 `responseType: "blob"`
+- [ ] 加解密靠 `VITE_ENCODE_SWITCH`；无单请求 `crypto: true`
+- [ ] 组件调用有 `try/finally` 或 `try/catch`
 
-### 常见错误示例
+## 安全
 
-```typescript
-// ❌ 错误：watch 可以用 computed 替代
-watch(searchText, () => {
-  filteredList.value = list.value.filter(item => item.name.includes(searchText.value));
-});
+- [ ] 无硬编码密钥/Token/密码
+- [ ] 提交前校验；忌不可信内容 `v-html`
+- [ ] 权限用 `v-auth` / `ReAuth`；敏感操作有确认框
 
-// ✅ 正确：使用 computed
-const filteredList = computed(() =>
-  list.value.filter(item => item.name.includes(searchText.value))
-);
+## 性能
 
-// ❌ 错误：template 中调用方法（每次渲染都执行）
-<template>{{ getFullName(user) }}</template>
+- [ ] 路由组件 `() => import()`；大列表分页或虚拟滚动
+- [ ] 图表 `onUnmounted` → `dispose()`；`v-for` 稳定 `:key`
+- [ ] 能 `computed` 不用多余 `watch`；监听器卸载时移除
 
-// ✅ 正确：使用 computed 缓存
-const fullName = computed(() => `${user.firstName} ${user.lastName}`);
-```
-
-## 六、样式规范检查
-
-### 必须通过
-
-- [ ] 样式使用 `scoped`，不会污染全局。
-- [ ] 颜色使用 CSS 变量（`var(--el-color-primary)`），不硬编码。
-- [ ] 优先使用 UnoCSS 原子类（`flex-center`、`mb-4`）。
-- [ ] UnoCSS 类名为连字符形态：`p-5` / `w-full` / `px-5` / `gap-10`；禁止 `p5` / `w100%` / `px5` / `gap10`（无 CSS 产出，样式静默失效）。
-- [ ] 背景/文字色按语义取变量：`bg-bg_color` / `var(--el-text-color-*)`；禁止 `bg-[#fff]` + `dark:bg-[#303030]` 成对硬编码。
-- [ ] 组件尺寸按场景档位：查询区与 `ReTableBar` 工具栏按钮 `size="small"`；表格 `:size="size"`（禁写死）；弹窗表单 default；整屏主表单 `large`（细则见 `core-kernel`「四之二、样式契约」）。
-- [ ] 业务图标优先 `<svg-icon name="..." />`（本地无冒号 / Iconify 含 `:`）；菜单 `meta.icon` 为 string；细则见 `icons`。
-- [ ] 不使用 `!important`，除非覆盖第三方组件样式且有注释说明。
-- [ ] 不使用深层嵌套选择器（不超过 3 层）。
-- [ ] 移动端不使用固定 `px` 宽度，使用 `rem` 或百分比。
-- [ ] 新增全局样式时，同步在 `dark.scss` 中添加暗黑模式覆盖。
-- [ ] 不直接修改 `--el-color-primary`，而是通过 `setEpThemeColor()` 设置（保证色阶同步更新）。
-- [ ] 使用 `chroma-js` 处理颜色，不使用 `color`、`polished` 等其他库。
-- [ ] 侧边栏相关样式通过 `html[data-theme]` 选择器设置，不写在 `:root` 中。
-- [ ] 覆盖 Element Plus 组件的全局样式放在 `src/styles/element-plus.scss`，不在组件内写。
-
-### 设计规范遵从（命中 design-system 时必查，细则见 `design-system.md`）
-
-- [ ] 已输出「规范识别回执」，且规范 ID / 主色在令牌层、`platform-config.json`、侧栏主题三处一致（防识别漂移）。
-- [ ] 已建立令牌层 `design-tokens.scss`（**唯一新增文件**，纯 `:root` 数据无选择器；含用户可自定义区块 + 模版桥接令牌 + `--el-*` 映射）；组件几何重写已并入 `element-plus.scss`（令牌引用 + 规范注释）；文件名不得漂移成 `tokens.scss` 等变体，无独立重写层文件残留。
-- [ ] `index.scss` 中 `design-tokens` 位于 `@use` 最前；模版其余顺序未动。
-- [ ] `design-system.md` 第四节「模版硬编码冲突清单」逐条处理并在回复中逐条回填（重点：通配符 font-family、reset.scss body 字体与 `label { font-weight: 700 }`、`.el-card__body` padding 5px、弹窗渐变蓝底、表头硬编码色）。
-- [ ] 主色三态（hover/active）、字体、控件高度、圆角、卡片内边距、表单标签字重、表头视觉均符合目标规范（按第二节验证清单核验）。
-- [ ] 业务代码无裸控件高度/内边距/字号/圆角；组件几何覆盖只集中在 `element-plus.scss`；存量裸值扫描已执行。
-- [ ] 公共区域已按规范落地：`theme.scss` 侧栏配色（激活条 = 规范主色）、`index.scss` 壳变量（导航高/内容边距/弹窗底）、`HeaderHeight` 一致。
-- [ ] `platform-config.json` 的 `EpThemeColor` 与规范主色一致，已提醒清理 localStorage 缓存；新增令牌已在 `dark.scss` 补暗色覆盖。
+## 样式
 
-## 七、业务逻辑检查
+- [ ] `scoped`；色用 CSS 变量；优先 UnoCSS 连字符类（`p-5` 非 `p5`）
+- [ ] 语义色 `bg-bg_color` / `--el-*`；尺寸档位见 `core-kernel` 样式契约
+- [ ] 图标见 `icons`；忌滥 `!important`；选择器 ≤3 层
+- [ ] 全局 EP 覆盖在 `element-plus.scss`；侧栏色用 `html[data-theme]`
+- [ ] 主色经 `setEpThemeColor()`；颜色处理用 `chroma-js`
 
-### 必须通过
+### design-system（命中时）
 
-- [ ] 表单提交前调用了 `validate()`。
-- [ ] 删除操作有确认弹窗（`ElMessageBox.confirm` 或 `showConfirmDialog`）。
-- [ ] 提交按钮有 `loading` 状态防止重复提交。
-- [ ] 列表页有加载状态（`v-loading`）。
-- [ ] 空数据有占位提示（`el-empty` 或 `van-empty`）。
-- [ ] 编辑页正确加载并回显了已有数据。
-- [ ] 路由跳转使用了正确的参数传递方式（`query` 而非 `params`）。
-- [ ] 分页切换正确触发了数据加载。
+- [ ] 规范识别回执；令牌 / `platform-config.json` / 侧栏主题一致
+- [ ] 已建 `design-tokens.scss`；`index.scss` 中其 `@use` 最前
+- [ ] 冲突清单已逐条处理（见 `design-system`）
+- [ ] 有上游设计产出时已读 `design-handoff`；`EpThemeColor`/`Theme`/侧栏桥接/`Version` 一致
 
-### 查询列表页布局（命中 crud-pages / 列表需求时必查）
+## 业务
 
-- [ ] `ref="content"` 挂在 **`el-card`**（组件），不是原生 `div`。
-- [ ] 卡片样式为固定 **`height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`**，不是 `minHeight`。
-- [ ] 查询 `el-form`：`inline` + `class="bg-bg_color p-5"`；`ReGrid` 有 `:gap="[0, 20]"` 与响应式 `cols`。
-- [ ] 表单项有 `class="w-[100%] !mr-0"`；操作按钮用 `<ReGridItem suffix>`。
-- [ ] 折叠事件为 `@should-show-collapse`（不是 `@show-collapse`）。
-- [ ] 展示区用 `ReTableBar class="bg-bg_color"`，与查询区视觉分离。
-- [ ] 表格 `:style="{ height: \`${tableHeight}px\` }"`；`paginationRef` 在表格下方且同属 `ReTableBar` `#default`。
-- [ ] 卡片内除查询表单、表格+分页外还有其他模块（统计块/页签/提示条等）时，已包进一个根元素并绑 `ref="otherRef"`（从 `useTableSearch` 解构）；未绑则 `tableHeight` 漏减该模块高度。
-- [ ] `RePagination` 使用 `:pagination` + `@handle-current-change` / `@handle-size-change`。
-- [ ] `ReTableOperate` 使用 `:list`（不是 `:buttons`）。
+- [ ] 提交前 `validate()`；删除有确认；提交有 loading；列表有 `v-loading`
+- [ ] 编辑回显正确；分页切换会拉数
 
-## 八、代码风格检查
+### 列表→详情（命中 detail-page 时）
 
-### 必须通过
+- [ ] 兄弟绝对 path；`showLink:false`；`activePath`=列表 path；非空 `title`
+- [ ] 仅 `toDetail`；详情 `initToDetail`；`name` 对齐
+- [ ] 按需 `keepAlive` / `moreTags`
 
-- [ ] 使用 `const` / `let`，不使用 `var`。
-- [ ] 字符串使用双引号（遵循 ESLint 配置），模板字符串用于变量拼接。
-- [ ] 函数和变量使用驼峰命名。
-- [ ] 组件名使用大驼峰（`UserList`），文件名使用短横线（`user-list.vue`）。
-- [ ] 常量使用全大写下划线分隔（`MAX_PAGE_SIZE`）。
-- [ ] 没有未使用的变量、导入或参数。
-- [ ] 没有 `console.log` 残留（生产代码中）。
+### 列表布局（命中 crud-pages 时）
 
-## 审查流程
+- [ ] 对照 `crud-pages` L1–L8（不在此复述示例）
 
-1. **生成/改码落盘之后**（不是生成前）：执行上方「强制执行协议」。
-2. **发现问题**：立即修正并重跑 `pnpm lint:fix` + `pnpm type-check`，不要带着已知问题收工。
-3. **不确定项**：写入结果块「待确认」，必要时在代码加 `// TODO: 需要确认`。
-4. **严重问题**（安全 / 类型错误 / lint 报错 / 列表布局硬约束违反）：必须修正后再输出最终回复。
-5. **最终回复**：必须含「代码质量审查」结果块；禁止只用「命中模块含 code-quality」代替。
+## 代码风格
 
-## 快速自检命令
-
-完成代码修改后，运行以下命令验证（**均必跑**）：
-
-```bash
-# 必跑：Lint 自动修复（优先用项目脚本）
-pnpm lint:fix
-
-# 必跑：TypeScript 类型检查（优先用项目脚本）
-pnpm type-check
-
-# 无 lint:fix 时的回退
-pnpm lint
-# 或
-pnpm exec eslint . --fix
-
-# 无 type-check 脚本时的回退
-pnpm exec vue-tsc --noEmit
-```
+- [ ] `const`/`let`；驼峰；组件大驼峰；无未使用导入；无残留 `console.log`