55 lines
3.4 KiB
Markdown
55 lines
3.4 KiB
Markdown
# F-143 — API contract documentation
|
|
|
|
## Resumen del cambio (user-facing)
|
|
New backoffice **Reporting** module delivering the shared filter contract + RBAC foundation (F-142 §3/§6/§9). No report data is read here (F-144+ owns report data); `GET /reporting/filters/schema` only introspects the contract. Two new endpoints, both backoffice-only (backoffice_session or storefront `mdv_session` via `combinedAuth`):
|
|
|
|
## Nuevas rutas
|
|
| Method | Path | Auth (authenticate) | Permission | Body / Query | 200 response |
|
|
|--------|------|---------------------|------------|--------------|--------------|
|
|
| GET | `/reporting/filters/schema` | `combinedAuth` (authenticated) | `REPORTING_VIEW` | n/a | `{ filterSchema, comparison, dataAvailability, permissions }` |
|
|
| GET | `/reporting/filters/validate` | `combinedAuth` (authenticated) | `REPORTING_SALES` | `?from&to&compare?…` (see below) | `{ ok, filters, comparison: { range } }` |
|
|
|
|
## RBAC
|
|
Permissions are role-based (no permission table yet — F-142 §9 "compatibilidad inicial"):
|
|
- `admin` — all reporting permissions (incl. `REPORTING_FINANCIAL`, `REPORTING_EXPORT`).
|
|
- `editor` — VIEW + SALES + PRODUCTS + CUSTOMERS + INVENTORY + DISCOUNTS + REFUNDS + TAXES.
|
|
- `pos_manager` — VIEW + SALES + PAYMENTS + CASH.
|
|
- `pos_cashier` — VIEW + SALES.
|
|
- `customer` — none (403 on both routes).
|
|
|
|
A future `backoffice_permissions` migration keeps the `requireReportingPermission(user, perm)` call-site signature.
|
|
|
|
## Filter schema (shared contract)
|
|
Query params parsed by `reportingFiltersSchema` via `parseJson` (→ 400 `VALIDATION_ERROR` on bad input):
|
|
|
|
- `from` *(string, required)* — ISO 8601 datetime, **inclusive** start.
|
|
- `to` *(string, required)* — ISO 8601 datetime, **exclusive** end. `from < to` enforced (400 on inversion).
|
|
- `compare` — enum `none | previous_equal | previous_calendar` (default `none`).
|
|
- `channel` — enum `all | ecommerce | pos | admin` (default `all`).
|
|
- `storeId`, `terminalId`, `cashierId`, `paymentMethodId`, `productId`, `categoryId`, `brandId` — repeatable UUID (single value or repeated).
|
|
- `customerId` — single UUID (optional; walk-in POS has none).
|
|
- `state` — repeatable string (e.g. `PAID,SHIPPED`).
|
|
- `groupBy` — enum `day|week|month|hour|store|channel|terminal|cashier|payment`.
|
|
- `page` *(int, default 1)*, `pageSize` *(int, 1..200, default 50)*.
|
|
- `sort` — string (e.g. `-revenue`).
|
|
|
|
### Comparison range (`comparisonRange`, `[from,to)`)
|
|
- `none` → `comparison.range = null`.
|
|
- `previous_equal` → exact-duration mirror; prior window ends exactly at `range.from`.
|
|
- `previous_calendar` → UTC-aligned prior window of `ceil(span_days)` days.
|
|
|
|
## `dataAvailability` (metadata only — F-142 §4 baseline)
|
|
Never converted to 0. Currently:
|
|
- `available`: `grossSales`, `discounts`, `tax`, `unitsSold`, `orders`, `customers`.
|
|
- `unavailable`: `netSales`, `margin`, `paymentMethod`, `refunds`, `shipping`.
|
|
|
|
## Errores
|
|
- `401` — unauthenticated (`authenticate` rejects).
|
|
- `403` — authenticated but lacks the route permission.
|
|
- `400` — malformed query (zod → `VALIDATION_ERROR`), incluyendo `from >= to` e UUIDs inválidos.
|
|
|
|
## Implementación
|
|
- `project/src/modules/reporting/` (domain/application/api + tests + index).
|
|
- `project/src/app/build-app.ts` — `registerReportingRoutes` registered inside `if (deps.pool)` with `combinedAuth`.
|
|
No migrations, no DB schema or data-table changes in this ticket.
|