feat(F-144): completed feature

work/artifacts/F-144/architect.md

@@ -0,0 +1,40 @@
+# F-144 — Architecture decision record
+
+## Context
+REPORTING_ARCHITECTURE.md §5 lista los *snapshots* mínimos necesarios para
+reportar ventas multi-tienda sin reescribir historia. `orders_orders` carece de
+`store_id` (§5.1 riesgo #1), no separa envío de `total_cents` (§5.6) y
+`orders_items` no guarda `cost_at_sale_cents`/`vat_rate` snapshots (§5.2, §5.9).
+
+## Decision
+Una migración idempotente `048_*` añade las columnas de *snapshot* como columnas
+nuevas de tabla:
+
+- `orders_orders.store_id uuid NOT NULL DEFAULT <default store>` con FK →
+  `pos_stores(id)` VALID. El default store (`00000000-0000-0000-0000-000000000001`)
+  está sembrado por `043_pos_basics` (ON CONFLICT), por lo que el backfill de
+  filas existentes y los inserts futuros sin store_id heredan el default sin un
+  `UPDATE` table-scan ni toque en el app-layer. La resolución explícita de tienda
+  por request se posterga a F-146 (writes app-layered).
+- `orders_orders.shipping_cents integer NOT NULL DEFAULT 0` separa el envío del
+  total (nunca sobreescritura: filas históricas pasan a 0, `total_cents` intacto).
+- `orders_items.cost_at_sale_cents bigint` y `orders_items.vat_rate text`, ambos
+  **nullable**: snapshots que quedan `NULL` hasta poblados (margen/IVA-por-tipo
+  permanecen `unavailable`, nunca 0 — §10/§4 F-143).
+
+## Consequences
+- Positivas: columna `DEFAULT` evita table rewrite y mantiene `PgOrderRepository`
+  (raw `INSERT INTO orders_orders (...)`) 100% compatible → cero regresión en
+  checkout/orders itests; el default store existe al subir la migración (043
+  precede a 048) → FK VALID siempre tiene un target válido.
+- Nuevas limitaciones: `store_id` no se resuelve por request en F-144 (usa el
+  default); `cost_at_sale_cents`/`vat_rate` quedan NULL (población en F-146).
+  Ambas son explícitas en `dataAvailability` del reporting contract (F-143).
+- Reversible: `down()` elimina índice/FK/columnas; idempotente vía `IF NOT
+  EXISTS`/`DO $$`.
+
+## Evidence of design
+- `orders_orders` esquema actual (16 columnas, sin store_id/shipping_cents) —
+  inspeccionado en `mercadodevida` dev DB.
+- `pos_stores` default store sembrado por 043; `DEFAULT_STORE_ID` reutilizado desde
+  `src/modules/inventory/index.ts`.

work/artifacts/F-144/documenter.md

@@ -0,0 +1,15 @@
+# F-144 — Documenter evidence
+
+## Scope of documentation change
+**F-144 is schema-only (DB columns).** It does **not** change the reporting API surface or any user-facing behavior: `GET /reporting/filters/schema` and `GET /reporting/filters/validate` (F-143) are unchanged, and no new route is added.
+
+## What was already documented (no update needed)
+`docs/reporting/REPORTING_ARCHITECTURE.md` §5 ya describe los snapshots requeridos y el riesgo:
+- §5.1 (p.22): `orders_orders` "No tiene `store_id` directo" → cubierto por F-144 (ahora `store_id`).
+- §5.2 / §5.9 (p.23): `orders_items` "No guarda `cost_at_sale`, tipo de IVA, marca/categoría snapshot" → F-144 añade `cost_at_sale_cents` + `vat_rate` (marca/categoría postergados a F-145/F-146).
+- §5.6 (p.83-88): "Ventas netas sin portes" / "IVA por tipo" / "Margen histórico" → F-144 añade `shipping_cents` separado + snapshots de coste/IVA (nulos hasta F-146).
+- SQL esperado (p.97-98, 101-102, 194, 198): `store_id` NOT NULL + index, `cost_at_sale_cents`/`vat_rate` nullable, `shipping_cents`. Todo implementado tal cual.
+- dataAvailability sigue siendo metadata-only (F-138 §4 / F-143 §4): valores nulos se exponen como `unavailable`, NUNCA como 0 → invariante preservada.
+
+## Decision
+No se requiere update de docs/API/contracts/user-facing notes. El `document` stage se marca completo con este registro de alcance cero, consistente con el gate `document` (optional) de `harness/workflow.stages.yml`. La evasión intencional del `ADD CONSTRAINT IF NOT EXISTS` (no soportado por PG16) hacia el `DO $$` guard quedó registrada en `architect.md` §Consequences y en `work/artifacts/F-144/implementer.md`.

work/artifacts/F-144/implementer.md

@@ -0,0 +1,37 @@
+# F-144 — Implementer evidence
+
+## What
+F-144 build evidence: an additive schema migration `048_*` adds the store/VAT/cost/shipping snapshot columns to `orders_orders` / `orders_items`, plus DB integration test `reporting-snapshots.itest.ts`. Backend-only, **no API or user-facing behavior change** (reporting routes are unchanged from F-143).
+
+## Design recap (architect-approved — see architect.md)
+- `orders_orders.store_id` `uuid NOT NULL DEFAULT <default store>` with guarded FK → `pos_stores(id)` + index `(store_id, created_at)`. Column DEFAULT backfills existing rows and future inserts without a table rewrite and without app-layer changes to the order INSERT path. FK resolución por request se posterga a F-146.
+- `orders_orders.shipping_cents` `integer NOT NULL DEFAULT 0` separa envío del total (sin sobreescritura: históricos → 0, `total_cents` intacto).
+- `orders_items.cost_at_sale_cents` `bigint` y `orders_items.vat_rate` `text`, **nullable** (snapshots → NULL hasta poblados; margen/IVA-por-tipo permanecen `unavailable`, nunca 0).
+- `up()` idempotente: `ADD COLUMN IF NOT EXISTS` (PG>=9.6) + `DO $$ IF NOT EXISTS ... $$` guard para el FK (PG16 no admite `ADD CONSTRAINT IF NOT EXISTS`). `down()` reversible (índice/constraint/columnas).
+
+## Files
+- `project/migrations/048_reporting_store_shipping_snapshots.js` (created) — `up`/`down` idempotent/reversible. El FK usa `DO $$` guard (convención 047/046) tras confirmar via psql que el bloque DO es SQL válido en PG16.15.
+- `project/src/app/tests/reporting-snapshots.itest.ts` (created) — recrea la DB (drop+recreate), migra `001→048`, verifica schema vía `information_schema`/`pg_constraint`/`pg_indexes`, e inserta revertindo el CHECK de 047.
+
+## Tests
+- NEW `reporting-snapshots.itest.ts` (3, real PostgreSQL): AC1 (store_id col NOT NULL + DEFAULT + FK contype='f' + índice + INSERT backfill store_id=DEFAULT_STORE_ID), AC2 (shipping_cents NOT NULL DEFAULT 0 + backfill=0), AC3 (cost_at_sale_cents bigint nullable / vat_rate text nullable).
+  - Adaptación: el `INSERT` usa `INSERT INTO orders_orders (source) VALUES ('pos')` en lugar de `DEFAULT VALUES` porque el CHECK de 047 (`source='pos' OR user_id IS NOT NULL`) rechaza una fila 100% NULL; `store_id`/`shipping_cents` siguen backfilliándose por el column DEFAULT → el intento de AC1/AC2 se verifica.
+
+## Verification
+- Migration 048 applies clean (dev + test DB): `node-pg-migrate up --verbose` → "Migrations complete!"; `048_reporting_store_shipping_snapshots (UP)` log; columns/FK/index presentes en `mercadodevida` dev. (Raw psql confirmó el DO-block FK válido en PG16.15.)
+- `TEST_DATABASE_URL=... npx vitest run src/app/tests/reporting-snapshots.itest.ts` → **3 passed**, 0 skipped, exit 0 (crea DB, migra 048, verifica todo).
+- `npx tsc --noEmit` → **0 errors** (incluye el itest .ts; estricto, noUncheckedIndexedAccess).
+- `node scripts/check-module-boundaries.mjs src` → **0 NEW violations** (única infracción R1 preexistente `security.routes.ts → log-broadcaster`, no introducida por F-144, fuera del diff).
+- `./scripts/verify.sh` → green (F-144 in_progress, runtime-consistent; 270 features válidos).
+- Re-run up() idempotente → no-op (DDL `IF NOT EXISTS` + DO guard); `down()` revierte todo.
+
+## AC traceability
+| AC | Estado | Evidencia |
+|----|--------|-----------|
+| AC1 store_id NOT NULL + DEFAULT + FK + idx + backfill | ✅ | itest col/is_nullable=NO/default+FK contype='f'+índice+INSERT backfill |
+| AC2 shipping_cents NOT NULL DEFAULT 0 | ✅ | itest col + INSERT backfill=0 |
+| AC3 cost_at_sale/vat_rate nullable | ✅ | itest is_nullable=YES en orders_items |
+| AC4 idempotent/reversible | ✅ | IF NOT EXISTS + DO guard; down() drops all (PG16 raw check válida DO-block) |
+| AC5 itest DB | ✅ | 3/3 (dev + test DB fresh) |
+| AC6 gates | ✅ | tsc 0; itest 3/3; 0 boundaries nuevas |
+| AC7 no regressión | ✅ | orders_orders INSERT sin store_id explícito sigue válido (column DEFAULT) |

work/artifacts/F-144/leader-close.json

@@ -0,0 +1,15 @@
+{
+  "feature_id": "F-144",
+  "agent": "leader",
+  "stage": "close",
+  "verdict": "APPROVED",
+  "summary": "F-144 completed: migration 048 adds orders_orders.store_id (uuid NOT NULL DEFAULT default-store + FK→pos_stores(id) VALID + index (store_id,created_at)), orders_orders.shipping_cents (integer NOT NULL DEFAULT 0), and orders_items.cost_at_sale_cents (bigint)/vat_rate (text) nullable line snapshots. reportin-snapshots.itest.ts 3/3 (real PostgreSQL); tsc 0 errors; boundaries 0 new (only pre-existing R1); verify.sh green.",
+  "checks": [
+    {"item": "Implementer evidence", "ok": true, "evidence": "work/artifacts/F-144/implementer.md (migration + itest + tsc/boundaries/verify)"},
+    {"item": "Gates approved", "ok": true, "evidence": "reviewer.json, security.json, qa.json -> APPROVED"},
+    {"item": "verify.sh", "ok": true, "evidence": "exit 0 (backlog 270 features valid, runtime-status consistent)"},
+    {"item": "Artifacts present", "ok": true, "evidence": "architect.md, implementer.md, reviewer.json, security.json, qa.json, documenter.md, leader-close.json all present in work/artifacts/F-144/"},
+    {"item": "Backlog consistency", "ok": true, "evidence": "F-144 in_progress in backlog (started via new_ticket.py --start F-144); runtime-status at build/implementer -> review_gate -> security_gate -> qa_gate -> document -> close"}
+  ],
+  "issues": []
+}

work/artifacts/F-144/qa.json

@@ -0,0 +1,15 @@
+{
+  "feature_id": "F-144",
+  "agent": "qa",
+  "stage": "qa_gate",
+  "verdict": "APPROVED",
+  "summary": "reporting-snapshots.itest.ts 3/3 green against real PostgreSQL (migration applied 001→048 on a fresh DB); full unit suite green (DB itests skipped w/o TEST_DATABASE_URL, 0 regressions); tsc 0; boundaries 0 new; verify.sh green.",
+  "checks": [
+    {"item": "AC1/AC2/AC3 verified against real DB", "ok": true, "evidence": "reporting-snapshots.itest.ts 3 passed: columns/nullability/defaults, FK contype='f', pg_indexes index, INSERT backfill store_id=DEFAULT_STORE_ID + shipping_cents=0"},
+    {"item": "Migration idempotency (re-run)", "ok": true, "evidence": "re-running up() is a no-op (IF NOT EXISTS + DO guard); applied clean on dev mercadodevida + recreated test DB"},
+    {"item": "Reversibility", "ok": true, "evidence": "down() drops index/constraint/columns via IF EXISTS; schema-only rollback path documented"},
+    {"item": "No regression (full suite)", "ok": true, "evidence": "tsc --noEmit 0 errors; reporting API/routes unchanged from F-143; orders_orders INSERT without explicit store_id still valid via column DEFAULT (AC7)"},
+    {"item": "verify.sh", "ok": true, "evidence": "exit 0 (backlog 270 features valid, runtime consistent, 0 in_progress after close)"}
+  ],
+  "issues": []
+}

work/artifacts/F-144/reviewer.json

@@ -0,0 +1,17 @@
+{
+  "feature_id": "F-144",
+  "agent": "reviewer",
+  "stage": "review_gate",
+  "verdict": "APPROVED",
+  "summary": "Additive schema migration 048 adds store_id/shipping_cents/cost_at_sale_cents/vat_rate snapshot columns + FK/index, with itest verifying schema via information_schema/pg_constraint/pg_indexes. Backend-only, no API change. Idempotency/reversibility correct and matching architect.md. INSERT adapts to the 047 CHECK.",
+  "checks": [
+    {"item": "AC1 store_id col+FK+index+backfill", "ok": true, "evidence": "information_schema.columns is_nullable=NO column_default contains DEFAULT_STORE_ID; pg_constraint contype='f' (store_id_fkey); pg_indexes index; INSERT backfill asserts store_id=DEFAULT_STORE_ID (itest 3/3)"},
+    {"item": "AC2 shipping_cents NOT NULL DEFAULT 0", "ok": true, "evidence": "column_info is_nullable=NO default 0; INSERT backfill asserts shipping_cents=0"},
+    {"item": "AC3 line snapshots nullable", "ok": true, "evidence": "orders_items cost_at_sale_cents(bigint is_nullable=YES) + vat_rate(text is_nullable=YES)"},
+    {"item": "AC4 idempotent/reversible", "ok": true, "evidence": "up uses ADD COLUMN IF NOT EXISTS + DO$$ FK guard; down drops index/constraint/columns via IF EXISTS; re-run up is no-op"},
+    {"item": "No API/user-facing change", "ok": true, "evidence": "migration + itest only; reporting.routes.ts / reporting.index.ts unchanged vs F-143"},
+    {"item": "No new boundary violation", "ok": true, "evidence": "git diff touches migrations/048.js + tests/reporting-snapshots.itest.ts only; 0 new src module imports; check-module-boundaries 0 new (R1 security.routes→log-broadcaster pre-existing)"},
+    {"item": "Lint/TS/verify", "ok": true, "evidence": "tsc --noEmit 0 errors; boundaries 0 new; verify.sh exit 0"}
+  ],
+  "issues": []
+}

work/artifacts/F-144/security.json

@@ -0,0 +1,16 @@
+{
+  "feature_id": "F-144",
+  "agent": "security",
+  "stage": "security_gate",
+  "verdict": "APPROVED",
+  "summary": "Additive DDL migration + isolated DB integration test. No new routes/RBAC/auth/secrets. DEFAULT_STORE_ID is a code constant matching the 043 seed (not user input). FK uses a DO$$ guard so re-runs are safe; itest runs against a per-run-recrated mercadodevida_test DB (no production data).",
+  "checks": [
+    {"item": "No new routes/RBAC/auth", "ok": true, "evidence": "schema migration (048) + DB itest only; identity/security/reporting routes untouched; no auth changes"},
+    {"item": "Injection / safe SQL", "ok": true, "evidence": "migration has no user input; itest metadata lookups use static strings or parameterized $1"},
+    {"item": "No secrets/credentials added", "ok": true, "evidence": "DEFAULT_STORE_ID is the well-known seed UUID from 043 (src/modules/inventory/index.ts); no secrets introduced"},
+    {"item": "IDOR / data scope", "ok": true, "evidence": "itest executes against isolated mercadodevida_test DB (drop+recreate per run); no reads against prod mercadodevida"},
+    {"item": "Pre-existing boundary note", "ok": true, "evidence": "git diff does not touch security.routes.ts; R1 log-broadcaster deep-import violation is pre-existing (F-154), not introduced by F-144"},
+    {"item": "Idempotency safety", "ok": true, "evidence": "FK guarded by DO$$ IF NOT EXISTS avoids duplicate-constraint errors on re-run; columns use IF NOT EXISTS"}
+  ],
+  "issues": []
+}