npmapps 1.0.24 → 1.0.26

package/app/docs/superpowers/specs/2026-05-29-quill-editor-design.md

@@ -0,0 +1,210 @@
+# QuillEditor组件封装设计
+
+**日期**:2026-05-29
+**作者**: wk-7500f
+**状态**: Approved
+
+##背景
+
+`src/views/element/index.vue` 已经预留了 "Quill编辑器" tab 并 import 了
+`./quillEditor/example.vue`,但 `src/views/element/quillEditor/`目录为空,
+example.vue也不存在。需要:
+
+1.封装一个功能齐全的 Quill 富文本编辑器 Vue2组件
+2. 必须包含表格(table)功能
+3. 在 element tab 下展示多实例对比案例
+
+##决策记录
+
+|维度 | 选择 |理由 |
+|------|------|------|
+| Quill 版本 |2.0.2 | quill-table-better@1.2.3明确要求 quill.js >= v2.0.0;Quill 是框架无关的,Vue2也能用2.x;生态最新最活跃 |
+|表格模块 | quill-table-better1.2.3 |唯一活跃维护的 Quill表格模块,功能齐全(增删/合并/拆分/样式),官方要求 Quill2.x |
+| 图片上传 | base64 内联 | 无后端依赖、零配置、适合 demo场景 |
+|主题 | snow | Quill 默认浅色主题,和现有 element tab风格一致 |
+|放置位置 | `src/views/element/quillEditor/` | 仅给 element tab 用,不放全局 components |
+|案例形式 | 多实例对比 | 同时展示基础/只读/禁用三种配置 |
+
+##架构
+
+```
+src/views/element/index.vue (el-tabs)
+ └─ <el-tab-pane name="quillEditor">
+ └─ <QuillEditorDemo /> (example.vue)
+ ├─ <QuillEditor v-model="..." /> 实例1:基础
+ ├─ <QuillEditor v-model="..." :readonly="true"/> 实例2:只读
+ └─ <QuillEditor v-model="..." :disabled="true"/> 实例3:禁用
+
+src/views/element/quillEditor/
+├── index.vue QuillEditor 主组件
+├── example.vue Demo页面(已存在 tab引用)
+├── toolbar.js 默认工具栏配置
+└── README.md 使用文档
+```
+
+外部依赖:
+
+- `quill@2.0.2` 富文本核心
+- `quill-table-better@1.2.3`表格模块(明确要求 Quill >=2.0.0)
+- `quill-image-drop-module` 图片拖拽上传(兼容 Quill2.x)
+- `quill-image-resize-module` (兼容 Quill2.x 版本) 图片缩放
+- `quill/dist/quill.snow.css` snow主题样式
+- `quill-table-better/dist/quill-table-better.css`表格样式
+
+> **修订记录**:2026-05-29实施前发现 quill-table-better实际依赖 Quill2.x,
+>升级方案由 "Quill1.x + quill-table-better"改为 "Quill2.x + quill-table-better1.2.3"。
+
+##组件 API
+
+### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | String | `''` | 编辑器 HTML 内容,支持 v-model |
+| `placeholder` | String | `'请输入内容...'` | 占位文字 |
+| `readonly` | Boolean | `false` | 是否只读 |
+| `disabled` | Boolean | `false` | 是否禁用工具栏 |
+| `height` | String \| Number | `300` | 编辑区高度,数字按 px,字符串按原值 |
+| `toolbar` | Array \| Object | 见下方"默认工具栏" | 自定义工具栏配置;不传则用默认全量 |
+| `imageHandler` | Function | `null` | 自定义图片处理;不传则走 base64 内联 |
+| `theme` | String | `'snow'` |主题 |
+
+### Events
+
+|事件 |触发时机 | 参数 |
+|------|---------|------|
+| `input` | 内容变化 | `(html: String)` |
+| `change` | 内容变化(去抖300ms) | `(html: String)` |
+| `ready` | Quill初始化完成 | `(quill: Quill)` |
+| `focus` | 编辑器获得焦点 | `()` |
+| `blur` | 编辑器失去焦点 | `()` |
+
+### Methods(ref 调用)
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `getHtml()` | String | 获取当前 HTML |
+| `getText()` | String | 获取纯文本 |
+| `setHtml(html)` | - | 设置内容 |
+| `clear()` | - | 清空内容 |
+| `focus()` | - |聚焦 |
+| `getQuill()` | Quill | 获取底层 Quill 实例 |
+
+### 默认工具栏(全量)
+
+```
+[
+ [{ header: [1,2,3,4,5,6, false] }],
+ [{ font: [] }],
+ [{ size: ['small', false, 'large', 'huge'] }],
+ ['bold', 'italic', 'underline', 'strike'],
+ [{ color: [] }, { background: [] }],
+ [{ script: 'sub' }, { script: 'super' }],
+ ['blockquote', 'code-block'],
+ [{ list: 'ordered' }, { list: 'bullet' }],
+ [{ indent: '-1' }, { indent: '+1' }],
+ [{ align: [] }],
+ ['link', 'image', 'video'],
+ ['table-better'],
+ ['clean'],
+ ['undo', 'redo'],
+]
+```
+
+## 文件内部实现要点
+
+### toolbar.js
+
+导出:
+
+- `defaultToolbar`:默认工具栏数组(上述全量配置)
+- `defaultHandlers`:`{ image, 'table-better' }`,image handler触发组件内的 file input;
+ table-better 由 quill-table-better 模块自身注册
+
+### index.vue关键实现
+
+1. **生命周期**
+ - `mounted`(nextTick):创建 Quill 实例,挂载到 `ref="editor"` div
+ - `beforeDestroy`:销毁 Quill 实例、清理事件、移除 file input
+ - 用 `this._quill`缓存实例,避免 hot reload重复挂载
+
+2. **v-model双向同步**
+ - `watch.value`(immediate):外部值变化 → `quill.clipboard.dangerouslyPasteHTML(value)`
+ - 用 `isInternalChange`标志位避免 watch循环
+ - Quill `text-change`事件 →触发 `input` +300ms 去抖触发 `change`
+
+3. **图片处理(base64 内联)**
+ - 自定义 image handler:创建隐藏 `<input type="file" accept="image/*">`,点击触发选择
+ - FileReader读 File → onload 转 base64 → `quill.insertEmbed(range.index, 'image', dataUrl)`
+ - 若 `imageHandler` prop传入,优先调用 prop;失败回退 base64
+
+4. **表格模块**
+ - 通过 Quill `theme.include`机制注册 quill-table-better
+ - 在 `index.vue` 中 import quill-table-better CSS
+
+5. **样式**
+ - scoped容器,只控制外层高度和 disabled态样式
+ - Quill内部样式通过 `index.vue` 中 `import 'quill/dist/quill.snow.css'`
+
+### example.vue 内容
+
+```vue
+<template>
+ <div class="quill-demo">
+ <h3>实例1:基础编辑器(v-model双向绑定)</h3>
+ <QuillEditor v-model="content1" @change="onChange" />
+
+ <h3>实例2:只读模式(readonly)</h3>
+ <QuillEditor v-model="content2" :readonly="true" />
+
+ <h3>实例3:禁用模式(disabled,工具栏灰掉)</h3>
+ <QuillEditor v-model="content3" :disabled="true" :height="200" />
+
+ <h3>当前实例1 的 v-model 内容:</h3>
+ <pre>{{ content1 }}</pre>
+ </div>
+</template>
+```
+
+实例1预填一段带表格的 HTML,演示表格功能;实例2、3共享同一份初始内容,
+便于对比 readonly 和 disabled 的视觉差异。
+
+##错误处理与边界
+
+|场景 | 处理 |
+|------|------|
+|依赖未安装(window.Quill 不存在) |渲染 `<div class="quill-editor-error">请先安装 quill依赖</div>` + console.error |
+| value 非字符串 |强制 `String(value)` |
+|重复创建 | 用 `this._quill`缓存,hot reload 不重复挂载 |
+| watch循环 | `isInternalChange`标志位 |
+|组件销毁 |销毁 Quill 实例、清理事件、移除 file input |
+| 图片 >5MB | ElMessage.warning提示但仍允许插入(base64 内联策略) |
+
+## 测试策略
+
+项目无现成测试框架(jest/vitest 未安装),通过 example演示 +人工验证:
+
+-三个实例能否正常渲染
+- v-model双向同步是否正确
+-工具栏按钮(尤其 table-better、image)是否可用
+- readonly / disabled切换是否生效
+-组件销毁后无控制台报错
+
+## 实现步骤
+
+1. 安装依赖:`quill@2.0.2`、`quill-table-better@1.2.3`、`quill-image-drop-module`、
+ `quill-image-resize-module`(注意选兼容 Quill2.x 的版本)
+2.写 `toolbar.js`(默认工具栏 + handlers)
+3.写 `index.vue`(QuillEditor 主组件,实现上述所有要点)
+4.写 `example.vue`(三实例对比 demo)
+5.写 `README.md`(用法 + Props/Events/Methods 说明)
+6. `index.vue` (element tab) 已经 import 该组件,无需修改
+
+##范围之外(本期不做)
+
+- 图片上传到后端 API(默认 base64,后续如需可加 `imageHandler` prop)
+- 自定义主题(只用 snow)
+-暗黑模式
+-协同编辑
+- 字数限制(可在调用方通过 `change`事件自行截断)
+-移动端适配

