feat(club-003): club POS integration: identify member and register cashback from sales

work/artifacts/CLUB-003/reviewer.json

@@ -0,0 +1,59 @@
+{
+  "feature_id": "CLUB-003",
+  "agent": "reviewer",
+  "stage": "review_gate",
+  "verdict": "APPROVED",
+  "summary": "Revisión técnica aprobada: CLUB-003 conecta el TPV con el módulo Club mediante resolución de socio por código, acumulación idempotente de cashback en ledger y extensiones fail-safe en la creación de venta POS.",
+  "checks": [
+    {
+      "item": "El endpoint GET /club/resolve resuelve socios activos por memberCode sin exponer tokens ni datos internos.",
+      "ok": true
+    },
+    {
+      "item": "El cashback se calcula como round(totalCents * cashbackBps / 10000) y se acumula en el ledger con idempotency_key club-earn-{orderId} dentro de la misma transacción que la venta.",
+      "ok": true
+    },
+    {
+      "item": "El cashback solo se acumula cuando orderState === 'COMPLETED'; las ventas PENDING no acumulan.",
+      "ok": true
+    },
+    {
+      "item": "Si la escritura del ledger falla, la venta continúa sin bloquearse (fail-safe).",
+      "ok": true
+    },
+    {
+      "item": "loadResult recupera clubEarnedCents del ledger al recargar venta por idempotency key.",
+      "ok": true
+    },
+    {
+      "item": "Validaciones: typecheck backend/POS, build backend/POS/frontend, verify.sh, vitest de payment allocation y club boundary tests.",
+      "ok": true
+    }
+  ],
+  "issues": [],
+  "notes": [
+    "El frontend TPV no está modificado todavía para buscar socio Club por código; la integración de API está lista y se puede usar desde la UI del terminal.",
+    "El idempotency key del ledger incluye el orderId, garantizando una única acumulación por venta incluso si la venta se cobra en múltiples pasos.",
+    "receive-rest-payment devuelve clubEarnedCents: 0 porque pagos adicionales sobre ventas ya completadas no deben re-acumular cashback."
+  ],
+  "evidence": [
+    "work/artifacts/CLUB-003/architect.md",
+    "work/artifacts/CLUB-003/implementer.md",
+    "project/src/modules/club/api/club.routes.ts",
+    "project/src/modules/club/application/club-service.ts",
+    "project/src/modules/club/domain/ports.ts",
+    "project/src/modules/club/infrastructure/pg-club-repository.ts",
+    "project/src/modules/pos/domain/pos-sale.ts",
+    "project/src/modules/pos/application/create-pos-sale.ts",
+    "project/src/modules/pos/api/pos.routes.ts",
+    "project/apps/pos/src/types/checkout.ts",
+    "cd project && npm run typecheck",
+    "cd project && npm run build",
+    "cd project/apps/pos && npm run build",
+    "cd project && npx vitest run src/modules/pos/tests/payment-allocation.test.ts",
+    "cd project && npx vitest run src/modules/club/tests/",
+    "./scripts/verify.sh",
+    "git diff --check"
+  ],
+  "timestamp": "2026-08-26T18:15:10Z"
+}