Skip to content
Terminales Docs

PDR 0002 — MVP reports catalog

Purpose: record the product decision on which reports the MVP must ship, so Wave 3 verifies against a fixed list and the deferred reports are explicit. The domain detail (data, filters, sources, fields) lives in reporting.md; this PDR records the scope decision and the verification obligation.

  • Status: Accepted
  • Date: 2026-07-11
  • Deciders: Product Owner (confirmed in reporting.md, 2026-07-09) + Wave 3 planning
  • Repos: terminales-api, terminales-web, terminales
  • Related: ../business-rules/reporting.md, wave3-mvp-analysis §3.6 + Track G

Context

Section titled “Context”

The Wave 2 analysis drafted “remaining MVP report endpoints” (rows 40/41) as build work. As of 2026-07-09 the API MVP report suite is implemented (src/reports/pos/mvp-reports.controller.ts, #178) with CSV export (report-csv.util.ts) and rollup-backed long ranges (daily_sales_rollups via src/pos/sales/finalize-workflow.ts). So in Wave 3 reports become a verification obligation (do the eight work correctly, are the web views present, are the margin/rollup fields deployed) rather than net-new build — this PDR pins the list they verify against.

Decision — eight must-have MVP reports; CSV-only export for v1

Section titled “Decision — eight must-have MVP reports; CSV-only export for v1”

The MVP report set (must exist and be correct at go-live):

  1. Daily Sales Summary (Corte Diario) — gross/net/tax/discounts/refunds, txn count, avg ticket, units, sales-by-tender, sales-by-hour.
  2. Shift Z-Report & Cortes de caja history — frozen shift_reports snapshot; expected vs counted cash + variance; reprintable.
  3. Sales by Product / Category — units, gross, net, margin (needs line_items.unitCost from products.costPrice), top-N.
  4. Sales by Payment Method (tender mix) — amount/count/%, commissions, net, effective rate.
  5. Sales by Employee — per-cashier sales, txn count, avg ticket, discounts, voids, cash variance.
  6. Commissions Report (W57) — by provider/method/concept; depends on transactions.commission / netAmount (AngelPay Q5 for card commission data).
  7. Cash Movements Report — non-sale cash in/out from cash_movements.
  8. Voids & Discounts (exceptions) — voided orders + applied discounts with who authorized.

Export: CSV only for v1. PDF, share-sheet, and email delivery are explicitly future formats.

Scope rules carried from reporting.md: reports are online-only (the offline terminal computes no aggregates); rollups/snapshots are derived & reconcilable, never authoritative (rebuildable from the transactions / stock_movements ledgers; voids decrement, never drop); everything keys on the store-local business date (stores.timezone), not UTC; RLS scopes every read by role (cashier = own shift, supervisor = store, manager/owner = portfolio).

Deferred (post-MVP “later phases”): Inventory/Stock valuation, Sales by Terminal/Device, Multi-store Comparison, Tax/Fiscal CFDI, Merchant Balance/Settlement, Refunds, Sales Trends/ABC, and Customer reports (the last blocked until the Clientes module lands per PDR-0001).

Rationale: these eight cover the operational, cash-reconciliation, and loss-prevention needs a merchant has on day one; CSV is a universal, low-effort export that unblocks accounting without a rendering pipeline; the deferred set is analytics/fiscal depth the client can operate without.

Alternatives rejected

Section titled “Alternatives rejected”
  • Ship reports with PDF/email export in v1 → deferred; CSV meets the day-one need, richer formats are a renderer swap later (§5 print-from-web readiness).
  • Include Customer/Refund/Multi-store reports in MVP → deferred; they depend on post-MVP entities (customers, explicit refund model) or are portfolio analytics beyond the launch need.

Consequences

Section titled “Consequences”
  • Track G includes a reports verification ticket per platform: prove the eight endpoints return correct figures (incl. void-decrement and business-date correctness), confirm the web report views (W55–W58) render them with the documented filters + CSV export, and verify the reporting field additions (line_items.unitCost, sales_orders.businessDate, transactions.commission/netAmount, etc.) are deployed.
  • The Commissions report (6) stays gated on the AngelPay Q5 commission-data answer; it is verified as far as its data source allows and flagged where it can’t be.

References

Section titled “References”