# Composable 集成失败根因分析报告
**日期**: 2025-01-30
**目标**: 分析为什么 useFileEdit 和 useFilePreview 无法集成到 FileSystem.vue

---

## 执行摘要

集成尝试失败的根本原因：**Composables 和本地实现在设计哲学、API 契约、功能范围上存在系统性差异**。

- ❌ **useFileEdit**: 不兼容（状态变量不匹配：`isEditMode` vs `isEditableView`）
- ❌ **useFilePreview**: 不兼容（URL 格式、路径处理、ZIP 模式支持差异）
- ✅ **useNavigation**: 兼容（已成功集成）

---

## 一、useFileEdit.js vs FileSystem.vue

### 1.1 状态变量差异

| 功能点 | useFileEdit.js | FileSystem.vue | 兼容性 |
|--------|----------------|----------------|--------|
| **编辑模式开关** | `isEditMode` (简单 ref) | `isEditableView` (复杂 computed) | ❌ 不兼容 |
| **路径来源** | `filePath` (单一) | `selectedFilePath` \| `filePath` (双重) | ❌ 不兼容 |
| **文件修改检测** | 简单比较 | 复杂逻辑（含新建文件） | ❌ 不兼容 |

### 1.2 致命差异：`canSaveFile` 的条件

**useFileEdit.js:87-89**
```javascript
const canSaveFile = computed(() => {
  return isEditMode.value && contentChanged.value
})
```

**FileSystem.vue:2997**
```javascript
const canSaveFile = computed(() => isEditableView.value && contentChanged.value)
```

**问题**：
- `isEditMode`: 简单的布尔值 ref，来自 localStorage
- `isEditableView`: 复杂的 computed，依赖预览状态

```javascript
// FileSystem.vue:2968-2974
const isEditableView = computed(() => {
  return !isImageView.value &&
         !isVideoView.value &&
         !isAudioView.value &&
         !isPdfFile.value &&
         !isBinaryFile.value
})
```

**影响**：
- 使用 `isEditMode` → 保存按钮可能在图片预览时也显示（错误）
- 使用 `isEditableView` → 保存按钮只在文本编辑时显示（正确）

### 1.3 致命差异：`isFileModified` 的逻辑

**useFileEdit.js:71-74**
```javascript
const isFileModified = computed(() => {
  return originalContent.value !== undefined &&
         originalContent.value !== fileContent.value
})
```

**FileSystem.vue:2977-2988**
```javascript
const isFileModified = computed(() => {
  const hasContent = fileContent.value !== '' && fileContent.value.trim() !== ''
  const hasModified = selectedFilePath.value && fileContent.value !== originalContent.value
  const isNewFile = !selectedFilePath.value && hasContent  // ← 新建文件检测
  return isEditableView.value && (hasModified || isNewFile)
})
```

**缺失功能**：
- Composable 版本**不支持新建文件场景**
- FileSystem.vue 版本可以检测到"未选择文件路径但有内容"的新建文件状态

### 1.4 依赖图对比

**useFileEdit 依赖树**:
```
canSaveFile
  ├─ isEditMode (ref)
  └─ contentChanged
      ├─ fileContent
      └─ originalContent
```

**FileSystem.vue 依赖树**:
```
canSaveFile
  ├─ isEditableView (computed)
  │   ├─ isImageView
  │   ├─ isVideoView
  │   ├─ isAudioView
  │   ├─ isPdfFile
  │   └─ isBinaryFile
  └─ contentChanged
      ├─ fileContent
      └─ originalContent
```

**结论**: FileSystem.vue 的依赖更复杂，Composable 过于简化

---

## 二、useFilePreview.js vs FileSystem.vue

### 2.1 URL 构建差异（致命）

**useFilePreview.js:163**
```javascript
const encodedPath = encodeURIComponent(pathToPreview)
previewUrl.value = `${fileServerURL.value}/file?path=${encodedPath}`
```

**FileSystem.vue:1503**
```javascript
previewUrl.value = `${fileServerURL.value}/localfs/${normalizeFilePath(pathToPreview, true)}`
```

**问题**：
- Composable: `/file?path=xxx` (查询参数格式)
- FileSystem.vue: `/localfs/xxx` (路径格式，需要规范化)

**不兼容原因**：
- 后端可能只支持其中一种格式
- `normalizeFilePath()` 可能有特殊处理（如 Windows 路径转换）

### 2.2 路径参数优先级差异

**useFilePreview.js:148**
```javascript
const previewImage = async (targetPath) => {
  const pathToPreview = targetPath || filePath.value  // 只用 filePath
  // ...
}
```

**FileSystem.vue:1487**
```javascript
const previewImageLocal = async (targetPath) => {
  const pathToPreview = targetPath || selectedFilePath.value || filePath.value  // 三级优先级
  // ...
}
```

**三级优先级**：
1. `targetPath` (显式传入)
2. `selectedFilePath` (当前选中的文件)
3. `filePath` (当前目录)

**影响**：
- Composable 在"选中文件但未传参"时会失败
- FileSystem.vue 可以自动回退到 `selectedFilePath`

