@agile-team/wl-skills-kit 2.7.3 → 2.9.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [2.9.1] - 2026-05-17
+
+### Added
+
+- **`validate` 三项新检查**（接 v2.9.0 的 standards/14 落地阻断）：
+  - 🔴 `error`：页面 `index.vue` 出现 `<C_Splitter>` 标签
+  - 🔴 `error`：`index.vue` / `data.ts` 出现 `import C_Splitter`
+  - ℹ `info`：提及 `C_Splitter` 的过时注释（如 `已改为 C_Splitter`、`migrate to C_Splitter`、`TODO ... C_Splitter`）
+- **`scripts/lint-skills.js` 新增规则 8**：扫描 `files/**/*.{vue,ts}`，禁止任何 `<C_Splitter>` 标签或 `import C_Splitter`（仅允许 `files/src/components/global/C_Splitter/index.vue` 自身保留废弃声明）。
+- **`.husky/pre-commit` 接入 `lint-skills`**：维护者侧提交时自动守门，从源头阻止 C_Splitter 回潮。
+
+### Notes
+
+- 实战验证：wl-mdata 现网 28 个页面 0 命中（之前已全量迁移）；故意污染测试用例可精准触发 3 项检查。
+- 兼容性：所有新检查均为加法，未改动既有 validate 规则；下游项目无需调整。
+
+## [2.9.0] - 2026-05-17
+
+### Added
+
+- **`files/.github/standards/14-layout-containers.md`**（新规范，🔴 必遵 + 阻断）：布局容器规范。根因解析 `C_Splitter` 在 `onMounted` 中调用 `slots.default()` 冻结 vnode 快照、导致子树响应式完全失效；明确左右分割只用 `jh-drag-col`（`#left`/`#right`），上下分栈只用 `jh-drag-row`（`#top`/`#bottom`）；附迁移对照表、lint 规则、废弃路线图。
+- **`files/src/components/global/C_Splitter/index.vue`** 加入 `@deprecated` 注释 + 运行时 `console.warn`（同会话仅警告一次），引导改用 `jh-drag-col` / `jh-drag-row`。
+
+### Changed
+
+- **`standards/index.md`**：13 条 → 14 条；任务 A（生成新页面）/ B（修改重构）必读集合纳入 `14`。
+- **`standards/13-platform-components.md`** 与 `copilot-instructions.md`：「左右分割」推荐组件由 `C_Splitter` 改为 `jh-drag-col`；明确 `C_Splitter` 已废弃及根因。
+- **TPL-TREE-LIST.md**：模板示例改为 `<jh-drag-col :leftWidth="220">` + `#left`/`#right` 显式插槽；SCSS 去除 `.my-splitter-container :deep` 残留；顶部加「布局硬约束」段。
+- **TPL-DETAIL-TABS.md**：示例由 `<C_Splitter direction="vertical">` 改为 `<jh-drag-row :topHeight="380">` + `#top`/`#bottom`；移除 `import C_Splitter`。
+- **`page-codegen/SKILL.md`** 与 `templates/_index.md`：TREE_LIST 描述同步至 jh-drag-col；上下分栈描述同步至 jh-drag-row。
+- **`prototype-scan/SKILL.md`**：原型扫描产出物示例与说明同步至 jh-drag-col。
+- **`demo/sale/demo/add-demo/`** 与 **`demo/sale/demo/metallurgical-spec/`**：示例 `<C_Splitter>` 全部迁移到 `<jh-drag-row>`；SCSS 注释、README 文案对齐。
+
+### Notes
+
+- 兼容性：`C_Splitter` 源文件保留但加废弃警告，**不删除**，避免外部业务项目升级时立即报错；下一个 major 版本前再做物理移除评估。
+- 参考案例：`wl-ui-sale` 项目所有左树右表/上下分栈页面（material、materialCategory、transactionType、unit、price-maintain、ContractEditTab 等）均使用 `jh-drag-col` / `jh-drag-row`，未踩 `C_Splitter` 冻 vnode 坑——本次规范固化的正是该实战路径。
+
+## [2.8.0] - 2026-05-16
+
+### Added
+
+- **`files/docs/mock-architecture.md`**（新文档）：Mock 架构规范，涵盖目录约定（按业务域分目录 `mock/[域]/[模块].ts`）、`_utils.ts` 共享工具、`ENV_MOCK` 开关机制、STORE 可变数组持久化模式、端点覆盖检查、一键清理流程。
+- **`files/mock/_utils.ts`**（种子文件）：`init`/`update` 自动写入目标项目 `mock/_utils.ts`，提供 `pageResult`/`ok`/`paginate`/`nowStr`/`pick` 五个共享工具，消除各 mock 模块重复定义。
+- **CLI `mock-clean` 命令**：`--domain <name>` 按域清理（如 `mock-clean --domain mdata`）、`--all` 全量清理（保留 `_utils.ts`）、支持 `--dry-run` 预览。清理后提示修改 `ENV_MOCK` 并运行 `validate`。
+
+### Changed
+
+- **`copilot-instructions.md`** 新增 Mock 架构节：目录结构约定、开关机制、URL 对齐、STORE 模式、模块自治原则、`mock-clean` CLI 用法。
+- **`page-codegen/SKILL.md`** 规则修正：规则 9 → `mock/[业务域]/[模块].ts` 按域分目录 + 强制 `import ../_utils`；规则 20 → 自检 `mock/_utils.ts` 存在；规则 21 → 路径格式对齐；禁止 14 → 引用 `docs/mock-architecture.md`。
+- **`validate` 增强**：新增 3 项 mock 架构质量检查 —— `_utils.ts` 存在性（warn）、mock 文件是否按域分目录（info）、是否引用共享工具（info）。输出新增 `ℹ` info 级别图标。
+- **`_best-practices.md`** 场景 6 扩展：从一句话描述 → 完整 mock 架构速览 + 目录树 + 开关/清理说明。
+- **`--domain` / `--all` 加入 `KNOWN_FLAGS`**；flag 校验兼容 `--domain=xxx` 等号格式。
+
+### Notes
+
+- Mock 架构为前端最佳实践固化，已在 wl-mdata 项目验证。新项目 `init` 后即获得 `mock/_utils.ts`；已有项目 `update` 后自动补充。
+
 ## [2.7.3] - 2026-05-13
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.7.3** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.9.1 ** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -23,6 +23,15 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 
 ## 版本亮点
 
