EAC App — Feature & Test Guide

What you need

• A phone number that can receive SMS (OTP codes are 4 digits and expire on a 2-minute resend timer).
• At least one real customer code (format 123-456789) plus two invoice numbers from that customer — required to link an account.
• Access to the EAC STAGING or DEMO environment. Switch environments through Developer Options (section 13); the unlock code is 2025.
• Test devices: at least one Android, one iOS, and a desktop browser for the web build. Many behaviors differ per platform (section 14).
• Test in both languages (Khmer is the default) and both themes (light/dark, plus "System").

1.1 Splash screen / app startup

Shows the EAC logo and a spinner while the app loads its environment, theme, language, and saved login. If a valid session exists it goes straight to the Dashboard; otherwise to Login.

• Cold start while logged in → lands on Dashboard without asking anything.
• Cold start while logged out → lands on Login.
• Cold start in airplane mode → error view ("check your internet connection…") with a Retry button; Retry works after network returns.
• The error view still shows the environment name and the Developer Options button (when enabled).
• With an expired/invalid saved session → "Unauthorized" dialog, then automatic logout to Login.
• Opening a payment deep link while the app is closed → splash first, then the payment result page (the link is replayed after loading).

1.2 Under maintenance

When the server flags maintenance (via the environment file or a push message on the maintenance topic), every screen redirects to a full-screen blue "System Maintenance" page.

• While in maintenance, no screen is reachable — the back button cannot escape the page.
• The page still shows the environment badge and Developer Options button (the only escape: switch environment).
• When maintenance is lifted, the app automatically returns to the Dashboard without a restart.
• A maintenance push notification flips the running app into (and out of) maintenance live.

1.3 App update dialogs

The server can announce a newer build. An optional update shows a dismissible dialog; a forced update shows a dialog that cannot be dismissed.

• Optional update → dialog appears and can be dismissed; app continues normally.
• Forced update → dialog cannot be dismissed (tapping outside / back does nothing).
• The update button opens Google Play on Android and the App Store on iOS.

1.4 Offline behavior

The app has no offline cache — every screen needs the network. A connectivity banner appears at the bottom of the Dashboard, and API calls made while offline are blocked with a "No internet access" dialog.

• Going offline on the Dashboard → red "disconnected" banner appears.
• Coming back online → green "connected" banner appears, then hides itself after ~3 seconds.
• Any action requiring the network while offline → "No internet access" dialog (not a crash, not an endless spinner).
• Content screens opened while offline show the "Load data failed" view with a working Retry.

1.5 Route protection (web especially)

• Typing a protected URL (e.g. /dashboard/settings) while logged out redirects to /login.
• Refreshing the browser on any OTP page bounces back to /login (the OTP session is lost by design).
• A logged-in user who has no PIN yet is always forced to Setup PIN — no URL can skip it.
• A logged-in user visiting /login is bounced to the Dashboard.

2.1 Login (phone number)

Phone-number-only login. First login on a device goes through OTP; a returning login on the same device skips OTP and asks for the PIN instead.

Phone rules: starts with 0, then 8–9 digits (e.g. 012 345 678). The leading 0 is fixed in the field; input is masked as *# ### ####.

• Empty phone → "Please input your phone number". Wrong format (too short/long) → "Invalid phone number".
• Valid number, first time on this device → goes to the OTP screen.
• Same number, second login on this device → no OTP; the PIN dialog appears instead (biometric allowed). Correct PIN → Dashboard.
• Cancelling the PIN dialog leaves you on Login with no error.
• "Create new account" opens Registration.
• Toolbar: theme toggle works; environment badge shows the current environment; Developer Options button appears only when enabled.
• Desktop / landscape web: the two-column layout with the form in a card renders correctly.

2.2 OTP screen (shared by login, registration, reset PIN)

Four digit boxes, a countdown, and a Resend link. The code auto-submits the moment the 4th digit is entered — the Verify button is a fallback.

