---
name: fix-tree-component
overview: 修复 fms-vue 中 Tree 组件的多个缺陷：致命运行时错误（filterExpand 未定义）、受控键模型遗漏、过滤高亮缺失、键盘焦点不同步、展开交互混乱与拖拽视觉残留，并同步完善 demo。
todos:
  - id: fix-critical-errors
    content: 修复 tree.vue 中 filterExpand 未定义导致的渲染崩溃，并补充缺失的 defaultLoadedKeys prop
    status: completed
  - id: refactor-expand-select
    content: 重构展开/选中交互：加回 switcher 箭头、toggleExpand 改用用户展开集合、行点击只选中并同步键盘焦点，参考 [skill:antdv-next] 交互规范
    status: completed
    dependencies:
      - fix-critical-errors
  - id: filter-highlight
    content: 在 tree-node.vue 实现过滤关键词高亮渲染，命中片段包裹 tree-highlight
    status: completed
    dependencies:
      - fix-critical-errors
  - id: fix-drag-cleanup
    content: 修复 onDragLeave 未清理 drop 状态导致的指示线残留，并清理 index.scss 无用样式
    status: completed
    dependencies:
      - fix-critical-errors
  - id: fix-demo
    content: 修正 demo/tree.vue 中 check-strictly 示例绑定与联动文案错乱问题
    status: completed
  - id: verify-build
    content: 运行 pnpm lint、fmt:check 与 build 验证修复无回归
    status: completed
    dependencies:
      - refactor-expand-select
      - filter-highlight
      - fix-drag-cleanup
      - fix-demo
---

## 用户需求

用户反馈 `fms-vue/src/components/ui/tree` 组件由上一个 AI 编写，存在较多问题，要求自检问题并修复。经过代码自检，已确认以下问题：

## 核心问题

- **致命错误**：`tree.vue` 的 `effectiveExpanded` computed 引用了未定义的 `filterExpand` 变量，组件渲染即抛 `ReferenceError`，Tree 完全不可用
- **Props 缺失**：`useKeyModel('loadedKeys', 'defaultLoadedKeys', ...)` 引用了不存在的 `defaultLoadedKeys` prop
- **过滤高亮缺失**：`filterTree` 返回的命中集合与 `.tree-highlight` 样式均未用于渲染关键词高亮
- **展开交互缺陷**：展开/收起箭头被移除，无可展开视觉提示；行点击同时触发展开与选中造成误触；`toggleExpand` 基于 `effectiveExpanded` 会把过滤临时展开的祖先固化进用户展开集合
- **键盘导航缺陷**：点击节点后未同步 `activeKey` 与焦点，键盘导航起点错乱
- **拖拽视觉残留**：`onDragLeave` 未清理 `dropKey`/`dropPosition`，指示线残留
- **样式残留**：`.tree-node.is-danger`、`.tree-leaf-icon` 等无用样式
- **Demo 错乱**：check-strictly 示例未绑定 checkedKeys，联动文案错标在严格模式示例下

## 修复范围

仅修复内部实现与 demo 演示，保持组件既有 API（props/emits/slot 名称）不变，不引入新依赖，样式沿用现有 `--fms-*` token。

## 技术栈

- Vue 3.5（`<script setup>`）+ SCSS，项目现有技术栈，无需变更
- 图标使用项目已依赖的 `@lucide/vue`（现有导出 `ChevronRight`、`Loader`、`LoaderCircle`）
- 验证命令：`pnpm lint`（oxlint）、`pnpm fmt:check`（oxfmt）、`pnpm build`（vite build）

## 实现方案

### 1. 修复致命错误与模型缺失（tree.vue）

- 删除 `effectiveExpanded` 中对未定义 `filterExpand` 的引用，改为从 `filterResult.value.expand` 派生过滤需展开的祖先集合（computed 缓存，判空处理）
- props 补充声明 `defaultLoadedKeys: { type: Array, default: () => [] }`，与其余受控键的 default* 声明保持一致

