@agile-team/wl-skills-kit 2.11.1 → 2.11.3

package/files/.wl-skills/src/types/page.ts

@@ -1,24 +1,24 @@
-/*
- * @Author: ChenYu ycyplus@gmail.com
- * @Date: 2026-01-02 11:00:00
- * @LastEditors: ChenYu ycyplus@gmail.com
- * @LastEditTime: 2026-01-02 11:00:00
- * @FilePath: \cx-ui-sale\src\types\page.ts
- * @Description: 页面常用类型统一导出
- * Copyright (c) 2026 by CHENY, All Rights Reserved 😎.
- */
-
-// 页面 Hook
-export { AbstractPageQueryHook } from "@jhlc/common-core/src/page-hooks/page-query-hook";
-
-// 查询组件类型
-export { BaseQueryItemDesc } from "@jhlc/common-core/src/components/form/base-query/type";
-
-// 工具栏类型
-export { ActionButtonDesc } from "@jhlc/common-core/src/components/toolbar/type";
-
-// 表格类型
-export { TableColumnDesc } from "@jhlc/common-core/src/components/table/base-table/type";
-
-// 业务逻辑数据类型
-export { BusLogicDataType } from "@jhlc/types/src/logical-data";
+/*
+ * @Author: ChenYu ycyplus@gmail.com
+ * @Date: 2026-01-02 11:00:00
+ * @LastEditors: ChenYu ycyplus@gmail.com
+ * @LastEditTime: 2026-01-02 11:00:00
+ * @FilePath: \cx-ui-sale\src\types\page.ts
+ * @Description: 页面常用类型统一导出
+ * Copyright (c) 2026 by CHENY, All Rights Reserved 😎.
+ */
+
+// 页面 Hook
+export { AbstractPageQueryHook } from "@jhlc/common-core/src/page-hooks/page-query-hook";
+
+// 查询组件类型
+export { BaseQueryItemDesc } from "@jhlc/common-core/src/components/form/base-query/type";
+
+// 工具栏类型
+export { ActionButtonDesc } from "@jhlc/common-core/src/components/toolbar/type";
+
+// 表格类型
+export { TableColumnDesc } from "@jhlc/common-core/src/components/table/base-table/type";
+
+// 业务逻辑数据类型
+export { BusLogicDataType } from "@jhlc/types/src/logical-data";

package/files/.wl-skills/standards/04-coding-basics.md

@@ -5,7 +5,7 @@
 
 ---
 
-## 13 条核心约定
+## 14 条核心约定
 
 1. **变量声明**：优先 `const`，必须重新赋值时用 `let`，禁止 `var`
 2. **解构赋值**：优先使用 `const { a, b } = obj`，而非 `obj.a` / `obj.b`
@@ -20,6 +20,44 @@
 11. **v-for**：必须设置 `:key`，优先用业务主键 id 而非 index
 12. **指令缩写**：统一 `:`（v-bind）、`@`（v-on）、`#`（v-slot）
 13. **this 别名**：`<script setup>` 中无 `this`；旧 Options API 中的 `this` 别名用 `self`
+14. **圈复杂度**：单函数圈复杂度 ≤ **10**（Mcabe），尽量小；超阈值必须拆分
+
+---
+
+## 圈复杂度（Mcabe）细则
+
+> 对应确定性执行器 **R13**（`wl-skills validate` AST 引擎，阻断级）。
+
+- **定义**：`复杂度 = 1 + 决策点数`，决策点 = `if` / `case` / `for` / `for-in` / `for-of` / `while` / `do-while` / `catch` / 三元 `?:` / `&&` / `||` / `??`。与 ESLint `complexity` 规则完全一致。
+- **范围**：`index.vue <script>` 与 `data.ts` 中的**每一个**函数 / 方法 / 箭头函数独立计算（嵌套函数单独计，不叠加到父函数）。
+- **上限**：`10`。`> 10` 由 R13 报 error 阻断提交。
+- **豁免**：单函数加 `// wl-skills:ignore R13` 可精确豁免（仅限确有复杂第三方对接场景，需注释说明）。
+
+**降低复杂度的手法**（按优先级）：
+
+1. **提前 return**（Guard Clause）替代嵌套 `if`
+2. 查表驱动（`map[cond]()`）替代 `if-else` / `switch` 长链
+3. 按职责抽取子函数（每个子函数单一职责）
+4. 策略 / 状态机模式消除多分支
+
+**示例**：
+
+```typescript
+// ❌ 复杂度 6，难读
+function getLabel(type: string, v: number) {
+  if (type === "a") { if (v > 0) { return "A+" } else { return "A-" } }
+  else if (type === "b") { if (v > 0) { return "B+" } else { return "B-" } }
+  return v > 0 ? "OTHER+" : "OTHER-"
+}
+
+// ✅ 复杂度 2，查表驱动
+const LABEL_MAP = { a: ["A-", "A+"], b: ["B-", "B+"] } as const
+function getLabel(type: string, v: number) {
+  const pair = LABEL_MAP[type as keyof typeof LABEL_MAP]
+  if (pair) return pair[v > 0 ? 1 : 0]
+  return v > 0 ? "OTHER+" : "OTHER-"
+}
+```
 
 ---
 

