centralplatform - Locker Improvments
---
Integration & Improvement Plan for Locker (LKR_V2)
A. Locker ↔ Admin (freekiosk-admin) Integration
The Admin already supports apptype = "tmklocker" and "revelapps" devices. The Locker app currently only talks to the old TMK server. We need to make it talk to the Admin platform instead.
┌─────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────┬────────┐
│ # │ Task │ Priority │ Effort │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A1 │ Add HTTP server to Locker — Embed a lightweight HTTP server (like NanoHTTPD) so Admin can send commands directly to the device (same pattern as FreeKiosk's port 8080) │ HIGH │ Large │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A2 │ Add WebSocket call-home client — Connect to Admin's /ws/device endpoint so the device can receive commands even behind NAT / different networks │ HIGH │ Large │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A3 │ Add MQTT client — Subscribe to freekiosk/{device_name}/set/* topics to receive commands via the Admin's Mosquitto broker │ MEDIUM │ Medium │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A4 │ Implement command handler — Process Admin commands: seturl, setbrightness, screenon/off, reboot, launchapp, installapk, reload, setvolume, etc. Map them to existing │ HIGH │ Medium │
│ │ SystemUtil/AppUtil calls │ │ │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A5 │ Status reporting — Periodically send device status (battery, WiFi SSID, screen state, kiosk mode, storage, selected app, app version) back to Admin via WebSocket/MQTT/HTTP │ HIGH │ Medium │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A6 │ Device registration with Admin — Replace/augment the old TMK VersionControl registration with Admin's enrollment API (POST /api/enrollment/enroll) using device token │ HIGH │ Medium │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A7 │ QR code enrollment — Add camera/scanner to read Admin's enrollment QR codes for zero-touch onboarding │ MEDIUM │ Medium │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A8 │ Remote screenshot — Capture screen and send base64 to Admin (Admin already has screenshot endpoints) │ MEDIUM │ Small │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A9 │ GPS location reporting — Send location to Admin's /api/locations endpoint for map tracking │ LOW │ Small │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ A10 │ APK update from Admin — Pull APK updates from Admin's MinIO/upload storage instead of the old TMK server │ MEDIUM │ Medium │
└─────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────┴────────┘
---
B. Locker ↔ QARevel Integration
QARevel can test Android devices via Appium. The goal is to make Locker-locked devices testable and to feed test results/device health back into QARevel.
┌─────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────┬────────┐
│ # │ Task │ Priority │ Effort │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B1 │ Register Locker devices in QARevel — Call POST /devices/register with platform=android, serial, IP, capabilities so QARevel knows about each Locker device │ HIGH │ Medium │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B2 │ Heartbeat worker — Background worker sends periodic heartbeat to QARevel (POST /devices/:id/heartbeat) with status, battery, kiosk mode state │ HIGH │ Small │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B3 │ Test mode toggle — Add a "QA mode" that temporarily unlocks kiosk restrictions so Appium/UiAutomator2 can interact with the device for automated testing │ HIGH │ Medium │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B4 │ Crash/error forwarding — Catch uncaught exceptions and ANRs, send them to QARevel as CrashEvent records for error analysis │ MEDIUM │ Medium │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B5 │ Console/log forwarding — Forward logcat output to QARevel's /logs endpoint for centralized log viewing │ LOW │ Medium │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B6 │ App target registration — Auto-register the locked app (TMK/POS) as an AppTarget in QARevel so test cases can reference it │ LOW │ Small │
├─────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼────────┤
│ B7 │ Test run triggers from Admin — Admin sends "run QA test" command → Locker triggers QARevel test run via API → results shown in both dashboards │ MEDIUM │ Large │
└─────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────┴────────┘
---
C. General Improvements (Locker App)
Security (Critical)
┌─────┬───────────────────────────────────────────────────────────────────────────────────────────────┬──────────┐
│ # │ Task │ Priority │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C1 │ Replace MD5 with SHA-256 or bcrypt for password hashing │ HIGH │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C2 │ Enable HTTPS — Use TLS for all server communication, add certificate pinning │ HIGH │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C3 │ Remove hardcoded WiFi credentials from source code, fetch from server │ HIGH │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C4 │ Remove hardcoded keystore passwords from build.gradle, use env vars or local.properties │ HIGH │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C5 │ Encrypt SharedPreferences — Use EncryptedSharedPreferences (AndroidX Security) │ MEDIUM │
├─────┼───────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C6 │ Add API key auth — Require token for all server requests (match Admin's device_token pattern) │ HIGH │
└─────┴───────────────────────────────────────────────────────────────────────────────────────────────┴──────────┘
Modernization
┌─────┬───────────────────────────────────────────────────────────────────────────────────────┬──────────┐
│ # │ Task │ Priority │
├─────┼───────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C7 │ Upgrade targetSdkVersion from 26 → 34 (required by Play Store, fixes deprecated APIs) │ HIGH │
├─────┼───────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C8 │ Replace Retrofit 1.9 with Retrofit 2.x + OkHttp4 + Coroutines │ MEDIUM │
├─────┼───────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C9 │ Migrate to Kotlin — Incremental migration, start with new files │ LOW │
├─────┼───────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C10 │ Replace AsyncTask (deprecated) with WorkManager or Kotlin Coroutines │ MEDIUM │
├─────┼───────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C11 │ Update Gradle Plugin from 3.5.1 → 8.x with AGP 8.x │ HIGH │
├─────┼───────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C12 │ Update compileSdkVersion from 28 → 34 │ HIGH │
└─────┴───────────────────────────────────────────────────────────────────────────────────────┴──────────┘
Features
┌─────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────┐
│ # │ Task │ Priority │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C13 │ Multi-app lockdown — Allow locking to multiple approved apps instead of just one │ MEDIUM │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C14 │ Scheduled kiosk mode — Time-based profiles (e.g., unlock for maintenance at 2 AM) │ LOW │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C15 │ Remote admin password reset — Sync password from Admin server (partially exists via ApiUtil but unreliable) │ MEDIUM │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C16 │ Battery/health monitoring service — Persistent foreground service reporting device health │ MEDIUM │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C17 │ Proper BootReceiver — Currently a no-op; should auto-launch kiosk mode and re-establish Admin connection on boot │ HIGH │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C18 │ OTA self-update — Download and install Locker updates silently using Device Owner privileges (no root needed) │ MEDIUM │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C19 │ Admin UI redesign — The admin panel uses SmartTabLayout 1.6; modernize with Material Design 3 components │ LOW │
└─────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────┘
Code Quality
┌─────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────┐
│ # │ Task │ Priority │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C20 │ Add ProGuard/R8 rules — Currently minimal; protect against reverse engineering │ MEDIUM │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C21 │ Remove hardcoded default password ("0512") from source │ HIGH │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C22 │ Error handling — Add proper try/catch and retry logic for network calls (currently crashes silently) │ MEDIUM │
├─────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┤
│ C23 │ Structured logging — Replace scattered Log.d with a proper logging framework │ LOW │
└─────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────┘
---
Recommended Priority Order
Phase 1 — Connect Locker to Admin (most impactful)
▎ A1, A2, A4, A5, A6 + C1, C6, C17, C21
Phase 2 — Security & Modernization
▎ C2, C3, C4, C5, C7, C11, C12
Phase 3 — Connect to QARevel
▎ B1, B2, B3, B4
Phase 4 — Feature Enhancements
▎ A3, A7, A8, A10, C13, C15, C16, C18
Phase 5 — Full Modernization
▎ C8, C9, C10, C19, B5, B6, B7