@agile-team/wl-skills-kit 2.1.2 → 2.1.4

package/files/.github/standards/01-toolchain.md

@@ -1,57 +1,57 @@
-# 01 — 工具链前置检测
-
-> **强制度**：🔴 阻断式。检测未通过 → AI 必须暂停代码生成。
-
----
-
-## 检测目标
-
-确认项目已正确安装 `@robot-admin/git-standards`，工具链有效。
-
-## 检测项
-
-AI 在执行任何代码生成任务**之前**，必须检查以下三个特征文件是否存在于项目根目录：
-
-```
-✓ .prettierrc.js
-✓ eslint.config.ts
-✓ .husky/  （目录）
-```
-
-## 判定规则
-
-| 状态         | 处理                        |
-| ------------ | --------------------------- |
-| 三者全部存在 | ✅ 工具链就绪，继续执行任务 |
-| 缺任意一个   | ❌ 暂停任务，输出下方提示   |
-
-## 暂停提示标准格式
-
-```
-❌ 工具链检测失败：未找到 .prettierrc.js / eslint.config.ts / .husky/
-   → 请执行：npx @robot-admin/git-standards init
-   → 或联系 CHENY（工号 409322）解决
-   → ⛔ 代码生成已暂停，修复后重新触发
-```
-
-## Pre-flight 声明示例
-
-工具链就绪：
-
-```
-✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓  [全部就绪]
-```
-
-工具链缺失：
-
-```
-❌ 工具链检测：未检测到 .husky/  → 已暂停，提醒已发出
-```
-
----
-
-## 为什么必须前置
-
-- `eslint.config.ts` 缺失 → 代码风格无法约束，AI 生成代码可能不通过 lint
-- `.prettierrc.js` 缺失 → 格式不统一，团队协作冲突
-- `.husky/` 缺失 → 提交前钩子失效，console.log / 死代码会进入仓库
+# 01 — 工具链前置检测
+
+> **强制度**：🔴 阻断式。检测未通过 → AI 必须暂停代码生成。
+
+---
+
+## 检测目标
+
+确认项目已正确安装 `@robot-admin/git-standards`，工具链有效。
+
+## 检测项
+
+AI 在执行任何代码生成任务**之前**，必须检查以下三个特征文件是否存在于项目根目录：
+
+```
+✓ .prettierrc.js
+✓ eslint.config.ts
+✓ .husky/  （目录）
+```
+
+## 判定规则
+
+| 状态         | 处理                        |
+| ------------ | --------------------------- |
+| 三者全部存在 | ✅ 工具链就绪，继续执行任务 |
+| 缺任意一个   | ❌ 暂停任务，输出下方提示   |
+
+## 暂停提示标准格式
+
+```
+❌ 工具链检测失败：未找到 .prettierrc.js / eslint.config.ts / .husky/
+   → 请执行：npx @robot-admin/git-standards init
+   → 或联系 CHENY（工号 409322）解决
+   → ⛔ 代码生成已暂停，修复后重新触发
+```
+
+## Pre-flight 声明示例
+
+工具链就绪：
+
+```
+✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓  [全部就绪]
+```
+
+工具链缺失：
+
+```
+❌ 工具链检测：未检测到 .husky/  → 已暂停，提醒已发出
+```
+
+---
+
+## 为什么必须前置
+
+- `eslint.config.ts` 缺失 → 代码风格无法约束，AI 生成代码可能不通过 lint
+- `.prettierrc.js` 缺失 → 格式不统一，团队协作冲突
+- `.husky/` 缺失 → 提交前钩子失效，console.log / 死代码会进入仓库

package/files/.github/standards/02-code-structure.md