package/files/.wl-skills/standards/09-typescript.md

@@ -1,7 +1,29 @@
 # 09 — TypeScript 类型规范
 
-> **强制度**：🟡 建议。
-> 项目使用 `strict: false` 宽松模式起步。
+> **强制度**：🔴 必遵。
+> 项目使用 `strict: false` 宽松模式起步，但**类型错误零容忍**：`vue-tsc --noEmit` 必须 0 error。
+
+---
+
+## 类型错误零容忍（R14）
+
+> 对应确定性执行器 **R14**（`wl-skills validate --typecheck` / MCP `wls_validate_page {typecheck:true}`，阻断级）。
+
+- **基线**：`vue-tsc --noEmit`（无 `vue-tsc` 时回退 `tsc --noEmit`）必须退出码 0。
+- **何时跑**：
+  - **CI 必跑**：流水线中 `wl-skills validate --typecheck`（与 `--strict` 组合），任何 TS error 阻断合并
+  - **pre-push / 发版前必跑**：本地 `pnpm wl-skills validate --typecheck`
+  - **pre-commit 不建议开启**：全量类型检查较慢，避免拖慢日常提交
+- **优雅降级**：项目无 `tsconfig.json` 或未安装 `vue-tsc` / `tsc` 时，R14 输出 warn 不阻断（提示安装后纳入 CI）。
+- **为什么必遵**：类型错误在运行时才暴露，成本高；CI 阶段拦截是 ROI 最高的质量门。
+
+```bash
+# CI / 发版前
+wl-skills validate --typecheck --strict
+
+# MCP（AI 编辑器中）
+wls_validate_page({ path: "src/views", typecheck: true })
+```
 
 ---
 