### 2.3 computed 属性功能差异

**currentFileName** 对比：

| 功能 | useFilePreview | FileSystem.vue | 差异 |
|------|----------------|----------------|------|
| **ZIP 模式支持** | ❌ 无 | ✅ 有 | 关键差异 |
| **目录检测** | ❌ 无 | ✅ 有 | UX 增强 |
| **路径截断** | ❌ 无 | ✅ 有 | UX 增强 |
| **错误处理** | ❌ 无 | ✅ try-catch | 健壮性 |

**FileSystem.vue:1437-1460** (23行，包含 ZIP 逻辑)
```javascript
const currentFileNameDisplay = computed(() => {
  if (isBrowsingZip.value && selectedFilePath.value) {
    // ZIP 模式：从 zip 内路径中提取文件名
    const parts = selectedFilePath.value.split('/')
    return parts[parts.length - 1] || parts[parts.length - 2] || ''
  }
  if (selectedFilePath.value) {
    // 正常模式：如果文件在当前目录，只显示文件名；否则显示完整路径
    try {
      if (isFileInCurrentDirectory.value) {
        return getFileName(selectedFilePath.value)
      } else {
        return selectedFilePath.value  // 返回完整路径
      }
    } catch (error) {
      debugWarn('[currentFileName] 计算失败，返回文件名:', error)
      return getFileName(selectedFilePath.value)
    }
  }
  return ''
})
```

**useFilePreview.js:122-126** (5行，无特殊逻辑)
```javascript
const currentFileName = computed(() => {
  if (!filePath.value) return ''
  const parts = filePath.value.split(/[/\\]/)
  return parts[parts.length - 1]
})
```

### 2.4 函数命名体系差异

| 功能 | useFilePreview | FileSystem.vue |
|------|----------------|----------------|
| 图片预览 | `previewImage` | `previewImageLocal` |
| 视频预览 | `previewVideo` | `previewVideoLocal` |
| 音频预览 | `previewAudio` | `previewAudioLocal` |
| PDF 预览 | `previewPdf` | `previewPdfLocal` |
| HTML 预览 | `previewHtml` | `previewHtmlLocal` |
| Markdown 预览 | `previewMarkdown` | `previewMarkdownLocal` |

**Local 后缀的意义**：
- 表明这是本地实现，避免与外部库或全局函数冲突
- 如果替换为 Composable，需要全局重命名模板中的所有调用点（30+ 处）

---

## 三、useNavigation.js vs FileSystem.vue

### 3.1 集成状态

✅ **已成功集成** (FileSystem.vue:605-625)

```javascript
const {
  navHistory,
  navIndex,
  isNavigating,
  canGoBack,
  canGoForward,
  addToHistory,
  pushNav,
  goBack,
  goForward,
  onPathSelect,
  onPathEnter,
  browseDirectory,
} = useNavigation({
  filePath,
  onListDirectory: async (path) => {
    filePath.value = path
    await listDirectory()
  }
})
```

### 3.2 为什么成功？

1. **清晰的回调接口**: `onListDirectory` 作为回调，连接到本地实现
2. **状态变量简单**: 只依赖 `filePath`，没有复杂的 computed 依赖
3. **无 API 假设**: 不涉及 URL 格式、网络请求等
4. **功能独立**: 导航逻辑不依赖预览、编辑等其他模块

### 3.3 集成模式

```
┌─────────────────┐
│ useNavigation   │
└────────┬────────┘
         │
         │ onListDirectory(path)
         ▼
┌─────────────────┐
│ FileSystem.vue  │
│  listDirectory()│
└─────────────────┘
```

这种模式清晰、解耦、易于测试。

---

## 四、根因总结

### 4.1 设计哲学差异

| 维度 | Composables | FileSystem.vue |
|------|-------------|----------------|
| **复杂度** | 追求简洁、纯粹 | 追求功能完整 |
| **假设** | 单一路径、标准API | 多路径源、自定义API |
| **范围** | 单一职责 | 全功能 |
| **演进** | 从头设计 | 增量演进（ZIP、新建文件等） |

### 4.2 API 契议不匹配

**Composable 隐式假设**：
```javascript
// 假设 1: URL 格式
`${fileServerURL}/file?path=${encodedPath}`

// 假设 2: 路径来源
const path = filePath.value  // 单一来源

// 假设 3: 状态变量
const canSave = isEditMode && changed  // 简单布尔值
```

**FileSystem.vue 实际**：
```javascript
// 实际 1: URL 格式
`${fileServerURL}/localfs/${normalizeFilePath(path, true)}`

// 实际 2: 路径来源
const path = targetPath || selectedFilePath || filePath  // 三级优先级

// 实际 3: 状态变量
const canSave = isEditableView && changed  // 复杂 computed
```

### 4.3 功能演进差距

**FileSystem.vue 独有功能**：
- ✅ ZIP 文件浏览模式
- ✅ 新建文件检测
- ✅ 目录感知显示
- ✅ 路径规范化
- ✅ 文件是否在当前目录检测

