# OOP 服务层实施方案 - 彻底解决初始化问题

**日期**: 2026-01-31
**问题**: 第5次依然出现 "Cannot access before initialization" 错误
**方案**: 采用面向对象的服务层架构

---

## 🎯 核心问题

当前 Composition API 方案存在**根本性缺陷**：

```typescript
// 问题1: 函数定义顺序依赖手动保证
const config = computed(() => useHelper())  // Line 362
const useHelper = () => { ... }             // Line 869 ❌

// 问题2: 解构容易遗漏
const { previewUrl, isImageView } = useFilePreview()
// ❌ 忘记解构 updatePreviewUrl

// 问题3: 返回值过多
const { 15+个返回值 } = useFilePreview()

// 问题4: 状态分散
const state1 = ref()
const state2 = ref()
const state3 = ref()
// 状态和行为分离，内聚性差
```

---

## 💡 OOP 解决方案

### 架构设计

```
┌─────────────────────────────────────────┐
│           View Layer (Vue)              │
│  <template> | index.vue | 组件           │
└─────────────┬───────────────────────────┘
              │ 调用
┌─────────────▼───────────────────────────┐
│       Adapter Layer (Composables)        │
│  轻量级适配器，提供响应式接口             │
└─────────────┬───────────────────────────┘
              │ 使用
┌─────────────▼───────────────────────────┐
│        Service Layer (OOP)              │
│  核心业务逻辑，状态+行为封装              │
└─────────────┬───────────────────────────┘
              │ 依赖
┌─────────────▼───────────────────────────┐
│         Infrastructure Layer            │
│  文件API、ZIP处理等底层服务               │
└─────────────────────────────────────────┘
```

---

## 📝 具体实现

### 1. 服务基类

```typescript
// core/ServiceBase.ts
export abstract class ServiceBase {
  protected readonly logger = console
  protected readonly scope: string

  constructor(scope: string) {
    this.scope = scope
    this.initialize()
  }

  protected initialize(): void {
    // 子类可以覆盖
  }

  protected log(message: string, ...args: any[]): void {
    this.logger.log(`[${this.scope}]`, message, ...args)
  }

  protected error(message: string, error: Error): void {
    this.logger.error(`[${this.scope}]`, message, error)
  }
}
```

### 2. 文件预览服务

