droovo/droovo-mobile-public

# Droovo 移动应用（公开版） [](https://github.com/droovo/droovo-mobile-public/actions/workflows/flutter-ci.yml) 欢迎使用 **公开的 Droovo Flutter 应用仓库**！此仓库仅包含该 Flutter 应用的一个子集：外部贡献者可以参与开发和改进的辅助类及可测试代码。 📊 **[实时项目仪表板](https://public.droovo.tn/)** — 一目了然地查看分支、近期活动、Pull Request、CI 构建和下载。 🌐 [droovo.tn](https://droovo.tn/) • 📱 [在 Google Play 上获取](https://play.google.com/store/apps/details?id=tn.droovo.droovo_app) • ✉️ [联系我们](https://droovo.tn/contact) ## 目录 * [项目概述](#project-overview) * [仪表板](#dashboard) * [快速入门](#getting-started) * [贡献指南](#contributing) * [CI/CD 与测试](#cicd--testing) * [下载](#downloads) * [更新工作流](#workflow-for-updates) * [报告问题](#reporting-issues) * [许可证](#license) ## 项目概述 这是一个真实且可运行的 Flutter 项目 —— 它没有产品界面，仅包含纯粹的业务逻辑辅助类及其测试。它包含： * `lib/helpers/`：从私有应用中移植过来的纯逻辑辅助类。它们都不涉及 Firebase、HTTP 或平台插件，因此只要能在运行 `flutter test` 的地方，它们就能运行： | Helper | 功能说明 | | --- | --- | | `auth_validation_helper.dart` | 密码强度/反馈、邮箱验证、邮箱掩码 | | `car_helper.dart` | 车辆格式化/状态、座位设置检查、预订编辑时的座位重新锁定 | | `chat_helper.dart` | 消息截断、最新消息查找、群组差异对比、群组命名 | | `distance_helper.dart` | Haversine 距离、位置文本辅助方法 | | `pricing_calculator.dart` | 行程价格计算（距离 × 费率 × AC 倍数） | | `ride_filter_helper.dart` | 行程列表的列表过滤、排序、分组和去重 | | `ride_form_validation_helper.dart` | 行程创建表单字段验证 | | `ride_search_helper.dart` | 行程搜索/匹配算法：带回退层级的扩展半径搜索 | | `ride_validation_helper.dart` | 预订不变量、行程状态颜色标签、一致性报告 | | `seat_helper.dart` | 座位布局生成和预订的座位分配 | | `time_helper.dart` | 行程倒计时/相对时间和日期格式化，带有可注入的时钟 | | `feedback_helper.dart` | 从列表中挑选最佳（评分最高、最新）的反馈 | | `location_name_helper.dart` | 清理反向地理编码的地名以便显示 | | `request_helper.dart` | 座位请求状态标签和列表过滤 | | `settings_helper.dart` | 带有安全回退机制的存储语言键解析 | * `lib/models/`：纯 Dart 数据类（`Ride`, `Car`, `Seat`, `User`, `Message`, `Feedback`, `RequestOrder`, `Language`...），它们映射了私有应用实体的结构，但没有任何 Firestore/Hive 的连接代码。 * `lib/main_public.dart`：一个无界面的演示入口点，仅用于证明这些辅助类可以作为真实的 Flutter 应用运行 —— 请参阅[快速入门](#getting-started)。 * `test/`：每个辅助类对应一个测试文件，以及 `test/fixtures/sample_data.json` —— 包含虚构的行程、车辆、用户和聊天消息，所有测试都会使用这些数据；还有 `test/helpers/test_data.dart`，它负责将数据加载到上述强类型模型中。 完整的应用，包括敏感的业务逻辑、支付和后端集成，都在私有的 GitLab 仓库中。 ### 适合新手的贡献 有少数测试被刻意命名，以标记移植逻辑中真实存在且尚未解决的缺陷 —— 在测试套件中搜索 `BUG DETECTOR` 和 `BUG-COMPATIBLE` 即可找到它们（目前位于 `ride_search_helper_test.dart`、`seat_helper_test.dart` 和 `location_name_helper_test.dart` 中）。每一个都记录了从私有应用中原样移植过来的真实怪癖（例如：搜索结果去重的遗漏、在部分失败时无法回滚的座位分配函数、位置名称清理中无法到达的回退分支），而不是生造的例子。选择其中一个，理解它发生的原因，并提出修复方案（附带证明修复有效的测试），是最有价值的贡献方式之一 —— 此处确认的修复正是 Droovo 团队会移植回私有应用的内容。 ## 仪表板 **[public.droovo.tn](https://public.droovo.tn/)** 是一个实时、只读的项目仪表板 —— 一个纯静态站点（`dashboard/`），它直接从 GitHub API 读取公开数据并显示： * **活动** —— `main` 分支上的近期提交，让你能看到改动了什么以及是谁改动的。 * **Pull Request** —— 贡献者打开和近期更新的 PR。 * **分支** —— 每个分支及其最新提交。 * **构建** —— 近期 CI 运行及其通过/失败状态，并链接到 GitHub 上的每次运行（下载该运行的 artifact 仍需要登录 GitHub —— 这是 GitHub 自身的策略，本仪表板无法绕过）。 * **下载** —— 带有 APK/AAB/Web 构建附件的标签发布，可直接下载且**无需登录 GitHub**。 它托管在 Firebase Hosting 上，并通过 [`.github/workflows/firebase-hosting-merge.yml`](.github/workflows/firebase-hosting-merge.yml) 在每次推送到 `main` 分支时自动重新部署；Pull Request 也会通过 [`firebase-hosting-pull-request.yml`](.github/workflows/firebase-hosting-pull-request.yml) 获得各自的实时预览 URL（作为 PR 评论发布）。它不提供任何后端，也不 存储自身的数据 —— 显示的所有内容都是在 访客浏览器中从 `api.github.com` 实时获取的。 ## 快速入门 ### 前置条件 * [Flutter](https://flutter.dev/docs/get-started/install) ≥ 3.x * Android Studio / Xcode（用于设备构建） * Git ### 克隆仓库 ``` git clone https://github.com/droovo/droovo-mobile-public.git cd droovo-mobile-public ``` ### 安装依赖 ``` flutter pub get ``` ### 运行可测试应用 ``` flutter run -t lib/main_public.dart ``` 这将会使用公开的辅助代码启动应用，让你能够安全地测试更改。 ## CI/CD 与测试 每次推送和 Pull Request 都会在 GitHub Actions 上运行 [`.github/workflows/flutter-ci.yml`](.github/workflows/flutter-ci.yml)： 1. **验证** —— `dart format --set-exit-if-changed .` 和 `flutter analyze`。 2. **测试** —— `flutter test`（`test/` 下的完整测试套件）。 3. **构建** —— 发布 **APK**、**AAB** (Android App Bundle) 和 **Web** 构建，并作为可下载的 artifact 上传到工作流运行的 *Summary* 页面（保留 30 天）。 由于这是一个社区演示应用，而非 Play Store 发布版本，因此 Android 发布版使用 Flutter 默认的 debug keystore 进行签名（参见 `android/app/build.gradle.kts`）—— 构建它们不需要任何签名密钥。 推送类似 `v1.0.0` 的标签会运行相同的流水线，并额外发布一个附带 APK/AAB/Web zip 文件的 **GitHub Release** —— 请参阅[下载](#downloads)。 ## 下载 有两种方法可以在不自行编译的情况下获取构建版本： * **最新的标签发布**（推荐，永久链接，无需登录 GitHub）：请查看 [Releases 页面](../../releases) 获取最新的 `app-release.apk`、`app-release.aab` 和 `droovo-public-helpers-web.zip`。 * **任何特定的提交/PR 构建**：在 [Actions 选项卡](../../actions/workflows/flutter-ci.yml)下打开相应的运行记录，滚动到 *Artifacts*，并下载为该推送生成的 APK/AAB/Web zip（需要登录 GitHub；artifact 将在 30 天后过期）。 这些构建仅包含来自 `lib/main_public.dart` 的无界面演示应用 —— 这里没有可安装的产品 UI，它们的主要存在意义是为了证明流水线（以及辅助类）确实可以构建和运行。 ## 更新工作流 1. 贡献者向公开仓库提交 PR。 2. 经过审查和测试后，已获批准的辅助类更改会被手动合并到私有的 GitLab 仓库中。 3. `main_public.dart` 仅用于测试目的，**不会**被合并到私有仓库中。 此工作流确保贡献者能够在不暴露完整应用的情况下，安全地改进共享代码。 ## 报告问题 * 如果你在此仓库的辅助逻辑中发现 bug 或有改进建议，请提交 issue。 * 尽可能提供详细的描述、重现步骤和截图。 * 对于关于线上应用本身（账户/账单/行程问题）的任何事宜，请改用 [droovo.tn/contact](https://droovo.tn/contact) —— 此仓库的维护者无法通过 GitHub issue 处理这些问题。 ## 许可证 本项目由 **Droovo** 维护。贡献行为受 [LICENSE](LICENSE) 文件中条款的约束。 感谢你帮助让 Droovo 变得更好！ 🚀

标签：Flutter, 业务逻辑, 出行服务, 单元测试, 拼车应用, 移动开发