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

package/files/.github/standards/11-form-validation.md

@@ -1,81 +1,81 @@
-# 11 — 表单与校验规范
-
-> **强制度**：🔴 必遵。
-
----
-
-## c_formModal / c_formSections 场景
-
-平台已封装组件，**内置完整生命周期**：
-
-```
-open → 数据回填 → validate → submit → close / resetFields
-```
-
-✅ AI 直接按组件文档使用即可，**不需要重复写 validate / resetFields 逻辑**。
-
-参考：`src/components/local/c_formModal/README.md`
-
----
-
-## FORM_ROUTE 独立路由表单页（c_formModal 不适用时）
-
-无 c_formModal 托管的复杂表单（多 Tab、多子表、向导式），**必须遵守**：
-
-### 1. 提交前调用 validate
-
-```typescript
-async function handleSubmit() {
-  const valid = await formRef.value?.validate();
-  if (!valid) return;
-  await postAction(API_CONFIG.save, formData.value);
-}
-```
-
-### 2. 取消/离开调用 resetFields
-
-```typescript
-function handleCancel() {
-  formRef.value?.resetFields();
-  router.back();
-}
-
-onBeforeRouteLeave(() => {
-  formRef.value?.resetFields();
-});
-```
-
-### 3. rules 在 data.ts 中独立导出
-
-```typescript
-// data.ts
-export const formRules = {
-  fieldName: [
-    { required: true, message: "请输入字段名", trigger: "blur" },
-    { max: 50, message: "不超过 50 字符", trigger: "blur" },
-  ],
-  status: [{ required: true, message: "请选择状态", trigger: "change" }],
-};
-```
-
-❌ **禁止**：把 rules 写在 `<template>` 字面量里。
-
----
-
-## 校验时机
-
-| 时机              | 触发                             |
-| ----------------- | -------------------------------- |
-| `blur` 失焦       | 字符串类、必填字段               |
-| `change` 变更     | 选择类（select / date / picker） |
-| 手动 `validate()` | 提交时全量校验                   |
-| 字段间联动        | `watch` + 手动 `validateField()` |
-
-## AI 检查清单
-
-生成 FORM_ROUTE 模板代码时确认：
-
-- [ ] 提交按钮 click 处理函数中调用了 `formRef.value?.validate()`
-- [ ] 取消按钮 / 路由离开钩子中调用了 `resetFields()`
-- [ ] rules 定义在 `data.ts` 而非 `<template>`
-- [ ] 必填字段都加了 `required: true` 校验规则
+# 11 — 表单与校验规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## c_formModal / c_formSections 场景
+
+平台已封装组件，**内置完整生命周期**：
+
+```
+open → 数据回填 → validate → submit → close / resetFields
+```
+
+✅ AI 直接按组件文档使用即可，**不需要重复写 validate / resetFields 逻辑**。
+
+参考：`src/components/local/c_formModal/README.md`
+
+---
+
+## FORM_ROUTE 独立路由表单页（c_formModal 不适用时）
+
+无 c_formModal 托管的复杂表单（多 Tab、多子表、向导式），**必须遵守**：
+
+### 1. 提交前调用 validate
+
+```typescript
+async function handleSubmit() {
+  const valid = await formRef.value?.validate();
+  if (!valid) return;
+  await postAction(API_CONFIG.save, formData.value);
+}
+```
+
+### 2. 取消/离开调用 resetFields
+
+```typescript
+function handleCancel() {
+  formRef.value?.resetFields();
+  router.back();
+}
+
+onBeforeRouteLeave(() => {
+  formRef.value?.resetFields();
+});
+```
+
+### 3. rules 在 data.ts 中独立导出
+
+```typescript
+// data.ts
+export const formRules = {
+  fieldName: [
+    { required: true, message: "请输入字段名", trigger: "blur" },
+    { max: 50, message: "不超过 50 字符", trigger: "blur" },
+  ],
+  status: [{ required: true, message: "请选择状态", trigger: "change" }],
+};
+```
+
+❌ **禁止**：把 rules 写在 `<template>` 字面量里。
+
+---
+
+## 校验时机
+
+| 时机              | 触发                             |
+| ----------------- | -------------------------------- |
+| `blur` 失焦       | 字符串类、必填字段               |
+| `change` 变更     | 选择类（select / date / picker） |
+| 手动 `validate()` | 提交时全量校验                   |
+| 字段间联动        | `watch` + 手动 `validateField()` |
+
+## AI 检查清单
+
+生成 FORM_ROUTE 模板代码时确认：
+
+- [ ] 提交按钮 click 处理函数中调用了 `formRef.value?.validate()`
+- [ ] 取消按钮 / 路由离开钩子中调用了 `resetFields()`
+- [ ] rules 定义在 `data.ts` 而非 `<template>`
+- [ ] 必填字段都加了 `required: true` 校验规则