**useFileEdit/useFilePreview 创建时未考虑这些功能**

---

## 五、集成失败的三个层次

### 层次 1: 语法层面（易于发现）
```
❌ ReferenceError: loadDraft is not defined
❌ Identifier 'previewImage' has already been declared
```

### 层次 2: 语义层面（运行时错误）
```
❌ 保存按钮在图片预览时也显示 (isEditMode vs isEditableView)
❌ URL 404 错误 (/file?path= vs /localfs/)
❌ 新建文件无法保存
```

### 层次 3: 设计层面（深层不兼容）
```
❌ 单一路径模型 vs 多路径源
❌ 简单布尔值 vs 复杂 computed
❌ 标准API vs 自定义API
❌ 静态功能 vs 增量演进
```

---

## 六、解决方案

### 方案 A: 保持现状 + 提取工具函数（推荐）

**理由**：
- 功能完整性优先
- 避免破坏性重构
- 渐进式优化

**行动**：
1. 保留 `useNavigation` 集成
2. 删除 `useFileEdit` 和 `useFilePreview`（或作为参考文档）
3. 提取真正的通用工具函数：
   ```javascript
   // utils/pathHelpers.js
   export const splitPath = (path) => path.split(/[/\\]/)
   export const getFileName = (path) => { /* ... */ }
   export const getParentPath = (path) => { /* ... */ }

   // utils/fileHelpers.js
   export const isImageFile = (ext) => FILE_EXTENSIONS.IMAGE.includes(ext)
   export const isVideoFile = (ext) => FILE_EXTENSIONS.VIDEO_BROWSER.includes(ext)
   ```

4. 减少调试日志（65 → 10）

### 方案 B: 重构 FileSystem.vue（激进）

**风险**: 高
**时间**: 2-3周
**收益**: 长期可维护性

**步骤**：
1. 统一状态管理（单一 `filePath` vs `selectedFilePath`）
2. 标准化 API（统一 URL 格式）
3. 组件化拆分（子组件）
4. 然后重新集成 Composables

### 方案 C: 创建轻量级 Composables（折中）

```javascript
// useFileEditMinimal.js
export function useFileEditMinimal({ fileContent, originalContent }) {
  const contentChanged = computed(() =>
    fileContent.value !== '' &&
    fileContent.value !== originalContent.value
  )

  return { contentChanged }
}

// FileSystem.vue
const { contentChanged } = useFileEditMinimal({ fileContent, originalContent })
const canSaveFile = computed(() => isEditableView.value && contentChanged.value)
```

---

## 七、检查清单

### 立即行动（本周）

- [x] 分析集成失败根因
- [ ] 修复 `loadDraft is not defined` 运行时错误
- [ ] 决定方案 A/B/C
- [ ] 执行决定

### 短期优化（2周）

- [ ] 提取路径工具函数
- [ ] 提取文件类型判断函数
- [ ] 统一 localStorage 键名
- [ ] 减少调试日志

### 长期重构（1个月）

- [ ] 组件化拆分（子组件）
- [ ] 状态管理优化
- [ ] TypeScript 迁移
- [ ] 单元测试覆盖

---

## 八、关键发现

### 发现 1: Composables 是"理想版本"

Composables 基于**理想假设**设计：
- 单一路径来源
- 标准 API
- 简单状态
- 纯净功能

但 FileSystem.vue 是**现实版本**：
- 多路径源（历史包袱）
- 自定义 API（性能优化）
- 复杂状态（功能完整）
- 增量演进（业务需求）

### 发现 2: 命名体系反映演进历史

所有预览函数都有 `Local` 后缀：
```javascript
previewImageLocal    // 表明"本地实现"
previewVideoLocal    // 避免"全局冲突"
```

这说明开发者在添加这些函数时，**已经意识到可能存在外部冲突**，因此添加后缀。

如果强行使用无后缀的 Composable 版本，会破坏这种防御性设计。

### 发现 3: useNavigation 成功的启示

useNavigation 成功的关键：
1. **清晰的边界**: 只负责导航历史
2. **回调接口**: 不直接操作文件系统
3. **状态简单**: 只依赖 `filePath`
4. **无副作用**: 不涉及 UI 状态

**教训**: 如果要提取 Composables，应该遵循同样的原则。

---

## 九、最终建议

### 推荐：方案 A - 提取工具函数

**原因**：
1. **风险最低**: 不破坏现有功能
2. **收益明确**: 减少代码重复（路径处理、文件类型判断）
3. **时间可控**: 1周内完成
4. **渐进式**: 为未来重构铺路

**具体行动**：
```javascript
// 第1步：提取工具函数
// utils/pathHelpers.js
// utils/fileTypeHelpers.js

// 第2步：替换重复代码
// path.split(/[/\\/]/) → splitPath(path)

// 第3步：删除未使用的 Composables
// rm useFileEdit.js useFilePreview.js

// 第4步：减少调试日志
// 保留 10 个关键日志，删除 55 个
```

**预期结果**：
- 代码减少 ~200 行
- DRY 评分改善 5%
- 维护成本降低
- 为长期重构打好基础