```typescript
// services/FilePreviewService.ts
import { ref, type Ref } from 'vue'
import { Message } from '@arco-design/web-vue'
import { ServiceBase } from '@/core/ServiceBase'
import type { FileApiService } from './FileApiService'
import { FileTypes } from '@/utils/fileTypeHelpers'

/**
 * 文件预览服务
 * 负责处理各种文件类型的预览逻辑
 */
export class FilePreviewService extends ServiceBase {
  // ========== 状态（私有） ==========
  private readonly _previewUrl = ref<string>('')
  private readonly _imageLoading = ref<boolean>(false)
  private readonly _currentImageDimensions = ref<string>('')

  // ========== 依赖注入 ==========
  constructor(
    private readonly fileApi: FileApiService,
    private readonly filePath: Ref<string>
  ) {
    super('FilePreviewService')
  }

  // ========== 公共接口（访问器） ==========

  /** 获取预览URL（响应式） */
  get previewUrl(): Ref<string> {
    return this._previewUrl
  }

  /** 获取图片加载状态（响应式） */
  get imageLoading(): Ref<boolean> {
    return this._imageLoading
  }

  /** 获取图片尺寸（响应式） */
  get currentImageDimensions(): Ref<string> {
    return this._currentImageDimensions
  }

  // ========== 公共方法 ==========

  /**
   * 更新预览URL
   */
  updatePreviewUrl(url: string): void {
    this._previewUrl.value = url
  }

  /**
   * 预览文件
   */
  async previewFile(filePath: string): Promise<void> {
    const ext = FileTypes.getExtension(filePath)

    if (this.isImageFile(filePath)) {
      await this.previewImage(filePath)
    } else if (this.isVideoFile(filePath)) {
      await this.previewVideo(filePath)
    } else if (this.isAudioFile(filePath)) {
      await this.previewAudio(filePath)
    } else if (this.isPdfFile(filePath)) {
      await this.previewPdf(filePath)
    }
  }

  /**
   * 判断是否为图片文件
   */
  isImageFile(path: string): boolean {
    return FileTypes.isImage(path)
  }

  /**
   * 判断是否为视频文件
   */
  isVideoFile(path: string): boolean {
    return FileTypes.isVideo(path)
  }

  /**
   * 判断是否为音频文件
   */
  isAudioFile(path: string): boolean {
    return FileTypes.isAudio(path)
  }

  /**
   * 判断是否为PDF文件
   */
  isPdfFile(path: string): boolean {
    return FileTypes.isPdf(path)
  }

  /**
   * 判断是否为HTML文件
   */
  isHtmlFile(path: string): boolean {
    return FileTypes.isHtml(path)
  }

  /**
   * 判断是否为Markdown文件
   */
  isMarkdownFile(path: string): boolean {
    return FileTypes.isMarkdown(path)
  }

  /**
   * 判断是否支持编辑/预览切换
   */
  isEditableWithPreview(filename: string): boolean {
    const ext = filename.split('.').pop()?.toLowerCase() || ''
    return ['html', 'htm', 'md', 'markdown'].includes(ext)
  }

  // ========== 私有方法 ==========

  private async previewImage(path: string): Promise<void> {
    this._imageLoading.value = true
    try {
      const url = await this.fileApi.getImageUrl(path)
      this.updatePreviewUrl(url)
      this.log('图片预览加载成功', path)
    } catch (error) {
      this.error('图片预览加载失败', error as Error)
      Message.error('图片加载失败')
    } finally {
      this._imageLoading.value = false
    }
  }

  private async previewVideo(path: string): Promise<void> {
    const url = await this.fileApi.getFileUrl(path)
    this.updatePreviewUrl(url)
  }

  private async previewAudio(path: string): Promise<void> {
    const url = await this.fileApi.getFileUrl(path)
    this.updatePreviewUrl(url)
  }

  private async previewPdf(path: string): Promise<void> {
    const url = await this.fileApi.getFileUrl(path)
    this.updatePreviewUrl(url)
  }
}
```

### 3. ZIP浏览服务

```typescript
// services/ZipBrowserService.ts
import { ref, computed, type Ref } from 'vue'
import { Message } from '@arco-design/web-vue'
import { ServiceBase } from '@/core/ServiceBase'
import type { FileApiService } from './FileApiService'
import type { FilePreviewService } from './FilePreviewService'
import type { FileItem } from '@/types/file-system'

/**
 * ZIP浏览服务
 * 负责ZIP文件浏览逻辑
 */
export class ZipBrowserService extends ServiceBase {
  // ========== 状态 ==========
  private readonly _isBrowsingZip = ref<boolean>(false)
  private readonly _currentZipPath = ref<string>('')
  private readonly _currentZipDirectory = ref<string>('')
  private readonly _pathBeforeZip = ref<string>('')

  // ========== 依赖注入 ==========
  constructor(
    private readonly fileApi: FileApiService,
    private readonly previewService: FilePreviewService,
    private readonly fileList: Ref<FileItem[]>,
    private readonly filePath: Ref<string>
  ) {
    super('ZipBrowserService')
    // 构造函数保证依赖已初始化
  }

  // ========== 计算属性 ==========

  /** 是否正在浏览ZIP */
  get isBrowsingZip(): Ref<boolean> {
    return this._isBrowsingZip
  }

  /** 当前ZIP路径 */
  get currentZipPath(): Ref<string> {
    return this._currentZipPath
  }

  /** 显示路径 */
  get displayPath(): Ref<string> {
    return computed(() => {
      if (this._currentZipDirectory.value) {
        return `📦 ${this._currentZipPath.value} [${this._currentZipDirectory.value}]`
      }
      return `📦 ${this._currentZipPath.value}`
    })
  }

  // ========== 公共方法 ==========

  /**
   * 进入ZIP浏览模式
   */
  async enterZipMode(zipPath: string): Promise<void> {
    this._pathBeforeZip.value = this.filePath.value
    this._currentZipPath.value = zipPath
    this._isBrowsingZip.value = true
    this._currentZipDirectory.value = ''

    await this.loadZipDirectory()
    this.log('进入ZIP浏览模式', zipPath)
  }

  /**
   * 退出ZIP浏览模式
   */
  exitZipMode(): void {
    this._isBrowsingZip.value = false
    this._currentZipPath.value = ''
    this._currentZipDirectory.value = ''
    this.log('退出ZIP浏览模式')
  }

  /**
   * 获取ZIP文件名
   */
  getZipFileName(zipPath: string): string {
    const parts = zipPath.split(/[/\\]/)
    return parts[parts.length - 1] || zipPath
  }

  /**
   * 获取面包屑
   */
  getZipBreadcrumbs(): ZipBreadcrumbItem[] {
    const crumbs: ZipBreadcrumbItem[] = [
      { name: this.getZipFileName(this._currentZipPath.value), path: '' }
    ]

    if (this._currentZipDirectory.value) {
      const parts = this._currentZipDirectory.value.split('/')
      let currentPath = ''
      for (const part of parts) {
        currentPath += (currentPath ? '/' : '') + part
        crumbs.push({ name: part, path: currentPath })
      }
    }

    return crumbs
  }

  /**
   * 导航到指定目录
   */
  async navigateToZipDirectory(path: string): Promise<void> {
    this._currentZipDirectory.value = path
    await this.loadZipDirectory()
  }

  // ========== 私有方法 ==========

  private async loadZipDirectory(): Promise<void> {
    // 加载逻辑
  }
}
```