@@ -1,111 +1,111 @@
-# 02 — 代码结构与顺序规范
-
-> **强制度**：🔴 必遵。AI 生成代码必须严格按下列顺序输出。
-
----
-
-## 4 文件原则（页面目录强制结构）
-
-```
-src/views/[域]/[模块]/[子模块]/[kebab-case目录]/
-├── index.vue    ← 纯模板 + 解构，不写业务逻辑
-├── data.ts      ← AbstractPageQueryHook 类 + API_CONFIG
-├── index.scss   ← 页面样式（可为空）
-└── api.md       ← 接口约定文档
-```
-
-**禁止**：把业务逻辑写在 index.vue；缺少 data.ts；缺少 api.md。
-
-## 弹窗组件归属
-
-| 场景                    | 位置                                 |
-| ----------------------- | ------------------------------------ |
-| 通用弹窗（2+ 页面复用） | `src/components/local/c_xxxModal/`   |
-| 极个性弹窗（仅单页面）  | 页面目录下 `components/xxxModal.vue` |
-
----
-
-## index.vue 三段式（顺序固定，不可调换）
-
-```vue
-<template>
-  <!-- 纯模板 + 组件组合 -->
-</template>
-
-<script setup lang="ts">
-/* 业务逻辑全部从 data.ts 导入，按下方 9 段式 */
-</script>
-
-<style scoped lang="scss">
-@import "./index.scss";
-/* 仅允许这一行 import，全部样式写在 index.scss */
-</style>
-```
-
----
-
-## `<script setup>` 9 段式（按需使用，用到的必须遵守此顺序）
-
-```typescript
-// ===== 1. import 语句（外部库 → 内部模块 → 类型）=====
-import { ref, computed, onMounted } from "vue";
-import { createPage } from "./data";
-
-// ===== 2. 组件宏（defineOptions / defineProps / defineEmits）=====
-defineOptions({ name: "PageName" });
-
-// ===== 3. 路由 & Store =====
-const route = useRoute();
-
-// ===== 4. createPage() 调用 + 解构（核心模式）=====
-const Page = createPage();
-const {
-  tableRef,
-  page,
-  queryParam,
-  list,
-  queryItems,
-  columns,
-  toolbars,
-  select,
-} = Page;
-
-// ===== 5. 页面补充状态（ref / reactive / computed）=====
-const loading = ref(false);
-
-// ===== 6. watch / watchEffect =====
-
-// ===== 7. 业务方法（API 调用 / 事件处理）=====
-async function handleSubmit() {}
-
-// ===== 8. 生命周期 =====
-onMounted(() => select());
-
-// ===== 9. defineExpose =====
-defineExpose({ select });
-```
-
----
-
-## data.ts 内部顺序（强制）
-
-```typescript
-// 1. import（类型 → 基类 → API 工具 → 工具函数）
-// 2. API_CONFIG（接口路径集中声明，as const）
-// 3. createPage()（constructor → queryDef → toolbarDef → columnsDef → 业务方法）
-// 4. 页面共用辅助函数（可选，纯函数）
-```
-
----
-
-## index.scss 顺序（建议）
-
-```scss
-// 1. 变量覆盖
-// 2. 容器级样式 (.app-page-container)
-// 3. 区域级样式 (.search-area / .table-area)
-// 4. 组件深层覆盖 (:deep(.el-table))
-// 5. 响应式 (@media)
-```
-
-> 禁止 `::v-deep` / `/deep/`，统一使用 `:deep()`。
+# 02 — 代码结构与顺序规范
+
+> **强制度**：🔴 必遵。AI 生成代码必须严格按下列顺序输出。
+
+---
+
+## 4 文件原则（页面目录强制结构）
+
+```
+src/views/[域]/[模块]/[子模块]/[kebab-case目录]/
+├── index.vue    ← 纯模板 + 解构，不写业务逻辑
+├── data.ts      ← AbstractPageQueryHook 类 + API_CONFIG
+├── index.scss   ← 页面样式（可为空）
+└── api.md       ← 接口约定文档
+```
+
+**禁止**：把业务逻辑写在 index.vue；缺少 data.ts；缺少 api.md。
+
+## 弹窗组件归属
+
+| 场景                    | 位置                                 |
+| ----------------------- | ------------------------------------ |
+| 通用弹窗（2+ 页面复用） | `src/components/local/c_xxxModal/`   |
+| 极个性弹窗（仅单页面）  | 页面目录下 `components/xxxModal.vue` |
+
+---
+
+## index.vue 三段式（顺序固定，不可调换）
+
+```vue
+<template>
+  <!-- 纯模板 + 组件组合 -->
+</template>
+
+<script setup lang="ts">
+/* 业务逻辑全部从 data.ts 导入，按下方 9 段式 */
+</script>
+
+<style scoped lang="scss">
+@import "./index.scss";
+/* 仅允许这一行 import，全部样式写在 index.scss */
+</style>
+```
+
+---
+
+## `<script setup>` 9 段式（按需使用，用到的必须遵守此顺序）
+
+```typescript
+// ===== 1. import 语句（外部库 → 内部模块 → 类型）=====
+import { ref, computed, onMounted } from "vue";
+import { createPage } from "./data";
+
+// ===== 2. 组件宏（defineOptions / defineProps / defineEmits）=====
+defineOptions({ name: "PageName" });
+
+// ===== 3. 路由 & Store =====
+const route = useRoute();
+
+// ===== 4. createPage() 调用 + 解构（核心模式）=====
+const Page = createPage();
+const {
+  tableRef,
+  page,
+  queryParam,
+  list,
+  queryItems,
+  columns,
+  toolbars,
+  select,
+} = Page;
+
+// ===== 5. 页面补充状态（ref / reactive / computed）=====
+const loading = ref(false);
+
+// ===== 6. watch / watchEffect =====
+
+// ===== 7. 业务方法（API 调用 / 事件处理）=====
+async function handleSubmit() {}
+
+// ===== 8. 生命周期 =====
+onMounted(() => select());
+
+// ===== 9. defineExpose =====
+defineExpose({ select });
+```
+
+---
+
+## data.ts 内部顺序（强制）
+
+```typescript
+// 1. import（类型 → 基类 → API 工具 → 工具函数）
+// 2. API_CONFIG（接口路径集中声明，as const）
+// 3. createPage()（constructor → queryDef → toolbarDef → columnsDef → 业务方法）
+// 4. 页面共用辅助函数（可选，纯函数）
+```
+
+---
+
+## index.scss 顺序（建议）
+
+```scss
+// 1. 变量覆盖
+// 2. 容器级样式 (.app-page-container)
+// 3. 区域级样式 (.search-area / .table-area)
+// 4. 组件深层覆盖 (:deep(.el-table))
+// 5. 响应式 (@media)
+```
+
+> 禁止 `::v-deep` / `/deep/`，统一使用 `:deep()`。

