110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# F-146 — Architect
|
|
|
|
## Feature
|
|
Reporting: service summary and sales API.
|
|
|
|
## Background
|
|
F-143 set up the RBAC and filter contracts. F-144 added store_id/shipping_cents snapshots. F-145 added payment lines. F-146 wires up the ReportingService that reads the actual data using those columns.
|
|
|
|
## Objetivo
|
|
Implementar ReportingService con métodos `summary()` y `sales()` que:
|
|
- Usan el CTE `filtered_orders` del architecture doc §7
|
|
- Aplican todos los filtros del schema de F-143
|
|
- Devuelven métricas con `dataAvailability` correcto
|
|
- Soportan `groupBy`, `pagination` y `compare`
|
|
|
|
## Diseño
|
|
|
|
### ReportingService (application layer)
|
|
|
|
```typescript
|
|
// src/modules/reporting/application/reporting-service.ts
|
|
|
|
interface ReportingServiceDeps {
|
|
pool: pg.Pool;
|
|
}
|
|
|
|
class ReportingService {
|
|
constructor(private deps: ReportingServiceDeps) {}
|
|
|
|
async summary(filters: ReportingFilters): Promise<SummaryResponse>
|
|
async sales(filters: ReportingFilters): Promise<SalesResponse>
|
|
}
|
|
```
|
|
|
|
### SQL base (CTE de §7 arquitectura)
|
|
|
|
```sql
|
|
WITH filtered_orders AS (
|
|
SELECT o.*
|
|
FROM orders_orders o
|
|
WHERE o.created_at >= $1 -- from (UTC)
|
|
AND o.created_at < $2 -- to (UTC)
|
|
AND o.state IN ('PAID','PROCESSING','SHIPPED','DELIVERED','COMPLETED')
|
|
AND ($3::text IS NULL OR o.source = $3) -- channel
|
|
AND (cardinality($4::uuid[]) = 0 OR o.store_id = ANY($4::uuid[]))
|
|
AND (cardinality($5::uuid[]) = 0 OR o.terminal_id = ANY($5::uuid[]))
|
|
AND (cardinality($6::text[]) = 0 OR o.state = ANY($6::text[]))
|
|
),
|
|
filtered_items AS (
|
|
SELECT i.*, o.source, o.store_id, o.terminal_id
|
|
FROM orders_items i
|
|
JOIN filtered_orders o ON o.id = i.order_id
|
|
)
|
|
SELECT
|
|
COUNT(DISTINCT o.id)::int AS orders,
|
|
COUNT(DISTINCT o.user_id) FILTER (WHERE o.user_id IS NOT NULL)::int AS customers,
|
|
COALESCE(SUM(i.unit_price_cents * i.quantity), 0)::bigint AS gross_sales_cents,
|
|
COALESCE(SUM(i.discount_cents), 0)::bigint AS discounts_cents,
|
|
COALESCE(SUM(i.tax_cents), 0)::bigint AS tax_cents,
|
|
COALESCE(SUM(i.quantity), 0)::int AS units_sold
|
|
FROM filtered_orders o
|
|
LEFT JOIN filtered_items i ON i.order_id = o.id
|
|
```
|
|
|
|
### groupBy extension (sales endpoint)
|
|
|
|
```sql
|
|
-- Para groupBy=day (agrupación por día UTC)
|
|
DATE_TRUNC('day', o.created_at) AS period
|
|
```
|
|
|
|
### dataAvailability (según modelo actual)
|
|
|
|
```typescript
|
|
const dataAvailability: DataAvailability = {
|
|
grossSales: 'available',
|
|
netSales: 'unavailable', // sin shipping_cents aún (F-144 existe, service aún no lo usa)
|
|
discounts: 'available',
|
|
tax: 'available',
|
|
unitsSold: 'available',
|
|
orders: 'available',
|
|
customers: 'available',
|
|
margin: 'unavailable', // sin cost_at_sale en orders_items
|
|
paymentMethod: 'unavailable', // sin JOIN con reporting_payment_lines aún
|
|
refunds: 'unavailable', // necesita state=REFUNDED/PARTIALLY_REFUNDED en filtro
|
|
shipping: 'available', // shipping_cents en orders_orders (F-144)
|
|
};
|
|
```
|
|
|
|
### Rutas
|
|
|
|
- `GET /reporting/summary?from=&to=&channel=&storeId=&...` → SummaryResponse
|
|
- `GET /reporting/sales?from=&to=&groupBy=day&page=1&...` → SalesResponse (con pagination)
|
|
|
|
### Caching
|
|
|
|
F-146 NO implementa caché (postergado a F-148 post-dashboard). La respuesta incluye `updatedAt: new Date().toISOString()` y `cache: { hit: false, maxAgeSeconds: 0 }` como placeholder.
|
|
|
|
## Acceptance Criteria
|
|
|
|
AC1: GET /reporting/summary devuelve métricas agregadas (orders, customers, grossSales, discounts, tax, units) con rango filtrado.
|
|
AC2: GET /reporting/sales devuelve filas agrupadas por día/semana/mes/hora/store/channel.
|
|
AC3: Filtros storeId/terminalId/state/channel se aplican correctamente.
|
|
AC4: Paginación funciona (page/pageSize).
|
|
AC5: dataAvailability refleja correctamente qué métricas son calculables.
|
|
AC6: Compare previous_equal devuelve rango previo del mismo tamaño.
|
|
AC7: Errores de validación (fechas invertidas, IDs inválidos) devuelven 400.
|
|
AC8: Permisos RBAC aplicados (REPORTING_VIEW para summary, REPORTING_SALES para sales).
|
|
AC9: tsc 0, itest pasa, verify.sh verde.
|