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

package/files/.github/skills/core/page-codegen/templates/universal/TPL-TREE-LIST.md

@@ -1,13 +1,14 @@
 # TREE_LIST：树形+列表
 
 > 见 SKILL.md 主文件（约束 + 按钮规则 + Mock 规范等共用规则）。
+> **布局硬约束**：严禁使用 `C_Splitter`（冻vnode导致响应式完全失效），必须用 `jh-drag-col`（详 standards/14-layout-containers.md）。
 
 #### index.vue
 
 ```vue
 <template>
-  <div class="app-container app-page-container">
-    <C_Splitter :left-width="220">
+  <div class="app-container app-page-container" style="height: 100%">
+    <jh-drag-col :leftWidth="220">
       <template #left>
         <C_Tree
           :tree-data="treeData"
@@ -40,7 +41,7 @@
           @size-change="select"
         />
       </template>
-    </C_Splitter>
+    </jh-drag-col>
   </div>
 </template>
 
@@ -197,10 +198,8 @@ export function createPage(editModalRef?: any) {
 
 ```scss
 .app-page-container {
-  // C_Splitter 需要父容器撑满高度
-  :deep(.my-splitter-container) {
-    height: 100%;
-  }
+  // jh-drag-col 需要父容器擑满高度
+  height: 100%;
 }
 ```
 

package/files/.github/skills/core/prototype-scan/SKILL.md

@@ -144,7 +144,7 @@ AI 根据提取的信息，内部构建 page-spec JSON（**不输出给用户**
 | --------------- | --------------------- | ------------------------------------------------ |
 | `LIST`          | 查询区 + 表格 + 分页  | BaseQuery + BaseTable + jh-pagination            |
 | `MASTER_DETAIL` | 上方主表 + 下方明细表 | jh-drag-row（需 `.drager_row { height: 100% }`） |
-| `TREE_LIST`     | 左侧树 + 右侧表格     | C_Splitter + C_Tree                              |
+| `TREE_LIST`     | 左侧树 + 右侧表格     | jh-drag-col + C_Tree                              |
 | `FORM_MODAL`    | 弹窗中的表单          | el-dialog + el-form                              |
 | `COMPOSITE`     | 多种组合              | 组合使用                                         |
 
@@ -195,7 +195,7 @@ AI 根据提取的信息，内部构建 page-spec JSON（**不输出给用户**
 | 表格     | BaseTable               | 通过 `columnsDef()` 声明式配置       |
 | 分页     | jh-pagination           | 固定用法，见 copilot-instructions.md |
 | 上下分栏 | jh-drag-row             | 主从表必备，需设 `:top-height`       |
-| 左右分割 | C_Splitter              | 树形+列表必备，设 `:left-width`      |
+| 左右分割 | jh-drag-col             | 树形+列表必备，设 `:leftWidth` + #left/#right slot |
 | 树形面板 | C_Tree                  | 含搜索+Tab 切换                      |
 | 下拉选择 | jh-select               | dict 属性自动加载字典数据            |
 | 日期选择 | jh-date / jh-date-range | 参见 `docs/jh-date.md`               |

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

@@ -31,8 +31,8 @@
 | 下拉 / 选择器       | `jh-select` / `jh-picker`                     | ❌ el-select 手写 options    |
 | 只读文本展示        | `jh-text`                                     | ❌ span/div 直接渲染         |
 | 分页                | `jh-pagination`                               | ❌ el-pagination             |
-| 上下分栏            | `jh-drag-row`                                 | ❌ 手动 flex/grid            |
-| 左右分割            | `C_Splitter`                                  | ❌ 手动 flex/grid            |
+| 上下分栏            | `jh-drag-row` (#top/#bottom)                  | ❌ 手动 flex/grid          |
+| 左右分割            | `jh-drag-col` (#left/#right)                  | ❌️ `C_Splitter`（已废弃，onMounted 冻vnode，导致子树响应式完全失效） |
 | 树形面板            | `C_Tree`                                      | ❌ el-tree 手写              |
 | 状态标签            | `C_TagStatus`                                 | ❌ el-tag + 颜色映射         |
 | HTTP 请求           | `getAction/postAction/putAction/deleteAction` | ❌ axios / fetch 直接调用    |

package/files/.github/standards/14-layout-containers.md

@@ -0,0 +1,139 @@
+# 14 — 布局容器规范（C_Splitter 禁用 + jh-drag-col/row 唯一推荐）
+
+> **强制度**：🔴 必遵 + 阻断式（lint 命中即报错）。
+> **背景**：2024 年 12 月一次真实事故，左树右表页面右侧面板永不刷新，最终定位为 `C_Splitter` 在 `onMounted` 中调用 `slots.default()` 冻结 vnode 快照，导致子树所有响应式绑定与父组件 ref 脱钩。
+> **结论**：项目中**禁止再使用 `C_Splitter`**，所有左右/上下分栏一律用 `jh-drag-col` / `jh-drag-row`。
+
+---
+
+## 1. 强制对照
+
+| 场景       | ✅ 必用                                | ❌ 禁用             |
+| ---------- | -------------------------------------- | ------------------- |
+| 左右分栏   | `<jh-drag-col :leftWidth="240">` + `#left` / `#right` slot | `C_Splitter`、`el-aside`+`el-main` 手写 flex |
+| 上下分栏   | `<jh-drag-row :topHeight="240">` + `#top` / `#bottom` slot  | `C_Splitter direction="vertical"`、手写 flex |
+| 嵌套分栏   | 多层 `jh-drag-col` / `jh-drag-row` 直接嵌套 | C_Splitter 嵌套（双倍 vnode 冻结） |
+
+> `@jhlc/jh-ui` 的 `jh-drag-col` / `jh-drag-row` 使用 Vue 原生 `<slot />` 直接渲染，**不缓存 vnode**，子组件响应式与父组件 ref 完全连通。
+
+---
+
+## 2. C_Splitter 为什么必须废弃（根因）
+
+`src/components/global/C_Splitter/index.vue` 内部实现：
+
+```js
+onMounted(() => {
+  const defaultSlots = slots.default ? slots.default() : [];
+  // ...
+  vnodes.value = children;  // 冻结 vnode 列表
+});
+// 模板里
+// <component :is="item" />
+```
+
+**反应链**：
+
+1. `slots.default()` 只在 `onMounted` 执行一次 → 拿到的是**当时**的 vnode 快照
+2. 模板用 `<component :is="item" />` 渲染快照 → 子组件的所有 props/slot props/ref 绑定**永远定格在 mount 那一刻**
+3. 父组件后续修改 ref（`activeModelId.value = "xxx"`）→ 子组件 v-if/v-show/插值**全部失效**
+4. 表现：点击树节点，右侧表格**永远显示初始数据**或空白；vue-devtools 看 ref 已变但 UI 不动
+
+> 这是 Vue 3 slot 渲染模型的本质：`slots.default()` 是一次性的 render function 调用，**不能用 ref 缓存其结果当模板用**。任何"缓存 vnode 数组再 component is 渲染"的写法都有同样的 bug。
+
+---
+
+## 3. 标准用法
+
+### 3.1 左树右表（最常见）
+
+```vue
+<template>
+  <div class="app-container app-page-container" style="height: 100%">
+    <jh-drag-col :leftWidth="240">
+      <template #left>
+        <C_Tree :data="treeData" @node-click="onNodeClick" />
+      </template>
+      <template #right>
+        <BaseQuery ... />
+        <BaseToolbar ... />
+        <BaseTable v-if="activeModelId" ... />
+      </template>
+    </jh-drag-col>
+  </div>
+</template>
+```
+
+✅ `v-if`、`ref` 赋值、所有响应式都能正常驱动右侧重渲染。
+
+### 3.2 上表下详情（master-detail）
+
+```vue
+<jh-drag-row :topHeight="320">
+  <template #top>
+    <BaseTable ... @row-click="onRowClick" />
+  </template>
+  <template #bottom>
+    <DetailPanel v-if="currentRow" :data="currentRow" />
+  </template>
+</jh-drag-row>
+```
+
+### 3.3 上 Tab 表单 + 下子表
+
+```vue
+<jh-drag-row :topHeight="280">
+  <template #top>
+    <el-tabs v-model="activeTab"> ... </el-tabs>
+  </template>
+  <template #bottom>
+    <BaseTable ... />
+  </template>
+</jh-drag-row>
+```
+
+---
+
+## 4. 兼容期处理
+
+若现存项目仍引用 `C_Splitter`：
+
+1. **当前版本**：保留组件文件，在 `onMounted` 顶部加 `console.warn("[C_Splitter 已废弃] ...")` 提示
+2. **下一版本**：删除 `src/components/global/C_Splitter/`，全量替换为 `jh-drag-col/row`
+3. **lint 规则**：`wl-skills validate` / `wl-skills doctor-ui` 命中 `import C_Splitter` 或 `<C_Splitter` 时报 ERROR
+
+---
+
+## 5. 自动迁移建议
+
+```bash
+# 项目根目录执行
+grep -rln "C_Splitter" src/views | while read f; do
+  echo "需要人工改造：$f"
+done
+```
+
+迁移要点：
+
+| 旧写法 | 新写法 |
+| ------ | ------ |
+| `<C_Splitter :left-width="220">` | `<jh-drag-col :leftWidth="220">` |
+| `<C_Splitter direction="vertical">` | `<jh-drag-row :topHeight="...">` |
+| 默认 slot 顺序：第一项 / 第二项 | 显式 `#left` `#right` / `#top` `#bottom` |
+| 拖动配置：`min-left-width="200"` | `jh-drag-col` 内置阈值 |
+
+---
+
+## 6. lint / codegen 强制项
+
+- `prototype-scan` / `page-codegen` 生成的模板**禁止**包含 `C_Splitter`
+- TPL-TREE-LIST、TPL-DETAIL-TABS 等模板必须使用 `jh-drag-col` / `jh-drag-row`
+- `wl-skills validate-page` 扫到 `C_Splitter` 直接 fail
+
+---
+
+## 关联
+
+- `12-base-table.md` — BaseTable 内部高度撑满依赖父容器有明确高度，jh-drag-col/row 已正确给子区设 `height: 100%`
+- `13-platform-components.md` — 平台组件对照表已同步移除 C_Splitter
+- 真实场景案例：`demo/produce/aiflow/mmwr-customer-detail/`（master-detail 使用 jh-drag-row）