### 4. 文件系统服务（聚合服务）

```typescript
// services/FileSystemService.ts
import { ref, type Ref } from 'vue'
import { ServiceBase } from '@/core/ServiceBase'
import { FilePreviewService } from './FilePreviewService'
import { ZipBrowserService } from './ZipBrowserService'
import { FileEditService } from './FileEditService'
import type { FileItem } from '@/types/file-system'

/**
 * 文件系统服务（门面）
 * 聚合所有文件相关服务
 */
export class FileSystemService extends ServiceBase {
  // ========== 状态 ==========
  private readonly _fileList = ref<FileItem[]>([])
  private readonly _fileLoading = ref<boolean>(false)
  private readonly _selectedFile = ref<FileItem | null>(null)

  // ========== 子服务（依赖注入） ==========
  readonly preview: FilePreviewService
  readonly zip: ZipBrowserService
  readonly edit: FileEditService

  // ========== 构造函数（保证初始化顺序） ==========
  constructor(
    private readonly fileApi: FileApiService,
    private readonly filePath: Ref<string>
  ) {
    super('FileSystemService')

    // 按顺序初始化子服务
    // 1. 预览服务（无依赖）
    this.preview = new FilePreviewService(this.fileApi, this.filePath)

    // 2. 编辑服务（依赖预览服务）
    this.edit = new FileEditService(this.fileApi, this.preview)

    // 3. ZIP服务（依赖预览服务）
    this.zip = new ZipBrowserService(
      this.fileApi,
      this.preview,
      this._fileList,
      this.filePath
    )

    this.log('文件系统服务初始化完成')
  }

  // ========== 公共接口 ==========

  /** 文件列表（响应式） */
  get fileList(): Ref<FileItem[]> {
    return this._fileList
  }

  /** 加载状态（响应式） */
  get fileLoading(): Ref<boolean> {
    return this._fileLoading
  }

  /** 选中文件（响应式） */
  get selectedFile(): Ref<FileItem | null> {
    return this._selectedFile
  }

  /**
   * 加载目录
   */
  async loadDirectory(path: string): Promise<void> {
    this._fileLoading.value = true
    try {
      const files = await this.fileApi.listDirectory(path)
      this._fileList.value = files
      this.log('目录加载成功', path, files.length, '个文件')
    } catch (error) {
      this.error('目录加载失败', error as Error)
      Message.error('加载目录失败')
    } finally {
      this._fileLoading.value = false
    }
  }

  /**
   * 预览文件
   */
  async previewFile(file: FileItem): Promise<void> {
    if (this.zip.isBrowsingZip.value) {
      await this.zip.previewZipFile(file.path)
    } else {
      await this.preview.previewFile(file.path)
    }
  }
}
```

### 5. Composable 适配器