package/files/.github/standards/03-comments.md

@@ -1,53 +1,53 @@
-# 03 — 注释规范
-
-> **强制度**：🟡 建议。
-
----
-
-## 文件头注释
-
-由 VS Code 插件 **koroFileHeader** 自动生成，不手写。
-项目根有 `.fileheader` 配置文件。
-
-**插件缺失提示**：
-
-```
-⚠️ 未检测到 koroFileHeader 配置生效
-   → 请安装插件：VS Code 扩展商店搜索 "koroFileHeader"
-   → 或联系 CHENY（工号 409322）获取一键安装指引
-```
-
----
-
-## 函数注释
-
-仅复杂业务逻辑需要：
-
-```typescript
-/**
- * @description 批量提交客户档案
- * @param ids 选中的客户 ID 列表
- * @returns 后端响应结果
- */
-async function batchSubmit(ids: string[]) { ... }
-```
-
----
-
-## 行内注释
-
-- 解释「**为什么**」而非「是什么」
-- 统一使用 `//`，不使用 `/* */`
-
-```typescript
-// 后端要求 status 必须先转字符串再传（接口字段类型不一致历史遗留）
-params.status = String(params.status);
-```
-
----
-
-## 禁止事项
-
-- ❌ 提交注释掉的死代码（直接删除，git 可追溯历史）
-- ❌ 显而易见的注释，如 `// 声明变量`、`// 调用接口`
-- ❌ TODO 不带责任人或日期，如 `// TODO: 待优化`，应写为 `// TODO(cheny, 2026-04): 接口字段后端确认中`
+# 03 — 注释规范
+
+> **强制度**：🟡 建议。
+
+---
+
+## 文件头注释
+
+由 VS Code 插件 **koroFileHeader** 自动生成，不手写。
+项目根有 `.fileheader` 配置文件。
+
+**插件缺失提示**：
+
+```
+⚠️ 未检测到 koroFileHeader 配置生效
+   → 请安装插件：VS Code 扩展商店搜索 "koroFileHeader"
+   → 或联系 CHENY（工号 409322）获取一键安装指引
+```
+
+---
+
+## 函数注释
+
+仅复杂业务逻辑需要：
+
+```typescript
+/**
+ * @description 批量提交客户档案
+ * @param ids 选中的客户 ID 列表
+ * @returns 后端响应结果
+ */
+async function batchSubmit(ids: string[]) { ... }
+```
+
+---
+
+## 行内注释
+
+- 解释「**为什么**」而非「是什么」
+- 统一使用 `//`，不使用 `/* */`
+
+```typescript
+// 后端要求 status 必须先转字符串再传（接口字段类型不一致历史遗留）
+params.status = String(params.status);
+```
+
+---
+
+## 禁止事项
+
+- ❌ 提交注释掉的死代码（直接删除，git 可追溯历史）
+- ❌ 显而易见的注释，如 `// 声明变量`、`// 调用接口`
+- ❌ TODO 不带责任人或日期，如 `// TODO: 待优化`，应写为 `// TODO(cheny, 2026-04): 接口字段后端确认中`