• Countdown starts at 2:00 and counts down; Resend is greyed out until it reaches 0:00.
• Entering the 4th digit submits automatically (no need to press Verify).
• Wrong code → server error dialog; the field can be corrected and re-submitted.
• Resend after the timer → green "OTP code has been sent" snackbar, timer restarts at 2:00, field is cleared, and the new code works (the old one shouldn't).
• Android: the code auto-fills from the SMS. iOS: the code is suggested above the keyboard.
• Reset-PIN OTP masks the phone number (e.g. 012 ***** 78); login/register OTP shows it in full.
• Web: the field is focused automatically; typing works without tapping the boxes.

2.3 Registration

Create an account with full name, date of birth, gender, phone, and email, then confirm by OTP. After the OTP, the new account is logged in and forced to set up a PIN.

• "Create" stays disabled until the Terms & Conditions checkbox is ticked.
• Empty full name → "Please input your full name". Phone follows the same rules as Login.
• Email is optional, but an invalid email (when filled) → "Invalid email".
• Date of birth opens a date picker (range: 100 years ago → today). Gender opens a selection dialog.
• The Terms & Conditions link opens in-app on mobile and in a new tab on web.
• OTP success → logged in → immediately forced to Setup PIN → then Dashboard.
• Registering with an already-registered phone number → verify the server error message is clear.

3.1 Setup PIN (first time)

• Any login into an account without a PIN is forced here; Dashboard is unreachable until a PIN is set.
• PIN must be exactly 4 digits → otherwise "Please input 4 digits PIN". Mismatched confirmation → "PIN mismatch".
• Both fields are hidden by default; the eye icons reveal them independently.
• Successful submit → straight to Dashboard.
• The logout icon in the top bar asks for confirmation, then returns to Login.
• Back button / gestures cannot reach the Dashboard without a PIN.

3.2 PIN entry (gate & dialog)

Mobile shows a numeric pad with 4 dots; web shows a single text field. After the 4th digit it verifies automatically.

• Wrong PIN → "Incorrect PIN code", the icon and dots turn red, the entry clears, and the phone vibrates (mobile only).
• "Forgot PIN?" only appears after a failed attempt, and opens the Reset PIN flow.
• Correct PIN → brief success state, then the protected content appears / the dialog closes.
• When biometric is enabled, the fingerprint key on the pad works and the biometric prompt fires automatically on open (where allowed).
• A failed/cancelled biometric quietly returns to PIN entry (no error message) and the PIN still works.
• Web: the text field accepts only digits, max 4, and the arrow button submits.

3.3 Change PIN

• The screen first demands the current PIN — and biometric is deliberately not accepted here (the fingerprint key is inert).
• New PIN + confirmation follow the same 4-digit / mismatch rules as Setup.
• Success → "Your PIN has been changed!" snackbar → back to Settings; the new PIN works and the old one fails everywhere.

3.4 Reset PIN (forgot PIN)

Enter a new PIN, then confirm with an OTP sent to the account's phone (shown masked). The old PIN is never asked.

• Flow completes: new PIN → OTP → "Your PIN has been reset." snackbar → Dashboard.
• The old PIN no longer works after the reset.
• Resend on the reset OTP works and the new code is accepted.

3.5 Biometric login (fingerprint / Face ID)

• Turning the toggle ON opens the enable page (behind a PIN check); "Enable" fires the OS biometric prompt; success → "Biometric authentication enabled!" dialog.
• Once enabled, PIN screens offer biometric automatically (login verify, edit profile…), with PIN as fallback.
• Device without enrolled biometrics → dialog offering to open device Settings (Security on Android, Settings on iOS).
• Too many failed scans (OS lockout) → "…lock and unlock your device again." message; PIN still works.
• The setting is per device and per account — reinstalling the app or switching accounts resets it to off.
• The biometric row does not appear at all on the web build.

4.1 Dashboard overview

The home screen: quick actions (News, Service, About EAC, Notifications), the active customer account with its supplier, the outstanding debt with a Pay button, recent invoices, and a 12-month usage chart.

• Pull-to-refresh reloads every section.
• The four quick-action buttons open the right screens; the Notification button shows an unread badge ("9+" above nine).
• No linked account → illustration with a "Link an account" button (not an error).
• Supplier card shows logo, name, license number, address; a supplier without a logo shows the fallback icon.
• Customer card: label chip, name, status color, customer code (tap = copies to clipboard), ampere, address.
• The "N accounts" chip opens the linked-accounts list; the link icon opens the link-account wizard.

4.2 Debt & Pay button

• With debts in two currencies, a currency dropdown appears; with one currency it does not.
• Total amount is tappable and copies the number to the clipboard (without thousand separators).
• Expiry line reads correctly both before ("expires in N days") and after ("expired N days ago") the due date.
• No debt at all → friendly "no debt" state, no Pay button.
• Pay button opens Checkout with the right amount and currency.

4.3 Invoices & usage chart

• The 1-month / 6-month toggle switches between the newest invoice only and the full recent list (animated).
• Invoice cards show title, amount, consumption (kWh), invoice date, due date; the expiry countdown appears only on pending invoices; status colors are correct (pending / partial / reversed / paid).
• Tapping an invoice opens Invoice Detail.
• "Last 12 months" bar chart matches the month/kWh grid below it; the year legend colors match the bars.

4.4 Account actions from the dashboard

• Telegram button: links (opens the Telegram invitation) and unlinks the account's Telegram notifications.
• Menu → "Share account details" opens the system share sheet with the account text.
• Menu → "Set a label" opens the label picker (section 5.4).
• Menu → Unlink: confirmation dialog → PIN verification → success snackbar → dashboard reloads without the account.

5.1 Linked account list

• All linked accounts appear with label, name, status, code, ampere, address, and supplier line; the default account has a highlighted border.
• Tapping an account makes it the active one and returns to the Dashboard showing it.
• List paginates while scrolling (10 per page); no duplicates appear; short lists still allow pull-to-refresh.
• Search finds accounts by keyword; clearing the field restores the full list automatically; a no-match search shows the empty-search state.
• Unlink from a card: confirmation → PIN → the card disappears; with an active search, the result list refreshes.
• The + icon opens the link-account wizard and a newly linked account appears on return.

5.2 Link an account (wizard)

Three steps: enter/scan the customer code → verify ownership with two invoice numbers → optionally tag a label.

• Typing a valid customer code and pressing Next identifies the customer and advances to verification.
• An unknown code → clear error, stays on step 1.
• QR scan (mobile only) fills the code; a scanned code not matching 123-456789 format → "invalid customer code" dialog and the scan is discarded.
• The custom numeric keypad appears instead of the system keyboard (overlay in portrait, inline on web/landscape) and closes properly on back/help/scan.
• Help icons show sample invoice images (zoomable).
• Verification: both invoice fields are pre-filled with CINV; correct invoice numbers link the account (success snackbar); wrong ones show the server error.
• "Link and tag label" continues to the label step; plain "Link" returns to the caller with the account added.
• Backing out after identifying a customer asks to discard the link.
• Linking an account already linked to this user → verify the server error is understandable.

5.3 QR / barcode scanner

• First use asks for camera permission; denying returns silently to the form.
• "Don't allow and never ask again" → a dialog offers to open app settings.
• The frame overlay and scan line render; scanning a customer QR from a paper bill fills the code and closes the scanner.

5.4 Account labels

Pick a colored label for an account (e.g. "Home", "Shop"), or create/edit labels with a title and one of 15 colors.

• Selecting a label previews it live on the account card; Done saves it and the chip shows on the Dashboard and the list.
• Tapping the selected label again deselects it; Done then removes the label from the account.
• Create label: title + color grid + live preview; the new label appears in the list and stays selected.
• Creating a label with a title that already exists is blocked with an error.
• Edit and delete existing labels; deleting a label in use — check what happens to accounts wearing it.

6.1 Invoice detail screen

Full invoice: customer info, total due banner colored by status, invoice numbers/dates, consumption breakdown by meter, totals, and the 12-month usage chart.

• Customer code and invoice number copy to the clipboard on tap.
• Consumption breakdown shows the meter period as "from – to (N days)" and per-item amounts; totals add up.
• Status banner color matches the invoice state (pending / partial / reversed / paid).
• Pull-to-refresh reloads; a failed load shows Retry.

6.2 Add due date to calendar

Creates a reminder in a dedicated "EAC App" device calendar at 7:00 on the due date, with a reminder N days before.

• The calendar icon is hidden on web, on paid invoices, and on already-expired invoices — but stays visible (green) if an event was already added.
• First use asks for calendar permission; denial → dialog offering device settings.
• Reminder-day choices adapt to the days remaining (up to 1/3/5/7 days before).
• Success dialog appears; the event exists in the device calendar with the right date and reminder.
• Adding the same invoice twice is blocked ("already exists"); the dialog offers Delete for an existing event, and deletion works.
• iOS known bug: on a device whose default calendar is a non-iCloud account, adding the event fails. Reproduce and document the exact failure.

6.3 Save invoice as image

• A rendering overlay appears briefly, then: mobile saves a PNG to the gallery with a "saved to gallery" dialog.
• The saved image contains the full invoice (supplier header, all sections, footer) and is sharp (3× resolution).
• iOS asks for the add-to-photos permission on first save; denial is handled gracefully.
• Web downloads the PNG file instead — note there is no confirmation after the download on web (known gap).

7.1 Checkout (single payment)

• The amount shown equals the Dashboard's total due for the selected currency, and is not editable.
• Confirm opens the Bill24 payment window; its dark/light style and language follow the app's settings.
• Completing payment in Bill24 returns to the app's payment-result screen with the transaction.
• Cancelling / closing the Bill24 window leaves the app in a sane state (button usable again, no stuck spinner).
• KHR amounts under 100 are rejected by validation ("invalid min amount").
• While the payment initializes, the Confirm button shows "Processing…" and cannot be double-tapped into two transactions.

7.2 Pay by account (multi-account)

• The supplier filter (funnel icon) lists all suppliers with search; picking one refilters the accounts.
• KHR / USD switch reloads the debts for that currency; the summary card shows "selected / total" and the sum to pay.
• Unpaid / Paid tabs filter the cards; "Select all" appears only on Unpaid; paid accounts show a green badge and cannot be selected.
• Selecting accounts updates count and total live; changing currency/supplier/tab clears the selection.
• Selecting accounts under different license numbers and paying → a warning dialog blocks the payment.
• Pay hands the selected total to Bill24 and success comes back to the result screen; afterwards the paid accounts move to the Paid tab.
• A currency with no invoices shows a friendly empty state.

7.3 Payment result

Verifies the transaction and shows a receipt (bank, transaction number, date, account count, amount) plus a 5-second "processing" animation before the Done button appears.

• The receipt matches the payment: bank name (localized), transaction no., date/time (dd/MM/yyyy hh:mm a, local time), amount with the right currency format (KHR without decimals, USD with 2).
• Done appears after the processing animation and returns to Pay-by-account (multi flow) or Dashboard (single flow); the Dashboard then shows the reduced/zero debt.
• Opening the payment deep link (…/single-payment?tran_id=…) with the app closed, backgrounded, and logged-out — all three end up on the correct result page after loading.
• A deep link with a missing or invalid tran_id shows the error dialog and returns to the Dashboard (no crash).
• A failed verification shows the server's (Khmer) error message and exits to the Dashboard.

8.1 Notification list & detail

• Opening the list marks everything read; the Dashboard badge clears when you come back (not before — it refreshes on leaving the page).
• Unread items show a red dot; icons and colors match the type (news, invoice, receipt = green, credit control = red, generic bell).
• List paginates on scroll (20 per page) and supports pull-to-refresh; empty state shows "No Notification".
• Tapping an invoice notification opens the right Invoice Detail; a service notification opens the request timeline; others open the notification detail page.
• Detail page: title, date (dd/MM/yyyy hh:mm a), body; links/phone numbers/emails inside the body are tappable and open correctly.

8.2 Push notifications

• App in foreground: Android shows a heads-up banner; iOS shows the system banner; the unread badge updates live.
• App in background: the notification arrives in the tray; tapping it opens the app at the right target.
• App closed: tapping the notification cold-starts the app, and after loading (and login if needed) it navigates to the target.
• A notification with a broken/missing payload falls back to opening the notification list (no crash).
• After logout, the device stops receiving user-targeted pushes (topics are unsubscribed).
• Maintenance broadcast flips the app into/out of the maintenance screen while running.

9.1 News hub, list & article

• Two tabs — "Hot News" and "General News" — each with its own list; switching tabs keeps scroll position and does not refetch.
• Cards show thumbnail (placeholder icon when missing), 2-line title, and a relative date ("2 days ago"); dates read naturally in Khmer too.
• Infinite scroll (20 per page) and pull-to-refresh work; each tab has its own empty ("No News") and error states.
• The article page shows title, date, image (with a smooth hero transition), caption, description, and attachment images.
• Tapping the image or an attachment opens the full-screen viewer: pinch-zoom (up to 4×) and pan work; back returns cleanly.
• An article with a broken image URL doesn't crash the page.

10.1 About EAC hub

• Contact cards: phone (opens a hotline list; each number dials), email (mail app), website & Facebook & Telegram (browser/app), location (opens Maps at EAC).
• Each launcher behaves sensibly on a device without the target app (no mail app, no Telegram, no Maps).
• The details menu opens: Connection Price, Tariff List, Legal, Location, Q&A.
• A failed load shows Retry, and Retry recovers.

10.2 Connection price

• One tab per fee group; the table shows Connection type / Connection fee / Bond / Total with correct currency formatting.
• Empty groups and an entirely empty list both show a friendly empty state; failures offer Retry.

10.3 Tariffs

• Recent list: groups with their latest tariff PDFs; tapping a group header opens the full searchable list; tapping an item opens the PDF.
• Tariff list: search filters as you type; pull-to-refresh resets the search; infinite scroll works.
• Khmer search input behaves correctly.

10.4 Legal documents & Q&A

• Legal: one tab per server-driven category (horizontally scrollable); each tab lists documents; tapping opens the PDF viewer; per-tab empty/error states.
• Q&A: accordion questions expand/collapse; several can be open at once; long Khmer answers wrap correctly.

10.5 PDF viewer

• Download progress shows as a percentage; the PDF then renders and scrolls smoothly (test a large one).
• The share button shares the actual PDF file with a sensible file name.
• A document with no attachment shows "No attachment" instead of a blank screen.

10.6 Terms & Conditions viewer

• Mobile: the document loads in an in-app webview with a progress bar; dark mode renders readable text.
• Web: the document renders as in-app text (no webview) in the app's font and colors.
• Offline → the failed-load view, not a blank page.
• Accessible while logged out (it's a public page, linked from Register).

11.1 Service requests

Electricity service requests, powered by the embedded Oone workflow SDK: a "Service" tab with the request menu and a "My request" tab listing submitted requests (with timeline detail pages).

• The service menu loads and each service type opens its request form.
• Submitting a request (with attachments, if the form has them) succeeds and appears under "My request".
• A request's timeline page shows its progress/status history.
• Both tabs behave in Khmer and English, and in dark mode (the SDK screens should match the app theme).
• Service push notifications open the matching request timeline (see 8.2).

11.2 Festival branding

• When a festival is active, the Dashboard's EAC logo animates to the festival logo; tapping it opens a full-screen festival page with title and description.
• With no active festival, the normal logo shows and nothing is tappable.

12.1 Settings screen

• Profile card: photo (tap opens full-screen viewer — only when a photo exists), gender icon, name, and a masked phone number.
• Menu order and function: Appearance (Light/Dark/System inline), Change PIN, Biometric toggle (hidden on web), Terms & Conditions, About, Logout, and a red "Deactivate account".
• Logout asks for confirmation, shows a spinner, and returns to Login. Note: logging back in with the same number skips OTP and asks only the PIN.
• Desktop web: the two-column settings layout renders correctly.

12.2 Edit profile

Guarded by PIN/biometric. Change photo, name, date of birth, gender, email. The phone number is visible but locked.

• The PIN (or biometric) gate appears before the form; cancelling returns to Settings.
• Photo: Camera (mobile only) / Gallery / Remove options; every picked photo goes through a square crop step; cancelling the crop changes nothing.
• Denied camera/gallery permission is handled without a crash (currently: silently — note it).
• "Remove profile" asks confirmation; the removal is only committed when Save is pressed.
• Empty name blocks saving; invalid email blocks saving; DOB picker allows 100 years back through today.
• Save → "Your profile has been updated" snackbar → back; the new name/photo shows on Settings and the Dashboard.
• Leaving with unsaved changes asks "Discard changes?".
• Web: photo pick + the custom web crop dialog work in Chrome at minimum.

12.3 Theme (appearance)

• Light / Dark / System each apply instantly and persist across app restarts.
• "System" follows a live OS theme change while the app is open.
• Spot-check dark mode on: Dashboard, invoice detail, payment screens, PDF viewer, T&C webview, Bill24 window.

12.4 Language

• Khmer ↔ English switch applies immediately across the app and persists; the choice is saved to the user's account (a per-row spinner shows while saving).
• Logging in on another device applies the account's saved language automatically.
• Khmer renders correctly app-wide (fonts, wrapping, dates, currency) — spot-check every major screen.
• Note: OS font-size / accessibility text scaling is intentionally ignored (text size is locked). Confirm this is accepted behavior.

12.5 About

• Shows logo, app name, and "Version 2.4.9 (222)" matching the build under test.

12.6 Account deactivation

• The page names the account and lists the consequences; the red button demands PIN only (biometric refused).
• Cancelling the PIN aborts with no change.
• Success → "deactivated" snackbar → Login; the account can no longer log in, and the phone number requires OTP again on this device.
• A server failure during deactivation must not log the user out or half-delete anything.

13.1 Developer options screen

Internal screen guarded by the static code 2025. Reachable in any app state — including under maintenance and logged out.

• The entry button only appears when "Developer options enabled" is on; the gate accepts 2025 and rejects anything else.
• "Payment enabled" off → the Dashboard Pay button disappears (may need a dashboard refresh); on → it returns.
• Language, primary color, and Beta Mode toggles apply and persist.
• Turning "Developer options enabled" off hides the entry button everywhere — verify the team's documented way back in before doing it.

13.2 Environment switching

• Environments listed: PRODUCTION, EAC STAGING, DEMO (+ any custom). The active one is marked and shown in the badge on Login/Splash.
• Switching shows a blocking spinner, logs out, wipes saved logins, and the app then talks to the new environment.
• A failed switch (bad URL) shows an error and stays on the current environment.
• Swipe-to-delete removes a custom environment; the active environment cannot be deleted (delete is disabled).
• "Add new environment": a valid config URL adds it to the list; an invalid/unreachable URL shows an error and the dialog stays open.