```typescript
// composables/useFileSystem.ts
import { createSingleton } from '@/utils/singleton'
import { FileSystemService } from '@/services/FileSystemService'

/**
 * 文件系统 Composable
 * 轻量级适配器，桥接 Vue 响应式系统和服务层
 */
export function useFileSystem(options: UseFileSystemOptions = {}) {
  // 创建或获取服务单例
  const service = createSingleton(() => {
    const fileApi = new FileApiService()
    const filePath = ref(options.initialPath || '')
    return new FileSystemService(fileApi, filePath)
  }, 'fileSystemService')

  // 返回响应式接口
  return {
    // 状态（直接返回 ref）
    fileList: service.fileList,
    fileLoading: service.fileLoading,
    selectedFile: service.selectedFile,

    // 方法（委托给服务）
    loadDirectory: (path: string) => service.loadDirectory(path),
    previewFile: (file: FileItem) => service.previewFile(file),

    // 类型判断（委托给预览服务）
    isImageFile: (path: string) => service.preview.isImageFile(path),
    isVideoFile: (path: string) => service.preview.isVideoFile(path),
    isPdfFile: (path: string) => service.preview.isPdfFile(path),

    // 服务实例（可选，用于高级用法）
    $service: service
  }
}
```

### 6. 在 Vue 中使用

```typescript
// index.vue
<script setup lang="ts">
import { useFileSystem } from './composables/useFileSystem'

// 简单使用（和之前一样）
const {
  fileList,
  fileLoading,
  loadDirectory,
  previewFile
} = useFileSystem()

// 或者访问完整服务
const { $service } = useFileSystem()

// 可以访问所有服务方法
$service.preview.updatePreviewUrl(url)
$service.zip.enterZipMode(path)

// Computed 配置
const fileEditorPanelConfig = computed(() => ({
  // 使用服务方法，不会出现初始化问题
  isImageView: $service.preview.isImageFile(currentFileName),
  canPreviewFile: $service.preview.isEditableWithPreview(currentFileName),
  // ...
}))
</script>
```

---

## ✅ 方案优势

### 1. 解决初始化顺序问题

```typescript
// ❌ 之前：依赖手动保证顺序
const config = computed(() => useHelper())
const useHelper = () => { ... }  // 太晚了

// ✅ 现在：构造函数保证顺序
class Service {
  constructor(helper: HelperService) {  // 必须先创建 helper
    this.helper = helper
  }
}
```

### 2. 依赖注入，避免循环依赖

```typescript
class FileSystemService {
  constructor(
    private preview: FilePreviewService,  // 先初始化
    private zip: ZipBrowserService        // 可以依赖 preview
  ) {}
}
```

### 3. 高内聚，状态和行为绑定

```typescript
class FilePreviewService {
  private _previewUrl = ref('')  // 状态

  updatePreviewUrl(url: string) {  // 行为
    this._previewUrl.value = url
  }
}
```

### 4. 类型安全，IDE 友好

```typescript
const service = new FilePreviewService(...)
service.  // IDE 自动提示所有公共方法
```

### 5. 易于测试

```typescript
// Mock 依赖
const mockApi = new MockFileApiService()
const service = new FilePreviewService(mockApi, filePath)

// 测试方法
expect(service.isImageFile('test.jpg')).toBe(true)
```

---

## 📋 实施步骤

### 阶段1：创建服务层（1周）

1. 创建核心基类 `ServiceBase`
2. 实现 `FilePreviewService`
3. 实现 `ZipBrowserService`
4. 实现 `FileSystemService`

### 阶段2：创建适配器（3天）

1. 实现 `useFileSystem` composable
2. 确保向后兼容

### 阶段3：迁移功能（2周）

1. 逐步迁移现有功能到服务层
2. 保持老代码可用
3. 充分测试

### 阶段4：清理优化（1周）

1. 移除旧的 composables
2. 优化性能
3. 完善文档

---

## 🎯 总结

### 当前问题的根本原因

Composition API + 函数式方案**无法从架构层面**保证初始化顺序，只能依赖开发者手动保证。

### OOP 方案的核心优势

**构造函数 + 依赖注入**可以从编译器和运行时两个层面保证初始化顺序。

### 建议

立即采用 OOP 服务层方案，彻底解决初始化顺序问题。

---

**生成时间**: 2026-01-31
**预计工作量**: 3-4周
**风险等级**: 中等（需要重构，但可以渐进式迁移）