139 lines
6.3 KiB
Markdown
139 lines
6.3 KiB
Markdown
# AGENTS.md
|
||
|
||
本文档为 Codex (Codex.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()` 调用。 |