# Repository Guidelines

## 项目结构与模块组织

这是一个 Flutter 移动应用项目，当前产品方向仅保留 Android，后续开发与验证不需要关注 iOS 平台。应用代码位于 `lib/`。`lib/app/` 存放启动、路由、主题和配置；`lib/core/` 存放网络、缓存、权限、日志和平台工具；`lib/shared/widgets/` 存放通用 UI 组件；`lib/features/` 按业务模块组织，例如登录、录制、扫码和弹窗。生成的资源访问代码位于 `lib/gen/`。测试文件位于 `test/`，尽量与源码目录对应。静态资源在 `pubspec.yaml` 中声明，主要放在 `assets/images/` 和 `assets/html/`。Android 原生实现位于 `android/`。

## 构建、测试与开发命令

- `flutter pub get`：安装 Dart 和 Flutter 依赖。
- `flutter analyze`：按 `analysis_options.yaml` 执行静态检查。
- `flutter test`：运行全部单元测试和 widget 测试。
- `flutter run -d <device-id>`：在指定 Android 设备或模拟器上运行应用。
- `flutter build apk --debug`：构建 Android debug APK。
- `dart run build_runner build --delete-conflicting-outputs`：资源或生成代码变化后重新生成文件，例如 `lib/gen/assets.gen.dart`。

项目还包含 `build-apk.sh`、`build-apk-split.sh` 和 `clean.sh` 等辅助脚本，使用前先阅读脚本内容。

## 代码风格与命名规范

遵循 Dart 和 Flutter 常规风格，使用两个空格缩进。Analyzer 继承 `package:flutter_lints/flutter.yaml`，并启用 `prefer_single_quotes`，因此字符串优先使用单引号。文件名使用 `snake_case.dart`，类和 widget 使用 `PascalCase`，方法、变量、provider 和字段使用 `lowerCamelCase`。新增能力前优先复用现有 `shared/widgets`、`core` 服务和 feature 内已有模式，避免重复抽象。

## 测试规范

使用 `flutter_test` 编写单元测试和 widget 测试。测试文件放在 `test/` 下，并以 `_test.dart` 结尾，例如 `test/features/recording/view_model_recording_test.dart`。业务逻辑、权限判断、Android 平台通道边界、录制流程和可复用 widget 需要补充聚焦测试。提交前运行 `flutter test` 和 `flutter analyze`。

## 提交与 PR 规范

当前 Git 历史多使用简洁中文提交信息，描述实际行为变化，例如 `更新 AndroidManifest.xml 以启用明文流量`。保持提交范围单一，避免混入无关格式化。PR 应包含变更说明、测试结果、关联 issue，以及 UI、录制、扫码、WebView 或权限流程变化对应的截图或录屏。涉及原生代码时，只需说明 Android 设备或系统版本覆盖情况。

## Agent 特定说明

产品已放弃 iOS 方向，后续 agent 不需要主动检查、构建、修复或维护 `ios/` 目录内容。除非用户明确要求处理历史 iOS 文件，否则所有实现、调试和验证都应以 Android 为准。

## 安全与配置提示

不要提交私有 token、签名文件或环境专用密钥。修改 `lib/app/config/`、Android manifest、网络安全配置、摄像头、麦克风、存储或后台录制相关行为时，需要重点核对权限和运行时兼容性。