package/files/.github/standards/index.md

@@ -5,7 +5,7 @@
 
 ---
 
-## 13 条规范清单
+## 14 条规范清单
 
 | 编号 | 文件                        | 主题                   | 强制度         |
 | ---- | --------------------------- | ---------------------- | -------------- |
@@ -22,6 +22,7 @@
 | 11   | `11-form-validation.md`     | 表单与校验             | 🔴 必遵        |
 | 12   | `12-base-table.md`          | BaseTable + AGGrid cid | 🔴 必遵        |
 | 13   | `13-platform-components.md` | 平台组件合规（核心）   | 🔴 必遵 + 阻断 |
+| 14   | `14-layout-containers.md`   | 布局容器（禁用 C_Splitter） | 🔴 必遵 + 阻断 |
 
 ---
 
@@ -32,14 +33,14 @@
 ### 任务类型 A：生成新页面（page-codegen）
 
 ```
-必读：01 / 02 / 04 / 12 / 13
+必读：01 / 02 / 04 / 12 / 13 / 14
 按需：09（TS 类型复杂时） / 10（涉及 Store） / 11（FORM_ROUTE 模板）
 ```
 
 ### 任务类型 B：修改/重构既有页面
 
 ```
-必读：02 / 04 / 13
+必读：02 / 04 / 13 / 14
 按需：09 / 10 / 11
 ```
 

