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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [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.8.0** — 一键将 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.8.0
  *
  * 命令:
  *   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 生成报告（团队累积数据，存在则跳过）
@@ -853,6 +866,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({
@@ -933,7 +994,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 +1168,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 +1275,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 层开发。

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

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）
-> **当前版本**：v2.7.3（2026-05-13）
+> **当前版本**：v2.8.0（2026-05-16）
 
 ---
 
@@ -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` 属于生成失败。

package/files/docs/mock-architecture.md

@@ -0,0 +1,321 @@
+# Mock 架构规范
+
+> **适用范围**：所有基于 wl-skills-kit 的 Vue 3 业务子应用
+> **技术依赖**：`vite-plugin-mock` + `mockjs`
+> **源码参考**：wl-mdata 项目实践（v2.7.x 基线）
+
+---
+
+## 一、设计目标
+
+| 目标 | 实现方式 |
+|---|---|
+| **与页面代码完全解耦** | Mock 文件独立放在 `mock/` 目录，不在 `src/views` 中 import 任何 mock |
+| **开关零污染** | `ENV_MOCK=false` → vite-plugin-mock 整体不挂载，不拦截任何请求 |
+| **按业务模块自治** | 每个模块一个 mock 文件，删除模块只需删除对应 mock 文件 |
+| **共享工具复用** | `_utils.ts` 提供标准响应构造器，子模块 import 而非重复定义 |
+| **会话内数据可见** | `let STORE = [...]` 可变数组，CRUD 操作直接修改内存，下次查询可见 |
+| **跨会话重置** | dev server 重启时模块重新加载，STORE 恢复初始状态 |
+| **真实接口无缝切换** | `API_CONFIG` 保持真实路径，mock 端点带 `/dev-api` 前缀，关闭 mock 后无需改代码 |
+
+---
+
+## 二、目录结构
+
+```
+项目根目录/
+├── .env.dev                    ← ENV_MOCK=true（Mock 总开关）
+├── vite.config.ts              ← viteMockServe({ mockPath: "./mock", enable: ... })
+├── mock/
+│   ├── _utils.ts               ← 共享工具（pageResult / ok / paginate / nowStr / pick）
+│   └── [业务域]/               ← 镜像 src/views 第一级目录
+│       ├── [模块].ts           ← 一个模块可覆盖多个相关页面
+│       ├── [模块].ts
+│       └── ...
+└── src/
+    └── views/
+        └── [业务域]/
+            └── [模块]/
+                └── [页面]/
+                    ├── index.vue
+                    ├── data.ts   ← API_CONFIG 保持真实路径
+                    └── api.md
+```
+
+**命名约定**：
+
+| src/views 路径 | mock 文件路径 | 说明 |
+|---|---|---|
+| `src/views/mdata/model/` | `mock/mdata/model.ts` | 一个模块一个文件 |
+| `src/views/mdata/management/` | `mock/mdata/master.ts` | 可按业务语义命名 |
+| `src/views/sale/customer/` | `mock/sale/customer.ts` | 镜像第一级域 |
+| `src/views/sale/contract/` | `mock/sale/contract.ts` | 同域不同模块 |
+
+> **一个 mock 文件可覆盖同模块下多个页面的接口**，只要它们属于同一业务实体（如"客户管理"和"客户申请"可共用 `mock/sale/customer.ts`）。
+
+---
+
+## 三、`_utils.ts` 共享工具
+
+> 该文件由 `wl-skills init` 自动写入 `mock/_utils.ts`。无 `export default`，vite-plugin-mock 会安全跳过。
+
+```typescript
+import Mock from "mockjs";
+
+export const Random = Mock.Random;
+export const pick = <T>(arr: T[]): T => Random.pick(arr) as T;
+export const bool = () => Random.boolean();
+
+/** 标准分页响应 */
+export function pageResult(records: any[], total: number) {
+  return { code: 2000, message: "操作成功", data: { records, total } };
+}
+
+/** 标准成功响应 */
+export function ok(data: any = null) {
+  return { code: 2000, message: "操作成功", data };
+}
+
+/** 通用分页截取（兼容 pageNo/current、pageSize/size） */
+export function paginate(pool: any[], query: any) {
+  const current = Number(query?.current || query?.pageNo) || 1;
+  const size = Number(query?.size || query?.pageSize) || 10;
+  const start = (current - 1) * size;
+  return pageResult(pool.slice(start, start + size), pool.length);
+}
+
+/** 当前时间字符串 */
+export function nowStr() {
+  return new Date().toLocaleString("zh-CN", { hour12: false }).replace(/\//g, "-");
+}
+```
+
+所有 mock 模块文件统一通过 `import { paginate, ok, pick, nowStr } from "../_utils"` 引入。
+
+---
+
+## 四、Mock 文件编写规范
+
+### 4.1 文件头注释
+
+每个 mock 文件顶部必须声明覆盖的业务模块和接口：
+
+```typescript
+/**
+ * [业务模块名] Mock
+ * 覆盖接口：[接口前缀1] / [接口前缀2]
+ */
+import type { MockMethod } from "vite-plugin-mock";
+import Mock from "mockjs";
+import { paginate, ok, pick, nowStr } from "../_utils";
+```
+
+### 4.2 STORE 模式
+
+```typescript
+// ─── 数据生成器 ──────────────────────────────────────────────────
+function genRecord() {
+  return {
+    id: Mock.Random.id(),
+    code: `MDM${Mock.Random.string("number", 8)}`,
+    name: Mock.Random.cword(4, 10),
+    status: pick(["ACTIVE", "DRAFT", "FROZEN"]),
+    createBy: Mock.Random.cname(),
+    createTime: Mock.Random.datetime("yyyy-MM-dd HH:mm:ss"),
+  };
+}
+
+// ─── 可变存储（dev server 会话内持久化）──────────────────────────
+let STORE: any[] = Array.from({ length: 50 }, genRecord);
+```
+
+**核心规则**：
+- 用 `let`（非 `const`）声明 STORE，允许 splice/unshift/assign
+- 生成器函数 `genRecord()` 封装单条数据的随机逻辑
+- 初始数据量建议 20-100 条，支持分页验证
+
+### 4.3 端点编写
+
+```typescript
+export default [
+  // ── 列表（分页）──
+  {
+    url: "/dev-api/[服务]/[资源]/list",
+    method: "get",
+    response: ({ query }: any) => paginate(STORE, query),
+  },
+
+  // ── 新增 ──
+  {
+    url: "/dev-api/[服务]/[资源]/save",
+    method: "post",
+    response: ({ body }: any) => {
+      STORE.unshift({ ...genRecord(), ...body, id: Mock.Random.id(), createTime: nowStr() });
+      return ok(null);
+    },
+  },
+
+  // ── 编辑 ──
+  {
+    url: "/dev-api/[服务]/[资源]/update",
+    method: "post",
+    response: ({ body }: any) => {
+      const idx = STORE.findIndex((r) => r.id === body?.id);
+      if (idx >= 0) Object.assign(STORE[idx], body, { updateTime: nowStr() });
+      return ok(null);
+    },
+  },
+
+  // ── 删除 ──
+  {
+    url: "/dev-api/[服务]/[资源]/remove",
+    method: "post",
+    response: ({ body }: any) => {
+      const ids = Array.isArray(body?.ids) ? body.ids : [body?.id];
+      ids.forEach((id: string) => {
+        const idx = STORE.findIndex((r) => r.id === id);
+        if (idx >= 0) STORE.splice(idx, 1);
+      });
+      return ok(null);
+    },
+  },
+
+  // ── 详情 ──
+  {
+    url: "/dev-api/[服务]/[资源]/getById",
+    method: "get",
+    response: ({ query }: any) => ok(STORE.find((r) => r.id === query?.id) || null),
+  },
+] as MockMethod[];
+```
+
+### 4.4 端点覆盖检查
+
+**每个 `API_CONFIG` 的 key 都必须在 mock 文件中有对应端点**，零遗漏。
+
+| 操作 | STORE 修改方式 |
+|---|---|
+| 删除 | `STORE.splice(idx, 1)` |
+| 新增 | `STORE.unshift({ ...genRecord(), ...body, id })` |
+| 编辑 | `Object.assign(STORE[idx], body)` |
+| 启用/停用 | 修改 `item.status` |
+| 提交/审批 | 修改 `item.approvalStatus` |
+| 作废 | `STORE.splice(idx, 1)` 或修改状态 |
+
+> ❌ 禁止端点只返回 `{ code: 2000 }` 不修改 STORE — 否则 `select()` 刷新后看不到变化。
+
+---
+
+## 五、开关机制
+
+### 5.1 环境变量
+
+```bash
+# .env.dev
+ENV_MOCK=true    # true = 启用 mock，false = 关闭 mock 走真实接口
+```
+
+### 5.2 Vite 配置
+
+```typescript
+// vite.config.ts
+import { viteMockServe } from "vite-plugin-mock";
+
+plugins: [
+  viteMockServe({
+    mockPath: "./mock",
+    enable: command === "serve" && config.ENV_MOCK !== "false",
+    logger: true,
+  }),
+]
+```
+
+**关键**：`enable` 判断只在 `serve` 模式且 `ENV_MOCK` 不为 `"false"` 时挂载。生产构建永远不包含 mock。
+
+### 5.3 切换流程
+
+```
+开发阶段（Mock）：ENV_MOCK=true  → 所有接口走 mock，Network 可见
+联调阶段（真实）：ENV_MOCK=false → mock 插件不加载，接口走 proxy → 后端
+部分联调：       ENV_MOCK=false + 仅保留需要 mock 的端点（手动注释其余）
+```
+
+> 切换时**无需修改任何页面代码**。`API_CONFIG` 始终保持真实路径，mock 端点的 `/dev-api` 前缀由 Vite proxy 统一处理。
+
+---
+
+## 六、一键清理
+
+CLI 提供 `mock-clean` 命令，支持按模块清理或全量清理：
+
+```bash
+# 清理指定业务域的 mock
+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 mock-clean --all --dry-run
+```
+
+清理后建议：
+1. 将 `.env.dev` 中 `ENV_MOCK` 改为 `false`
+2. 确认 `vite.config.ts` 中 proxy 已配置正确的后端地址
+3. 运行 `wl-skills validate` 确认页面无 mock 依赖残留
+
+---
+
+## 七、validate 检查项
+
+`wl-skills validate` 对 mock 的检查（自动执行）：
+
+| 检查项 | 级别 | 说明 |
+|---|---|---|
+| `mock/_utils.ts` 是否存在 | warn | 缺失则提示 `wl-skills init` 补充 |
+| API_CONFIG URL 是否有对应 mock 端点 | warn | 每个 URL 在 mock 文件中必须有 `/dev-api` 前缀的端点 |
+| mock 文件是否 import `_utils` | info | 未使用共享工具则提示 |
+| mock 文件是否按域分目录 | info | 扁平放在 `mock/` 根目录则提示迁移 |
+
+---
+
+## 八、常见问题
+
+### Q: mock 和真实接口返回格式不一致怎么办？
+
+确保 `_utils.ts` 中 `pageResult` / `ok` 的返回格式与后端统一：
+```typescript
+// 如果后端用 code: 200
+export function ok(data: any = null) {
+  return { code: 200, message: "操作成功", data };
+}
+
+// 如果后端用 code: 2000（平台默认）
+export function ok(data: any = null) {
+  return { code: 2000, message: "操作成功", data };
+}
+```
+
+> 在 `_utils.ts` 中统一修改一处即可，无需改每个 mock 文件。
+
+### Q: 多个页面共享同一套数据怎么办？
+
+同一个 mock 模块文件中声明一个 STORE，多个端点共享。例如"客户列表"和"客户申请"可共享 `CUSTOMER_STORE`。
+
+### Q: 某个接口需要走真实后端，其余走 mock？
+
+方案一：删除该接口在 mock 文件中的端点，vite-plugin-mock 找不到匹配就会放行到 proxy。
+方案二：保持 `ENV_MOCK=true`，在 vite proxy 中对特定路径单独配置 target。
+
+---
+
+## 九、架构要点速查
+
+| 能力 | 实现方式 |
+|---|---|
+| **新增数据可见** | 每个模块维护 `let STORE = [...]` 可变数组，save 用 `unshift` 置顶，下次 list 查询即可看到 |
+| **关闭 mock 零污染** | `ENV_MOCK=false` → vite-plugin-mock 整体不挂载，不会有任何 mock handler 拦截真实请求 |
+| **按模块独立** | 每个文件自治，未来删某业务模块 mock 只删对应文件 |
+| **共享工具复用** | `_utils.ts` 提供 `pageResult` / `ok` / `paginate` / `nowStr` / `pick`，子模块 import 而非重复定义 |
+| **跨会话重置** | dev server 重启时内存清空，mock 数据恢复初始状态（符合预期） |
+| **URL 零修改切换** | `API_CONFIG` 保持真实路径，mock URL 带 `/dev-api` 前缀，关闭 mock 后业务代码无需任何改动 |

package/files/mock/_utils.ts

@@ -0,0 +1,35 @@
+/**
+ * Mock 公共工具函数
+ * 由 wl-skills-kit 提供，所有 mock 模块文件统一 import 此文件。
+ * 注意：本文件无 export default，vite-plugin-mock 会安全跳过，不会报错。
+ */
+import Mock from "mockjs";
+
+export const Random = Mock.Random;
+export const pick = <T>(arr: T[]): T => Random.pick(arr) as T;
+export const bool = () => Random.boolean();
+
+/** 标准分页响应 */
+export function pageResult(records: any[], total: number) {
+  return { code: 2000, message: "操作成功", data: { records, total } };
+}
+
+/** 标准成功响应 */
+export function ok(data: any = null) {
+  return { code: 2000, message: "操作成功", data };
+}
+
+/** 通用分页截取（兼容 pageNo/current、pageSize/size 两种参数名） */
+export function paginate(pool: any[], query: any) {
+  const current = Number(query?.current || query?.pageNo) || 1;
+  const size = Number(query?.size || query?.pageSize) || 10;
+  const start = (current - 1) * size;
+  return pageResult(pool.slice(start, start + size), pool.length);
+}
+
+/** 当前时间字符串 */
+export function nowStr() {
+  return new Date()
+    .toLocaleString("zh-CN", { hour12: false })
+    .replace(/\//g, "-");
+}

package/mcp/tools/dictSync.js

@@ -1,178 +1,178 @@
-'use strict'
-
-const { queryDictModules, saveDictModule, saveDictItem } = require('../api/dictApi')
-
-/**
- * 从字典树查询响应中提取模块列表
- * 响应结构: { dictionary: { children: DictModule[] } }
- *
- * @param {any} data - queryDictModules 返回的 result.data
- * @returns {object[]}
- */
-function extractModules(data) {
-  if (!data) return []
-  if (data.dictionary && Array.isArray(data.dictionary.children)) {
-    return data.dictionary.children
-  }
-  if (Array.isArray(data)) return data
-  return []
-}
-
-/**
- * wls_dict_query 工具处理器
- * 查询当前应用的所有字典模块及字典项
- *
- * @param {object} config
- * @returns {Promise<string>}
- */
-async function handleDictQuery(config) {
-  const result = await queryDictModules(config)
-
-  if (!result.ok) {
-    return `❌ 查询字典失败: ${result.error} (code: ${result.code})`
-  }
-
-  const modules = extractModules(result.data)
-
-  if (modules.length === 0) {
-    return '✅ 字典查询成功，当前应用暂无字典数据'
-  }
-
-  return `✅ 字典查询成功，共 ${modules.length} 个模块\n\n${JSON.stringify(modules, null, 2)}`
-}
-
-/**
- * wls_dict_upsert 工具处理器
- * 新增或更新字典模块及字典项（完整幂等流程）
- *
- * 流程：
- * ① 查询现有模块，检查 strSn 是否已存在
- * ② 若不存在：创建模块（data=null）→ 重新查询 → 用 strSn 定位拿 id
- * ③ 若已存在：跳过模块创建，直接取已有 id
- * ④ 遍历 items，跳过 strSn 已存在的，其余逐条创建
- *
- * @param {{ module: object, items?: object[] }} args
- * @param {object} config
- * @returns {Promise<string>}
- */
-async function handleDictUpsert(args, config) {
-  const { module: moduleBody, items = [] } = args
-
-  if (!moduleBody || !moduleBody.strSn) {
-    return '❌ 参数错误：module.strSn 必填'
-  }
-  if (!moduleBody.strName) {
-    return '❌ 参数错误：module.strName 必填'
-  }
-
-  // ① 查询现有模块
-  const queryResult = await queryDictModules(config)
-  if (!queryResult.ok) {
-    return `❌ 查询字典失败: ${queryResult.error}`
-  }
-
-  const existingModules = extractModules(queryResult.data)
-  let targetModule = existingModules.find((m) => m.strSn === moduleBody.strSn)
-  let moduleAction
-
-  // ② 模块不存在时创建
-  if (!targetModule) {
-    const saveBody = {
-      strSn: moduleBody.strSn,
-      strName: moduleBody.strName,
-      sortPriority: moduleBody.sortPriority != null ? String(moduleBody.sortPriority) : '1',
-      strLevel: 2,
-    }
-
-    const createResult = await saveDictModule(saveBody, config)
-    if (!createResult.ok) {
-      return `❌ 创建字典模块失败: ${createResult.error}`
-    }
-
-    // ③ 重新查询（data=null，只能靠 re-query 拿 id）
-    const reQueryResult = await queryDictModules(config)
-    if (!reQueryResult.ok) {
-      return `❌ 重新查询字典失败: ${reQueryResult.error}`
-    }
-
-    const freshModules = extractModules(reQueryResult.data)
-    targetModule = freshModules.find((m) => m.strSn === moduleBody.strSn)
-
-    if (!targetModule) {
-      return `❌ 字典模块创建后未能找到（strSn="${moduleBody.strSn}"），请在字典管理后台确认`
-    }
-
-    moduleAction = '✅ 已创建'
-  } else {
-    moduleAction = '⏭ 已存在（跳过创建）'
-  }
-
-  const moduleId = targetModule.id
-
-  // ④ 处理字典项
-  const existingItems = Array.isArray(targetModule.dictionaries)
-    ? targetModule.dictionaries
-    : []
-  const existingSns = new Set(existingItems.map((i) => i.strSn))
-
-  const itemResults = []
-
-  for (const item of items) {
-    if (existingSns.has(item.strSn)) {
-      itemResults.push({
-        strSn: item.strSn,
-        strName: item.strName || '',
-        status: '⏭ 已存在（跳过）',
-      })
-      continue
-    }
-
-    const itemBody = {
-      moduleId,
-      strSn: item.strSn,
-      strName: item.strName,
-      strLevel: 2,
-      dtlValue: item.dtlValue != null ? item.dtlValue : '',
-      dtlValueRequired: item.dtlValueRequired || false,
-      dtlValue2Required: item.dtlValue2Required || false,
-      dtlValue3Required: item.dtlValue3Required || false,
-      dtlValue4Required: item.dtlValue4Required || false,
-    }
-
-    const createResult = await saveDictItem(itemBody, config)
-    if (createResult.ok) {
-      itemResults.push({ strSn: item.strSn, strName: item.strName || '', status: '✅ 已创建' })
-    } else {
-      itemResults.push({
-        strSn: item.strSn,
-        strName: item.strName || '',
-        status: `❌ 失败: ${createResult.error}`,
-      })
-    }
-  }
-
-  const createdCount = itemResults.filter((r) => r.status.startsWith('✅')).length
-  const skippedCount = itemResults.filter((r) => r.status.startsWith('⏭')).length
-  const failedCount = itemResults.filter((r) => r.status.startsWith('❌')).length
-
-  let output = `字典模块 "${moduleBody.strSn}" (${moduleBody.strName})：${moduleAction}\n`
-  output += `模块 ID：${moduleId}\n`
-
-  if (items.length > 0) {
-    output += `字典项：创建 ${createdCount}，跳过 ${skippedCount}，失败 ${failedCount}\n\n`
-    output += '| strSn | strName | 状态 |\n'
-    output += '|---|---|---|\n'
-    for (const r of itemResults) {
-      output += `| ${r.strSn} | ${r.strName} | ${r.status} |\n`
-    }
-  }
-
-  return output
-}
-
-module.exports = {
-  handleDictQuery,
-  handleDictUpsert,
-  // 导出纯工具函数供单测覆盖
-  _internal: { extractModules },
-}
+'use strict'
+
+const { queryDictModules, saveDictModule, saveDictItem } = require('../api/dictApi')
+
+/**
+ * 从字典树查询响应中提取模块列表
+ * 响应结构: { dictionary: { children: DictModule[] } }
+ *
+ * @param {any} data - queryDictModules 返回的 result.data
+ * @returns {object[]}
+ */
+function extractModules(data) {
+  if (!data) return []
+  if (data.dictionary && Array.isArray(data.dictionary.children)) {
+    return data.dictionary.children
+  }
+  if (Array.isArray(data)) return data
+  return []
+}
+
+/**
+ * wls_dict_query 工具处理器
+ * 查询当前应用的所有字典模块及字典项
+ *
+ * @param {object} config
+ * @returns {Promise<string>}
+ */
+async function handleDictQuery(config) {
+  const result = await queryDictModules(config)
+
+  if (!result.ok) {
+    return `❌ 查询字典失败: ${result.error} (code: ${result.code})`
+  }
+
+  const modules = extractModules(result.data)
+
+  if (modules.length === 0) {
+    return '✅ 字典查询成功，当前应用暂无字典数据'
+  }
+
+  return `✅ 字典查询成功，共 ${modules.length} 个模块\n\n${JSON.stringify(modules, null, 2)}`
+}
+
+/**
+ * wls_dict_upsert 工具处理器
+ * 新增或更新字典模块及字典项（完整幂等流程）
+ *
+ * 流程：
+ * ① 查询现有模块，检查 strSn 是否已存在
+ * ② 若不存在：创建模块（data=null）→ 重新查询 → 用 strSn 定位拿 id
+ * ③ 若已存在：跳过模块创建，直接取已有 id
+ * ④ 遍历 items，跳过 strSn 已存在的，其余逐条创建
+ *
+ * @param {{ module: object, items?: object[] }} args
+ * @param {object} config
+ * @returns {Promise<string>}
+ */
+async function handleDictUpsert(args, config) {
+  const { module: moduleBody, items = [] } = args
+
+  if (!moduleBody || !moduleBody.strSn) {
+    return '❌ 参数错误：module.strSn 必填'
+  }
+  if (!moduleBody.strName) {
+    return '❌ 参数错误：module.strName 必填'
+  }
+
+  // ① 查询现有模块
+  const queryResult = await queryDictModules(config)
+  if (!queryResult.ok) {
+    return `❌ 查询字典失败: ${queryResult.error}`
+  }
+
+  const existingModules = extractModules(queryResult.data)
+  let targetModule = existingModules.find((m) => m.strSn === moduleBody.strSn)
+  let moduleAction
+
+  // ② 模块不存在时创建
+  if (!targetModule) {
+    const saveBody = {
+      strSn: moduleBody.strSn,
+      strName: moduleBody.strName,
+      sortPriority: moduleBody.sortPriority != null ? String(moduleBody.sortPriority) : '1',
+      strLevel: 2,
+    }
+
+    const createResult = await saveDictModule(saveBody, config)
+    if (!createResult.ok) {
+      return `❌ 创建字典模块失败: ${createResult.error}`
+    }
+
+    // ③ 重新查询（data=null，只能靠 re-query 拿 id）
+    const reQueryResult = await queryDictModules(config)
+    if (!reQueryResult.ok) {
+      return `❌ 重新查询字典失败: ${reQueryResult.error}`
+    }
+
+    const freshModules = extractModules(reQueryResult.data)
+    targetModule = freshModules.find((m) => m.strSn === moduleBody.strSn)
+
+    if (!targetModule) {
+      return `❌ 字典模块创建后未能找到（strSn="${moduleBody.strSn}"），请在字典管理后台确认`
+    }
+
+    moduleAction = '✅ 已创建'
+  } else {
+    moduleAction = '⏭ 已存在（跳过创建）'
+  }
+
+  const moduleId = targetModule.id
+
+  // ④ 处理字典项
+  const existingItems = Array.isArray(targetModule.dictionaries)
+    ? targetModule.dictionaries
+    : []
+  const existingSns = new Set(existingItems.map((i) => i.strSn))
+
+  const itemResults = []
+
+  for (const item of items) {
+    if (existingSns.has(item.strSn)) {
+      itemResults.push({
+        strSn: item.strSn,
+        strName: item.strName || '',
+        status: '⏭ 已存在（跳过）',
+      })
+      continue
+    }
+
+    const itemBody = {
+      moduleId,
+      strSn: item.strSn,
+      strName: item.strName,
+      strLevel: 2,
+      dtlValue: item.dtlValue != null ? item.dtlValue : '',
+      dtlValueRequired: item.dtlValueRequired || false,
+      dtlValue2Required: item.dtlValue2Required || false,
+      dtlValue3Required: item.dtlValue3Required || false,
+      dtlValue4Required: item.dtlValue4Required || false,
+    }
+
+    const createResult = await saveDictItem(itemBody, config)
+    if (createResult.ok) {
+      itemResults.push({ strSn: item.strSn, strName: item.strName || '', status: '✅ 已创建' })
+    } else {
+      itemResults.push({
+        strSn: item.strSn,
+        strName: item.strName || '',
+        status: `❌ 失败: ${createResult.error}`,
+      })
+    }
+  }
+
+  const createdCount = itemResults.filter((r) => r.status.startsWith('✅')).length
+  const skippedCount = itemResults.filter((r) => r.status.startsWith('⏭')).length
+  const failedCount = itemResults.filter((r) => r.status.startsWith('❌')).length
+
+  let output = `字典模块 "${moduleBody.strSn}" (${moduleBody.strName})：${moduleAction}\n`
+  output += `模块 ID：${moduleId}\n`
+
+  if (items.length > 0) {
+    output += `字典项：创建 ${createdCount}，跳过 ${skippedCount}，失败 ${failedCount}\n\n`
+    output += '| strSn | strName | 状态 |\n'
+    output += '|---|---|---|\n'
+    for (const r of itemResults) {
+      output += `| ${r.strSn} | ${r.strName} | ${r.status} |\n`
+    }
+  }
+
+  return output
+}
+
+module.exports = {
+  handleDictQuery,
+  handleDictUpsert,
+  // 导出纯工具函数供单测覆盖
+  _internal: { extractModules },
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.7.3",
-  "description": "AI Skill 模板包 v2.7.3 — 13 条编码规范 + 10 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
+  "version": "2.8.0",
+  "description": "AI Skill 模板包 v2.8.0 — 13 条编码规范 + 10 个 AI Skill + 17 个 MCP Tool + Mock 架构体系，一条命令导入 Vue 3 项目",
   "main": "./bin/wl-skills.js",
   "bin": {
     "wl-skills": "bin/wl-skills.js"
@@ -75,4 +75,4 @@
       "eslint --fix --no-cache"
     ]
   }
-}
+}