Field Staff Android App & Mobile Workstation
Complete operational guide for field splicing crews, Android APK wrapper architecture, shift punch-in, GPS premises check-in, optical signal dBm logging, and photo proof capture.
1. Overview & Mobile Architecture
The ConnectCare Field Staff App is designed for outdoor, one-handed mobile use by optical technicians, cable splicers, and on-site support engineers. It combines a lightweight Native Android APK wrapper (android-staff-app) with a high-performance web workstation (technician.html).
2. Subfeature Breakdown
Subfeature 3.1: Native Android APK Wrapper (android-staff-app)
Maintained under D:\BroadBand Complaint Portal\android-staff-app:
- Geolocation Permissions: Bridges hardware GPS location to web JavaScript with
ACCESS_FINE_LOCATION.
- Camera & File Uploads: Integrates
WebChromeClient.onShowFileChooser() to invoke the native camera or photo library.
- Cookie Persistence: Synchronizes
PHPSESSID session cookies across Android app restarts.
Subfeature 3.2: Mobile Number, WhatsApp OTP & Personal PIN Authentication
Field technicians authenticate rapidly without Google OAuth barriers using their registered mobile number and a secure 4-digit PIN. Initial provisioning and PIN lifecycle are secured via WhatsApp OTP:
- Automated Manager Provisioning: When an ISP manager provisions a field engineer in the portal, a cryptographically secure 6-digit OTP is automatically generated and dispatched to the technician's registered WhatsApp (valid 24 hours).
- First-Time Workstation Login: Upon receiving the WhatsApp message, the technician opens the portal, enters the 6-digit OTP, and configures their private 4-digit PIN (hashed with
bcrypt into pin_hash, marking pin_set = 1).
- Self-Service PIN Reset: If a technician forgets their PIN, they can request a 15-minute OTP to their registered WhatsApp directly from the login page, verify the code, and set a new PIN.
- In-Workstation PIN Update: Logged-in technicians can tap the "🔑 PIN" button in the workstation header anytime to update their security credentials.
# 1. Self-Service WhatsApp OTP Request
curl -X POST https://api.radhicorp.net/api/auth/staff-login.php \
-H "Content-Type: application/json" \
-d '{"action": "request_otp", "identifier": "9800000001"}'
# 2. Verify OTP and Set Permanent 4-Digit PIN
curl -X POST https://api.radhicorp.net/api/auth/staff-login.php \
-H "Content-Type: application/json" \
-d '{"action": "set_pin", "identifier": "9800000001", "otp": "654321", "pin": "5678", "confirm_pin": "5678"}'
Subfeature 3.3: Shift Attendance Punch-In / Punch-Out
Technicians begin their duty by tapping "⚡ Punch In" in the top header. Attendance timestamps are recorded in engineer_attendance_logs.
⚡
Mandatory Shift Gate: If tech_require_punch_in = 1, off-duty technicians are barred from claiming, servicing, or updating tickets until they punch in.
Subfeature 3.4: Unassigned Work Order Self-Claim Queue
Under the "Claim Available" tab, technicians can view unassigned tickets in their sector and claim them with one tap ("✋ Claim & Assign to Me").
- Concurrency Guard: If active WIP tickets $\ge$
tech_max_concurrent_wip, the button is disabled and backend returns HTTP 429.
- Peer Reassignment Hijack Prevention: Technicians cannot reassign tickets allocated to peers (HTTP 403 Forbidden). Only managers can reassign active tickets.
Subfeature 3.5: Hardware GPS Customer Premises Arrival Check-In
Technicians tap "📍 GPS Check-In at Premises" upon reaching the subscriber location. Browser captures hardware latitude, longitude, and accuracy radius ($\pm \text{meters}$), stamping premises_arrived_at.
Subfeature 3.6: Optical Line Power (dBm) Verification Gate
Technicians measure signal power at the customer ONU/ONT port using an optical power meter and input the reading before closing the ticket:
| dBm Range | Classification | Tolerance Indicator |
|---|
| -15.0 to -24.0 dBm | Optimal | ✓ Pass (GPON Compliant) |
| -24.1 to -27.0 dBm | Marginal / High Attenuation | ⚠️ Warning (Check Splicing) |
| < -27.0 or > -8.0 dBm | Critical / Unacceptable | ✕ Critical (Fault Persists) |
Subfeature 3.7: Proof Photo Capture & ≤100KB Compression
Technicians upload photos of the ONT LEDs or splice tray. The client-side canvas dynamically compresses and scales the photo before network transmission to guarantee file size is strictly under $100\text{ KB}$.
Subfeature 3.8: Native Biometric Authentication (Fingerprint & Face Unlock)
Field technicians can unlock the workstation in under 1 second without typing phone numbers or PINs repeatedly under outdoor field conditions:
- Hardware-Backed Sensor Bridge: Leverages AndroidX Biometric API (
androidx.biometric:biometric:1.1.0) with BIOMETRIC_STRONG | BIOMETRIC_WEAK sensor checks.
- 1-Touch Sign-In Flow: If registered, a prominent "⚡ 👆 Quick Sign-In with Biometrics" button appears on the login screen. Tapping invokes native system BiometricPrompt.
- Cryptographic Device Token Binding: Verified device tokens are hashed with SHA-256 and stored in
portal_users.biometric_token_hash, verified against POST /api/auth/biometric-login.php.
- Security Revocation: Changing or resetting personal PIN automatically wipes stored token hashes, requiring re-enrollment. Technicians can also unlink the device via the in-workstation PIN modal.
# 1. Native Biometric Login API
curl -X POST https://api.radhicorp.net/api/auth/biometric-login.php \
-H "Content-Type: application/json" \
-d '{"device_token": "cc_bio_random_token_string"}'
# 2. Biometric Device Enrollment (Authenticated)
curl -X POST https://api.radhicorp.net/api/auth/biometric-enroll.php \
-H "Content-Type: application/json" \
-d '{"device_token": "cc_bio_random_token_string", "device_name": "Field Android Device"}'
Subfeature 3.9: Mobile Responsive Navigation, Drawer & Hardware Back-Button Handling
Resolves handheld viewport clipping, off-canvas canvas blowout, and navigation traps:
- Collapsible Hamburger Navigation (
☰): Replaces horizontal navigation rows on screens ≤ 768px with a slide-out drawer containing user info, tenant switcher, portal jump links, and a prominent red "🚪 Sign Out" button.
- Strict Viewport Confinement: Eliminates off-canvas horizontal drift using
overflow-x: hidden and enclosed table containers.
- Hardware Back Button Interception: In
MainActivity.java, back-press events query active modals in the DOM first before executing history navigation, preventing unexpected session exits.
Subfeature 3.10: Real-Time Field Dispatch & Outage Broadcast System Notifications
Instantaneous multi-sensory alerting keeps field technicians informed of assigned work orders and network-wide incidents even with the screen locked or app in the background:
- Android Native Notification Channel: Dispatched via channel
connectcare_dispatch_alerts (High Importance, Vibration, Sound enabled) targeting Android 13+ with POST_NOTIFICATIONS runtime permissions.
- Vector Status Bar Icon: Rendered using clean 24dp monochrome vector asset (
R.drawable.ic_stat_dispatch) compliant with Android 12+ Adaptive Icon guidelines.
- In-App Heads-Up Banners: Real-time animated top banners slide down upon alert arrival:
- Ticket Dispatch (Blue): Displays ticket ID, customer name, sector, and complaint reason.
- Outage Broadcast (Urgent Red): Prominently highlights localized network outages, fiber cut alerts, and geo-spike trip events.
- Acoustic & Haptic Alerting: Distinct Web Audio synthesis patterns: pleasant two-tone rising chime (880 Hz → 1175 Hz) for ticket dispatches, and an urgent pulsing triple-alarm (440 Hz → 587 Hz) for outage escalations, coupled with hardware vibration.
- Background & Foreground Synchronization: Operates via synchronized polling (
api/engineers/notifications.php) in the Native Java Service and Web Worker, ensuring zero missed alerts and instant acknowledgment once delivered.