package/app/docs/superpowers/specs/2026-06-06-lazy-cascader-design.md

@@ -0,0 +1,400 @@
+# 懒加载级联选择器(LazyCascader)设计
+
+**日期**:2026-06-06
+**作者**: wk-7500f
+**状态**: Approved
+
+## 背景
+
+`el-cascader`(Element UI 2.x)自带的懒加载模式(`lazy` + `lazyLoad`)是按需向
+后端请求子节点的。但在某些场景下,后端会**一次性**返回所有数据(扁平数组或
+树形结构),数据量较大(数千条),如果直接拼成整棵 options 树一次性渲染会
+导致卡顿。本设计要解决:
+
+1. 把"一次性拿到的大数据"在**前端**拆成"按需懒加载"的体验
+2. 支持**默认值回显**(虽然数据全在前端,但 el-cascader lazy 模式初始化时
+   不会主动拉祖先节点,需要手动喂数据)
+3. 支持**只选最后一级**且输入框只显示最后一级(`emitPath: false`)
+4. 支持 `v-if` 销毁/重建组件后仍然能正确回显
+5. 支持"先有默认值、后到数据"和"后端给的是树形结构"的兼容
+6. 提供**树→扁平**工具函数,把后端返的树形数据转扁平后走同一套逻辑
+
+## 决策记录
+
+| 维度 | 选择 | 理由 |
+|------|------|------|
+| 组件放置 | `src/views/element/lazyCascader/` | 与 quillEditor / bpmn 等已有 Type 同级;该组件本就是给 element tab 演示用,不上全局 components |
+| 数据契约 | 扁平数组 `{ id, parentId, label }[]` | 与"后端一次性返扁平数组"对齐;`parentId` 为空/null 即根 |
+| 公共组件 | `LazyCascader.vue`(支持 props) | 用户已确认;真实工程做法,可复用 |
+| 懒加载底层 | `el-cascader` 自带 `lazy` + `lazyLoad` | 原生支持,无需 hack |
+| 默认值回显 | 组件内 `mounted` / `watch value` 时主动预 resolve 祖先链并缓存 | 解决 lazy 模式首屏不自动拉祖先的问题 |
+| 树→扁平工具 | `flattenTree(tree)` 递归遍历 children | 放在 `data.js`,与 mock 数据同文件 |
+| Mock 规模 | 3 省 × 3~4 市 × 2~3 区 ≈ 30 节点 | 够演示又不卡 |
+
+## 架构
+
+```
+src/views/element/index.vue (el-tabs)
+ └─ <el-tab-pane label="级联懒加载" name="lazyCascader">
+   └─ <LazyCascaderDemo />   (lazyCascader/index.vue)
+
+src/views/element/lazyCascader/
+├── index.vue         # Demo 页面:展示 6 个 case
+├── LazyCascader.vue  # 公共组件:可复用,接受 props
+└── data.js           # 模拟扁平数据 + 模拟树形数据 + 工具函数
+```
+
+## 公共组件 API (`LazyCascader.vue`)
+
+### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `Array \| String` | `[]` | `v-model` 绑定值;`emitPath=true`(默认)时为 id 路径数组;`emitPath=false` 时为叶子 id 字符串(单值) |
+| `data` | `Array` | `[]` | 扁平原始数据 `[{ id, parentId, label }]`;**必传**(若不传则空) |
+| `placeholder` | `String` | `'请选择'` | 输入框占位 |
+| `checkStrictly` | `Boolean` | `false` | `true` 可选任意级;`false` 只能选叶子级 |
+| `emitPath` | `Boolean` | `true` | `true` v-model 接 id 路径数组;`false` 只接叶子 id,输入框只显示最后一级 |
+| `disabled` | `Boolean` | `false` | 是否禁用 |
+| `clearable` | `Boolean` | `true` | 是否可清空 |
+
+### Events
+
+| 事件 | 触发时机 | 参数 |
+|------|---------|------|
+| `input` | 选择变化 | `(value: Array\|String)` |
+| `change` | 选择变化 | `(value: Array\|String)` |
+| `ready` | 首次挂载完成(已处理默认值回显) | `()` |
+
+### Methods(ref 调用)
+
+| 方法 | 说明 |
+|------|------|
+| `reload()` | 清空内部缓存并重置,用于"先有默认值、后到数据"场景主动重新拉取 |
+| `getFlatData()` | 返回当前传入的扁平数据(只读引用) |
+
+## 核心实现要点 (`LazyCascader.vue`)
+
+### 1. 内部缓存
+
+```js
+data() {
+  return {
+    _flatList: [],        // 扁平数据快照(props.data 的引用,组件内方便用)
+    _resolvedCache: new Map(), // parentId -> 已被 lazyLoad 取过的子节点(避免重复 resolve)
+  }
+},
+watch: {
+  data: {
+    immediate: true,
+    handler(v) { this._flatList = v || [] }
+  }
+}
+```
+
+### 2. `lazyLoad(node, resolve)`
+
+```js
+lazyLoad(node, resolve) {
+  // 模拟接口延时(0~50ms),让 loading 状态可见
+  const delay = 0
+  setTimeout(() => {
+    const parentId = node.level === 0 ? '' : node.data.id
+    // 优先用缓存(默认值回显可能预先塞过)
+    if (this._resolvedCache.has(parentId)) {
+      return resolve(this._resolvedCache.get(parentId))
+    }
+    const children = this._flatList
+      .filter(item => (item.parentId || '') === parentId)
+      .map(item => ({
+        ...item,
+        leaf: !this._flatList.some(c => (c.parentId || '') === item.id),
+        children: [],
+      }))
+    this._resolvedCache.set(parentId, children)
+    resolve(children)
+  }, delay)
+}
+```
+
+注意:lazy 模式下,每个被返回的节点必须有 `leaf` 或 `children` 字段,
+Element UI 据此判断是否还能继续展开。
+
+### 3. 默认值回显(关键)
+
+`el-cascader` 在 `lazy=true` 时,首次渲染**不会**主动调 `lazyLoad` 拉
+`value` 的祖先链(它假设懒加载就是按需,默认值由调用方负责准备好)。
+解决方案:**在 `mounted` / `value` 变化时,提前把"链上每一层"的**所有兄弟**
+都预 resolve 进 cache**。这样 Element UI 渲染首屏时触发 `lazyLoad(根)`,
+我们直接从 cache 返,链上祖先能正常显示,用户也能看到该层所有兄弟
+(未涉及的层不会被提前渲染,lazy 仍然成立)。
+
+```js
+mounted() {
+  this._primeDefaultValue()
+},
+watch: {
+  value: {
+    immediate: true,
+    handler() { this._primeDefaultValue() }
+  }
+},
+methods: {
+  _primeDefaultValue() {
+    if (!this.value || (Array.isArray(this.value) && this.value.length === 0)) return
+    if (!this._flatList || this._flatList.length === 0) return
+    // 从 value 提取要回显的叶子 id
+    const leafId = this.emitPath
+      ? this.value[this.value.length - 1]
+      : (Array.isArray(this.value) ? this.value[0] : this.value)
+    if (!leafId) return
+    // 反向追溯整条祖先链
+    const chain = []
+    let cur = this._flatList.find(i => i.id === leafId)
+    while (cur) {
+      chain.unshift(cur)
+      cur = cur.parentId ? this._flatList.find(i => i.id === cur.parentId) : null
+    }
+    if (!chain.length) return
+    // ⚠️ 关键:对链上每一层,把"该 parent 的所有子"全部预 resolve
+    //   不能只缓存链上节点本身,否则兄弟节点展开时 lazyLoad 仍要走
+    //   一次同步查表(虽然能 work,但首屏会有"先空再填"的闪烁)
+    const parentIds = ['', ...chain.slice(0, -1).map(n => n.id)]
+    parentIds.forEach(pid => {
+      if (!this._resolvedCache.has(pid)) {
+        this._resolvedCache.set(pid, this._buildChildren(pid))
+      }
+    })
+  },
+  _buildChildren(parentId) {
+    return this._flatList
+      .filter(item => (item.parentId || '') === (parentId || ''))
+      .map(item => ({
+        ...item,
+        leaf: !this._flatList.some(c => (c.parentId || '') === item.id),
+        children: [],
+      }))
+  }
+}
+```
+
+### 4. `props` 透传给 el-cascader
+
+```js
+computed: {
+  cascaderProps() {
+    return {
+      lazy: true,
+      lazyLoad: this.lazyLoad,
+      value: 'id',
+      label: 'label',
+      children: 'children',
+      leaf: 'leaf',
+      checkStrictly: this.checkStrictly,
+      emitPath: this.emitPath,
+    }
+  }
+}
+```
+
+## Demo 页面 (`lazyCascader/index.vue`)
+
+### 案例清单
+
+| # | 案例 | 关键 props | 默认值 | 验证点 |
+|---|------|------------|--------|--------|
+| 1 | 基础:可选任意级 | `checkStrictly=true` | 无 | 展开三级、可选任意级关掉面板 |
+| 2 | 基础:只选最后一级 + 输入框只显示最后一级 | `checkStrictly=false`, `emitPath=false` | 无 | 选叶子后输入框只显示叶子 label;v-model 是叶子 id |
+| 3 | 默认值回显 | `emitPath=true` | 预设一个三级路径 | 组件挂载即显示完整路径;可继续点开重选 |
+| 4 | v-if 销毁/重建 | `emitPath=true` | 预设一个三级路径 | 按钮 toggle v-if;再次显示时回显正确 |
+| 5 | 先有默认值、后到数据 | `emitPath=true` | 预设一个三级路径 | 初始 `data=[]` 渲染,1s 后模拟接口返回 `data`;同时触发组件 `reload()` |
+| 6 | 后端返的是树形结构 | `emitPath=true` | 预设一个三级路径 | `tree` 经 `flattenTree` 转扁平后传给组件;正常回显 |
+
+每个 case 下有辅助按钮:
+- **查看当前值** — `<pre>` 打印 v-model 和 emitPath 影响
+- **重置** — 清空选择
+- **重置为默认** — 把 v-model 重新设回该 case 的默认
+
+### 关键代码骨架
+
+```vue
+<template>
+  <div class="lazy-cascader-demo">
+    <PageHeader title="级联懒加载(前端拆分)" :description="..." :usage="..." />
+
+    <el-card class="case" header="案例 1: 基础 - 可选任意级">
+      <LazyCascader
+        v-model="case1.value"
+        :data="flatRegions"
+        :check-strictly="true"
+        placeholder="请选择(任意级)"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="showValue('case1')">查看当前值</el-button>
+        <el-button size="mini" @click="case1.value = []">重置</el-button>
+      </div>
+      <pre v-if="case1.display">{{ JSON.stringify(case1.value, null, 2) }}</pre>
+    </el-card>
+
+    <el-card class="case" header="案例 2: 基础 - 只选最后一级 + 输入框只显示最后一级">
+      <LazyCascader
+        v-model="case2.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :emit-path="false"
+        placeholder="请选择(只选叶子)"
+      />
+      <!-- ... -->
+    </el-card>
+
+    <el-card class="case" header="案例 3: 默认值回显">
+      <LazyCascader
+        v-model="case3.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :emit-path="true"
+      />
+    </el-card>
+
+    <el-card class="case" header="案例 4: v-if 销毁/重建">
+      <el-button size="mini" @click="case4.visible = !case4.visible">
+        {{ case4.visible ? '隐藏' : '显示' }}
+      </el-button>
+      <LazyCascader
+        v-if="case4.visible"
+        v-model="case4.value"
+        :data="flatRegions"
+      />
+    </el-card>
+
+    <el-card class="case" header="案例 5: 先有默认值,后到数据">
+      <LazyCascader
+        :ref="'case5Ref'"
+        v-model="case5.value"
+        :data="case5.data"
+      />
+      <el-button size="mini" @click="loadCase5Data">模拟接口返回(1s 后)</el-button>
+    </el-card>
+
+    <el-card class="case" header="案例 6: 后端返回的是树形结构">
+      <LazyCascader
+        v-model="case6.value"
+        :data="case6.flatData"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="case6.flatData = flattenTree(treeRegions)">
+          重新调用 flattenTree
+        </el-button>
+      </div>
+    </el-card>
+  </div>
+</template>
+```
+
+`loadCase5Data`:
+
+```js
+loadCase5Data() {
+  this.$message.info('1s 后模拟接口返回…')
+  setTimeout(() => {
+    this.case5.data = flatRegions
+    this.$nextTick(() => {
+      this.$refs.case5Ref?.reload?.() // 触发组件内部 _primeDefaultValue 重跑
+    })
+  }, 1000)
+}
+```
+
+## Mock 数据 (`data.js`)
+
+```js
+// 1. 扁平:3 省 × 3~4 市 × 2~3 区 ≈ 30 节点
+export const flatRegions = [
+  // 河北省
+  { id: 'hebei', parentId: '', label: '河北省' },
+  { id: 'sjz',    parentId: 'hebei', label: '石家庄市' },
+  { id: 'sjz-cd', parentId: 'sjz',    label: '长安区' },
+  { id: 'sjz-qx', parentId: 'sjz',    label: '桥西区' },
+  // ... (展开 30+ 节点,覆盖 2~3 级)
+]
+
+// 2. 树形:同一份数据,只是 children 嵌套
+export const treeRegions = [
+  {
+    id: 'hebei', label: '河北省', children: [
+      { id: 'sjz', label: '石家庄市', children: [
+        { id: 'sjz-cd', label: '长安区' },
+        ...
+      ]},
+      ...
+    ]
+  },
+  ...
+]
+
+// 3. 工具:树 → 扁平
+export function flattenTree(tree) {
+  const out = []
+  const walk = (nodes, parentId) => {
+    nodes.forEach(n => {
+      const { children, ...rest } = n
+      out.push({ ...rest, parentId: parentId || '' })
+      if (Array.isArray(children) && children.length) walk(children, n.id)
+    })
+  }
+  walk(tree, '')
+  return out
+}
+
+// 4. 模拟接口(返回 Promise,带 0~50ms 延时)
+export function fetchChildren(parentId, flat = flatRegions) {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      resolve(flat.filter(i => (i.parentId || '') === (parentId || '')))
+    }, Math.random() * 50)
+  })
+}
+```
+
+> 真实工程里 `fetchChildren` 可以走 axios;这里用 `flatRegions` 当数据源
+> 模拟,演示"后端一次返完"的语义。
+
+## 错误处理与边界
+
+| 场景 | 处理 |
+|------|------|
+| `data` 为空数组 | 组件渲染空面板,不报错 |
+| `value` 对应的 id 在 `data` 中找不到 | `_primeDefaultValue` 静默跳过,清空缓存,组件正常显示空 |
+| `value` 是叶子 id 但 `emitPath=true` | 触发整条链追溯,缓存每一层兄弟 |
+| `value` 在 `data` 变化(案例 5)后变更 | `watch data` 触发 `reload()` 由外部调用;组件内部 `watch value` 重新 prime |
+| `flattenTree` 节点无 `children` 字段 | 视为叶子,跳过递归 |
+| 重复创建(_hot reload_) | 用 `this._resolvedCache = new Map()` 在 `created` 初始化,无副作用 |
+
+## 测试策略
+
+项目无现成测试框架,采用 demo 页面 + 人工验证:
+
+- 6 个 case 全部能正常渲染
+- 案例 1:可选任意级,选完关闭面板
+- 案例 2:只能选叶子级;选完输入框只显示叶子 label;v-model 是叶子 id(字符串)
+- 案例 3:挂载即回显默认值,可继续重选
+- 案例 4:v-if 切换后默认值仍然正确
+- 案例 5:`data` 从 `[]` 变 `flatRegions` 后,默认值自动回显
+- 案例 6:`flattenTree(treeRegions)` 出来的扁平数据能正确驱动回显
+
+## 实现步骤
+
+1. 写 `data.js`(扁平 + 树形 + flattenTree + fetchChildren)
+2. 写 `LazyCascader.vue`(组件实现,带默认值回显逻辑)
+3. 写 `index.vue`(Demo 页面,6 个 case)
+4. 修改 `src/views/element/index.vue`,新增 tab 并 import Demo
+5. 启动 dev server,人工验证 6 个 case
+
+## 范围之外(本期不做)
+
+- 多选(只做单选)
+- 搜索/过滤
+- 自定义节点渲染(slot)
+- 虚拟滚动(数据量仅 30 节点,无需)
+- 异步获取整棵 data(本期假设 data 同步传入;真要异步可走案例 5 的
+  `data=[]` → `data=...` 模式 + `reload()`)

package/app/jsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "esnext",
+    "baseUrl": "./",
+    "moduleResolution": "node",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    },
+    "lib": [
+      "esnext",
+      "dom",
+      "dom.iterable",
+      "scripthost"
+    ]
+  }
+}