# CLAUDE.md

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

## 项目概览

这是一个名为 "Aslan" 的 Flutter 应用程序（项目 `atu`），是一个具有实时音频/视频、聊天、礼物和家族功能的社交语音聊天应用。它采用清晰架构分层：core、data、domain、presentation。

**主要依赖**：
- **实时通信**：Agora RTC (`agora_rtc_engine`)、腾讯云聊天 (`tencent_cloud_chat_sdk`)
- **状态管理**：Provider (`provider`)
- **路由**：Fluro (`fluro`)
- **网络请求**：Dio (`dio`) 带有自定义拦截器
- **本地包**：修改版本的 `webview_flutter`、`tancent_vap`、`on_audio_query`、`flutter_foreground_task` 包含在 `local_packages/` 中。在更新 pub 依赖前请始终检查这些目录。

## 常用开发任务

### 运行应用
```bash
# 运行应用
flutter run
```

### 构建
- **Android**：`flutter build apk` 或 `flutter build appbundle`
- **iOS**：`flutter build ios`

### 测试
- 运行单元/部件测试：`flutter test`
- 单个测试文件：`flutter test test/widget_test.dart`

### 代码检查和分析
- 静态分析：`flutter analyze`
- 代码格式化：`flutter format .`

### 管理依赖
- 获取包：`flutter pub get`
- 升级包：`flutter pub upgrade`
- 检查过时包：`flutter pub outdated`

### iOS 特定设置
- 更新 Flutter 插件后在 `ios/` 中运行 `pod install`。
- Podfile 包含自定义权限标志（相机、麦克风、相册、通知已启用；其他已禁用）。按需调整。

## 架构

### 层级结构
- **`lib/core/`**：常量、工具、共享组件、路由。
  - `constants/`：应用全局配置 (`GlobalConfig`)、颜色、屏幕尺寸。
  - `routes/`：Fluro 路由设置 (`Routes.dart`, `router_init.dart`)。
  - `compontent/`：可复用的 UI 组件（自定义应用栏、图片、按钮、对话框）。
  - `utils/`：工具类（设备 ID、键盘、深度链接）。
- **`lib/domain/`**：业务逻辑。
  - `entities/`：数据模型。
  - `repositories/`：仓库接口。
  - `use_cases/`：业务逻辑类（文本格式化器、标签选择器等）。
- **`lib/data/`**：数据层实现。
  - `datasources/remote/net/`：HTTP 客户端 (`http.dart`, `api.dart`)，带有自定义拦截器用于头部、超时、日志。
  - `datasources/local/`：本地存储 (`StorageManager`)、用户管理 (`UserManager`)、前台服务助手。
  - `datasources/repositories/`：仓库实现。
  - `models/`：数据传输对象和枚举。
- **`lib/presentation/`**：UI 层。
  - `pages/`：基于功能页面的目录（登录、房间、聊天、家族等）。
  - `providers/`：状态管理的 ChangeNotifier 提供者（认证、用户、房间、礼物等）。

### 状态管理
- 使用 `provider` 包和 `ChangeNotifier`。
- 提供者在 `main.dart` (`MyAppWithProviders`) 中注册。部分提供者为懒加载。
- 关键提供者：`AuthProvider`、`UserProvider`、`RoomProvider`、`RtcProvider`、`RtmProvider`、`GiftProvider`、`LocaleProvider`、`ThemeProvider`。

### 路由
- 使用 `fluro` 进行导航。
- 路由定义在 `lib/core/routes/Routes.dart` 和各功能的模块化 `IRouterProvider` 实现 (`*_route.dart`)。
- 导航工具：`fluro_navigator.dart` 中的 `NavigatorUtils`。

### 网络层
- 基础 URL 配置在 `GlobalConfig.apiHost`。
- 自定义 `Http` 类继承 `BaseHttp`，带有用于头部、日志、超时的拦截器。
- 请求头包含设备信息、语言、令牌。
- 响应包装在 `ResponseData` 中，包含 `status`、`errorCode`、`body` 字段。

### 配置
- **配置架构**: 使用 `AppConfig` 系统管理应用配置
- **全局配置**: `lib/core/constants/global_config.dart` 从 `AppConfig.current` 获取配置值
- **配置内容**: API主机、腾讯IM App ID、Agora RTC App ID、功能开关、审核模式标志等
- **业务逻辑差异化**: 使用策略模式(`BusinessLogicStrategy`)实现页面差异化
  - `BaseBusinessLogicStrategy`: 原始应用默认实现
  - `Variant1BusinessLogicStrategy`: 马甲包差异化实现
  - 页面通过 `GlobalConfig.businessLogicStrategy` 访问策略方法
  - 已差异化页面: 首页、登录页、家族页、探索页、个人主页、管理编辑和搜索页

### UI 适配
- 使用 `flutter_screenutil` 进行响应式设计。
- 设计尺寸为 375×667（定义在 `lib/core/constants/screen.dart`）。
- 使用 `ScreenUtil().setWidth()`、`ScreenUtil().setHeight()`、`ScreenUtil().setSp()` 处理尺寸和字体大小。

### 本地化
- `assets/l10n/` 中的 JSON 文件支持英语、中文、阿拉伯语、土耳其语、孟加拉语。
- `ATAppLocalizations` 类加载翻译；使用 `ATAppLocalizations.of(context)!.keyName`。

### 资源
- 图片按功能组织在 `images/` 中（启动页、登录、房间、个人等）。
- 字体在 `fonts/` 中（自定义字体 `MyCustomFont`）。

## 重要说明

### 本地包
项目在 `local_packages/` 中包含多个插件的修改版本：
- `webview_flutter-4.13.0`
- `tancent_vap-1.0.0+1`（腾讯视频动画播放器）
- `on_audio_query-2.9.0`
- `flutter_foreground_task-9.1.0`

更新依赖时，请检查这些本地包的更改是否需要保留。除非有意替换，否则避免用 pub.dev 版本覆盖它们。

### iOS 权限
`ios/Podfile` 设置预处理器标志来禁用未使用的权限（日历、联系人、提醒事项等），仅启用相机、麦克风、相册、通知。如需额外权限，请修改 `GCC_PREPROCESSOR_DEFINITIONS` 块。

### 审核模式
`GlobalConfig.isReview` 控制应用是否处于审核模式（例如用于 App Store 审核）。这可能会影响功能可用性。

### 实时功能
- Agora RTC 用于语音/视频房间。
- 腾讯 IM 用于聊天消息。
- 确保 `GlobalConfig` 中设置了正确的 App ID。

### 错误报告
- 使用 Firebase Crashlytics 进行崩溃报告。
- 未捕获的错误通过 `runZonedGuarded` 和 `FlutterError.onError` 捕获。
- 网络错误通过日志记录并通过 toast 显示。


## 故障排除

- **Pod install 错误**：检查 `ios/Podfile` 语法；确保 Flutter 插件兼容。
- **本地包错误**：验证 `pubspec.yaml` 中的路径指向正确的本地包目录。
- **网络请求失败**：确认 `GlobalConfig.apiHost` 可达；检查 `ApiInterceptor` 中的头部。
- **状态未更新**：验证提供者是否在需要时不是懒加载状态；检查 `notifyListeners()` 调用。