+**v2.8.0**：Mock 架构体系固化 + `mock-clean` CLI 命令。
+
+- 新增 `docs/mock-architecture.md` — Mock 目录约定、开关机制、模块化规范、一键清理流程
+- 新增 `mock/_utils.ts` 种子文件 — `init` 自动写入，提供 `pageResult`/`ok`/`paginate`/`nowStr`/`pick`
+- 新增 CLI `mock-clean` 命令 — `--domain <name>` 按域清理、`--all` 全量清理（保留 `_utils.ts`）、`--dry-run` 预览
+- `copilot-instructions.md` 新增 Mock 架构节（目录约定、开关、STORE 模式、URL 对齐）
+- `page-codegen/SKILL.md` 规则 9/20/21 修正为按域分目录 + 强制引用 `_utils`
+- `validate` 增强：检查 `_utils.ts` 存在、mock 文件是否按域分目录、是否引用共享工具
+
 **v2.7.3**：工程质量提升 — MCP tools 单测覆盖、lint-skills 扩展到 core Skill、.gitattributes 消除行尾符噪音、permission-sync SKILL.md 精简。
 
 - 新增 `tests/mcp-tools.test.js`（30 个测试）覆盖 menuSync/dictSync/permissionSync 核心纯函数与参数校验
@@ -53,7 +62,7 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 - **单元测试**：registry / CLI / version-tools 共 18 项覆盖，上面三项防护都有连动验证
 - **单一数据源加固**：`SKILL_COUNT` 从常量改为从 `_registry.md` 动态计算；copilot-instructions 删除内嵌 Skill 表改为指针；dict-sync / code-fix 补 USAGE.md
 
-当前 2.6.x 重点补齐业务理解闭环：原型/详设 → 业务文档 → 接口契约 → 页面代码 → 复扫。
+2.6.x 以来重点补齐业务理解闭环：原型/详设 → 业务文档 → 接口契约 → 页面代码 → 复扫。
 
 - **新增 `business-doc-extract` Skill**：语义级智能触发（不依赖固定关键词），在资料达模块/项目级完整度时建议生成业务文档：
   ```text
@@ -125,16 +134,17 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ├── package.json                          name: @agile-team/wl-skills-kit
 │
 ├── bin/
-│   └── wl-skills.js                      CLI 实现（init / update / clean / check / diff / validate / validate-page / doctor-ui / export）
+│   └── wl-skills.js                      CLI 实现（init / update / clean / check / diff / validate / validate-page / doctor-ui / export / mock-clean）
 │
 ├── files/                                ★★★ 真正会被打包并复制到业务项目的内容 ★★★
-│   └── .github/
-│       ├── copilot-instructions.md       源 AI 主入口（编辑这里，不要编辑业务项目里的副本）
-│       ├── standards/                    13 条规范
-│       ├── skills/                       Skill 目录（含 _compat/ 多编辑器适配源）
-│       ├── guides/                       人读指南
-│       └── reports/                      领域基线模板（菜单/字典/权限）
-│   ├── docs/                             组件 API 文档
+│   ├── .github/
+│   │   ├── copilot-instructions.md       源 AI 主入口（编辑这里，不要编辑业务项目里的副本）
+│   │   ├── standards/                    13 条规范
+│   │   ├── skills/                       Skill 目录（含 _compat/ 多编辑器适配源）
+│   │   ├── guides/                       人读指南
+│   │   └── reports/                      领域基线模板（菜单/字典/权限）
+│   ├── docs/                             组件 API 文档 + Mock 架构规范
+│   ├── mock/                             Mock 共享工具种子（_utils.ts）
 │   └── demo/                             领域样例
 │
 ├── kit-internal/                         ★★ 仅仓库可见，不会安装到业务项目 ★★
@@ -163,7 +173,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 你的业务项目/
 │
 ├── .github/                              ← 来自本包 files/.github/
-│   ├── copilot-instructions.md           Copilot 主入口（精简 ~320 行）
+│   ├── copilot-instructions.md           Copilot 主入口（精简 ~340 行）
 │   ├── standards/                        13 条模块化规范 + index.md 门控
 │   │   ├── 01-toolchain.md
 │   │   ├── 02-code-structure.md
@@ -204,7 +214,11 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ├── .trae/rules/conventions.md            Trae（含 alwaysApply frontmatter）
 ├── .qoder/rules/conventions.md           Qoder
 │
-├── docs/                                 12 个组件 API 文档
+├── mock/                                 ← 来自本包 files/mock/（init 自动写入）
+│   ├── _utils.ts                         共享工具（pageResult / ok / paginate / nowStr / pick）
+│   └── [业务域]/[模块].ts               按域分目录，page-codegen 自动生成
+│
+├── docs/                                 12 个组件 API 文档 + mock-architecture.md
 ├── demo/                                 13 个领域样例
 └── src/
     ├── components/                       全局/局部/远程组件
@@ -254,6 +268,12 @@ npx @agile-team/wl-skills-kit clean
 # 清理但保留 reports/（菜单/字典/权限累积数据）
 npx @agile-team/wl-skills-kit clean --keep-reports
 
+# 清理指定业务域的 mock 文件（保留 _utils.ts）
+npx @agile-team/wl-skills-kit mock-clean --domain mdata
+
+# 清理全部 mock（保留 _utils.ts）
+npx @agile-team/wl-skills-kit mock-clean --all
+
 # 任何命令都可加 --dry-run 预览
 npx @agile-team/wl-skills-kit update --dry-run
 ```
