# CLAUDE.md
always response 中文

本文件为 Claude Code (claude.ai/code) 在此代码库中工作提供指导。

## 项目概述

TTMusic 是基于 OpenHarmony ArkTS 开发的功能丰富的音乐播放器应用，支持本地和网络音频播放，集成了 ijkplayer 进行媒体处理。

## 构建命令

### 依赖管理
```bash
# 安装依赖
ohpm install

# 更新特定依赖
ohpm update @ohos/ijkplayer
```

### 运行测试
当前项目没有正式的单元测试。测试通过手动设备测试和 DevEco Studio 的内置调试工具进行。

## 架构概览

### 模块结构
```
TTMusic/
├── entry/                  # 主应用模块
│   ├── src/main/ets/
│   │   ├── pages/         # 应用页面 (SplashIndex, MainIndex 等)
│   │   ├── view/          # 可复用UI组件 (LocalMusic, TitleBar 等)
│   │   ├── viewmodel/     # 数据模型和业务逻辑
│   │   ├── common/        # 工具类、常量和共享代码
│   │   ├── controller/    # 控制层 (AvSessionController, KnockController)
│   │   └── dialog/        # 对话框组件
├── ijkplayer/             # 基于 FFmpeg 的媒体播放器原生模块
├── lib/                   # 共享库 (歌词解析等)
└── hvigor/               # 构建配置
```

### 核心组件

**核心播放器架构:**
- `LocalMusic.ets` - 主音乐播放器界面和播放控制
- `IjkMediaPlayer` - 使用 FFmpeg 的原生媒体播放器后端
- `AvSessionController.ets` - 用于系统集成的音频会话管理
- `PlayerModel.ets` - 可观察的播放器状态模型

**导航和UI:**
- `MainIndex.ets` - 主标签导航 (当前已禁用标签，简化版)
- `SplashIndex.ets` - 应用初始化和加载页面
- `PlaylistDetailPage.ets` - 播放列表管理和详情视图

**数据管理:**
- `MediaTable.ets` & `PlaylistTable.ets` - 媒体和播放列表的数据库操作
- `ConfigManager.ets` - 基于API的远程配置系统
- `GlobalContext.ets` - 应用级状态管理

### 数据库架构
使用关系数据库 (RDB) 用于:
- 媒体文件元数据和索引
- 播放列表管理
- 用户偏好设置

### 配置系统
通过 `ConfigManager.ets` 进行远程配置管理:
- 从 `https://pay.ss5.xyz/switches/lists` 获取设置
- 支持 boolean、number、string 和 JSON 类型
- 与 AppStorage 集成以实现响应式UI更新

## 关键技术模式

### ArkTS 特定注意事项
- **禁止解构赋值**: 使用传统循环而不是 `for (const [key, value] of Object.entries(obj))`
- **需要空值安全**: 在对象方法调用前总是检查 null/undefined
- **禁止计算属性名**: 使用 `obj[key] = value` 而不是 `{[key]: value}`
- **显式错误类型**: 使用 `catch (e: Error)` 而不是 `catch (e)`
- **基于Promise的异步**: 数据库操作使用 `.then()/.catch()` 而不是 async/await

### 状态管理
- `@State` 用于组件本地状态
- `@StorageProp`/`@StorageLink` 用于 AppStorage 集成
- `@Observed` 类用于复杂数据模型
- 通过 `GlobalContext` 单例进行全局状态管理

### 音频播放集成
```typescript
// 标准播放器初始化模式
const player = IjkMediaPlayer.getInstance();
player.setDataSource(audioUrl);
player.prepareAsync();
player.setOnCompletionListener(this.handleCompletion.bind(this));
```

### 主题系统
多个内置主题 (默认、暮色、森林、珊瑚、极夜) 支持:
- 通过 AppStorage 进行动态颜色切换
- 基于资源的颜色定义 (`$r('app.color.brand')`)
- 明暗模式支持

## 开发指南

### 文件组织
- `pages/` 目录中的页面使用 `@Entry` 装饰器
- `view/` 目录中的可复用组件
- `viewmodel/` 中的业务逻辑，使用适当的模型类
- `common/util/` 中按功能组织的工具类

### 代码风格
- 类名使用 PascalCase (例如 `MediaTable`)
- 方法名使用 camelCase (例如 `queryByParentPath`)
- 常量使用 UPPER_SNAKE_CASE (例如 `DB_COLUMNS.FILE_PATH`)
- 私有属性使用 `_camelCase` 前缀

### 错误处理
- 在 catch 块中总是使用显式的 Error 类型
- 使用项目的 Logger 工具记录错误
- 通过 ToastUtil 显示用户友好的消息
- 正确处理数据库 Promise 拒绝

### API 集成
- 使用 NetAxiosUtil 进行 HTTP 请求
- 通过 ConfigManager 进行远程配置
- 正确的 JSON 解析和错误处理
- 在 CommonConstants 中定义的 API 端点

## 常见开发任务

### 添加新音乐格式
1. 更新 `CommonConstants.REAL_MUSIC_FORMAT` 数组
2. 确认 ijkplayer 支持该格式
3. 使用实际媒体文件测试

### 实现新主题
1. 在 `AppTheme.ets` 中添加颜色定义
2. 在设置中更新主题选择UI
3. 在所有使用主题颜色的组件中测试

### 数据库模式更新
1. 在相应的 Table 类中修改表创建
2. 在 `onCreate` 回调中添加版本升级逻辑
3. 处理现有数据的迁移

### 添加新对话框组件
1. 在 `dialog/` 目录中创建，遵循现有模式
2. 使用 `@pura/harmony-dialog` 保持样式一致性
3. 与父页面状态管理集成

## 重要依赖

- `@ohos/ijkplayer` - 媒体播放引擎 (基于FFmpeg)
- `@pura/harmony-utils` - 工具函数和助手
- `@pura/harmony-dialog` - 对话框管理系统
- `@seagazer/cclyric` - 歌词解析和显示
- `@chinalike/popup` - 弹窗和模态框组件

## 测试和调试

- 使用 DevEco Studio 的内置调试工具
- 使用 common/util/Logger.ets 中的 `Logger.info()`、`Logger.error()` 记录日志
- 在实际设备上测试音频功能
- 通过日志输出检查数据库操作

## 平台特定注意事项

- 需要 OpenHarmony API 12 (5.0.0(12)) 或更高版本
- 支持手机、平板和 2in1 设备
- 通过 `audioPlayback` 后台模式启用后台音频播放
- 在 module.json5 中配置音频/视频文件类型的文件关联
- 日志都需要加上一个前缀：“heanup”
- 禁止使用unknown和any类型