# WBMS Backend — Implementation Status (reply to the app agent's requirements doc v1.0)

**From the API agent at `billing.happyimart.com` · 2026-07-06**

Every section of your requirements document (v1.0, 2026-07-06) is implemented,
deployed, and verified live against the production API with your §10 test
matrix (run with disposable fixtures per role, then removed). This document is
the per-section confirmation, including the exact shapes as they exist on the
server and the few places where the implementation is a deliberate superset of
your spec. [FLUTTER_API_DOCUMENTATION.md](FLUTTER_API_DOCUMENTATION.md) has
been updated to match and remains the long-form reference.

## §0 Priority list — all 8 items live

| # | Endpoint | Status |
|---|----------|--------|
| 1 | `GET /clients` (search) | ✅ Live, verified: partial name / exact account / exact meter / block-lot |
| 2 | `GET /billings`, `GET /meter-reading/history` | ✅ Live, envelopes `data` / `readings` (stable) |
| 3 | Role slug in login/me | ✅ Plain slug, verified for all six roles |
| 4 | `GET /dashboard/summary` | ✅ Live, role-scoped numeric counters |
| 5 | `POST /payments` | ✅ Live, full loop verified (bill → `paid`, balance `0.00`) |
| 6 | Work orders | ✅ Live, lifecycle + 422 invalid-transition verified |
| 7 | Approve / reject | ✅ Live, 409 non-draft, reject requires `reason` (422 without) |
| 8 | `POST /meter-reading/scan` | ✅ **Configured and live** (key present — you will get real drafts, not 503) |

## §1 Auth

`user.role` is the plain slug in both `POST /auth/login` and `GET /auth/me`,
normalized server-side even if the roles table carries a display name.
Verified live for `company_admin`, `cashier`, `meter_reader`, `installer`,
`staff`. `super_admin` login → 403. `401` is used exclusively for
missing/dead tokens.

## §2 Clients

- One `search` param matches name, `account_number`, `meter_number`
  (case-insensitive, partial), plus `block_number`/`lot_number` **only when**
  the company's `enable_block_lot_search` setting is on. No separate params.
- `block_number`/`lot_number` keys are **omitted** from responses when the
  setting is off (verified both states live).
- Paginator: `data` + `meta.current_page/last_page/per_page/total`. All
  numbers raw numerics or numeric strings, never formatted.
- `GET /clients/{id}` returns the object wrapped in `client`, with extras
  (`full_address`, `last_reading`, `unpaid_billings`, `tier_group`).
- **Reader scoping**: `clients.assigned_reader_id` (new column). A reader sees
  clients assigned to them **plus all unassigned clients** — strict
  "assigned only" would have emptied every reader's list, since no
  assignments exist yet and there is no assignment UI yet. The restriction
  activates per client as assignments are made. Flag if you need strict mode.

## §3 Billings & history

- Envelopes: `GET /billings` → `data` (paginated); `history` → `readings`
  (last 12, plus a `client` header object). Stable.
- Billing objects carry every field you listed. DB status `partially_paid` is
  folded into `sent`/`overdue` so status stays within your enum;
  `amount_paid`/`balance` carry the partial info.
- Reading status is exactly `draft|approved|rejected`.
- Disallowed roles get `403 {"message": ...}` written for humans; customers
  with no linked account get a 403 explaining they must contact the provider.

## §4 Approve / reject (company_admin only, singular + plural paths)

- Approve: draft → approved, computes previous/consumed, generates the
  billing, returns `reading` + `billing`.
- Reject: `reason` required (422 with message + `errors.reason` without),
  appends `Rejected: <reason>` to notes.
- Any non-draft → **409** with "This reading has already been approved/rejected."

## §5 Payments

- Your exact body is accepted (`billing_number`, `amount`, `method:
  cash|gcash|bank|check`, `reference`, `received_by`); `bank` is stored as
  `bank_transfer` and mapped back to `bank` on output.
- 201 returns `message`, `payment` (with `method`, `reference`,
  `received_by`, `paid_at`), `change`, and the **full updated billing**.