package/files/.github/standards/04-coding-basics.md

@@ -1,33 +1,33 @@
-# 04 — 基础编码规范
-
-> **强制度**：🔴 必遵。
-> 参考 jhat.tech 开发规范 + Robot_Admin 实践。
-
----
-
-## 13 条核心约定
-
-1. **变量声明**：优先 `const`，必须重新赋值时用 `let`，禁止 `var`
-2. **解构赋值**：优先使用 `const { a, b } = obj`，而非 `obj.a` / `obj.b`
-3. **异步处理**：统一 `async/await`，禁止 `.then()` 链式调用
-4. **字符串引号**：统一单引号（以 `.prettierrc.js` 为准）
-5. **模板字符串**：替代字符串拼接，`` `Hello ${name}` `` 而非 `'Hello ' + name`
-6. **大括号**：所有代码块必须使用大括号包裹，即使只有一行
-7. **条件层级**：最多三层，超过三层必须抽成函数
-8. **模板表达式**：`<template>` 中只写简单表达式，复杂逻辑提取为 `computed` 或方法
-9. **对象遍历**：禁止 `for...in`，使用 `Object.keys(obj).forEach()`
-10. **undefined 判断**：使用 `typeof variable !== 'undefined'`
-11. **v-for**：必须设置 `:key`，优先用业务主键 id 而非 index
-12. **指令缩写**：统一 `:`（v-bind）、`@`（v-on）、`#`（v-slot）
-13. **this 别名**：`<script setup>` 中无 `this`；旧 Options API 中的 `this` 别名用 `self`
-
----
-
-## 全局禁止事项
-
-- ❌ index.vue 中写业务逻辑（逻辑全在 data.ts）
-- ❌ 使用 Vuex（本项目用 Pinia）
-- ❌ `::v-deep` / `/deep/`（用 `:deep()`）
-- ❌ 直接用 axios（用 getAction/postAction，详见 13-platform-components.md）
-- ❌ 手写查询表单/工具栏/分页（用 BaseQuery/BaseToolbar/jh-pagination）
-- ❌ 每个页面重复写弹窗（优先用 `c_modal` / `c_formModal` 等局部公共组件）
+# 04 — 基础编码规范
+
+> **强制度**：🔴 必遵。
+> 参考 jhat.tech 开发规范 + Robot_Admin 实践。
+
+---
+
+## 13 条核心约定
+
+1. **变量声明**：优先 `const`，必须重新赋值时用 `let`，禁止 `var`
+2. **解构赋值**：优先使用 `const { a, b } = obj`，而非 `obj.a` / `obj.b`
+3. **异步处理**：统一 `async/await`，禁止 `.then()` 链式调用
+4. **字符串引号**：统一单引号（以 `.prettierrc.js` 为准）
+5. **模板字符串**：替代字符串拼接，`` `Hello ${name}` `` 而非 `'Hello ' + name`
+6. **大括号**：所有代码块必须使用大括号包裹，即使只有一行
+7. **条件层级**：最多三层，超过三层必须抽成函数
+8. **模板表达式**：`<template>` 中只写简单表达式，复杂逻辑提取为 `computed` 或方法
+9. **对象遍历**：禁止 `for...in`，使用 `Object.keys(obj).forEach()`
+10. **undefined 判断**：使用 `typeof variable !== 'undefined'`
+11. **v-for**：必须设置 `:key`，优先用业务主键 id 而非 index
+12. **指令缩写**：统一 `:`（v-bind）、`@`（v-on）、`#`（v-slot）
+13. **this 别名**：`<script setup>` 中无 `this`；旧 Options API 中的 `this` 别名用 `self`
+
+---
+
+## 全局禁止事项
+
+- ❌ index.vue 中写业务逻辑（逻辑全在 data.ts）
+- ❌ 使用 Vuex（本项目用 Pinia）
+- ❌ `::v-deep` / `/deep/`（用 `:deep()`）
+- ❌ 直接用 axios（用 getAction/postAction，详见 13-platform-components.md）
+- ❌ 手写查询表单/工具栏/分页（用 BaseQuery/BaseToolbar/jh-pagination）
+- ❌ 每个页面重复写弹窗（优先用 `c_modal` / `c_formModal` 等局部公共组件）

