# US-MGN-004-005-001: Crear Factura de Cliente (Draft)

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

---

## User Story

**Como** usuario de ventas,
**Quiero** crear facturas de cliente en estado borrador con líneas y calcular impuestos automáticamente,
**Para** facturar ventas a mis clientes antes de validar y contabilizar.

---

## Descripción Detallada

Factura de cliente es un documento que registra una venta. Estados: draft (borrador), open (abierta/contabilizada), paid (pagada), cancelled (cancelada). En estado draft se puede editar libremente. Al validar se genera asiento contable automático.

---

## Criterios de Aceptación

### Escenario 1: Crear factura draft exitosamente
**Dado que** soy usuario ventas,
**Cuando** creo factura con partner_id, invoice_date="2024-01-15", líneas con productos e impuestos,
**Entonces** sistema crea factura state='draft', calcula totals (subtotal, taxes, total), retorna id y número.

### Escenario 2: Validar partner es cliente
**Dado que** partner_id no es tipo "customer",
**Cuando** creo factura,
**Entonces** error 400 "Partner debe ser tipo cliente".

### Escenario 3: Generar número de factura
**Dado que** journal "Ventas" tiene secuencia "INV/{year}/{seq}",
**Cuando** creo factura,
**Entonces** número generado automáticamente "INV/2024/0001".

### Escenario 4: Calcular totales automáticamente
**Dado que** líneas: L1 (1000, IVA 21%), L2 (500, IVA 21%),
**Cuando** guardo factura,
**Entonces** subtotal=1500, total_tax=315, total_amount=1815.

### Escenario 5: Permitir múltiples líneas
**Dado que** agrego 5 líneas de productos,
**Cuando** todas tienen impuestos configurados,
**Entonces** factura se crea con 5 invoice_lines y sus tax_lines correspondientes.

---

## Reglas de Negocio

- **RN-1:** type='out_invoice' para facturas de cliente.
- **RN-2:** Estado inicial es 'draft'.
- **RN-3:** Partner debe ser tipo customer o both.
- **RN-4:** Fecha de factura no puede ser futura.
- **RN-5:** Al menos 1 línea requerida.
- **RN-6:** Impuestos se calculan automáticamente por línea.
- **RN-7:** Número se genera automáticamente al guardar.
- **RN-8:** RLS filtra por company_id.

---

## Tareas Técnicas

### Backend
- [ ] POST /api/v1/financial/customer-invoices
- [ ] Service: CustomerInvoiceService.create()
- [ ] DTO: CreateCustomerInvoiceDto (partner_id, date, lines, payment_term_id)
- [ ] DTO: InvoiceLineDto (product_id, quantity, price_unit, tax_ids, discount)
- [ ] Validar partner es customer
- [ ] Generar número secuencial
- [ ] Calcular totales (subtotal, taxes, total)
- [ ] Crear invoice_lines y tax_lines
- [ ] Unit tests (10 test cases)
- [ ] Integration tests (8 test cases)

### Frontend
- [ ] Página: CreateCustomerInvoicePage.tsx
- [ ] Componente: CreateCustomerInvoiceForm.tsx
- [ ] Componente: InvoiceLineItems.tsx (tabla editable)
- [ ] Componente: InvoiceTotalsSummary.tsx
- [ ] API client: customerInvoiceApi.create()
- [ ] Store: useCustomerInvoiceStore.ts
- [ ] Component tests (6 test cases)
- [ ] E2E test: "should create customer invoice"

### Database
- [ ] Tabla: financial.invoices (type='out_invoice')
- [ ] Tabla: financial.invoice_lines
- [ ] Tabla: financial.invoice_tax_lines
- [ ] Índices: idx_invoices_partner_id, idx_invoices_date, idx_invoices_state
- [ ] RLS policy: company_isolation_invoices

---

## Mockups / Wireframes

**Formulario Crear Factura:**
```
┌─────────────────────────────────────┐
│ Cliente: [Select Partner] ▼        │
│ Fecha: [2024-01-15] (date picker)  │
│ Condiciones Pago: [30 días] ▼      │
│ Referencia: [SO001] (opcional)     │
├─────────────────────────────────────┤
│ Líneas:                             │
│ [Producto][Cantidad][Precio][Imp.] │
│ [MacBook]   [2]   [1000] [IVA 21%] │
│ [+ Agregar Línea]                   │
├─────────────────────────────────────┤
│ Subtotal:    2,000.00               │
│ Impuestos:     420.00               │
│ TOTAL:       2,420.00               │
├─────────────────────────────────────┤
│ [Guardar Borrador] [Cancelar]      │
└─────────────────────────────────────┘
```

---

## Casos de Prueba

1. **TC-001:** Crear factura draft exitosamente
2. **TC-002:** Error por partner no cliente
3. **TC-003:** Generar número secuencial
4. **TC-004:** Calcular totales correctamente
5. **TC-005:** Crear con múltiples líneas
6. **TC-006:** Error por fecha futura
7. **TC-007:** RLS filtra por empresa

---

## Dependencias

- **US bloqueantes:**
  - US-MGN-003-001-001 (CRUD Partners)
  - US-MGN-004-002-001 (CRUD Journals)
  - US-MGN-004-004-002 (Cálculo Impuestos)
- **Módulos:** MGN-003, MGN-004

---

## Estimación: 9 horas = 5 SP

---

## Definition of Done

- [ ] Código implementado
- [ ] Tests pasando (>80%)
- [ ] Totales calculan correctamente
- [ ] Número generado automáticamente
- [ ] Code review aprobado
- [ ] Merge a develop
- [ ] QA validado

---

## Referencias

- [RF-MGN-004-005](../../02-modelado/requerimientos-funcionales/mgn-004/RF-MGN-004-005-gestión-de-facturas-de-cliente.md)
- [ET-BACKEND-MGN-004-005](../../02-modelado/especificaciones-tecnicas/backend/mgn-004/ET-BACKEND-MGN-004-005-gestión-de-facturas-de-cliente.md)
- [TRACEABILITY-MGN-004.yaml](../../02-modelado/trazabilidad/TRACEABILITY-MGN-004.yaml)