@@ -313,6 +333,7 @@ npx @agile-team/wl-skills-kit update
 | `api-contract`     | ✅ 启用 | `skills/core/api-contract/`     | 生成 api.md 前后端契约                      |
 | `page-codegen`     | ✅ 启用 | `skills/core/page-codegen/`     | 页面骨架生成 + 模板调度                     |
 | `convention-audit` | ✅ 启用 | `skills/core/convention-audit/` | 13 条规范扫描 + 双报告                      |
+| `business-doc-extract` | ✅ 启用 | `skills/core/business-doc-extract/` | 语义触发，业务文档抽取与维护            |
 | `template-extract` | ✅ 启用 | `skills/core/template-extract/` | 现有页面 → 领域模板                         |
 | `menu-sync`        | ✅ 启用 | `skills/sync/menu-sync/`        | 菜单基线 ↔ 后端接口                         |
 | `dict-sync`        | ✅ 启用 | `skills/sync/dict-sync/`        | 字典基线 ↔ 后端接口                         |

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.7.3
+ * wl-skills-kit CLI v2.9.1 
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -13,6 +13,7 @@
  *   validate-page validate 的别名，适用于单页/目录检查
  *   doctor-ui 检查 @agile-team/wk-skills-ui 接入完整性
  *   export    导出 SYS_MENU / SYS_DICT / SYS_PERMISSION 为 xlsx
+ *   mock-clean 清理 mock 文件（按域或全部），保留 _utils.ts
  *   --help    帮助
  *   --dry-run 预览模式（所有命令均支持）
  */
