CLAUDE.md — usrv-batch-transaction-report

Guía para Claude Code al trabajar en este repositorio.

Descripción general

Servicio batch en Python que genera reportes de liquidación para merchants de Tonder. Corre en AWS Batch (Fargate). Dos reportes activos:

• Daily Transaction Report — diario
• Settlement Batch Report — lunes y jueves 8 AM UTC

Ejecución local

Ver LOCAL_TESTING.md y run_local.sh.

./run_local.sh pdn batch     # Settlement Batch
./run_local.sh pdn daily     # Daily Transaction

Arquitectura

Clean Architecture (Hexagonal): batch → services → repositories → gateway

src/
├── batch/                    # Entry points (scripts ejecutables)
├── gateway/                  # Acceso a infraestructura (MongoDB, S3, SSM, Lambda)
├── repositories/             # Queries a base de datos por tipo de transacción
├── services/
│   ├── shared/               # Usados por todos los reportes
│   └── reports/
│       ├── settlement_shared/  # Compartido entre settlement T+0, T+1, T+2
│       └── settlement_batch/   # Específico del Settlement Batch (T+0)
├── domain/                   # Modelos de dominio
└── infrastructure/           # Logger

Archivos clave

Entry points

• src/batch/settlement_batch_report.py — flujo principal del Settlement Batch
• src/batch/daily_transaction_report.py — flujo principal del Daily

Gateways

• src/gateway/mongodb_gateway.py — singleton MongoDB, socketTimeoutMS=120000 (batch pesado)
• src/gateway/s3_gateway.py — upload de archivos a S3
• src/gateway/lambda_gateway.py — invoke async a Lambda
• src/gateway/ssm_gateway.py — lectura de parámetros SSM

Servicios compartidos

• src/services/shared/config_service.py — lee SSM, caché singleton por ejecución. Métodos: get_testing_config(), get_email_config(), get_smtp_config()
• src/services/shared/email_service.py — envío de correos (daily y settlement)
• src/services/shared/merchant_log_capture.py — captura logs por merchant y los sube a S3 como .txt (cloud) o solo consola (local). Reutilizable en otros reportes.

Settlement Batch — servicios específicos

• src/services/reports/settlement_batch/date_calculation_service.py — calcula fechas del ciclo según día de la semana
• src/services/reports/settlement_batch/merchant_config_service.py — lee acquirers válidos y payout fee por merchant desde SSM
• src/services/reports/settlement_batch/date_helpers.py — get_rolling_reserve_dates() (90d y 180d lookback)
• src/services/reports/settlement_batch/payload_builder.py — construye el JSON para invocar la Lambda. Estructura idéntica a migracionv1/utils/settlement_json.py. Todos los valores POSITIVOS.

Settlement Batch — repositorios

• src/repositories/settlement_batch/constants.py — todas las constantes (colecciones, campos, acquirers, categorías)
• src/repositories/settlement_batch/payments_repository.py — payments, disputes won, APM, routing
• src/repositories/settlement_batch/disputes_repository.py — disputes activas (DISPUTE_IN_REVIEW), disputes won
• src/repositories/settlement_batch/refunds_repository.py — refunds
• src/repositories/settlement_batch/voids_repository.py — voids (solo kushki)
• src/repositories/settlement_batch/withdrawals_repository.py — withdrawals (bitso, stp)
• src/repositories/settlement_batch/rolling_reserve_repository.py — rolling reserve release. Ejecuta DOS queries: ANTIGUA (mv_payment_transactions, fechas 90/180d atrás) y NUEVA (usrv-finances-journals, fechas del ciclo actual). Siempre usa ANTIGUA para cálculos.
• src/repositories/settlement_batch/business_repository.py — merchants activos, respeta specific_merchants de SSM

Excel

• src/services/reports/settlement_shared/excel_builder.py — SettlementExcelBuilder, genera el Excel en /tmp/
• src/services/reports/settlement_shared/excel_translations.py — traducciones ESP/ENG para el Excel

Colecciones MongoDB

Colección	Uso
usrv-finances-journals	Fuente principal (FINANCES). Double-entry: siempre filtrar type: "OUT"
mv_payment_transactions	Solo para rolling reserve release ANTIGUA
usrv-withdrawals-withdrawals	Withdrawals
business_business	Merchants activos

SSM Parameters

Path: /usrv-batch-transaction-report/{stage}/

Parámetro	Descripción
SLS_BUILD	Config de MongoDB (leído en run_local.sh)
TESTING_CONFIG	default_config (cron) y manual_execution (testing manual). Ver src/services/shared/config_service.py
MERCHANT_CONFIG_SETTLEMENT_BATCH	Array de merchants con id, language, payout_fee, exclude_acq. Ver src/services/reports/settlement_batch/merchant_config_service.py
EMAIL_CONFIG	Config SMTP y recipients. settlement_batch.default_recipients para el reporte de liquidación
SETTLEMENT_LAMBDA_ARN	ARN de la Lambda a invocar con el payload JSON de settlement

Reglas críticas

FINANCES — double-entry bookkeeping

Cada transacción tiene dos registros (IN y OUT). Siempre agregar type: "OUT" o se duplican los montos. Ver src/repositories/settlement_batch/constants.py → JOURNAL_TYPE_OUT.

Categorías FINANCES correctas

• Payments: PAYMENT
• Disputes activas: DISPUTE_IN_REVIEW (no DISPUTE_REVIEW)
• Disputes ganadas: DISPUTE_WON
• Refunds: REFUND
• Voids: VOID
• Withdrawals: WITHDRAWAL
• Rolling reserve release: ROLLING_RESERVE_RELEASE

Rolling Reserve

• Query ANTIGUA (mv_payment_transactions): usa fechas 90/180 días atrás, campo rolling_reserve_amount
• Query NUEVA (usrv-finances-journals): usa fechas del ciclo de settlement actual, campo gross_amount, filtro process_id: {$not: {$regex: "^set-"}}
• Siempre usar ANTIGUA para cálculos. NUEVA solo para logging/comparación.

IVA

• La mayor parte viene de iva_amount en FINANCES
• El payout fee (tarifa_liquidacion) es hardcoded desde SSM y no tiene registro en FINANCES → calcular tarifa_liquidacion * 0.16 por separado

Payload Lambda

• Estructura idéntica a migracionv1/utils/settlement_json.py
• Valores POSITIVOS (absolutos), no negativos
• Campos adicionales propios: rolling_reserve_release_finances, settlement_type: "batch", s3

Detección cloud vs local

MerchantLogCapture usa AWS_BATCH_JOB_ID (presente solo en AWS Batch) para decidir si captura logs a S3 o solo imprime a consola.

Infraestructura AWS

Definida en serverless.yml:

• AWS Batch (Fargate) con dos Job Definitions
• EventBridge cron: lunes y jueves 8 AM UTC para settlement, diario para daily
• S3 bucket: {service}-{stage}-files
  • Daily: {business_id}/daily-report/{date}/
  • Settlement: {business_id}/settlement/batch/{date}/ (Excel + log .txt)
• IAM: permisos SSM, S3, STS, lambda:InvokeFunction