Merge remote-tracking branch 'origin/main' into codexd/issue-394-dependency-refresh

# Conflicts:
#	lib/core/services/notification_service.dart

Author: jjoonleo

.github/workflows/android-release-verify.yml

@@ -0,0 +1,45 @@
+name: Android Release Verification
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build_release:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.32.6"
+          channel: "stable"
+
+      - name: Decode Android Firebase config
+        env:
+          ANDROID_GOOGLE_SERVICES_JSON_B64: ${{ secrets.ANDROID_GOOGLE_SERVICES_JSON_B64 }}
+        run: |
+          if [ -z "$ANDROID_GOOGLE_SERVICES_JSON_B64" ]; then
+            echo "ANDROID_GOOGLE_SERVICES_JSON_B64 secret is required for Android release builds." >&2
+            exit 1
+          fi
+          mkdir -p android/app/src/release
+          printf '%s' "$ANDROID_GOOGLE_SERVICES_JSON_B64" | base64 --decode > android/app/src/release/google-services.json
+          test -s android/app/src/release/google-services.json
+
+      - run: flutter pub get
+
+      - run: dart run build_runner build -d
+
+      - name: Build Android app bundle
+        env:
+          REST_API_URL: ${{ vars.REST_API_URL }}
+        run: flutter build appbundle --release --dart-define=REST_API_URL=$REST_API_URL

.gitignore

@@ -53,6 +53,9 @@ app.*.map.json
 ios/Flutter/Dart-Defines.xcconfig
 ios/GoogleService-Info.plist
 android/app/google-services.json
+android/app/src/debug/google-services.json
+android/app/src/release/google-services.json
+android/app/src/google-services.json
 
 .cursor
 .codex/

README.md

@@ -1,5 +1,290 @@
-# on_time_front
+# OnTime Front
 
