Screen & Data Reference
The lookup page. Which screen lives where, what every table holds, what each status value means, what the demo data contains, and which reports you can export — with no procedure narrative in the way.
Screens
All nine screens sit under one Water Utility group in the sidebar. Each one is a hub whose sibling views are tabs inside it.
| Screen | URL | Tabs / sub-views | Needs |
|---|---|---|---|
| Dashboard | water_utility | KPI summary | reports |
| Accounts | water_utility/accounts | List · account view with recent bills · status changes | account |
| Connections & Meters | water_utility/connections | Connections · Zones · Meter registry (/meters) with install & pull | account, meter |
| Reading | water_utility/reading_cycles | Cycles · Route books · Capture queue · Exceptions · Evidence viewer | reading, reading_validate |
| Billing | water_utility/bill_runs | Bill runs (compute / approve / post) · Bills · Adjustments · Tariffs (/tariffs) with versions, tiers, validate and simulate | bill_run, bill_run_approve, tariff |
| Collections | water_utility/cashiering | Till · Payments · Batches · Aging · Promises · Daily report | cashiering |
| Enforcement | water_utility/service_orders | Orders · Notices · Enforcement candidates · Disconnection batch | service_order |
| Advisories | water_utility/advisories | List · Compose with reach estimate · Preview · Publish | advisory |
| Reports | water_utility/reports | Five reports, each exportable | reports |
Two more surfaces sit outside the sidebar: Settings → Water Utility
(water_utility/settings), and the customer-facing
MyWater app (water_utility/app) and OTP portal
(water_utility/portal).
Data tables
Twenty-seven tables, all prefixed wu_. Every one carries the standard audit block —
who created the row, when it was created, when it was last updated, and a soft-delete flag —
so nothing is ever physically destroyed by normal use.
Registry
| Table | Holds |
|---|---|
wu_zones | Billing / reading zones, with an optional soft link to a Field Service service zone. |
wu_service_connections | The physical tap: address, barangay, coordinates, connection size, tap date. |
wu_meters | The meter registry: serial, brand, model, size, digit count, multiplier, lifecycle status. |
wu_meter_installations | One meter's tenure on one connection — installed reading, removal reading and reason. Readings attach here, not to the meter. |
wu_accounts | The billing account: customer, connection, class, status, deposit, senior flag and OSCA ID, billing contacts. |
wu_number_sequences | The counters behind account, bill, receipt and order numbering. |
Reading
| Table | Holds |
|---|---|
wu_reading_cycles | One zone, one period, one reading window. |
wu_route_books | A reader's book for a zone, with the assigned reader. |
wu_route_sequences | The walk order — which connection is stop 1, 2, 3. |
wu_meter_readings | The read itself: previous and present register values, derived consumption, read type, source, GPS, and who validated it. |
wu_reading_evidence | Photos and files attached to a read, with a content hash and processing state. |
wu_reading_exceptions | Flags raised against a read — high, low, negative, stuck, rollover, no access, tamper — with severity and resolution. |
Billing
| Table | Holds |
|---|---|
wu_tariffs | A rate schedule for one customer class. |
wu_tariff_versions | An effective-dated, board-backed version of that schedule. |
wu_tariff_tiers | The minimum charge and the consumption blocks, optionally per meter size. |
wu_bill_runs | One run over one cycle, with its totals and its approval trail. |
wu_bills | The bill: register values, consumption, the five money columns, the due date, and the frozen snapshot_json. |
wu_bill_lines | The printed lines — minimum, water blocks, discount, penalty, arrears carried, environmental fee, other. |
wu_bill_adjustments | Signed corrections raised against a posted bill. |
Collections and enforcement
| Table | Holds |
|---|---|
wu_payments | The official-receipt ledger: OR number, channel, amount, teller, batch, void trail. |
wu_payment_allocations | How much of a receipt went to which bill, in what order. |
wu_collection_batches | A teller's shift: open → closed → remitted, with the total collected. |
wu_notices | Notices issued to an account, and how and when they were served. |
wu_promise_to_pay | An amount and a date a customer committed to, and whether it was kept. |
wu_service_orders | New connection, disconnection, reconnection, meter change, leak investigation, re-read — with an optional Field Service link. |
Customer contact
| Table | Holds |
|---|---|
wu_advisories | Zone-targeted notices, with a publication window and status. |
wu_portal_tokens | Customer-portal OTP and session credentials, stored as digests with an expiry and a use count. |
Status lifecycles
Twelve state machines. Every change is written by one shared component, which checks the move is a legal one, checks the user is allowed to make it, refuses any exit from a final state, and records it. Statuses in bold are final.
| Thing | Starts as | Path |
|---|---|---|
| Account | applicant | applicant → approved → active → for_disconnection ⇄ disconnected → closed · or applicant → rejected |
| Meter | in_store | in_store → installed → pulled → under_test → in_store · → condemned · → lost |
| Reading cycle | draft | draft → open → reading → validation → closed · → cancelled |
| Meter reading | captured | captured → validated → billed · → rejected |
| Bill run | draft | draft → computing → computed → approved → posted · → cancelled |
| Bill | draft | draft → posted → cancelled |
| Payment | posted | posted → voided |
| Collection batch | open | open ⇄ closed → remitted |
| Service order | open | open → scheduled → in_progress → completed · → cancelled |
| Tariff version | draft | draft → approved → superseded · draft → archived |
| Promise to pay | active | active → kept · → broken · → cancelled |
| Advisory | draft | draft → published → resolved · → archived |
Read types and exception codes
actual — the dial was read ·
estimated — billed, but labelled as an estimate ·
customer_reported — phoned or messaged in ·
no_read — access denied or unsafe.
high · low · negative ·
stuck · rollover · no_access ·
tamper — each with a severity, and open until resolved with a note.
Bill line types
Payment channels and service-order types
Receipts record a channel: teller, collector, bank,
portal, gcash or maya. Service orders are typed
new_connection, disconnection, reconnection,
meter_change, leak_investigation or meter_reading, and are
sourced from staff, enforcement or portal.
The demo dataset
Loaded with php erpat db:seed WaterUtilityDemo. Eighty-five rows across twenty-four
tables, every business code prefixed WU-DEMO-.
| What | Codes | Notes |
|---|---|---|
| Customers | WU Demo · … (6) | Created in the core customer registry. |
| Zones | WU-DEMO-Z1, -Z2 | Zone 1 has a complete month; zone 2 has registry only. |
| Connections / meters / accounts | -SC-001…006, -MTR-001…006, -ACCT-0001…0006 | Six taps, one meter and one account each. |
| Reading cycle | WU-DEMO-CY-202606 | June 2026, zone 1, closed. One route book, four reads, two exceptions. |
| Tariffs | WU-DEMO-TRF-RES, -TRF-COM | Both approved, effective 1 Jan 2026, 7 tiers each. |
| Bill run | WU-DEMO-BR-202606 | Posted. 4 bills · 84.000 cu.m · ₱3,239.00. |
| Bills | WU-DEMO-BILL-000001…000004 | See the table below. |
| Receipts | WU-DEMO-OR-000001, -000002 | ₱439.00 in full and ₱1,000.00 partial, in batch WU-DEMO-CB-01 (₱1,439.00, closed). |
| Enforcement | WU-DEMO-SO-000001 | One open disconnection order, one overdue notice, one active promise to pay for ₱1,330.00. |
| Advisory | WU-DEMO-ADV-0001 | Published scheduled interruption targeting zone 1. |
| Bill | Account | Class | Consumption | Total | Paid | Balance |
|---|---|---|---|---|---|---|
…BILL-000001 | …ACCT-0001 | residential | 18.000 cu.m | ₱439.00 | ₱439.00 | ₱0.00 |
…BILL-000002 | …ACCT-0002 | residential | 8.000 cu.m | ₱235.00 | ₱0.00 | ₱235.00 |
…BILL-000003 | …ACCT-0003 | commercial | 53.000 cu.m | ₱2,330.00 | ₱1,000.00 | ₱1,330.00 |
…BILL-000004 | …ACCT-0004 | residential (senior) | 5.000 cu.m | ₱235.00 | ₱0.00 | ₱235.00 |
The demo bills are priced by the module's own calculation engine, not typed in by hand, so their lines, totals and snapshots are internally consistent. The commercial bill is the interesting one: a ₱620.00 minimum for its 3/4" meter, three full blocks, then 13 cu.m billed above the top block — five lines that show the whole tier walk on one page.
Reports and exports
| Report | Answers |
|---|---|
| Billing register | Every bill in a run or period, with consumption and amounts. |
| Collection summary | What was receipted, by day, channel and teller. |
| Aging | Outstanding balances banded by how long they have been overdue. |
| Exceptions | Reading exceptions by code, severity and resolution state. |
| Route completion | How much of each route book was actually read in a cycle. |
All five are filterable and exportable, and every export is recorded in the audit log.
Background jobs
| Slug | Schedule |
|---|---|
wu_daily_servicing | 01:20 daily |
wu_expire_portal_tokens | every 30 minutes |
wu_field_sync | every 15 minutes |
wu_portal_payment_sync | every 10 minutes |
Notification events
Nine events, all grouped under the Water Utility category. Who receives each one, and the limits that apply, are covered in Administration → Notifications.
| Event key | Audience | Raised by |
|---|---|---|
wu_bill_generated | Customer | Posting a bill |
wu_bill_due_reminder | Customer | wu_daily_servicing, stage 1 |
wu_bill_overdue | Customer | wu_daily_servicing, stage 2 |
wu_payment_received | Customer | Issuing a receipt (teller or gateway import) |
wu_disconnection_notice | Customer | Raising a disconnection order |
wu_reconnection_completed | Customer | Completing a reconnection order |
wu_advisory_published | Customers in the targeted zones | Publishing an advisory (screen or API) |
wu_bill_run_ready_for_approval | Staff with water_utility_bill_run_approve | A run reaching computed |
wu_reading_exception_flagged | Staff with water_utility_reading_validate | Flagging a reading exception |