@@ -68,4 +90,5 @@ interface Customer {
 | -------------------- | ------------------------------------------ |
 | 已有 `tsconfig.json` | ✅ 直接安装 git-standards，零冲突          |
 | 无 TS 环境           | 先 `tsc --init` 初始化，再装 git-standards |
-| ESLint TS 规则       | `warn` 级别，不阻断提交，仅作质量提示      |
+
+> ESLint TS 规则维持 `warn`（风格类，不阻断提交）；**类型错误阻断由 R14 兜底**（`vue-tsc --noEmit` 非零退出码 → error），二者职责分离：ESLint 管风格，R14 管正确性。

package/files/.wl-skills/standards/12-base-table.md

@@ -132,10 +132,62 @@ subColumnsDef(): TableColumnDesc<any>[] {
 
 ### 豁免规则
 
-- 豁免场景仍**优先使用 `BaseTable`**（非 AGGrid 模式），而非裸 `el-table`
-- 豁免场景如果支持列持久化，仍**必须有 `cid`**
-- 审查报告中豁免项必须标注**原因**，避免滥用
-- 如果豁免场景后续升级为主列表，必须迁移到 AGGrid
+> **两层豁免机制**：单文件注释豁免（精确）+ 项目级配置豁免（批量）。标准列表页不受豁免影响，仍强制 `BaseTable + AGGrid`。
+
+#### 优先级：标准列表 vs 特殊场景
+
+| 场景类型 | 渲染要求 | R3（el-table）/ AGGrid 卡控 |
+|---|---|---|
+| **标准列表页**（分页查询、台账、核心业务列表） | `BaseTable` + `render-type="agGrid"` + `cid` | 🔴 强制，不可豁免 |
+| **BaseTable 可胜任的特殊表格**（弹窗小表、只读展示、嵌套子表） | `BaseTable`（非 AGGrid 也可），尽量带 `cid` | 🟢 豁免 AGGrid（R3 仍建议改 BaseTable） |
+| **BaseTable 受限的复杂场景**（表单/设计器内嵌表格、行内编辑明细表、特殊合并单元格/复杂行列布局） | 优先 `BaseTable`；确实受限时降级 `el-table` | 🟢 可豁免 R3（需登记豁免原因） |
+| **平台封装组件内部** | 按需 | 🟢 豁免 R3（封装层单独评审） |
+
+> 判定原则：**先用 BaseTable**；BaseTable 确实受限不能满足时，才降级 `el-table`，不直接裸用。
+
+#### 豁免方式一：单文件注释（精确到文件）
+
+在特殊文件内加注释标记，精确豁免该文件的指定规则（适合个别页面）：
+
+```vue
+<!-- index.vue -->
+<!-- wl-skills:ignore R3 -->   ← 整页豁免 R3（el-table 检测）
+<template>
+  <el-table> ... </el-table>   <!-- 表单设计器内嵌表格，AGGrid 内联编辑受限 -->
+</template>
+```
+
+```typescript
+// data.ts
+// wl-skills:ignore R10         ← 豁免该文件的 R10
+```
+
+#### 豁免方式二：项目级配置（批量到目录，推荐用于整片特殊场景）
+
+项目根放 `.wl-skills-validate.json`（kit 不主动创建，零功能影响；详见 `docs/validate-exempt.md`）：
+
+```json
+{
+  "exemptions": [
+    {
+      "paths": ["src/views/produce/designer"],
+      "rules": ["R3", "R10"],
+      "reason": "表单设计器内嵌表格，BaseTable AGGrid 内联编辑受限"
+    },
+    {
+      "paths": ["src/views/sale/order-edit/**"],
+      "rules": ["R3"],
+      "reason": "订单行内编辑明细表，AGGrid 行编辑成本高于收益"
+    }
+  ]
+}
+```
+
+- `paths`：页面目录前缀，支持 `/**` glob；命中该目录及其子目录
+- `rules`：规则编号（`R3`/`R10` 等），大小写不敏感
+- `reason`：**必填审计字段**，避免滥用
+
+> ⚠️ 豁免不是放任。豁免项升级为主列表页时，必须迁移回 `BaseTable + AGGrid`。`convention-audit` 审计时列出所有豁免项供人工复核。
 
 ### 审查报告中的分类
 

package/files/.wl-skills/standards/13-platform-components.md

@@ -116,6 +116,7 @@ export function createPage() {
 
 - [ ] 查询区使用了 BaseQuery，没有自己写 el-form？
 - [ ] 表格使用了 BaseTable + agGrid + cid，没有用 el-table？
+      （BaseTable 受限的特殊场景如表单/设计器内嵌表格，登记豁免后可用 el-table，见 standards/12 §豁免规则）
 - [ ] 弹窗使用了 c_formModal / c_listModal，没有手写 el-dialog？
 - [ ] 日期组件用了 jh-date 系列，没有用 el-date-picker？
 - [ ] HTTP 请求都走 `this.getAction / postAction`，没有 import axios？

package/files/.wl-skills/standards/index.md

@@ -17,7 +17,7 @@
 | 06   | `06-security.md`            | 安全规范               | 🔴 必遵        |
 | 07   | `07-config.md`              | 配置管理               | 🔴 必遵        |
 | 08   | `08-git.md`                 | Git 分支 & 提交 + 审计 | 🔴 必遵        |
-| 09   | `09-typescript.md`          | TypeScript 类型        | 🟡 建议        |
+| 09   | `09-typescript.md`          | TypeScript 类型 + 类型错误零容忍 | 🔴 必遵 + 阻断 |
 | 10   | `10-pinia.md`               | Pinia 状态管理         | 🔴 必遵        |
 | 11   | `11-form-validation.md`     | 表单与校验             | 🔴 必遵        |
 | 12   | `12-base-table.md`          | BaseTable + AGGrid cid | 🔴 必遵        |
@@ -79,7 +79,7 @@
 ✅ 已读取 standards/13-platform-components.md → 平台组件对照表
 ```
 
-> **不要** 一次性读取全部 13 条。错误示范：`✅ 已读取 standards/01 ~ standards/13`（浪费 token，违反懒加载原则）。
+> **不要** 一次性读取全部 14 条。错误示范：`✅ 已读取 standards/01 ~ standards/14`（浪费 token，违反懒加载原则）。
 
 ---
 

package/files/.wl-skills/templates/README.md

@@ -1,44 +1,44 @@
-# demo — 领域样例索引
-
-> AI 学习参考 + 开发者速查。每个样例均可独立运行（Mock 数据，不依赖后端）。
-> 安装 wl-skills-kit 后自动导入此目录，**不要在此目录下放业务代码**。
-
----
-
-## produce/aiflow/ — 生产域（客户档案模块，8 个页面）
-
-| 目录                                  | 模板类型       | 说明                                |
-| ------------------------------------- | -------------- | ----------------------------------- |
-| `mmwr-customer-archive/`              | LIST + Tabs    | 客户档案列表（带 c_formModal 弹窗） |
-| `mmwr-temp-customer-archive/`         | LIST           | 临时客户档案列表                    |
-| `mmwr-customer-apply-add/`            | LIST           | 客户新增申请列表                    |
-| `mmwr-customer-apply-add-form/`       | FORM_ROUTE     | 客户新增申请表单（独立路由）        |
-| `mmwr-customer-apply-change/`         | LIST           | 客户变更申请列表                    |
-| `mmwr-customer-apply-change-form/`    | FORM_ROUTE     | 客户变更申请表单（独立路由）        |
-| `mmwr-customer-apply-change-history/` | CHANGE_HISTORY | 客户变更历史比对                    |
-| `mmwr-customer-detail/`               | DETAIL_TABS    | 客户详情（多 Tab）                  |
-
-## sale/.wl-skills/templates/ — 销售域（平台默认样例，5 个页面）
-
-| 目录                     | 模板类型      | 说明                             |
-| ------------------------ | ------------- | -------------------------------- |
-| `domestic-trade-order/`  | LIST          | 标准内贸订单列表                 |
-| `metallurgical-spec/`    | MASTER_DETAIL | 冶金规范（jh-drag-row 上下分栏） |
-| `add-.wl-skills/templates/`              | FORM_ROUTE    | 新增表单演示（c_formSections）   |
-| `billet-flame-cut-plan/` | LIST          | 坯料火焰切割计划列表             |
-| `heat-batch-return/`     | LIST + Modal  | 炉批退判（含自定义弹窗）         |
-
----
-
-## 样例标准
-
-每个目录必须包含：
-
-- `index.vue` — 视图层（纯模板 + createPage 解构）
-- `data.ts` — 逻辑层（AbstractPageQueryHook 或 composable）
-- `index.scss` — 样式层
-- `api.md` — 接口约定（可选）
-
-## 贡献
-
-新增样例请放在 `.wl-skills/templates/{domain}/{submodule}/{page-name}/`，提 PR 到 wl-skills-kit 仓库。
+# demo — 领域样例索引
+
+> AI 学习参考 + 开发者速查。每个样例均可独立运行（Mock 数据，不依赖后端）。
+> 安装 wl-skills-kit 后自动导入此目录，**不要在此目录下放业务代码**。
+
+---
+
+## produce/aiflow/ — 生产域（客户档案模块，8 个页面）
+
+| 目录                                  | 模板类型       | 说明                                |
+| ------------------------------------- | -------------- | ----------------------------------- |
+| `mmwr-customer-archive/`              | LIST + Tabs    | 客户档案列表（带 c_formModal 弹窗） |
+| `mmwr-temp-customer-archive/`         | LIST           | 临时客户档案列表                    |
+| `mmwr-customer-apply-add/`            | LIST           | 客户新增申请列表                    |
+| `mmwr-customer-apply-add-form/`       | FORM_ROUTE     | 客户新增申请表单（独立路由）        |
+| `mmwr-customer-apply-change/`         | LIST           | 客户变更申请列表                    |
+| `mmwr-customer-apply-change-form/`    | FORM_ROUTE     | 客户变更申请表单（独立路由）        |
+| `mmwr-customer-apply-change-history/` | CHANGE_HISTORY | 客户变更历史比对                    |
+| `mmwr-customer-detail/`               | DETAIL_TABS    | 客户详情（多 Tab）                  |
+
+## sale/.wl-skills/templates/ — 销售域（平台默认样例，5 个页面）
+
+| 目录                     | 模板类型      | 说明                             |
+| ------------------------ | ------------- | -------------------------------- |
+| `domestic-trade-order/`  | LIST          | 标准内贸订单列表                 |
+| `metallurgical-spec/`    | MASTER_DETAIL | 冶金规范（jh-drag-row 上下分栏） |
+| `add-.wl-skills/templates/`              | FORM_ROUTE    | 新增表单演示（c_formSections）   |
+| `billet-flame-cut-plan/` | LIST          | 坯料火焰切割计划列表             |
+| `heat-batch-return/`     | LIST + Modal  | 炉批退判（含自定义弹窗）         |
+
+---
+
+## 样例标准
+
+每个目录必须包含：
+
+- `index.vue` — 视图层（纯模板 + createPage 解构）
+- `data.ts` — 逻辑层（AbstractPageQueryHook 或 composable）
+- `index.scss` — 样式层
+- `api.md` — 接口约定（可选）
+
+## 贡献
+
+新增样例请放在 `.wl-skills/templates/{domain}/{submodule}/{page-name}/`，提 PR 到 wl-skills-kit 仓库。

package/files/.wl-skills/templates/produce/aiflow/mmwr-customer-apply-add/api.md

@@ -1,54 +1,54 @@
-# 新增申请列表 — 接口约定
-
-## 服务缩写：`sale`  资源名：`customerApply`
-
-### 1. 分页查询
-
-- **方法**：POST  
-- **URL**：`/sale/customerApply/addList`  
-- **请求体**：`{ customerCode, approvalProduct, applyOrg, customerName, applyType, applyDept, applicant, approvalStatus, applyDateStart, applyDateEnd, verifyStatus, current, size }`  
-- **响应**：`{ code:2000, data:{ records:[], total, current, size } }`
-
-### 2. 删除
-
-- **方法**：POST  
-- **URL**：`/sale/customerApply/remove`  
-- **请求体**：`{ ids:[] }`
-
-### 3. 提交审批
-
-- **方法**：POST  
-- **URL**：`/sale/customerApply/submit`  
-- **请求体**：`{ ids:[] }`
-
-### 4. 撤回
-
-- **方法**：POST  
-- **URL**：`/sale/customerApply/withdraw`  
-- **请求体**：`{ ids:[] }`
-
-### 5. 导出
-
-- **方法**：GET  
-- **URL**：`/sale/customerApply/export`
-
----
-
-## 列表字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| id | string | 主键 |
-| applyCode | string | 申请编码（蓝色链接列） |
-| applyType | string | 申请类型 |
-| customerCode | string | 客户编码 |
-| customerName | string | 客户名称 |
-| approvalProduct | string | 审批产品别 |
-| applyReason | string | 申请原因 |
-| applicant | string | 申请人 |
-| applyDept | string | 申请部门 |
-| applyOrg | string | 申请组织 |
-| creator | string | 创建人 |
-| createTime | string | 创建时间 |
-| approvalStatus | string | 审批状态（色块）|
-| verifyStatus | string | 核实状态（色块）|
+# 新增申请列表 — 接口约定
+
+## 服务缩写：`sale`  资源名：`customerApply`
+
+### 1. 分页查询
+
+- **方法**：POST  
+- **URL**：`/sale/customerApply/addList`  
+- **请求体**：`{ customerCode, approvalProduct, applyOrg, customerName, applyType, applyDept, applicant, approvalStatus, applyDateStart, applyDateEnd, verifyStatus, current, size }`  
+- **响应**：`{ code:2000, data:{ records:[], total, current, size } }`
+
+### 2. 删除
+
+- **方法**：POST  
+- **URL**：`/sale/customerApply/remove`  
+- **请求体**：`{ ids:[] }`
+
+### 3. 提交审批
+
+- **方法**：POST  
+- **URL**：`/sale/customerApply/submit`  
+- **请求体**：`{ ids:[] }`
+
+### 4. 撤回
+
+- **方法**：POST  
+- **URL**：`/sale/customerApply/withdraw`  
+- **请求体**：`{ ids:[] }`
+
+### 5. 导出
+
+- **方法**：GET  
+- **URL**：`/sale/customerApply/export`
+
+---
+
+## 列表字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | string | 主键 |
+| applyCode | string | 申请编码（蓝色链接列） |
+| applyType | string | 申请类型 |
+| customerCode | string | 客户编码 |
+| customerName | string | 客户名称 |
+| approvalProduct | string | 审批产品别 |
+| applyReason | string | 申请原因 |
+| applicant | string | 申请人 |
+| applyDept | string | 申请部门 |
+| applyOrg | string | 申请组织 |
+| creator | string | 创建人 |
+| createTime | string | 创建时间 |
+| approvalStatus | string | 审批状态（色块）|
+| verifyStatus | string | 核实状态（色块）|