package/files/.github/standards/12-base-table.md

@@ -1,116 +1,116 @@
-# 12 — BaseTable 渲染与 AGGrid cid 唯一性规范
-
-> **强制度**：🔴 必遵。
-
----
-
-## 渲染模式（强制）
-
-所有 `BaseTable` 必须默认使用 **AGGrid** 渲染：
-
-```vue
-<BaseTable
-  ref="tableRef"
-  render-type="agGrid"
-  cid="mca-745831"
-  :data="list"
-  :columns="columns"
-  showToolbar
-/>
-```
-
-> 全局配置：`envConfig().componentConfig.table = { renderType: 'agGrid' }`
-> 设置后所有未显式指定 `render-type` 的 BaseTable 默认 AGGrid。
-
----
-
-## cid 命名规则（核心）
-
-AGGrid 通过 `cid` 持久化列配置（列宽、顺序、显示），**cid 必须全局唯一**。
-
-### 表格级 cid
-
-```
-格式：{页面目录首字母缩写}-{Unix秒后6位}
-```
-
-**生成规则（AI 执行）**：
-
-1. 取页面 kebab-case 目录名，每个单词取首字母拼接为缩写
-2. 取 `Math.floor(Date.now() / 1000).toString().slice(-6)` 作为 6 位时间戳后缀
-3. 用 `-` 连接
-
-**示例**：
-
-| 页面目录                 | 缩写 | cid               |
-| ------------------------ | ---- | ----------------- |
-| `mmwr-customer-archive`  | mca  | `mca-745831`      |
-| `domestic-trade-order`   | dto  | `dto-745832`      |
-| 同页面第二个表格（子表） | mca  | `mca-745831-sub1` |
-| 同页面第三个表格         | mca  | `mca-745831-sub2` |
-
-### 列级 cid
-
-```
-格式：{表格cid的缩写部分}-{fieldName}
-```
-
-```typescript
-// 表格缩写为 mca
-columnsDef(): TableColumnDesc<any>[] {
-  return [
-    { type: 'selection' },
-    { type: 'index' },
-    { label: '取样',     name: 'sampling',           cid: 'mca-sampling',           width: 70 },
-    { label: '线上公告', name: 'onlineAnnouncement', cid: 'mca-onlineAnnouncement', width: 70 },
-  ]
-}
-```
-
----
-
-## 禁止事项
-
-- ❌ 随机短字符串 `cid="ipiCfsb"`（AI 重新生成时极易碰撞）
-- ❌ 纯字段名 `cid: "sampling"`（不同页面同名字段冲突）
-- ❌ 省略 cid（列配置持久化完全失效）
-- ❌ 跨页面复用同一 cid
-
----
-
-## Pre-flight 声明示例
-
-```
-✅ cid 已生成：mca-745831（mmwr-customer-archive）
-✅ 列级 cid 前缀：mca-
-```
-
----
-
-## 完整代码示例
-
-```vue
-<!-- index.vue -->
-<template>
-  <BaseTable
-    ref="tableRef"
-    render-type="agGrid"
-    cid="mca-745831"
-    :data="list"
-    :columns="columns"
-    showToolbar
-  />
-</template>
-```
-
-```typescript
-// data.ts
-columnsDef(): TableColumnDesc<any>[] {
-  return [
-    { type: 'selection' },
-    { type: 'index' },
-    { label: '客户名称', name: 'customerName', cid: 'mca-customerName', minWidth: 120 },
-    { label: '状态',     name: 'status',       cid: 'mca-status',       minWidth: 80 },
-  ]
-}
-```
+# 12 — BaseTable 渲染与 AGGrid cid 唯一性规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## 渲染模式（强制）
+
+所有 `BaseTable` 必须默认使用 **AGGrid** 渲染：
+
+```vue
+<BaseTable
+  ref="tableRef"
+  render-type="agGrid"
+  cid="mca-745831"
+  :data="list"
+  :columns="columns"
+  showToolbar
+/>
+```
+
+> 全局配置：`envConfig().componentConfig.table = { renderType: 'agGrid' }`
+> 设置后所有未显式指定 `render-type` 的 BaseTable 默认 AGGrid。
+
+---
+
+## cid 命名规则（核心）
+
+AGGrid 通过 `cid` 持久化列配置（列宽、顺序、显示），**cid 必须全局唯一**。
+
+### 表格级 cid
+
+```
+格式：{页面目录首字母缩写}-{Unix秒后6位}
+```
+
+**生成规则（AI 执行）**：
+
+1. 取页面 kebab-case 目录名，每个单词取首字母拼接为缩写
+2. 取 `Math.floor(Date.now() / 1000).toString().slice(-6)` 作为 6 位时间戳后缀
+3. 用 `-` 连接
+
+**示例**：
+
+| 页面目录                 | 缩写 | cid               |
+| ------------------------ | ---- | ----------------- |
+| `mmwr-customer-archive`  | mca  | `mca-745831`      |
+| `domestic-trade-order`   | dto  | `dto-745832`      |
+| 同页面第二个表格（子表） | mca  | `mca-745831-sub1` |
+| 同页面第三个表格         | mca  | `mca-745831-sub2` |
+
+### 列级 cid
+
+```
+格式：{表格cid的缩写部分}-{fieldName}
+```
+
+```typescript
+// 表格缩写为 mca
+columnsDef(): TableColumnDesc<any>[] {
+  return [
+    { type: 'selection' },
+    { type: 'index' },
+    { label: '取样',     name: 'sampling',           cid: 'mca-sampling',           width: 70 },
+    { label: '线上公告', name: 'onlineAnnouncement', cid: 'mca-onlineAnnouncement', width: 70 },
+  ]
+}
+```
+
+---
+
+## 禁止事项
+
+- ❌ 随机短字符串 `cid="ipiCfsb"`（AI 重新生成时极易碰撞）
+- ❌ 纯字段名 `cid: "sampling"`（不同页面同名字段冲突）
+- ❌ 省略 cid（列配置持久化完全失效）
+- ❌ 跨页面复用同一 cid
+
+---
+
+## Pre-flight 声明示例
+
+```
+✅ cid 已生成：mca-745831（mmwr-customer-archive）
+✅ 列级 cid 前缀：mca-
+```
+
+---
+
+## 完整代码示例
+
+```vue
+<!-- index.vue -->
+<template>
+  <BaseTable
+    ref="tableRef"
+    render-type="agGrid"
+    cid="mca-745831"
+    :data="list"
+    :columns="columns"
+    showToolbar
+  />
+</template>
+```
+
+```typescript
+// data.ts
+columnsDef(): TableColumnDesc<any>[] {
+  return [
+    { type: 'selection' },
+    { type: 'index' },
+    { label: '客户名称', name: 'customerName', cid: 'mca-customerName', minWidth: 120 },
+    { label: '状态',     name: 'status',       cid: 'mca-status',       minWidth: 80 },
+  ]
+}
+```