package/files/demo/sale/demo/add-demo/index.scss

@@ -10,7 +10,7 @@
   display: flex;
   flex-direction: column;
 
-  // C_Splitter 区域
+  // jh-drag-row 区域
   .main-splitter {
     flex: 1;
     overflow: hidden;

package/files/demo/sale/demo/add-demo/index.vue

@@ -9,8 +9,9 @@
  -->
 <template>
   <div class="main-maintenance-container">
-    <!-- C_Splitter 包裹表单区和项次信息 -->
-    <C_Splitter direction="vertical" class="main-splitter">
+    <!-- jh-drag-row 包裹表单区和项次信息（上下拖拽） -->
+    <jh-drag-row :topHeight="480" class="main-splitter">
+      <template #top>
       <!-- 🆕 使用增强版组件（集成所有功能） -->
       <c_formSections
         :sections="sectionsConfig"
@@ -43,7 +44,9 @@
           </el-row>
         </template>
       </c_formSections>
+      </template>
 
+      <template #bottom>
       <el-card
         shadow="never"
         class="items-card"
@@ -88,7 +91,8 @@
           </div>
         </div>
       </el-card>
-    </C_Splitter>
+      </template>
+    </jh-drag-row>
 
     <!-- 全屏模式 - 使用 Teleport 传送到 body -->
     <Teleport to="body">
@@ -136,7 +140,7 @@
 <script setup lang="ts">
 import { onMounted } from "vue";
 import { ArrowDown, Close } from "@element-plus/icons-vue";
-import C_Splitter from "@/components/global/C_Splitter/index.vue";
+// jh-drag-row 是 @jhlc/jh-ui 全局注册组件，无需 import
 import c_formSections from "@/components/local/c_formSections/index.vue";
 import {
   form,

package/files/demo/sale/demo/metallurgical-spec/index.scss

@@ -220,7 +220,7 @@
 
     // 明细信息的表格容器（固定高度，给实验表格留空间）
     &[data-tab="detail"] {
-      // 移除 table-container 固定高度，让 C_Splitter 控制
+      // 移除 table-container 固定高度，让 jh-drag-row 控制
       .detail-tables-splitter {
         flex: 1;
       }

package/files/demo/sale/demo/metallurgical-spec/index.vue

@@ -151,7 +151,8 @@
 
                 <!-- 选择节点后显示表格数据 -->
                 <div v-else class="tables-content">
-                  <C_Splitter direction="vertical">
+                  <jh-drag-row :topHeight="320">
+                    <template #top>
                     <div class="main-table-section">
                       <BaseTable
                         :key="updateKey"
@@ -163,6 +164,8 @@
                         @row-click="handleRowClick"
                       />
                     </div>
+                    </template>
+                    <template #bottom>
                     <div>
                       <div class="experiment-section">
                         <div class="experiment-header">
@@ -193,7 +196,8 @@
                         </div>
                       </div>
                     </div>
-                  </C_Splitter>
+                    </template>
+                  </jh-drag-row>
                 </div>
               </div>
             </div>
@@ -220,7 +224,7 @@
 import { onMounted, onUnmounted, watch, nextTick } from "vue";
 import { ArrowDown, ArrowLeft } from "@element-plus/icons-vue";
 import c_formModal from "@/components/local/c_formModal/index.vue";
-import C_Splitter from "@/components/global/C_Splitter/index.vue";
+// jh-drag-row 是 @jhlc/jh-ui 全局注册组件，无需 import
 import {
   // 状态
   activeTab,

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 后业务代码无需任何改动 |