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、网络安全配置、摄像头、麦克风、存储或后台录制相关行为时，需要重点核对权限和运行时兼容性。

3.1 KiB Raw Blame History