-# widgetbook
+OnTime is a Flutter app for schedule preparation, alarms, and arrival-time planning. The app is organized with clean architecture: presentation widgets and BLoCs depend on domain use cases, while data sources, Drift DAOs, and repository implementations live behind domain contracts.
+
+Primary supported targets are web, Android, and iOS. Desktop platform folders are present in the Flutter project, but Firebase options are currently configured only for web, Android, and iOS.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Project Structure](#project-structure)
+- [First-Time Setup](#first-time-setup)
+- [Runtime Configuration](#runtime-configuration)
+- [Firebase Configuration](#firebase-configuration)
+- [Development Commands](#development-commands)
+- [Build and Release](#build-and-release)
+- [Widgetbook](#widgetbook)
+- [Troubleshooting](#troubleshooting)
+- [Further Reading](#further-reading)
+
+## Requirements
+
+- Flutter stable. CI uses Flutter `3.32.6`; use that version for release parity when possible.
+- Dart SDK compatible with `pubspec.yaml` (`^3.5.4`).
+- Java and Android SDK for Android builds.
+- Xcode and CocoaPods for iOS builds.
+- Firebase CLI and FlutterFire CLI when regenerating Firebase config.
+- Access to the project secrets/configuration values listed below.
+
+Check your local toolchain with:
+
+```sh
+flutter doctor
+flutter --version
+dart --version
+```
+
+## Project Structure
+
+```text
+lib/
+  core/           platform services, database, dependency injection, Dio, utilities
+  data/           data sources, DAOs, models, tables, repository implementations
+  domain/         entities, repository contracts, use cases
+  l10n/           localization files
+  presentation/   screens, blocs, cubits, shared widgets, routing, theme
+test/             tests mirroring app paths
+docs/             architecture and feature documentation
+assets/           shared assets and fonts
+widgetbook/       component catalog app
+```
+
+Generated Dart files such as `*.g.dart`, `*.freezed.dart`, `*.config.dart`, and `*.mocks.dart` are not committed. Regenerate them locally after dependency changes or code-generator changes.
+
+## First-Time Setup
+
+1. Install dependencies:
+
+   ```sh
+   flutter pub get
+   ```
+
+2. Generate code:
+
+   ```sh
+   dart run build_runner build --delete-conflicting-outputs
+   ```
+
+3. Provide environment values and platform config. At minimum, local app runs need `REST_API_URL`; some flows may also require Firebase and native sign-in config. See [Runtime Configuration](#runtime-configuration) and [Firebase Configuration](#firebase-configuration).
+
+4. Run the app:
+
+   ```sh
+   flutter run -d chrome --dart-define=REST_API_URL=<api-base-url>
+   ```
+
+For Android or iOS, replace `chrome` with the device id from `flutter devices`.
+
+## Runtime Configuration
+
+The app reads compile-time values from Dart defines in `lib/core/constants/environment_variable.dart`.
+
+| Define | Required | Used for |
+| --- | --- | --- |
+| `REST_API_URL` | Yes | Base URL for Dio API calls. |
+| `REST_AUTH_TOKEN` | Optional | Static auth token override for development/test scenarios. |
+| `GOOGLE_RESERVED_CLIENT_ID_IOS` | iOS release/archive only | Reversed iOS Google client ID used as the iOS URL scheme for Google Sign-In. |
+
+Pass defines directly on Flutter commands:
+
+```sh
+flutter run -d chrome \
+  --dart-define=REST_API_URL=<api-base-url>
+
+flutter build web --release \
+  --dart-define=REST_API_URL=<api-base-url>
+```
+
+For iOS release and archive builds, include the Google URL scheme define:
+
+```sh
+flutter build ios --release \
+  --dart-define=REST_API_URL=<api-base-url> \
+  --dart-define=GOOGLE_RESERVED_CLIENT_ID_IOS=<reversed-ios-client-id>
+```
+
+The iOS Xcode scheme decodes `DART_DEFINES` into `ios/Flutter/Dart-Defines.xcconfig`. Release builds fail if `GOOGLE_RESERVED_CLIENT_ID_IOS` is missing or if the built `Info.plist` does not contain the Google Sign-In URL scheme.
+
+## Firebase Configuration
+
+`lib/firebase_options.dart` is generated by FlutterFire and currently supports web, Android, and iOS. macOS, Windows, and Linux throw `UnsupportedError` unless Firebase is reconfigured for those targets.
+
+Tracked Firebase-related files:
+
+- `lib/firebase_options.dart`
+- `firebase.json`
+- `web/firebase-messaging-sw.js`
+
+Native Firebase files are intentionally not committed and must come from project secret/config access:
+
+- Android: `android/app/google-services.json`, or a variant-specific file under `android/app/src/debug/` or `android/app/src/release/`.
+- iOS: `ios/Runner/GoogleService-Info.plist`.
+
+Android local builds skip the Google Services Gradle plugin when no `google-services.json` file is present, which is useful for non-Firebase development. Firebase-dependent features and production builds should use the correct native config files.
+
+To regenerate Firebase configuration, use the FlutterFire CLI with the `ontime-c63f1` Firebase project and keep the outputs aligned with `firebase.json`.
+
+## Development Commands
+
+Install dependencies:
+
+```sh
+flutter pub get
+```
+
+Regenerate Drift, JSON, Injectable, Freezed, Mockito, and Widgetbook code:
+
+```sh
+dart run build_runner build --delete-conflicting-outputs
+```
+
+Format Dart code:
+
+```sh
+dart format lib test
+```
+
+Run analyzer:
+
+```sh
+flutter analyze
+```
+
+Run tests:
+
+```sh
+flutter test
+```
+
+Run tests with coverage:
+
+```sh
+flutter test --coverage
+```
+
+Run the web app locally:
+
+```sh
+flutter run -d chrome --dart-define=REST_API_URL=<api-base-url>
+```
+
+Do not use `npm test`; the root `package.json` script is a placeholder that intentionally fails.
+
+## Build and Release
+
+### Web
+
+Preview and production web deployments are handled by GitHub Actions and Firebase Hosting. CI uses the `REST_API_URL` GitHub environment variable and builds with:
+
+```sh
+flutter build web --release --dart-define=REST_API_URL=<api-base-url>
+```
+
+Firebase Hosting deploys `build/web` to project `ontime-c63f1`.
+
+### Android
+
+Build a release APK:
+
+```sh
+flutter build apk --release \
+  --dart-define=REST_API_URL=<api-base-url>
+```
+
+Build an app bundle for Play Console upload:
+
+```sh
+flutter build appbundle --release \
+  --dart-define=REST_API_URL=<api-base-url>
+```
+
+Before production upload, confirm the release `google-services.json`, signing configuration, version name, and version code. The current Gradle release block uses the debug signing config as a local-build fallback, so production signing must be configured before store release.
+
+### iOS
+
+Build locally:
+
+```sh
+flutter build ios --release \
+  --dart-define=REST_API_URL=<api-base-url> \
+  --dart-define=GOOGLE_RESERVED_CLIENT_ID_IOS=<reversed-ios-client-id>
+```
+
+Create an App Store archive from Xcode or CI with the same Dart defines. See [docs/iOS-Release-Configuration.md](docs/iOS-Release-Configuration.md) for the release-only validation flow.
+
+Before production upload, confirm `ios/Runner/GoogleService-Info.plist`, Apple signing, bundle id, app capabilities, push notification entitlement, build number, and App Store Connect metadata.
+
+## Widgetbook
+
+Widgetbook is a separate Flutter project under `widgetbook/`.
+
+Run locally:
+
+```sh
+cd widgetbook
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+flutter run -d chrome
+```
+
+Build for Firebase Hosting:
+
+```sh
+cd widgetbook
+flutter build web --release
+```
+
+Published Widgetbook:
 
 https://on-time-front-widgetbook.web.app/
+
+## Troubleshooting
+
+### Generated files are missing or stale
+
+Run:
+
+```sh
+dart run build_runner build --delete-conflicting-outputs
+```
+
+If generation still fails, clean generated state and fetch dependencies again:
+
+```sh
+flutter clean
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+```
+
+### API calls fail immediately
+
+Confirm `REST_API_URL` was passed to the `flutter run` or `flutter build` command. `String.fromEnvironment` values are compile-time constants, so changing a shell variable after launch does not update the app.
+
+### Firebase initialization fails on desktop
+
+Firebase options are not configured for macOS, Windows, or Linux. Use web, Android, or iOS, or regenerate Firebase options for desktop platforms before enabling those targets.
+
+### Android Firebase features do not work locally
+
+Add the appropriate `google-services.json` file under `android/app/` or a variant directory. Without that file, the Gradle build intentionally skips the Google Services plugin.
+
+### iOS release fails with `GOOGLE_RESERVED_CLIENT_ID_IOS`
+
+Pass the reversed iOS Google client ID with `--dart-define=GOOGLE_RESERVED_CLIENT_ID_IOS=<value>`. The release build validates both the Dart define extraction and the final `Info.plist` URL scheme.
+
+### Web push notifications do not arrive
+
+Confirm the browser has notification permission, the Firebase web config in `web/firebase-messaging-sw.js` matches the active Firebase project, and the app is served over HTTPS or localhost.
+
+### SQLite or Drift tests fail in CI-like environments
+
+Install SQLite system libraries before running tests. The GitHub Actions workflow installs `sqlite3` and `libsqlite3-dev` before `flutter test`.
+
+## Further Reading
+
+- [Architecture](docs/Architecture.md)
+- [Error handling and Result system](docs/Error-Handling-Result-System.md)
+- [Logging policy](docs/Logging-Policy.md)
+- [iOS release configuration](docs/iOS-Release-Configuration.md)
+- [Schedule timer system](docs/Schedule-Timer-System.md)
+- [Git workflow](docs/Git.md)

android/app/build.gradle

@@ -5,11 +5,32 @@ plugins {
     id "dev.flutter.flutter-gradle-plugin"
 }
 
+def isReleaseBuild = gradle.startParameter.taskNames.any {
+    it.toLowerCase().contains("release")
+}
+def googleServicesBuildType = isReleaseBuild ? "release" : "debug"
 def googleServicesConfigFiles = [
+    file("src/${googleServicesBuildType}/google-services.json"),
+    file("google-services.json"),
+    file("src/google-services.json"),
+]
+def releaseGoogleServicesConfigFiles = [
+    file("src/release/google-services.json"),
     file("google-services.json"),
-    file("src/${gradle.startParameter.taskNames.any { it.toLowerCase().contains('release') } ? 'release' : 'debug'}/google-services.json"),
     file("src/google-services.json"),
 ]
+def hasReleaseGoogleServicesConfig = releaseGoogleServicesConfigFiles.any {
+    it.exists()
+}
+
+if (isReleaseBuild && !hasReleaseGoogleServicesConfig) {
+    throw new GradleException(
+        "Android release builds require Firebase config. " +
+        "Provide android/app/src/release/google-services.json, usually by " +
+        "decoding the ANDROID_GOOGLE_SERVICES_JSON_B64 CI secret before " +
+        "running a release build."
+    )
+}
 
 if (googleServicesConfigFiles.any { it.exists() }) {
     apply plugin: "com.google.gms.google-services"
@@ -81,6 +102,10 @@ android {
         jvmTarget = "17"
     }
 
+    buildFeatures {
+        buildConfig = true
+    }
+
     defaultConfig {
         applicationId = "club.devkor.ontime"
         minSdk = 23