package/files/.github/standards/13-platform-components.md

@@ -1,123 +1,123 @@
-# 13 — 平台组件合规规范（核心 AI 质量门控）
-
-> **强制度**：🔴 必遵 + 阻断式。
-> 这是防止 AI 绕过平台封装、自由发挥使用 `el-*` 原生组件的核心规则。
-
----
-
-## 总原则
-
-> **优先使用平台封装组件；无对应封装时才允许使用 `el-*` 原生组件；
-> 跨 3+ 页面相同 `el-*` 模式 → convention-audit 输出"组件提取建议"到 `reports/`，由人工评审决定是否封装。**
-
----
-
-## 组件强制对照表
-
-| 场景                | 优先使用（有则必用）                          | 替代方案                     |
-| ------------------- | --------------------------------------------- | ---------------------------- |
-| 查询栏              | `BaseQuery`                                   | ❌ el-form 手写查询区        |
-| 工具栏 / 操作按钮行 | `BaseToolbar`                                 | ❌ 自定义按钮排列            |
-| 列表 / 表格         | `BaseTable` (`render-type="agGrid"`)          | ❌ el-table                  |
-| 表单弹窗            | `c_formModal`                                 | ❌ el-dialog + el-form 手写  |
-| 列表选择弹窗        | `c_listModal`                                 | ❌ el-dialog + el-table 手写 |
-| 表单内容分区        | `c_formSections`                              | ❌ 裸分组                    |
-| 分割标题            | `c_spliterTitle`                              | ❌ el-divider                |
-| 复杂路由表单页      | FORM-ROUTE 模板                               | ❌ 完全手写                  |
-| 日期 / 日期范围     | `jh-date` / `jh-date-range`                   | ❌ el-date-picker            |
-| 文件上传            | `jh-file-upload`                              | ❌ el-upload                 |
-| 用户选择            | `jh-user-picker`                              | ❌ 自定义弹窗选人            |
-| 部门选择            | `jh-dept-picker`                              | ❌ 同上                      |
-| 下拉 / 选择器       | `jh-select` / `jh-picker`                     | ❌ el-select 手写 options    |
-| 只读文本展示        | `jh-text`                                     | ❌ span/div 直接渲染         |
-| 分页                | `jh-pagination`                               | ❌ el-pagination             |
-| 上下分栏            | `jh-drag-row`                                 | ❌ 手动 flex/grid            |
-| 左右分割            | `C_Splitter`                                  | ❌ 手动 flex/grid            |
-| 树形面板            | `C_Tree`                                      | ❌ el-tree 手写              |
-| 状态标签            | `C_TagStatus`                                 | ❌ el-tag + 颜色映射         |
-| HTTP 请求           | `getAction/postAction/putAction/deleteAction` | ❌ axios / fetch 直接调用    |
-
----
-
-## 组件在 template 中的书写顺序
-
-当页面同时存在多个区块时，**有则按下列顺序排列**（**全部可选，不强制必须存在**）：
-
-```
-BaseQuery → BaseToolbar → BaseTable → jh-pagination
-```
-
-✅ 仅有 BaseTable 的页面：直接写 BaseTable，没问题
-✅ 仅 BaseQuery + BaseToolbar 的录入型页面：按此顺序，后接表单区即可
-❌ 顺序颠倒：BaseToolbar 写在 BaseQuery 之前
-
----
-
-## docs/ 文档前置读取清单
-
-生成涉及以下场景的代码时，AI 必须先读取对应文档（按需，不全读）：
-
-| 涉及组件 / 模式             | 必读文档                                      |
-| --------------------------- | --------------------------------------------- |
-| `jh-date` / `jh-date-range` | `docs/jh-date.md` / `docs/jh-date-range.md`   |
-| `jh-file-upload`            | `docs/jh-file-upload.md`                      |
-| `jh-user-picker`            | `docs/jh-user-picker.md`                      |
-| `jh-dept-picker`            | `docs/jh-dept-picker.md`                      |
-| `jh-select`                 | `docs/jh-select.md`                           |
-| `jh-picker`                 | `docs/jh-picker.md`                           |
-| `jh-text`                   | `docs/jh-text.md`                             |
-| `jh-pagination`             | `docs/jh-pagination.md`                       |
-| `jh-drag-row`               | `docs/jh-drag-row.md`                         |
-| HTTP 请求方式               | `docs/request.md`                             |
-| 页面 Hook 模式              | `docs/page-query-hook-best-practices.md`      |
-| BaseQuery / BaseTable 等    | `src/components/remote/{Component}/README.md` |
-| c_formModal / c_listModal   | `src/components/local/{component}/README.md`  |
-
-> AI 在 Pre-flight 声明中明确列出已读文档。
-
----
-
-## AbstractPageQueryHook（强制）
-
-所有页面 `data.ts` **必须** `extends AbstractPageQueryHook`：
-
-```typescript
-import { AbstractPageQueryHook } from '@jhlc/common-core/src/page-hooks/page-query-hook.ts'
-
-export function createPage() {
-  let Page = new (class extends AbstractPageQueryHook {
-    constructor() { super({ url: { list: '...' } }) }
-    queryDef() { return [...] }
-    toolbarDef() { return [...] }
-    columnsDef() { return [...] }
-  })()
-  return Page.create() as any
-}
-```
-
----
-
-## 提取建议触发规则
-
-`convention-audit` 扫描发现 **3+ 个页面**出现相同的未封装 `el-*` 模式时，输出到 `reports/组件提取建议.md`：
-
-```markdown
-| 建议组件名    | 出现次数 | 页面路径                        | 菜单位置（来自文件头）  | 模式描述         |
-| ------------- | -------- | ------------------------------- | ----------------------- | ---------------- |
-| c_statusBadge | 5 处     | src/views/sale/.../index.vue 等 | 销售管理 > 国内贸易订单 | 状态枚举彩色标签 |
-| c_priceFormat | 4 处     | ...                             | ...                     | 千分位金额显示   |
-```
-
-> ⚠️ AI **不自动提取**。人工确认后，触发 template-extract 或手动封装。
-
----
-
-## AI 检查清单（每次代码生成前自查）
-
-- [ ] 查询区使用了 BaseQuery，没有自己写 el-form？
-- [ ] 表格使用了 BaseTable + agGrid + cid，没有用 el-table？
-- [ ] 弹窗使用了 c_formModal / c_listModal，没有手写 el-dialog？
-- [ ] 日期组件用了 jh-date 系列，没有用 el-date-picker？
-- [ ] HTTP 请求都走 `this.getAction / postAction`，没有 import axios？
-- [ ] data.ts 继承了 AbstractPageQueryHook？
-- [ ] 涉及 jh-_ 组件时已读取对应 docs/jh-_.md？
+# 13 — 平台组件合规规范（核心 AI 质量门控）
+
+> **强制度**：🔴 必遵 + 阻断式。
+> 这是防止 AI 绕过平台封装、自由发挥使用 `el-*` 原生组件的核心规则。
+
+---
+
+## 总原则
+
+> **优先使用平台封装组件；无对应封装时才允许使用 `el-*` 原生组件；
+> 跨 3+ 页面相同 `el-*` 模式 → convention-audit 输出"组件提取建议"到 `reports/`，由人工评审决定是否封装。**
+
+---
+
+## 组件强制对照表
+
+| 场景                | 优先使用（有则必用）                          | 替代方案                     |
+| ------------------- | --------------------------------------------- | ---------------------------- |
+| 查询栏              | `BaseQuery`                                   | ❌ el-form 手写查询区        |
+| 工具栏 / 操作按钮行 | `BaseToolbar`                                 | ❌ 自定义按钮排列            |
+| 列表 / 表格         | `BaseTable` (`render-type="agGrid"`)          | ❌ el-table                  |
+| 表单弹窗            | `c_formModal`                                 | ❌ el-dialog + el-form 手写  |
+| 列表选择弹窗        | `c_listModal`                                 | ❌ el-dialog + el-table 手写 |
+| 表单内容分区        | `c_formSections`                              | ❌ 裸分组                    |
+| 分割标题            | `c_spliterTitle`                              | ❌ el-divider                |
+| 复杂路由表单页      | FORM-ROUTE 模板                               | ❌ 完全手写                  |
+| 日期 / 日期范围     | `jh-date` / `jh-date-range`                   | ❌ el-date-picker            |
+| 文件上传            | `jh-file-upload`                              | ❌ el-upload                 |
+| 用户选择            | `jh-user-picker`                              | ❌ 自定义弹窗选人            |
+| 部门选择            | `jh-dept-picker`                              | ❌ 同上                      |
+| 下拉 / 选择器       | `jh-select` / `jh-picker`                     | ❌ el-select 手写 options    |
+| 只读文本展示        | `jh-text`                                     | ❌ span/div 直接渲染         |
+| 分页                | `jh-pagination`                               | ❌ el-pagination             |
+| 上下分栏            | `jh-drag-row`                                 | ❌ 手动 flex/grid            |
+| 左右分割            | `C_Splitter`                                  | ❌ 手动 flex/grid            |
+| 树形面板            | `C_Tree`                                      | ❌ el-tree 手写              |
+| 状态标签            | `C_TagStatus`                                 | ❌ el-tag + 颜色映射         |
+| HTTP 请求           | `getAction/postAction/putAction/deleteAction` | ❌ axios / fetch 直接调用    |
+
+---
+
+## 组件在 template 中的书写顺序
+
+当页面同时存在多个区块时，**有则按下列顺序排列**（**全部可选，不强制必须存在**）：
+
+```
+BaseQuery → BaseToolbar → BaseTable → jh-pagination
+```
+
+✅ 仅有 BaseTable 的页面：直接写 BaseTable，没问题
+✅ 仅 BaseQuery + BaseToolbar 的录入型页面：按此顺序，后接表单区即可
+❌ 顺序颠倒：BaseToolbar 写在 BaseQuery 之前
+
+---
+
+## docs/ 文档前置读取清单
+
+生成涉及以下场景的代码时，AI 必须先读取对应文档（按需，不全读）：
+
+| 涉及组件 / 模式             | 必读文档                                      |
+| --------------------------- | --------------------------------------------- |
+| `jh-date` / `jh-date-range` | `docs/jh-date.md` / `docs/jh-date-range.md`   |
+| `jh-file-upload`            | `docs/jh-file-upload.md`                      |
+| `jh-user-picker`            | `docs/jh-user-picker.md`                      |
+| `jh-dept-picker`            | `docs/jh-dept-picker.md`                      |
+| `jh-select`                 | `docs/jh-select.md`                           |
+| `jh-picker`                 | `docs/jh-picker.md`                           |
+| `jh-text`                   | `docs/jh-text.md`                             |
+| `jh-pagination`             | `docs/jh-pagination.md`                       |
+| `jh-drag-row`               | `docs/jh-drag-row.md`                         |
+| HTTP 请求方式               | `docs/request.md`                             |
+| 页面 Hook 模式              | `docs/page-query-hook-best-practices.md`      |
+| BaseQuery / BaseTable 等    | `src/components/remote/{Component}/README.md` |
+| c_formModal / c_listModal   | `src/components/local/{component}/README.md`  |
+
+> AI 在 Pre-flight 声明中明确列出已读文档。
+
+---
+
+## AbstractPageQueryHook（强制）
+
+所有页面 `data.ts` **必须** `extends AbstractPageQueryHook`：
+
+```typescript
+import { AbstractPageQueryHook } from '@jhlc/common-core/src/page-hooks/page-query-hook.ts'
+
+export function createPage() {
+  let Page = new (class extends AbstractPageQueryHook {
+    constructor() { super({ url: { list: '...' } }) }
+    queryDef() { return [...] }
+    toolbarDef() { return [...] }
+    columnsDef() { return [...] }
+  })()
+  return Page.create() as any
+}
+```
+
+---
+
+## 提取建议触发规则
+
+`convention-audit` 扫描发现 **3+ 个页面**出现相同的未封装 `el-*` 模式时，输出到 `reports/组件提取建议.md`：
+
+```markdown
+| 建议组件名    | 出现次数 | 页面路径                        | 菜单位置（来自文件头）  | 模式描述         |
+| ------------- | -------- | ------------------------------- | ----------------------- | ---------------- |
+| c_statusBadge | 5 处     | src/views/sale/.../index.vue 等 | 销售管理 > 国内贸易订单 | 状态枚举彩色标签 |
+| c_priceFormat | 4 处     | ...                             | ...                     | 千分位金额显示   |
+```
+
+> ⚠️ AI **不自动提取**。人工确认后，触发 template-extract 或手动封装。
+
+---
+
+## AI 检查清单（每次代码生成前自查）
+
+- [ ] 查询区使用了 BaseQuery，没有自己写 el-form？
+- [ ] 表格使用了 BaseTable + agGrid + cid，没有用 el-table？
+- [ ] 弹窗使用了 c_formModal / c_listModal，没有手写 el-dialog？
+- [ ] 日期组件用了 jh-date 系列，没有用 el-date-picker？
+- [ ] HTTP 请求都走 `this.getAction / postAction`，没有 import axios？
+- [ ] data.ts 继承了 AbstractPageQueryHook？
+- [ ] 涉及 jh-_ 组件时已读取对应 docs/jh-_.md？