# US-MGN-004-004-002: Cálculo Automático de Impuestos en Facturas

**RF Asociado:** [RF-MGN-004-004](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-004-gestión-de-impuestos.md)
**Módulo:** MGN-004 - Financiero Básico
**Epic:** Impuestos
**Prioridad:** P0 (MVP)
**Story Points:** 3
**Sprint:** Sprint 9
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story

**Como** usuario de ventas o compras,
**Quiero** que el sistema calcule automáticamente los impuestos al agregar productos/servicios a facturas,
**Para** no tener que calcular manualmente los montos de impuestos.

---

## Descripción Detallada

Esta US implementa el cálculo automático de impuestos en facturas (customer invoices y vendor invoices). Al agregar una línea de factura con un producto/servicio que tiene impuestos asociados, el sistema:
- Identifica los impuestos configurados para ese producto
- Calcula el monto de impuesto según la tasa
- Actualiza los totales: subtotal, total_tax, total_amount
- Genera líneas de impuesto (tax_lines) vinculadas a la factura

---

## Criterios de Aceptación

### Escenario 1: Calcular IVA 21% en línea de factura
**Dado que** agrego una línea de factura con precio_unit=1000, quantity=1, tax_ids=["IVA 21%"],
**Cuando** el sistema calcula los impuestos,
**Entonces** se crea una tax_line con base=1000, tax_amount=210, tax_id="IVA 21%".

### Escenario 2: Múltiples impuestos en una línea
**Dado que** una línea tiene precio=1000 con impuestos ["IVA 21%", "IIBB 3%"],
**Cuando** calculo impuestos,
**Entonces** se crean 2 tax_lines: IVA=210, IIBB=30, total_tax=240.

### Escenario 3: Actualizar totales de factura
**Dado que** una factura tiene 2 líneas: L1 (base=1000, IVA 21%) y L2 (base=500, IVA 21%),
**Cuando** calculo totales,
**Entonces** subtotal=1500, total_tax=315, total_amount=1815.

### Escenario 4: Recalcular al cambiar cantidad
**Dado que** una línea tiene precio=100, quantity=10, IVA 21%,
**Cuando** cambio quantity=20,
**Entonces** base=2000, tax_amount=420, total_line=2420.

### Escenario 5: Impuestos no aplican si producto sin impuestos
**Dado que** un producto no tiene impuestos asociados,
**Cuando** agrego línea de ese producto,
**Entonces** NO se generan tax_lines, total_tax=0.

---

## Reglas de Negocio

- **RN-1:** Base imponible = precio_unit * quantity * (1 - discount/100).
- **RN-2:** Tax_amount = base * (tax_rate / 100).
- **RN-3:** Total_line = base + sum(tax_amounts).
- **RN-4:** Subtotal factura = sum(líneas.base).
- **RN-5:** Total_tax factura = sum(tax_lines.tax_amount).
- **RN-6:** Total_amount factura = subtotal + total_tax.
- **RN-7:** Redondeo a 2 decimales para montos monetarios.
- **RN-8:** Recalcular totales al agregar/editar/eliminar líneas.

---

## Tareas Técnicas

### Backend
- [ ] Service: `InvoiceService.calculateLineTaxes(lineData)`
- [ ] Service: `InvoiceService.calculateInvoiceTotals(invoiceId)`
- [ ] Service: `TaxService.calculateTaxAmount(base, taxId)`
- [ ] Lógica: Calcular base imponible (precio * cantidad * (1 - descuento))
- [ ] Lógica: Generar tax_lines al guardar invoice_lines
- [ ] Lógica: Sumar tax_lines para total_tax
- [ ] Validar que impuestos pertenecen al tipo correcto (sale/purchase)
- [ ] Unit tests (8 test cases)
- [ ] Integration tests (5 test cases)

### Frontend
- [ ] Lógica: Calcular impuestos en tiempo real al editar línea
- [ ] Componente: `TaxCalculationSummary.tsx` (mostrar desglose impuestos)
- [ ] Mostrar totales: Subtotal, Impuestos, Total
- [ ] Actualizar totales dinámicamente al editar cantidad/precio
- [ ] Component test: Cálculo automático de IVA

### Database
- [ ] Tabla: `financial.invoice_tax_lines` (invoice_id, tax_id, base, tax_amount)
- [ ] Campos: `invoices.subtotal`, `invoices.total_tax`, `invoices.total_amount`
- [ ] Trigger: Recalcular totales al insertar/update invoice_lines

---

## Mockups / Wireframes

**Línea de Factura con Impuestos:**
```
┌────────────────────────────────────────────┐
│ Producto: MacBook Pro                      │
│ Precio: 1000  Cantidad: [2] UoM: Unidad    │
│ Impuestos: ☑ IVA 21%  ☑ IIBB 3%           │
│                                            │
│ Subtotal: 2,000.00                         │
│ IVA 21%:    420.00                         │
│ IIBB 3%:     60.00                         │
│ ──────────────────                         │
│ Total:    2,480.00                         │
└────────────────────────────────────────────┘
```

**Totales de Factura:**
```
┌────────────────────────────┐
│ Subtotal:     2,000.00     │
│ Impuestos:      480.00     │
│ ─────────────────────      │
│ TOTAL:        2,480.00     │
└────────────────────────────┘
```

---

## Casos de Prueba

### Funcionales
1. **TC-001:** Calcular IVA 21% sobre 1000 = 210
2. **TC-002:** Múltiples impuestos (IVA 21% + IIBB 3%)
3. **TC-003:** Actualizar totales de factura
4. **TC-004:** Recalcular al cambiar cantidad
5. **TC-005:** Sin impuestos si producto no los tiene
6. **TC-006:** Descuento aplica antes de impuestos
7. **TC-007:** Redondeo a 2 decimales

### No Funcionales
1. **Performance:** Cálculo instantáneo (<100ms)
2. **Precisión:** Redondeo correcto en montos

---

## Dependencias

- **US bloqueantes:**
  - US-MGN-004-004-001 (CRUD Impuestos)
  - US-MGN-004-005-001 (Crear Factura Cliente - siguiente US)
- **Módulos:** MGN-004

---

## Estimación Detallada

| Tarea | Estimación |
|-------|------------|
| Backend | 2 horas |
| Frontend | 2 horas |
| Testing | 1.5 horas |
| Code Review | 0.5 hora |
| **TOTAL** | **6 horas = 3 SP** |

---

## Definition of Done

- [ ] Código implementado
- [ ] Tests pasando (>80%)
- [ ] Cálculos precisos (redondeo 2 decimales)
- [ ] Recálculo dinámico funciona
- [ ] Code review aprobado
- [ ] Merge a develop
- [ ] QA validado

---

## Referencias

- [RF-MGN-004-004](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-004-gestión-de-impuestos.md)
- [TRACEABILITY-MGN-004.yaml](../../02-modelado/trazabilidad/TRACEABILITY-MGN-004.yaml)
- [Financial Schema DDL](../../02-modelado/database-design/schemas/financial-schema-ddl.sql)