# US-MGN-004-007-001: Registrar Pago Recibido de Cliente

**RF Asociado:** [RF-MGN-004-007](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-007-gestión-de-pagos-y-conciliación.md)
**Módulo:** MGN-004 - Financiero Básico
**Epic:** Pagos y Conciliación
**Prioridad:** P0 (MVP)
**Story Points:** 5
**Sprint:** Sprint 12
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story

**Como** usuario de tesorería,
**Quiero** registrar pagos recibidos de clientes,
**Para** contabilizar los ingresos y conciliar con facturas pendientes.

---

## Descripción Detallada

Pagos recibidos (payment_type='inbound') registran dinero recibido de clientes. Al registrar pago:
- Se crea registro en financial.payments
- Se genera asiento contable: Débito Banco/Caja, Crédito Cuentas por Cobrar
- Se puede conciliar con una o múltiples facturas de cliente
- Si pago cubre factura completa, factura pasa a state='paid'

---

## Criterios de Aceptación

### Escenario 1: Registrar pago recibido exitosamente
**Dado que** soy usuario tesorería,
**Cuando** registro pago amount=1210, payment_date="2024-01-20", payment_method="bank_transfer", journal_id=BAN (banco),
**Entonces** payment created, payment_type='inbound', asiento contable generado y posteado.

### Escenario 2: Generar asiento contable de pago
**Dado que** registro pago recibido 1210,
**Cuando** se genera asiento,
**Entonces** líneas:
  - Débito: Banco (journal.default_account) 1210
  - Crédito: Cuentas por Cobrar (partner.receivable_account) 1210

### Escenario 3: Conciliar pago con factura
**Dado que** registro pago 1210 y tengo factura cliente pendiente por 1210,
**Cuando** concilio pago con factura,
**Entonces** factura.state='paid', reconciliation creada.

### Escenario 4: Pago parcial
**Dado que** factura por 1500 y pago 1000,
**Cuando** concilio,
**Entonces** factura.state='partial', amount_residual=500.

### Escenario 5: Pago múltiples facturas
**Dado que** pago 3000 y facturas F1=1210, F2=1790,
**Cuando** concilio con ambas,
**Entonces** ambas paid, reconciliations creadas.

---

## Reglas de Negocio

- **RN-1:** payment_type='inbound' para pagos recibidos.
- **RN-2:** Partner debe ser customer.
- **RN-3:** payment_method: cash, bank_transfer, credit_card, check.
- **RN-4:** Journal debe ser tipo bank o cash.
- **RN-5:** Asiento contable se postea automáticamente.
- **RN-6:** Factura paid si amount_residual=0.
- **RN-7:** Un pago puede conciliar múltiples facturas.
- **RN-8:** RLS filtra por company_id.

---

## Tareas Técnicas

### Backend
- [ ] POST /api/v1/financial/payments
- [ ] POST /api/v1/financial/payments/:id/reconcile
- [ ] DTO: CreatePaymentDto (amount, payment_date, payment_method, journal_id, partner_id, payment_type)
- [ ] DTO: ReconcilePaymentDto (invoice_ids, amounts)
- [ ] Service: PaymentService.create()
- [ ] Service: PaymentService.generateJournalEntry()
- [ ] Service: PaymentService.reconcile()
- [ ] Actualizar invoice.state según amount_residual
- [ ] Crear payment_invoice_reconciliations
- [ ] Unit tests (12 test cases)
- [ ] Integration tests (10 test cases)

### Frontend
- [ ] CreatePaymentPage.tsx (inbound)
- [ ] CreatePaymentForm.tsx
- [ ] ReconcilePaymentModal.tsx (seleccionar facturas)
- [ ] Campo: payment_method (select: cash, bank, card, check)
- [ ] API client: paymentApi.create(), paymentApi.reconcile()
- [ ] E2E test: "register inbound payment and reconcile"

### Database
- [ ] Tabla: financial.payments (payment_type enum: 'inbound', 'outbound')
- [ ] Tabla: financial.payment_invoice_reconciliations (payment_id, invoice_id, amount)
- [ ] Campo: invoices.amount_residual (total - sum(reconciliations))
- [ ] Índices: idx_payments_partner_id, idx_payments_date, idx_payments_type

---

## Mockups / Wireframes

**Formulario Registrar Pago Recibido:**
```
┌────────────────────────────────────┐
│ Cliente: [Select Customer] ▼      │
│ Monto: [1210____]                  │
│ Fecha: [2024-01-20] (date)         │
│ Método: [Transferencia] ▼          │
│ Cuenta Bancaria: [Banco Santander]│
│ Referencia: [TRF-12345] (opcional)│
│ [Guardar] [Guardar y Conciliar]   │
└────────────────────────────────────┘
```

**Modal Conciliar Pago:**
```
┌────────────────────────────────────┐
│ Conciliar Pago: $1210              │
├────────────────────────────────────┤
│ Facturas Pendientes:               │
│ ☑ INV/2024/001 | $1210 | Venc: ... │
│ ☐ INV/2024/015 | $500  | Venc: ... │
│                                    │
│ Total a Conciliar: $1210           │
│ Remanente: $0                      │
│ [Cancelar] [Confirmar]             │
└────────────────────────────────────┘
```

---

## Casos de Prueba

1. **TC-001:** Registrar pago inbound exitosamente
2. **TC-002:** Generar asiento con débito banco, crédito receivables
3. **TC-003:** Conciliar pago completo → factura paid
4. **TC-004:** Conciliar pago parcial → factura partial
5. **TC-005:** Conciliar con múltiples facturas
6. **TC-006:** Actualizar amount_residual correctamente
7. **TC-007:** Error por partner no customer
8. **TC-008:** Error por journal no bank/cash

---

## Dependencias

- **US bloqueantes:**
  - US-MGN-004-005-002 (Validar Factura Cliente)
  - US-MGN-004-002-001 (CRUD Journals)
- **Módulos:** MGN-003, MGN-004

---

## Estimación: 9 horas = 5 SP

---

## Definition of Done

- [ ] Código implementado
- [ ] Tests pasando (>80%)
- [ ] Asiento contable correcto
- [ ] Conciliación funciona
- [ ] Factura state actualizado
- [ ] Code review aprobado
- [ ] Merge a develop

---

## Referencias

- [RF-MGN-004-007](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-007-gestión-de-pagos-y-conciliación.md)
- [TRACEABILITY-MGN-004.yaml](../../02-modelado/trazabilidad/TRACEABILITY-MGN-004.yaml)