# 桌面播放器卡片设计文档

## 概述

桌面播放器卡片是一个基于HarmonyOS Form Kit的系统级小组件，为TTMusic应用提供桌面快速控制功能。该卡片将利用现有的AvSessionController和ijkplayer播放器架构，通过FormExtensionAbility实现与主应用的数据同步和控制交互。当前应用使用ijkplayer作为播放内核，通过AvSessionController管理媒体会话，卡片将通过这个架构实现播放控制。

## 架构设计

### 整体架构

```mermaid
graph TB
    A[桌面卡片UI] --> B[FormExtensionAbility]
    B --> C[FormProvider]
    C --> D[CommonEvent通信]
    D --> E[LocalMusic组件]
    E --> F[ijkplayer播放内核]
    E --> G[AvSessionController]
    
    H[数据存储] --> C
    I[卡片配置] --> C
    
    J[系统通知栏] --> G
    K[媒体控制中心] --> G
    L[投播控制] --> G
```

### 核心组件

1. **FormExtensionAbility**: 卡片生命周期管理
2. **FormProvider**: 卡片数据提供者和业务逻辑处理
3. **WidgetDataManager**: 卡片数据管理和持久化
4. **PlayerControlService**: 播放控制服务接口
5. **FormLayoutManager**: 多尺寸布局管理器

## 组件设计

### 1. FormExtensionAbility

负责卡片的生命周期管理和系统交互。

**主要职责：**
- 处理卡片创建、更新、销毁事件
- 管理卡片实例和配置
- 处理用户交互事件路由
- 与主应用建立通信连接

**关键接口：**
```typescript
interface FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData
  onUpdateForm(formId: string): void
  onRemoveForm(formId: string): void
  onFormEvent(formId: string, message: string): void
}
```

### 2. FormProvider

卡片的核心业务逻辑处理器。

**主要职责：**
- 管理播放状态数据
- 处理播放控制命令
- 同步主应用状态
- 格式化卡片显示数据

**数据模型：**
```typescript
interface WidgetPlayState {
  isPlaying: boolean
  currentSong: SongInfo
  progress: PlayProgress
  playMode: PlayMode
  hasPlaylist: boolean
}

interface SongInfo {
  title: string
  artist: string
  album: string
  coverUrl: string
  duration: number
}

interface PlayProgress {
  currentTime: number
  totalTime: number
  percentage: number
}
```

### 3. PlayerControlService

与主应用播放器的通信接口。

**主要功能：**
- 发送播放控制命令
- 接收播放状态更新
- 处理歌曲切换事件
- 管理播放列表状态

**通信机制：**
- 使用CommonEvent进行应用间通信（发送控制命令到LocalMusic组件）
- 监听AvSessionController的媒体会话状态变化
- 通过Preferences持久化卡片状态和播放信息
- 利用现有的emitter事件机制（eventId: 2, 101, 333, 888等）

### 4. FormLayoutManager

多尺寸卡片布局管理。

**支持的卡片尺寸：**
- **小卡片 (2x1)**: 基本播放控制 + 歌曲名
- **中卡片 (4x2)**: 完整信息 + 播放控制 + 进度条
- **大卡片 (4x3)**: 专辑封面 + 完整信息 + 扩展控制

## 数据模型

### 卡片状态数据

```typescript
interface WidgetData {
  // 播放状态
  playState: {
    isPlaying: boolean
    isPaused: boolean
    isLoading: boolean
  }
  
  // 当前歌曲信息
  currentSong: {
    id: string
    title: string
    artist: string
    album: string
    coverImagePath: string
    duration: number
  }
  
  // 播放进度
  progress: {
    currentPosition: number
    duration: number
    percentage: number
    currentTimeText: string
    totalTimeText: string
  }
  
  // 播放列表状态
  playlist: {
    hasNext: boolean
    hasPrevious: boolean
    currentIndex: number
    totalCount: number
  }
  
  // 卡片配置
  config: {
    size: WidgetSize
    theme: WidgetTheme
    showProgress: boolean
    showCover: boolean
  }
}
```

### 控制命令

```typescript
enum WidgetCommand {
  PLAY_PAUSE = 'play_pause',
  NEXT_SONG = 'next_song',
  PREV_SONG = 'prev_song',
  SEEK_TO = 'seek_to',
  OPEN_APP = 'open_app',
  OPEN_PLAYER = 'open_player'
}

interface WidgetControlMessage {
  command: WidgetCommand
  params?: {
    position?: number
    songId?: string
  }
}
```

## 接口设计

### 与主应用通信接口

```typescript
interface AppCommunicationService {
  // 发送控制命令到主应用
  sendControlCommand(command: WidgetCommand, params?: any): Promise<boolean>
  
  // 获取当前播放状态
  getCurrentPlayState(): Promise<WidgetData>
  
  // 注册状态变化监听
  registerStateListener(callback: (data: WidgetData) => void): void
  
  // 启动主应用
  launchMainApp(page?: string): Promise<boolean>
}
```

### 卡片数据管理接口

```typescript
interface WidgetDataManager {
  // 保存卡片数据
  saveWidgetData(formId: string, data: WidgetData): Promise<void>
  
  // 获取卡片数据
  getWidgetData(formId: string): Promise<WidgetData>
  
  // 更新卡片显示
  updateWidget(formId: string, data: WidgetData): Promise<void>
  
  // 批量更新所有卡片
  updateAllWidgets(data: WidgetData): Promise<void>
}
```

## 错误处理

### 错误类型定义

```typescript
enum WidgetErrorType {
  COMMUNICATION_ERROR = 'communication_error',
  DATA_SYNC_ERROR = 'data_sync_error',
  CONTROL_COMMAND_ERROR = 'control_command_error',
  LAYOUT_ERROR = 'layout_error'
}

interface WidgetError {
  type: WidgetErrorType
  message: string
  code: number
  timestamp: number
}
```

### 错误处理策略

1. **通信错误**: 显示离线状态，提供重连机制
2. **数据同步错误**: 使用缓存数据，后台重试同步
3. **控制命令错误**: 显示操作失败提示，记录错误日志
4. **布局错误**: 降级到基础布局，确保基本功能可用

## 测试策略

### 单元测试

- FormProvider业务逻辑测试
- 数据模型转换测试
- 通信接口模拟测试
- 错误处理逻辑测试

### 集成测试

- 卡片与主应用通信测试
- 多卡片实例同步测试
- 系统媒体会话集成测试
- 不同尺寸布局适配测试

### 用户体验测试

- 卡片响应速度测试
- 状态同步准确性测试
- 多场景交互测试
- 异常情况恢复测试

## 性能优化

### 数据更新优化

- 使用增量更新减少数据传输
- 实现智能缓存机制
- 优化图片加载和缓存
- 控制更新频率避免过度刷新

### 内存管理

- 及时释放不用的资源
- 优化图片内存占用
- 控制卡片实例数量
- 实现内存泄漏监控

### 电量优化

- 减少不必要的后台活动
- 优化定时器使用
- 智能调整更新频率
- 配合系统省电模式

## 安全考虑

### 数据安全

- 敏感信息加密存储
- 验证通信数据完整性
- 防止恶意命令注入
- 限制卡片权限范围

### 隐私保护

- 最小化数据收集
- 用户授权机制
- 数据本地化处理
- 遵循隐私保护规范