### 2. 重构展开/选中交互（tree.vue + tree-node.vue + index.scss）

- **加回 switcher 箭头**：`tree-node.vue` 行首渲染 `ChevronRight`（展开时旋转 90°），懒加载中渲染 `Loader`/`LoaderCircle` 转圈；箭头 `@click.stop` 只负责 `toggleExpand`，避免与行选中互相干扰；利用现有 `.tree-node-switcher`/`.tree-switcher-icon` 样式（已存在于 index.scss，仅模板缺失）
- **`toggleExpand` 基准改为 `expandedSet`**：基于用户展开集合增删，不再把过滤自动展开的祖先路径写回 `expandedKeys`，清除过滤后展开状态可正确还原
- **行点击只选中**：`onContentClick` 移除隐式 `toggleExpand` 调用（展开交给箭头），消除误触
- **点击同步键盘焦点**：`onContentClick` 中更新 `activeKey.value = key.value` 并 `rowRef.value.focus()`，保证 roving tabindex 与键盘导航起点正确
- 键盘导航 `ArrowRight/ArrowLeft` 保持调用 `toggleExpand` 不变

### 3. 实现过滤关键词高亮（tree-node.vue）

- 默认文本标题渲染时，依据 `ctx.filter` 与 `filterVisible` 中 matched 集合，用 `split` 匹配关键词片段，命中部分用 `<span class="tree-highlight">` 包裹（大小写不敏感，与 `filterTree` 一致）；自定义 `#title` 插槽场景不干预
- 高亮逻辑抽为组件内方法，避免重复计算；每次渲染仅处理当前节点标题，开销 O(title 长度)，无性能问题

### 4. 修复拖拽残留与样式清理（tree.vue + index.scss）

- `onDragLeave` 中清空 `dropKey`/`dropPosition`（仍 emit `dragleave`）；`onDragEnd` 已有兜底清理保留
- 清理 index.scss 中未使用的 `.tree-node.is-danger`、`.tree-leaf-icon` 规则（switcher 相关样式因加回箭头而保留复用）

### 5. 修复 Demo（demo/tree.vue）

- check-strictly 示例补充 `v-model:checked-keys` 绑定与输出展示；"checkedKeys（联动）"文案移回联动示例下方，修正演示语义

### 性能与可靠性

- 全部派生状态为 computed 缓存，`effectiveExpanded` 修复后只依赖 `expandedSet` + `filterResult`，无重复遍历
- 修改仅限 tree 组件目录与 demo 文件，不影响其他组件；无新依赖，无构建体积变化

## 目录结构

```
fms-vue/src/components/ui/tree/
├── tree.vue        # [MODIFY] 修复 filterExpand 未定义；补 defaultLoadedKeys；toggleExpand 基准改为 expandedSet；
│                   #          onDragLeave 清理 drop 状态；onContentClick 同步 activeKey/focus
├── tree-node.vue   # [MODIFY] 加回 switcher 箭头（ChevronRight/Loader，@click.stop）；行点击只选中；
│                   #          实现过滤关键词高亮渲染
├── index.scss      # [MODIFY] 清理 .is-danger/.tree-leaf-icon 无用规则；switcher 样式保留复用
└── utils.js        # [不变] 纯函数逻辑正确，无需修改
fms-vue/src/components/ui/demo/tree.vue  # [MODIFY] 修正 check-strictly 示例绑定与文案
```

## Agent Extensions

### Skill

- **antdv-next**
- 用途：在重构展开/选中交互时，参考 Ant Design Tree 的 switcher 箭头交互、行点击与箭头职责分离、键盘导航规范，确保修复后的交互符合成熟组件库惯例
- 预期结果：展开箭头点击展开/收起、行点击仅选中、键盘 ArrowRight/ArrowLeft 行为与成熟组件库一致，避免修复后再次出现交互职责混淆