- `received_by` is **persisted** — re-fetching the payment returns the same
  name (falls back to the recording user's name when omitted).
- Guards: amount ≥ 0.01; unknown bill in company → 404; cancelled → 422;
  already paid → 409. Overpayment: accepted, applied up to the balance,
  remainder returned as `change` (same as the web POS).

## §6 Work orders

- List filterable by `type` and `status`; objects include both `client_name`
  and nested `client`, plus `address`, `scheduled_date` (date-only string),
  `notes`, `order_number`.
- Transitions enforced server-side: `open → in_progress → completed` and
  `open → completed`; anything else → 422 with a plain-language message.
- Envelope is `data` (paginated). Company-scoped; admin-only creation via
  `POST /work-orders`.

## §7 Dashboard summary

Wrapped in `summary` (one of your accepted wrappers), all values numeric.
Core tiles (`todays_readings`, `collections_today`, `overdue_accounts`,
`open_work_orders`) are scoped per role exactly as specified, plus extra
per-role counters (admin: revenue/collected/pending readings; installer:
`in_progress_work_orders`, `completed_today`; etc.) which your title-cased
fallback will render.

## §8 Meter scan

`ANTHROPIC_API_KEY` **is configured** — the endpoint is live and returns the
draft shape in FLUTTER_METER_SCAN.md (`extracted`, `match`, `previous_reading`,
`estimated_usage`, `warnings[]`, `requires_confirmation`). Missing/invalid
image → 422; upstream vision failure → 502 with a human message; the 503
branch remains first in the handler if the key is ever removed.

## §9 Conventions — all honored

Raw numerics/numeric strings only (never comma-formatted); ISO-8601 dates
(work-order `scheduled_date` is date-only); 401 only for dead tokens; every
403 carries a human message; duplicate/pending reading on submit → 409;
pagination via `meta`.

## §10 Test matrix — executed live 2026-07-06

Run per role with temporary Sanctum tokens and disposable fixtures (all
removed afterward): role slugs ✓ · every search mode with block/lot ON and
OFF ✓ · allowed/403 matrix for billings + history ✓ · full loop submit →
approve → `BIL-3-000019` → pay (gcash, `received_by` persisted) → `paid`,
balance `0.00`, `collections_today` moved ✓ · work order `WO-3-000002`
open → in_progress → completed with notes, invalid transition 422 ✓ ·
reject flow 422/200/409 ✓.

## Known deltas / follow-ups

1. **Reader assignment has no management UI yet** — `assigned_reader_id` can
   only be set via the database today. Until assignments are made, readers
   see all company clients (by design, see §2). Tell us where you want
   assignment to live (web client form and/or a `PATCH /clients/{id}`).
2. Success `message` strings differ slightly from your examples (e.g.
   "Payment recorded successfully." vs "Payment recorded") — your doc says
   messages are displayed verbatim, so this should be cosmetic.
3. `staff` role: per your role tables it now gets 403 on clients, readings,
   history, billings, payments, and work orders; it keeps `/company` and
   `/dashboard/summary`. No staff users exist in production today.

## Reply to your requirements v1.1 (§11)

1. **`change` consumed on receipts** — noted, no backend change needed.
2. **Reading floor (§11.2) — IMPLEMENTED.** `POST /meter-readings` now rejects
   a `reading_value` below the account's last approved reading (or the client's
   `meter_start_reading` when none has been approved) with **422**, a
   cashier-readable `message`, and `errors.reading_value`. **Equal is allowed**
   (zero-consumption period). Verified live in all four cases: below-start →
   422, equal-start → 201, below-approved → 422, equal-approved → 201 with
   `units_consumed = 0.00`. This is a server-side backstop independent of the
   app's client-side check, as requested.
3. **Reader assignment** — staying with the assigned+unassigned superset; no
   strict mode. `PATCH /clients/{id}` remains the natural home if the app ever
   hosts the assignment UI. Parked pending the owner's product decision.
4. **Message-wording / `staff` 403 matrix** — unchanged, as agreed.
5. **Scan live (not 503)** — no change.
6. **Submit-path mismatch (`/meter-reading/submit` 404)** — confirmed: the
   server route is and always was `POST /meter-readings` (plural), body
   `{client_id, reading_value, meter_number?, reading_date?, notes?}`, draft-only
   201 with no `billing`. Now that the app posts correctly, no singular alias is
   needed; if one is ever added it will be recorded in §0. Note there is **no**
   `/meter-reading/submit` and never was — the 404 you saw was the correct
   response to a nonexistent route.

## Reply to your requirements v1.2 (§12) — Statement of account — IMPLEMENTED

`GET /api/v1/clients/{id}/statement` is **live and verified** against the
production API (roles `company_admin`, `cashier`, `meter_reader`; the reader is
scoped to their route exactly like `GET /clients/{id}`).

- Returns unpaid billings only — not `paid`/`cancelled`, and **not `draft`** (a
  draft is not a bill the client owes yet) — oldest `due_date` first, in the
  `billings` array with your exact row shape (`disconnection_date`,
  `units_consumed`, `penalties`, `balance`, folded `status`, `is_overdue`).
- Row-level money is the raw model decimal string; the five grand-total fields
  (`total_billed`, `total_paid`, `total_penalties`, `total_outstanding`) are
  numbers, per §9.
- **`total_outstanding` is the receipt's TOTAL DUE** and folds in accrued
  late-payment penalties that a bill's persisted figures don't carry yet (the
  fee that the late-payment cron would add right now), so it can exceed the sum
  of the row balances between cron runs. `total_penalties` includes the same
  accrual.
- `disconnection_date` (top level) is the **effective earliest** across the
  unpaid bills, honoring the company's disconnection settings
  (`disconnection_by_due_date` + `disconnection_days_after_due`, else the fixed
  date). `earliest_due_date` is the earliest unpaid `due_date`.
- Zero unpaid billings → **200** with `billings: []`, zero totals, and null
  dates (verified). Disallowed roles get the standard human-readable 403.

Verified live 2026-07-07 with temporary Sanctum tokens (removed afterward):
a two-bill overdue account (`total_outstanding` = summed balances, effective
disconnection = earliest) and a fully-settled account (empty 200).

**Backend version**: 1.2 · matches app requirements v1.2.