package/files/.github/standards/05-logging.md

@@ -1,38 +1,38 @@
-# 05 — 日志输出规范
-
-> **强制度**：🔴 必遵。
-
----
-
-## 开发期
-
-- 允许 `console.log` 调试，ESLint 仅给 `warn` 提示
-- AI 生成的代码**不要**包含调试用 `console.log`
-
-## 提交期
-
-- husky pre-commit 钩子自动触发 lint 检查
-- **必须清理** `console.log` / `console.warn` / `console.debug` 才能提交
-
-## 生产代码
-
-- ❌ 禁止出现 `console.log`、`console.warn`、`console.error`
-- ❌ 大量 console 输出会带来性能问题（参考 jhat.tech 规范）
-
-## 替代方案
-
-| 场景     | 替代方式                                       |
-| -------- | ---------------------------------------------- |
-| 错误监控 | 走全局错误处理器（接入 Sentry 或自研上报通道） |
-| 调试信息 | 仅在开发环境通过 `import.meta.env.DEV` 守卫    |
-| 用户提示 | 使用 `ElMessage` / `jh-message`                |
-
-```typescript
-// ✅ 允许：开发期守卫
-if (import.meta.env.DEV) {
-  console.log("[debug] payload:", payload);
-}
-
-// ❌ 禁止：生产代码无守卫的 console
-console.log("user info:", user);
-```
+# 05 — 日志输出规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## 开发期
+
+- 允许 `console.log` 调试，ESLint 仅给 `warn` 提示
+- AI 生成的代码**不要**包含调试用 `console.log`
+
+## 提交期
+
+- husky pre-commit 钩子自动触发 lint 检查
+- **必须清理** `console.log` / `console.warn` / `console.debug` 才能提交
+
+## 生产代码
+
+- ❌ 禁止出现 `console.log`、`console.warn`、`console.error`
+- ❌ 大量 console 输出会带来性能问题（参考 jhat.tech 规范）
+
+## 替代方案
+
+| 场景     | 替代方式                                       |
+| -------- | ---------------------------------------------- |
+| 错误监控 | 走全局错误处理器（接入 Sentry 或自研上报通道） |
+| 调试信息 | 仅在开发环境通过 `import.meta.env.DEV` 守卫    |
+| 用户提示 | 使用 `ElMessage` / `jh-message`                |
+
+```typescript
+// ✅ 允许：开发期守卫
+if (import.meta.env.DEV) {
+  console.log("[debug] payload:", payload);
+}
+
+// ❌ 禁止：生产代码无守卫的 console
+console.log("user info:", user);
+```