aslan-flutter/CLAUDE.md

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 依赖前请始终检查这些目录。

常用开发任务

运行应用

# 运行应用
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() 调用。