Book 1 — Sales & Revenue¶

Status: DRAFT for validation. Six chapters, static-analysis-derived (nav → routes → controllers → models → migrations across bizwiz + the bizwizorderanddelivery mobile app). Every chapter separates code-proven facts from inferences; inferences live in each chapter's §7 "Open questions to confirm". This index consolidates the flow, the seams between chapters, and the top items for you to validate with users/devs.

Chapters¶

#	Chapter	Covers	File
1	Order Taking & Sales Invoicing	How a sale becomes an order and a confirmed invoice — mobile capture, sales orders, salesman invoice, backend invoicing, credit invoice/note approvals, service invoices	01
2	Dispatch & Delivery	Loading-sheet dispatch, delivery schedules, gate pass & gateman verification, mobile delivery confirmation, cross-branch merge/split	02
3	POS / Cash Sales	Over-the-counter/tablet cash sales, receipting, dispatcher scan/verify, returns, cashier cash-blocking	03
4	Customer Management	Two-level customer record, onboarding→approval, KRA PIN, lifecycle (dormant/deactivate/suspend), bad debts, post-sales discounts, withholding, CRC	04
5	Route Management	Route definition, delivery centres, route-change approvals, geomapping/geotagging, route visits, teams	05
6	Banking & Receivables Reconciliation	Money-in matching engine — route/cash banking approval, statement matching→verify→approve→post to GL, unknown/suspended handling, GL recon	06

End-to-end flow (how the chapters connect)¶

flowchart TD
  subgraph Field["Field / Mobile (bizwizorderanddelivery)"]
    OT[Order captured on route\nCh1]
    DEL[Delivery confirmed\nCh2]
  end
  subgraph Counter["Counter (bizwizpos)"]
    POS[Cash sale + receipt\nCh3]
  end
  CUST[Customer master & credit\nCh4]
  ROUTE[Route / centre / visit plan\nCh5]

  ROUTE -.assigns shops to routes.-> OT
  CUST -.credit limit / approval gate.-> OT
  OT --> INV[Invoice confirmed\nCh1]
  INV --> DISP[Loading sheet & dispatch\nCh2]
  DISP --> DEL
  DEL --> RECV[Receivable / debtor balance]
  POS --> CASH[Cash collected]
  RECV --> BANK[Banking & reconciliation\nCh6]
  CASH --> BANK
  BANK --> GL[(GL posting\nFinance book)]

Cross-chapter seams (resolved during the deep dives)¶

Customer ↔ Route — Ch4 owns the customer record & credit lifecycle; Ch5 owns route structure, geomapping & visit scheduling. "Route customers" appear in both by design; each chapter references the other rather than duplicating.
Dispatch ↔ Route — RouteDeviationAlert is created in DeliveryScheduleController (Ch2/Fleet), not in Route Management. Confirmed and cross-noted.
Banking ↔ Finance (GL) — Ch6 owns matching/approval and the posting handoff; the chart-of-accounts/journals live in the Finance book. Two different "GL Reconciliation" controllers exist — banking-side (Ch6) vs finance-side — flagged to prevent confusion.
POS ↔ Banking — Ch3 records the cash sale; Ch6's "Cash Sales Banking" reconciles the cash. Clean handoff.

Recurring themes across Book 1 (worth your attention)¶

Behavior is settings-driven per tenant. Feature flags/admin settings switch entire flows (identify-sales-orders-from-normal-orders, allow-backend-invoice-order-taking, REQUEST_DELIVERY_OTP, SHOW_ROUTE_INTEGRATION_CODES, onboarding gates, etc.). The guide documents both branches where found — but which branch is live per client is a recurring open question.
Substantial legacy/dead code intermixed with live code. Multiple invoice document families, vestigial tables (pos_customers, wa_cash_sales), dead menu links ("Restored Bad Debts"), byte-identical " 2.php" duplicates, unrouted controllers (RouteManagerController), disabled-but-built workflows (Driver Undispatched). Recommend a dedicated "legacy inventory" pass later.
Approval queues everywhere (pending→verified→approved→closed). This is the biggest concentration of the "make users approvers, not curators" opportunity — and the richest audit-trail data.
Some processes are fully manual (dormancy marking, can_suspend) — clear automation candidates.

Consolidated open questions — for user/dev validation¶

Grouped; full context in each chapter's §7.

A. Which branch is live? (tenant/flavor configuration)¶

Sales-order 3-stage flow vs legacy invoice flow — per client? (Ch1, Ch2)
Delivery OTP / geo-fence enforcement on/off — per client? (Ch2)
Automated bank feeds vs manual Excel statement upload — per client? (Ch6)
Which POS cash-sale table family is current per flavor? (Ch3)

B. Confirm dead vs live¶

sales_orders FULFILLED/PARTIALLY-FULFILLED statuses — used at all? Model references an APPROVED state not in the enum. (Ch1)
"Restored Bad Debts" menu (href="#", no route) — intended feature or drop? (Ch4)
RouteMasterPlan (routed, no migration/relation), RouteManagerController (unrouted), Driver Undispatched Workflow (disabled) — roadmap or cruft? (Ch5, Ch2)
Vestigial tables: pos_customers, wa_cash_sales, cash_sale_entries, wa_pos_cash_sales_new*. (Ch3)

C. Process/logic to confirm with owners¶

What computes can_suspend? Is dormancy really only manual? (Ch4)
Met/unmet visit computation logic. (Ch5)
Is the sales-order confirmation step truly enforced (flag checks partly commented out)? (Ch1)
Overlap of is_settled vs verification_status vs reconciled on the money-in ledger. (Ch6)

D. Schema/citation items to spot-verify before publishing¶

credit_sale_invoices schema (inferred from controller, not read from migration). (Ch1)
banking_approvals full column set (stage/verified/approved live in ALTER migrations). (Ch6)
Sub-agent-sourced line numbers in POS service/job files — check for drift. (Ch3)
Casing mismatch: SHOP_ONBOARDING_PHONE_REQUIRED (blade) vs shop_onboarding_phone_required (DB slug). (Ch4)

Coverage & method notes¶

Coverage: ~90–95% of each chapter's nav scope traced to code. Thinner areas (geomapping table schemas, teams/field-visit field detail in Ch5) are flagged in-chapter.
Not done by design: no runtime/DB profiling, no screenshots — this is a "how it's built to work" guide, validated by review. Live walkthroughs reserved for anything review flags as ambiguous.
Correction logged: the initial research brief hinted WalletTran/WalletMatrix were the reconciliation ledger — they are not (employee wallet/commission). The money-in ledger is the payment_verification_* family + wa_debtor_trans.