@@ -39,6 +40,7 @@ const KNOWN_COMMANDS = new Set([
   "validate-page",
   "doctor-ui",
   "export",
+  "mock-clean",
 ]);
 const KNOWN_FLAGS = new Set([
   "--dry-run",
@@ -46,6 +48,8 @@ const KNOWN_FLAGS = new Set([
   "--force",
   "--help",
   "-h",
+  "--domain",
+  "--all",
 ]);
 
 const dryRun = args.includes("--dry-run");
@@ -56,7 +60,10 @@ const force = args.includes("--force");
 // 校验所有 flag 是否已知（--help 优先，跳过校验直接显示帮助）
 if (!showHelp) {
   const unknownFlags = args.filter(
-    (a) => a.startsWith("-") && !KNOWN_FLAGS.has(a),
+    (a) =>
+      a.startsWith("-") &&
+      !KNOWN_FLAGS.has(a) &&
+      !KNOWN_FLAGS.has(a.split("=")[0]),
   );
   if (unknownFlags.length > 0) {
     console.error("");
@@ -96,11 +103,14 @@ if (showHelp) {
     validate-page validate 的别名，适用于单页/目录检查
     doctor-ui  检查 @agile-team/wk-skills-ui 接入完整性
     export     导出 reports/SYS_* 数据为 xlsx
+    mock-clean 清理 mock 文件（按域或全部），保留 _utils.ts
 
   选项:
     --dry-run        预览模式，不实际写入/删除任何文件
     --keep-reports   clean 命令保留 .github/reports/（默认一起删除）
     --force          强制执行，跳过同版本检测（忽略已安装状态）
+    --domain <name>  mock-clean 指定要清理的业务域（如 sale、mdata）
+    --all            mock-clean 清理全部 mock（保留 _utils.ts）
     --help           显示帮助
 
   示例:
@@ -116,6 +126,9 @@ if (showHelp) {
     npx @agile-team/wl-skills-kit clean                 清理开发期文件
     npx @agile-team/wl-skills-kit clean --keep-reports  保留 reports/中的菜单/字典数据
     npx @agile-team/wl-skills-kit clean --dry-run       预览将要清理哪些文件
+    npx @agile-team/wl-skills-kit mock-clean --domain mdata  清理 mdata 域 mock
+    npx @agile-team/wl-skills-kit mock-clean --all           清理全部 mock
+    npx @agile-team/wl-skills-kit mock-clean --all --dry-run 预览将要清理的 mock 文件
 
   保护路径（init / update 不覆盖已存在的）:
     .github/reports/   AI 生成报告（团队累积数据，存在则跳过）
@@ -818,6 +831,17 @@ function scanPageDirs(scanRel) {
       hasEmptyOnClick: /onClick\s*:\s*\(\s*[^)]*\s*\)\s*=>\s*\{\s*\}/.test(
         dataContent,
       ),
+      hasCSplitterTag: /<C_Splitter\b/.test(indexContent),
+      hasCSplitterImport:
+        /from\s+["'][^"']*C_Splitter[^"']*["']/.test(indexContent) ||
+        /from\s+["'][^"']*C_Splitter[^"']*["']/.test(dataContent),
+      staleSplitterComments: (
+        (indexContent.match(/(?:已改为|migrate to|TODO).{0,40}C_Splitter/g) || [])
+          .concat(
+            dataContent.match(/(?:已改为|migrate to|TODO).{0,40}C_Splitter/g) ||
+              [],
+          )
+      ).length,
       apiUrls: Array.from(
         dataContent.matchAll(/:\s*["']([^"']+\/[^"']+)["']/g),
       ).map((m) => m[1]),
@@ -853,6 +877,54 @@ function runValidate() {
   const mockContent = mockFiles
     .map((rel) => fs.readFileSync(path.join(TARGET_DIR, rel), "utf8"))
     .join("\n");
+
+  // ── Mock 架构质量检查 ──────────────────────────────────────────────
+  const mockDir = path.join(TARGET_DIR, "mock");
+  const hasMockDir = fs.existsSync(mockDir);
+  const hasUtilsTs =
+    hasMockDir &&
+    (fs.existsSync(path.join(mockDir, "_utils.ts")) ||
+      fs.existsSync(path.join(mockDir, "_utils.js")));
+  if (hasMockDir && mockFiles.length > 0 && !hasUtilsTs) {
+    issues.push({
+      level: "warn",
+      dir: "mock/",
+      text: "缺少 mock/_utils.ts 共享工具文件（建议 wl-skills init 补充）",
+    });
+  }
+  // 检查 mock 文件是否按域分目录（非 _utils 的 ts/js 文件不应直接放在 mock/ 根）
+  for (const rel of mockFiles) {
+    const parts = rel
+      .replace(/\\/g, "/")
+      .replace(/^mock\//, "")
+      .split("/");
+    const basename = parts[parts.length - 1];
+    if (parts.length === 1 && !basename.startsWith("_")) {
+      issues.push({
+        level: "info",
+        dir: "mock/",
+        text:
+          basename +
+          " 直接放在 mock/ 根目录，建议按业务域分子目录（如 mock/sale/" +
+          basename +
+          "）",
+      });
+    }
+  }
+  // 检查 mock 模块文件是否 import _utils
+  for (const rel of mockFiles) {
+    const basename = path.basename(rel);
+    if (basename.startsWith("_")) continue;
+    const content = fs.readFileSync(path.join(TARGET_DIR, rel), "utf8");
+    if (hasUtilsTs && !/_utils/.test(content)) {
+      issues.push({
+        level: "info",
+        dir: rel,
+        text: "未引用 mock/_utils 共享工具，建议统一使用 pageResult/ok/paginate",
+      });
+    }
+  }
+
   for (const page of pages) {
     if (!page.hasDataTs)
       issues.push({
@@ -911,6 +983,27 @@ function runValidate() {
         dir: page.dir,
         text: "存在空 onClick: () => {}",
       });
+    if (page.hasCSplitterTag)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "禁用 <C_Splitter>：请改用 jh-drag-col（左右）/ jh-drag-row（上下），详 standards/14-layout-containers.md",
+      });
+    if (page.hasCSplitterImport)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "禁止 import C_Splitter：该组件已废弃（onMounted 冻 vnode 致响应式失效），详 standards/14",
+      });
+    if (page.staleSplitterComments > 0)
+      issues.push({
+        level: "info",
+        dir: page.dir,
+        text:
+          "发现 " +
+          page.staleSplitterComments +
+          " 处提及 C_Splitter 的过时注释，建议清理",
+      });
     if (page.apiConfigCount > 0 && mockFiles.length === 0)
       issues.push({
         level: "warn",
@@ -933,7 +1026,8 @@ function runValidate() {
   console.log("");
   const errors = issues.filter((issue) => issue.level === "error").length;
   for (const issue of issues) {
-    const icon = issue.level === "error" ? "✖" : "⚠";
+    const icon =
+      issue.level === "error" ? "✖" : issue.level === "info" ? "ℹ" : "⚠";
     console.log("  " + icon + " " + issue.dir + " — " + issue.text);
   }
   if (issues.length === 0) console.log("  ✔ 页面文件完整性检查通过");
@@ -1106,6 +1200,85 @@ function runExport() {
   console.log("");
 }
 
+// ─── mock-clean ──────────────────────────────────────────────────────────
+
+function runMockClean() {
+  console.log("");
+  console.log("  wl-skills-kit v" + PKG.version + "  [mock-clean]");
+  console.log("");
+
+  const mockDir = path.join(TARGET_DIR, "mock");
+  if (!fs.existsSync(mockDir)) {
+    console.log("  ⚠ mock/ 目录不存在，无需清理");
+    console.log("");
+    return;
+  }
+
+  const domainArg = args.find((a) => a.startsWith("--domain"));
+  const cleanAll = args.includes("--all");
+  let domain = "";
+  if (domainArg) {
+    // 支持 --domain=xxx 和 --domain xxx
+    if (domainArg.includes("=")) {
+      domain = domainArg.split("=")[1];
+    } else {
+      const idx = args.indexOf(domainArg);
+      domain = args[idx + 1] || "";
+    }
+  }
+
+  if (!domain && !cleanAll) {
+    console.error("  ✖ 请指定 --domain <name> 或 --all");
+    console.error("  示例: wl-skills mock-clean --domain mdata");
+    console.error("        wl-skills mock-clean --all");
+    console.error("");
+    process.exit(1);
+  }
+
+  // 收集要删除的文件/目录
+  const toRemove = [];
+  if (cleanAll) {
+    // 删除 mock/ 下除 _utils.ts/_utils.js 之外的所有文件和子目录
+    const entries = fs.readdirSync(mockDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith("_")) continue; // 保留 _utils.ts 等
+      toRemove.push(path.join(mockDir, entry.name));
+    }
+  } else {
+    // 删除指定域目录
+    const domainDir = path.join(mockDir, domain);
+    if (!fs.existsSync(domainDir)) {
+      console.log('  ⚠ mock/' + domain + '/ 不存在');
+      console.log("");
+      return;
+    }
+    toRemove.push(domainDir);
+  }
+
+  if (toRemove.length === 0) {
+    console.log("  ✔ 无需清理（仅剩 _utils.ts）");
+    console.log("");
+    return;
+  }
+
+  for (const target of toRemove) {
+    const rel = path.relative(TARGET_DIR, target);
+    if (dryRun) {
+      console.log("  [dry-run] 将删除: " + rel);
+    } else {
+      fs.rmSync(target, { recursive: true, force: true });
+      console.log("  ✔ 已删除: " + rel);
+    }
+  }
+
+  console.log("");
+  if (!dryRun) {
+    console.log("  建议：将 .env.dev 中 ENV_MOCK 改为 false");
+    console.log("  然后运行 wl-skills validate 检查页面无 mock 依赖残留");
+    console.log("");
+  }
+}
+
 // ─── 主路由 ─────────────────────────────────────────────────────────────
 
 switch (command) {
@@ -1134,6 +1307,9 @@ switch (command) {
   case "export":
     runExport();
     break;
+  case "mock-clean":
+    runMockClean();
+    break;
   default:
     console.error(
       '  ✖ 未知命令: "' + command + '"，请使用 --help 查看可用命令',

package/files/.github/copilot-instructions.md

@@ -28,6 +28,24 @@ src/views/[域]/[模块]/[子模块]/[kebab-case目录]/
 - **通用弹窗**（新增/编辑表单，2+ 页面可复用）→ 提取到 `src/components/local/c_xxxModal/`
 - **极个性弹窗**（仅单页面使用，c_modal 无法满足）→ 放在页面 `components/xxxModal.vue`
 
+## Mock 架构（与页面完全解耦）
+
+> 详细规范见 `docs/mock-architecture.md`
+
+```
+mock/
+├── _utils.ts              ← 共享工具（pageResult / ok / paginate / nowStr / pick）
+└── [业务域]/              ← 镜像 src/views 第一级目录
+    └── [模块].ts          ← 每个模块一个文件，export default MockMethod[]
+```
+
+- **开关**：`.env.dev` 中 `ENV_MOCK=true/false`，`vite.config.ts` 中 `viteMockServe({ enable: command === "serve" && config.ENV_MOCK !== "false" })`
+- **解耦**：mock 文件放在项目根 `mock/` 目录，不在 `src/views` 中 import 任何 mock
+- **URL 对齐**：`API_CONFIG` 保持真实路径（如 `/mdata/mdataModel/list`），mock 端点带 `/dev-api` 前缀，关闭 mock 后无需改页面代码
+- **STORE 模式**：`let STORE = Array.from({ length: N }, genRecord)` 可变数组，CRUD 直接修改内存，查询立即可见
+- **按模块自治**：删某业务 mock 只删对应文件，不影响其他模块
+- **一键清理**：`wl-skills mock-clean --domain [域]` 或 `--all`
+
 ## data.ts 核心模式
 
 > 配置化驱动，通过 `API_CONFIG` + `class extends AbstractPageQueryHook` 实现零 API 层开发。
@@ -185,7 +203,7 @@ onMounted(() => select());
 | 部门选择 | jh-dept-picker | @jhlc/jh-ui                      |
 | 文件上传 | jh-file-upload | @jhlc/jh-ui                      |
 | 文本翻译 | jh-text        | @jhlc/jh-ui                      |
-| 左右分割 | C_Splitter     | src/components/global            |
+| 左右分割 | jh-drag-col    | @jhlc/jh-ui (#left/#right slot)  |
 | 树形面板 | C_Tree         | src/components/global            |
 
 ## 组件提取策略

package/files/.github/guides/architecture.md

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）
-> **当前版本**：v2.7.3（2026-05-13）
+> **当前版本**：v2.9.1 （2026-05-17）
 
 ---
 
@@ -478,9 +478,11 @@ AI "假执行"——声称读了规范，实际按惯性输出。没有强制约
 | ---- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------- |
 | v1.x | 5 个 Skill 平铺 + 9 个 TPL 平铺 + 单一超长 copilot-instructions                                                                           | ✅ 已发布 |
 | v2.0 | 规范模块化（13 条）+ 模板分层（universal/domains）+ 报告分类 + Pre-flight + 工具链门控                                                    | ✅ 已发布 |
-| v2.1 | Skill 分级目录（core/sync/ops/domain）+ 多 AI 适配解耦（editors.json）+ 各 Skill USAGE.md + api-contract 真实响应 + 3 个 PLANNED 草稿补全 | ✅ 当前   |
-| v2.2 | dict-sync / permission-sync / code-fix 从 PLANNED → 转正（视后端接口稳定情况）                                                            | ⏳ 规划中 |
-| v2.3 | CI 流水线接入（convention-audit 报告注入 PR 评论）+ Skill 版本感知                                                                        | ⏳ 规划中 |
+| v2.1 | Skill 分级目录（core/sync/ops/domain）+ 多 AI 适配解耦（editors.json）+ 各 Skill USAGE.md + api-contract 真实响应 + 3 个 PLANNED 草稿补全 | ✅ 已发布 |
+| v2.2–2.3 | dict-sync / permission-sync / code-fix 从 PLANNED → 转正 + lint-skills 静态护栏 + MCP 自愈闭环                                      | ✅ 已发布 |
+| v2.6 | business-doc-extract 语义触发 + 业务文档体系 + AGGrid/cid/defineColumns/renderOps 最终标准 + doctor-ui / validate 增强                     | ✅ 已发布 |
+| v2.7 | JH 组件文档全面修正 + MCP tools 单测覆盖 + 场景索引路由 + _mcp-guardrail 自愈闭环 + .gitattributes + 版本一致性自检                       | ✅ 已发布 |
+| v2.8 | Mock 架构体系固化（mock-architecture.md + _utils.ts 种子 + mock-clean CLI + validate mock 质量检查 + 规则修正）                            | ✅ 当前   |
 
 ---
 

package/files/.github/skills/_best-practices.md

@@ -140,7 +140,17 @@ wls_code_scan          ← 概览：页面目录、API_CONFIG、文件完整性
 
 **用户典型话术**："先 mock 一下"、"假数据"、"后端没好先能跑"
 
-**推荐**：`page-codegen` 的 mock-first 规则，生成假数据 + 注释好真实接口对接位置。
+**推荐**：`page-codegen` 的 mock-first 规则。Mock 架构详见 `docs/mock-architecture.md`。
+
+```
+mock/
+├── _utils.ts              ← 共享工具（kit init 自动写入）
+└── [业务域]/[模块].ts     ← 按 src/views 第一级域分目录
+```
+
+- 生成页面自动生成 `mock/[业务域]/[模块].ts`，import `../_utils` 共享工具
+- 开关：`.env.dev` 中 `ENV_MOCK=true/false`，零污染切换
+- 清理：`wl-skills mock-clean --domain [域]` 按域清理，`--all` 全量清理（保留 `_utils.ts`）
 
 ---
 

package/files/.github/skills/core/page-codegen/SKILL.md

@@ -92,7 +92,7 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 
 - `pages.ts` 注册片段
 - **`reports/SYS_MENU_INFO.md`** — 集中式菜单配置，**追加写入**（见下方 §SYS_MENU_INFO 生成规则）
-- `mock/[页面kebab-name].ts`（项目根目录 `mock/` 下，`vite-plugin-mock` 自动加载，与 api.md 的 URL 和字段完全一致）
+- `mock/[业务域]/[模块].ts`（项目根目录 `mock/` 下按域分目录，`vite-plugin-mock` 自动加载，与 api.md 的 URL 和字段完全一致；详见 `docs/mock-architecture.md`）
 
 ---
 
@@ -108,7 +108,7 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 6. 字典字段用 `logicType: BusLogicDataType.dict, logicValue: "dictCode"`
 7. 同时生成 api.md（基于 api-contract Skill 模板）
 8. 提供 pages.ts 注册片段
-9. 同时在 `mock/` 目录下生成对应的 mock 文件（`MockMethod[]` + mockjs，URL 和字段与 api.md 一致，URL 必须带 `/dev-api` 前缀）
+9. 同时在 `mock/[业务域]/` 目录下生成对应的 mock 文件（`MockMethod[]` + mockjs，URL 和字段与 api.md 一致，URL 必须带 `/dev-api` 前缀）。业务域取 `src/views/` 下第一级目录名（如 `sale`、`mdata`）。mock 文件必须 `import { paginate, ok, pick, nowStr } from "../_utils"` 复用共享工具，不可自行重复定义
 10. **查询字段顺序**：`queryDef()` 中字段顺序必须与 page-spec `query` 数组顺序严格一致（即原型从左到右、从上到下）
 11. **表格列顺序**：`columnsDef()` 中列顺序必须与 page-spec `columns` 数组顺序严格一致（`selection` + `index` 在最前，其余按原型表头从左到右）
 12. **按钮顺序与颜色**：`toolbarDef()` 中按钮顺序和 `name`（颜色）必须与 page-spec `toolbar` 数组严格一致（`primary`=蓝底, `danger`=红色, `warning`=橙色, `default`=灰色; `plain: true`=线框）。**"新增"类按钮永远排第一**（如"新增"、"新增申请"），这是产品通用规范
@@ -119,8 +119,8 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 17. **按钮颜色映射**：按钮的 `type` 属性决定颜色，须根据原型按钮颜色或按钮语义映射（见下方 §按钮颜色映射表）
 18. **按钮必须可交互**：所有按钮的 `onClick` 必须有真实处理逻辑，禁止空函数 `() => {}`。通用交互实现见下方 §按钮交互实现规则
 19. **未知交互兜底**：当原型未提供交互细节、且无法从通用模式推断时，`onClick` 中使用 `ElMessage.info("需业务确认交互逻辑")` 作为占位
-20. **生成后依赖自检**：代码生成完成后，检查 `package.json` 是否已安装生成代码所需的依赖（`mockjs`、`vite-plugin-mock`、`lodash-es`、`xlsx` 等），若缺失则提示用户执行安装命令。同时检查 `vite.config.ts` 是否已注册 `viteMockServe`、`mock/` 目录是否存在
-21. **默认 Mock First**：新生成页面默认必须走 `vite-plugin-mock`。必须生成 `mock/[页面kebab-name].ts`，并确保 `API_CONFIG` 中每个 URL 都有对应 mock 端点；只有当用户明确要求关闭 mock 或 `.env.dev` 中 `ENV_MOCK=false` 时，才允许直接联调真实接口。
+20. **生成后依赖自检**：代码生成完成后，检查 `package.json` 是否已安装生成代码所需的依赖（`mockjs`、`vite-plugin-mock`、`lodash-es`、`xlsx` 等），若缺失则提示用户执行安装命令。同时检查 `vite.config.ts` 是否已注册 `viteMockServe`、`mock/_utils.ts` 是否存在（若不存在则从 kit 种子文件补充）
+21. **默认 Mock First**：新生成页面默认必须走 `vite-plugin-mock`。必须生成 `mock/[业务域]/[模块].ts`（import `../_utils` 共享工具），并确保 `API_CONFIG` 中每个 URL 都有对应 mock 端点；只有当用户明确要求关闭 mock 或 `.env.dev` 中 `ENV_MOCK=false` 时，才允许直接联调真实接口。
 22. **Mock URL 必须匹配真实请求**：`API_CONFIG` 保持真实接口路径（如 `/mdata/mdataModel/list`），mock 文件端点必须带 Vite 代理前缀（如 `/dev-api/mdata/mdataModel/list`），这样关闭 mock 后无需修改业务代码。
 23. **页面初始数据必须由 mock 提供**：列表页 `onMounted(() => select())` 后必须能显示模拟数据，不允许生成空白页等待后端接口；`list` 端点返回 `{ code: 2000, data: { records, total, size, current } }`。
 24. **必须使用 wk-skills-ui runtime 风格**：当项目安装了 `@agile-team/wk-skills-ui` 时，列表列定义必须使用 `defineColumns()`，操作列必须使用 `renderOps()`，状态/字典列优先使用 runtime 渲染器或 `logicType=dict` 自动映射；不可退回默认纯文本/空函数风格。
@@ -145,7 +145,7 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 11. **❌ 禁止表单控件宽度不统一**：`jh-select`、`jh-date`、`el-input-number`、`jh-file-upload` 默认宽度可能与 `el-input` 不一致，必须在 scoped style 中用 `:deep()` 统一设为 `width: 100%`（详见 §表单页 UI 细节规范）
 12. **❌ 禁止表单页无滚动**：独立路由表单页内容超出视口时必须可滚动，`.app-page-container` 须设 `overflow-y: auto`（**不要加 `height: 100%`，全局已有 `height: calc(100vh - 100px)`，叠加会导致双滚动条**）
 13. **❌ 禁止内联 style 散落**：所有页面/组件样式统一写在 `index.scss` 中（便于复用和移动），不可在 template 中大量使用内联 `style="..."`
-14. **❌ 禁止生成无 mock 的页面**：只写 `API_CONFIG` 但不写 `mock/*.ts` 属于生成失败。
+14. **❌ 禁止生成无 mock 的页面**：只写 `API_CONFIG` 但不写 `mock/[业务域]/*.ts` 属于生成失败。mock 文件必须按域分目录、import `_utils` 共享工具（详见 `docs/mock-architecture.md`）。
 15. **❌ 禁止生成空 onClick**：`onClick: () => {}` 属于生成失败；未知逻辑也必须用 `ElMessage.info(...)` 明示。
 16. **❌ 禁止忽略 wk-skills-ui**：项目已安装 `@agile-team/wk-skills-ui` 时，不使用 `defineColumns/renderOps` 属于生成失败。
 17. **❌ 禁止 BaseTable 非 AGGrid**：业务列表中 `<BaseTable>` 未写 `render-type="agGrid"` 或缺少 `cid/:cid` 属于生成失败。
@@ -1065,7 +1065,7 @@ SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
 | LIST | templates/universal/TPL-LIST.md | 标准查询+工具栏+表格+分页 | mmwr-customer-archive |
 | MASTER_DETAIL | templates/universal/TPL-MASTER-DETAIL.md | jh-drag-row 主从表，双击联动 | ompt-ht-plan-order |
 | TREE_LIST | templates/universal/TPL-TREE-LIST.md | 左侧 C_Tree + 右侧列表 | — |
-| DETAIL_TABS | templates/universal/TPL-DETAIL-TABS.md | C_Splitter 上Tab表单+下子表 | add-demo / domestic-trade-order |
+| DETAIL_TABS | templates/universal/TPL-DETAIL-TABS.md | jh-drag-row 上Tab表单+下子表 | add-demo / domestic-trade-order |
 | FORM_ROUTE | templates/universal/TPL-FORM-ROUTE.md | 复杂表单独立路由（非弹窗） | mmwr-customer-apply-add-form |
 | CHANGE_HISTORY | templates/universal/TPL-CHANGE-HISTORY.md | 左历史时间线+右变更详情 | mmwr-customer-apply-change-history |
 | RECORD_FORM | templates/universal/TPL-RECORD-FORM.md | BaseQuery选主记录+Form+Table无分页 | mmsm-convert-progress |

package/files/.github/skills/core/page-codegen/templates/_index.md

@@ -11,7 +11,7 @@
 | LIST            | `templates/universal/TPL-LIST.md`           | 标准列表页（查询+工具栏+表格+分页）     |
 | FORM_ROUTE      | `templates/universal/TPL-FORM-ROUTE.md`     | 复杂表单独立路由页（多 Tab / 多子表）   |
 | MASTER_DETAIL   | `templates/universal/TPL-MASTER-DETAIL.md`  | 主从表页（jh-drag-row 上下分栏）        |
-| TREE_LIST       | `templates/universal/TPL-TREE-LIST.md`      | 左树右列表页（C_Splitter 布局）         |
+| TREE_LIST       | `templates/universal/TPL-TREE-LIST.md`      | 左树右列表页（jh-drag-col 布局）         |
 | DETAIL_TABS     | `templates/universal/TPL-DETAIL-TABS.md`    | 详情 Tab 页（上方表单 + 下方 Tab 子表） |
 | CHANGE_HISTORY  | `templates/universal/TPL-CHANGE-HISTORY.md` | 变更历史比对页（时间线 + 字段差异）     |
 | RECORD_FORM     | `templates/universal/TPL-RECORD-FORM.md`    | 录入型实绩页（无分页，查询 + 内联表单） |

package/files/.github/skills/core/page-codegen/templates/universal/TPL-DETAIL-TABS.md

@@ -3,15 +3,16 @@
 > 见 SKILL.md 主文件（约束 + 按钮规则 + Mock 规范等共用规则）。
 
 > 适用场景：编辑/维护页面，上半区为多 Tab 表单（基本信息/客户信息/其他信息），下半区为子项表格。
-> 布局核心：`C_Splitter direction="vertical"` 垂直分割上下区域。
+> **布局核心**：`jh-drag-row :topHeight="..."` 垂直分割上下区域（严禁 `C_Splitter`，详 standards/14-layout-containers.md）。
 > **参考标杆**：`src/views/sale/demo/add-demo/`、`src/views/sale/demo/domestic-trade-order-mainten/`
 
 #### index.vue
 
 ```vue
 <template>
-  <div class="app-container app-page-container">
-    <C_Splitter direction="vertical">
+  <div class="app-container app-page-container" style="height: 100%">
+    <jh-drag-row :topHeight="380">
+      <template #top>
       <!-- 上：表单区 -->
       <el-card shadow="never" class="form-card">
         <!-- 页头工具栏 -->
@@ -66,7 +67,9 @@
           </el-tab-pane>
         </el-tabs>
       </el-card>
+      </template>
 
+      <template #bottom>
       <!-- 下：子项表格区 -->
       <el-card shadow="never" class="items-card">
         <div class="items-section">
@@ -97,13 +100,14 @@
           />
         </div>
       </el-card>
-    </C_Splitter>
+      </template>
+    </jh-drag-row>
   </div>
 </template>
 
 <script setup lang="ts">
 import { onMounted } from "vue";
-import C_Splitter from "@/components/global/C_Splitter/index.vue";
+// ⚠️ 不再需要 import C_Splitter——jh-drag-row 是 @jhlc/jh-ui 全局注册组件
 import {
   form,
   rules,