300 lines
13 KiB
Markdown
300 lines
13 KiB
Markdown
# Phase 13: Metatron Student ERP — Android Build Environment Setup and Release APK Report
|
||
|
||
**Date:** October 15, 2026
|
||
**Auditor/Build Engineer:** Antigravity Autonomous Agent
|
||
**Host Architecture:** macOS 26.6.2 (Darwin arm64 - Apple Silicon)
|
||
**Flutter SDK:** Flutter 3.47.7 (Channel stable, Dart 3.13.5)
|
||
**Backend:** Odoo 19 Community Edition (`metatron_academic`) | PostgreSQL 15 (`metatron_aca_erp`)
|
||
**Repository Branch:** `main` (HEAD: `921ddc9`)
|
||
|
||
---
|
||
|
||
## 1. Executive Summary and Build Status
|
||
|
||
An in-depth inspection of the Android build environment and Flutter mobile application (`flutter_app/`) was performed to evaluate readiness for Android Release APK and Android App Bundle (AAB) builds.
|
||
|
||
| Check / Phase | Status | Details |
|
||
|---|---|---|
|
||
| **Flutter Static Analysis** | **PASSED** | `flutter analyze` reported 0 issues |
|
||
| **Flutter Unit & Widget Tests** | **PASSED** | 64 / 64 unit and widget tests passed |
|
||
| **Flutter Live Integration Tests** | **PASSED** | 12 / 12 end-to-end tests passed against live backend |
|
||
| **Android Application Configuration** | **VERIFIED** | App ID, permissions, labels, and network security verified |
|
||
| **Environment & HTTPS Validation** | **VERIFIED** | `AppEnvironment` enforces HTTPS, rejects localhost in prod |
|
||
| **Release Signing Architecture** | **VERIFIED** | Dynamic `key.properties` loading with debug fallback |
|
||
| **Host Toolchain Check (Java / Android SDK)** | **MISSING** | No JDK or Android SDK installed on this macOS host |
|
||
| **Release APK Build Attempt** | **ENV-BLOCKED** | Blocked by missing Android SDK toolchain |
|
||
| **Release App Bundle (AAB) Attempt** | **ENV-BLOCKED** | Blocked by missing Android SDK toolchain |
|
||
|
||
---
|
||
|
||
## 2. Host Environment Inspection
|
||
|
||
### Flutter Toolchain Status (`flutter doctor -v`)
|
||
```text
|
||
[✓] Flutter (Channel stable, 3.47.7, on macOS 26.6.2 25G83 darwin-arm64, locale en-IN)
|
||
• Flutter version 3.47.7 on channel stable at /opt/homebrew/share/flutter
|
||
• Framework revision abaf9c5237 (2026-10-08 09:51:21 -0700)
|
||
• Engine revision deb287481e
|
||
• Dart version 3.13.5
|
||
• DevTools version 2.60.0
|
||
|
||
[✗] Android toolchain - develop for Android devices
|
||
✗ Unable to locate Android SDK.
|
||
Install Android Studio from: https://developer.android.com/studio/index.html
|
||
On first launch it will assist you in installing the Android SDK components.
|
||
(or visit https://flutter.dev/to/macos-android-setup for detailed instructions).
|
||
If the Android SDK has been installed to a custom location, please use
|
||
`flutter config --android-sdk` to update to that location.
|
||
|
||
[!] Xcode - develop for iOS and macOS
|
||
✗ Xcode installation is incomplete; full installation required for iOS/macOS.
|
||
! CocoaPods not installed.
|
||
|
||
[✓] Chrome - develop for the web
|
||
[✓] Connected device (2 available: macOS desktop, Chrome)
|
||
[✓] Network resources: Available
|
||
```
|
||
|
||
### Detailed Tool Discovery Results
|
||
1. **Java Runtime:**
|
||
- `/usr/bin/java`: Returns `The operation couldn’t be completed. Unable to locate a Java Runtime.`
|
||
- `/usr/libexec/java_home -V`: No Java virtual machines installed in `/Library/Java/JavaVirtualMachines/`.
|
||
- `JAVA_HOME`: Unset.
|
||
2. **Android Studio:**
|
||
- `/Applications/Android Studio.app`: Not installed.
|
||
- `~/Applications/Android Studio.app`: Not installed.
|
||
3. **Android SDK / Command-Line Tools:**
|
||
- `~/Library/Android/sdk`: Directory does not exist.
|
||
- `/Library/Android`: Directory does not exist.
|
||
- `/opt/homebrew/share/android-commandlinetools`: Not installed.
|
||
- `ANDROID_HOME` / `ANDROID_SDK_ROOT`: Unset.
|
||
|
||
---
|
||
|
||
## 3. Exact Mac Installation and Configuration Steps
|
||
|
||
Because the host machine currently lacks Java and the Android SDK, the following two standard installation options are available. Choose **Option A (GUI - Recommended)** or **Option B (Headless CLI via Homebrew)**:
|
||
|
||
### Option A: Android Studio Installation (Recommended)
|
||
1. **Download and Install Android Studio:**
|
||
- Download the Apple Silicon DMG from [developer.android.com/studio](https://developer.android.com/studio).
|
||
- Drag **Android Studio** into `/Applications`.
|
||
2. **Launch the Setup Wizard:**
|
||
- Open Android Studio. The Setup Wizard will automatically install:
|
||
- Android SDK (API 34 / Android 14)
|
||
- Android SDK Platform-Tools
|
||
- Android SDK Build-Tools (34.0.0+)
|
||
- OpenJDK bundled with Android Studio
|
||
3. **Install Android SDK Command-line Tools:**
|
||
- In Android Studio, go to **Settings (Preferences) -> Languages & Frameworks -> Android SDK -> SDK Tools**.
|
||
- Check **Android SDK Command-line Tools (latest)** and click **Apply**.
|
||
4. **Accept Android Licenses:**
|
||
```bash
|
||
flutter doctor --android-licenses
|
||
```
|
||
(Press `y` to accept all SDK licenses).
|
||
|
||
---
|
||
|
||
### Option B: Headless Command-Line Installation (via Homebrew)
|
||
If you prefer configuring without the full Android Studio IDE:
|
||
|
||
1. **Install OpenJDK 17 and Command-line Tools via Homebrew:**
|
||
```bash
|
||
brew install openjdk@17
|
||
brew install --cask android-commandlinetools
|
||
```
|
||
|
||
2. **Configure Environment Variables in `~/.zshrc`:**
|
||
```bash
|
||
# Add to ~/.zshrc:
|
||
export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home"
|
||
export ANDROID_HOME="/opt/homebrew/share/android-commandlinetools"
|
||
export ANDROID_SDK_ROOT="$ANDROID_HOME"
|
||
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"
|
||
```
|
||
Reload shell:
|
||
```bash
|
||
source ~/.zshrc
|
||
```
|
||
|
||
3. **Install Required SDK Platforms and Build-Tools via `sdkmanager`:**
|
||
```bash
|
||
sdkmanager --install "platforms;android-34" "build-tools;34.0.0" "platform-tools"
|
||
```
|
||
|
||
4. **Link Android SDK Path to Flutter and Accept Licenses:**
|
||
```bash
|
||
flutter config --android-sdk /opt/homebrew/share/android-commandlinetools
|
||
flutter doctor --android-licenses
|
||
```
|
||
|
||
5. **Verify Setup:**
|
||
```bash
|
||
flutter doctor -v
|
||
```
|
||
*(Confirmed target: `[✓] Android toolchain - develop for Android devices`)*.
|
||
|
||
---
|
||
|
||
## 4. Android App Configuration Verification
|
||
|
||
The application configuration in `flutter_app/` was inspected and verified against Google Play and production requirements:
|
||
|
||
### 1. Application Identity & Versioning
|
||
- **Application ID / Package:** `in.metatroncube.metatron_student_erp` (defined in `android/app/build.gradle.kts`)
|
||
- **Application Label:** `Metatron Student ERP` (defined in `android/app/src/main/AndroidManifest.xml`)
|
||
- **Version Name:** `1.0.0` (from `pubspec.yaml`)
|
||
- **Version Code:** `1` (from `pubspec.yaml`)
|
||
- **Min SDK:** 21 (Android 5.0 Lollipop)
|
||
- **Target / Compile SDK:** 34 (Android 14)
|
||
- **JVM Target:** Java 17
|
||
|
||
### 2. Permissions Declared
|
||
- `android.permission.INTERNET` (Network communication with Odoo backend)
|
||
- `android.permission.ACCESS_NETWORK_STATE` (Network connectivity detection)
|
||
|
||
### 3. Network Security Configuration (`network_security_config.xml`)
|
||
- Location: `flutter_app/android/app/src/main/res/xml/network_security_config.xml`
|
||
- **Default Policy:** Strict HTTPS enforcement (`cleartextTrafficPermitted="false"`) across all public network traffic.
|
||
- **Development Overrides:** Cleartext traffic permitted exclusively for `10.0.2.2` (Android emulator loopback) and `localhost`/`127.0.0.1` during debug testing.
|
||
|
||
### 4. Release Signing Setup
|
||
- Configured in `flutter_app/android/app/build.gradle.kts` using dynamic properties loading:
|
||
```kotlin
|
||
val keystoreProperties = Properties()
|
||
val keystorePropertiesFile = rootProject.file("key.properties")
|
||
if (keystorePropertiesFile.exists()) {
|
||
keystoreProperties.load(FileInputStream(keystorePropertiesFile))
|
||
}
|
||
```
|
||
- **Security Guardrail:**
|
||
- Production builds load credentials from `key.properties`.
|
||
- `key.properties` and `*.keystore` / `*.jks` are protected in root and app `.gitignore`.
|
||
- If `key.properties` is absent, the build safely falls back to `signingConfigs.debug` only to permit internal compile checks, preventing hard compilation crashes while guaranteeing no debug keystore is mistakenly shipped as a production secret.
|
||
|
||
---
|
||
|
||
## 5. API Environment Configuration & Security
|
||
|
||
The Flutter client uses compile-time environment defines (`--dart-define`) to enforce endpoint security:
|
||
|
||
```dart
|
||
// lib/core/api/api_config.dart
|
||
enum AppEnvironment { development, staging, production }
|
||
```
|
||
|
||
### Environment Matrix
|
||
1. **Production Mode (`--dart-define=ENVIRONMENT=production`):**
|
||
- Requires valid HTTPS endpoint (e.g. `--dart-define=API_BASE_URL=https://erp.yourdomain.edu`).
|
||
- Rejects unencrypted `http://` endpoints.
|
||
- **Localhost Fallback Blocked:** If `API_BASE_URL` is omitted, the app does **not** fall back to `localhost:10008`; it halts with `ApiException(code: NOT_CONFIGURED)`, prompting configuration via Settings.
|
||
2. **Staging Mode (`--dart-define=ENVIRONMENT=staging`):**
|
||
- Points to dedicated staging server (e.g. `https://staging-erp.yourdomain.edu`).
|
||
3. **Development Mode (Default):**
|
||
- Automatically routes to `http://10.0.2.2:10008` on Android emulator and `http://localhost:10008` on macOS/web.
|
||
|
||
---
|
||
|
||
## 6. Automated Test Results
|
||
|
||
### 1. Flutter Static Analysis
|
||
- **Command:** `flutter analyze`
|
||
- **Result:** `No issues found! (ran in 1.4s)`
|
||
|
||
### 2. Flutter Unit & Widget Test Suite
|
||
- **Command:** `flutter test`
|
||
- **Result:** `All 64 tests passed!`
|
||
- Authentication state, secure token storage, and session lifecycle: PASSED
|
||
- Dashboard screen, metric cards, and academic timeline: PASSED
|
||
- Student profile, contact editing, and verification status: PASSED
|
||
- Attendance session filters, statistics ring, and leave requests: PASSED
|
||
- Timetable period cards and weekday navigation: PASSED
|
||
- Exams schedule and published grades/result views: PASSED
|
||
- Announcements noticeboard, unread badges, and modal sheets: PASSED
|
||
- Finance fees overview, invoice line breakdown, and payment history: PASSED
|
||
- Document upload and certificate request workflows: PASSED
|
||
|
||
### 3. Flutter Live End-to-End Integration
|
||
- **Command:** `flutter test test/live_odoo_integration_test.dart`
|
||
- **Result:** `All 12 live integration tests passed!` (connected against live Odoo 19 backend container)
|
||
|
||
---
|
||
|
||
## 7. Build Diagnostics & Artifact Paths
|
||
|
||
### Release Build Commands Attempted
|
||
1. **Release APK:**
|
||
```bash
|
||
flutter build apk --release
|
||
```
|
||
**Output:** `[!] No Android SDK found. Try setting the ANDROID_HOME environment variable.`
|
||
2. **Release App Bundle (AAB):**
|
||
```bash
|
||
flutter build appbundle --release
|
||
```
|
||
**Output:** `[!] No Android SDK found. Try setting the ANDROID_HOME environment variable.`
|
||
|
||
### Target Artifact Locations (Once SDK is Installed)
|
||
When the Android SDK toolchain is installed per Section 3, executing the build commands will generate artifacts at the following canonical locations:
|
||
|
||
| Build Type | Command | Generated Artifact Path | Target Use Case |
|
||
|---|---|---|---|
|
||
| **Release APK (Fat)** | `flutter build apk --release` | `flutter_app/build/app/outputs/flutter-apk/app-release.apk` | Direct sideload testing on physical test devices |
|
||
| **Release APK (Split ABI)** | `flutter build apk --release --split-per-abi` | `flutter_app/build/app/outputs/flutter-apk/app-arm64-v8a-release.apk`<br>`flutter_app/build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk` | Optimized size for physical device distribution |
|
||
| **Android App Bundle** | `flutter build appbundle --release` | `flutter_app/build/app/outputs/bundle/release/app-release.aab` | Official Google Play Store distribution |
|
||
|
||
---
|
||
|
||
## 8. Step-by-Step Build Execution Commands (Post-Toolchain Setup)
|
||
|
||
Once OpenJDK 17 and Android SDK 34 are installed:
|
||
|
||
### Step 1: Set Up Private Release Keystore (Production Only)
|
||
```bash
|
||
# 1. Copy template:
|
||
cp flutter_app/android/key.properties.example flutter_app/android/key.properties
|
||
|
||
# 2. Populate key.properties with real values:
|
||
cat << 'EOF' > flutter_app/android/key.properties
|
||
storePassword=your_secure_keystore_password
|
||
keyPassword=your_secure_key_password
|
||
keyAlias=metatron_release
|
||
storeFile=/absolute/path/to/metatron_release.jks
|
||
EOF
|
||
```
|
||
|
||
### Step 2: Build Release APK for Internal Staging QA
|
||
```bash
|
||
cd flutter_app
|
||
|
||
# Builds release APK configured for staging server
|
||
flutter build apk --release \
|
||
--dart-define=ENVIRONMENT=staging \
|
||
--dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu
|
||
```
|
||
|
||
### Step 3: Build Production Android App Bundle for Google Play
|
||
```bash
|
||
cd flutter_app
|
||
|
||
# Builds signed AAB configured for production server
|
||
flutter build appbundle --release \
|
||
--dart-define=ENVIRONMENT=production \
|
||
--dart-define=API_BASE_URL=https://erp.yourdomain.edu
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Remaining Blockers & Next Actions
|
||
|
||
1. **Host Toolchain Installation:**
|
||
- Execute either Option A (Android Studio) or Option B (Homebrew CLI) as outlined in Section 3 to install OpenJDK 17 and Android SDK 34.
|
||
2. **Institutional Production API Domain:**
|
||
- Coordinate with the network/systems administrator to confirm the live HTTPS domain (e.g. `https://erp.metatroncube.in` or institutional domain) and configure DNS/SSL certificates.
|
||
3. **Production Signing Keystore:**
|
||
- Generate and securely store the production `.jks` file outside version control and supply `key.properties` for the final Google Play AAB build.
|
||
|
||
---
|
||
*Report completed. All code changes and configurations remain unpushed and within the workspace.*
|