erp-retail/docs/08-epicas/EPIC-RT-007-caja.md

# EPICA: EPIC-RT-007 - Caja (Arqueos y Cortes)

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-RT-007 |
| **Nombre** | Caja (Arqueos y Cortes) |
| **Modulo** | caja |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 28 |
| **Sprint(s)** | Sprint 5-6 |

---

## Descripcion

Módulo 100% nuevo para control de efectivo en tiendas. Gestión de fondos de caja, arqueos, cortes de caja, movimientos de efectivo (retiros, depósitos) y conciliación con ventas. Control de diferencias y auditoría.

---

## Objetivo de Negocio

- Control preciso de efectivo
- Prevenir faltantes y robos
- Conciliación diaria de ventas
- Auditoría de movimientos
- Responsabilidad por cajero

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-RT007-001 | Como supervisor, quiero abrir caja con fondo inicial para comenzar turno | P0 | 3 | Backlog |
| US-RT007-002 | Como cajero, quiero registrar retiro de efectivo (para depósito) | P0 | 3 | Backlog |
| US-RT007-003 | Como cajero, quiero registrar ingreso de efectivo (cambio) | P0 | 2 | Backlog |
| US-RT007-004 | Como cajero, quiero realizar arqueo parcial sin cerrar caja | P0 | 3 | Backlog |
| US-RT007-005 | Como cajero, quiero realizar corte de caja al final del turno | P0 | 5 | Backlog |
| US-RT007-006 | Como cajero, quiero declarar efectivo contado por denominación | P0 | 3 | Backlog |
| US-RT007-007 | Como supervisor, quiero aprobar corte con diferencias | P0 | 3 | Backlog |
| US-RT007-008 | Como gerente, quiero ver reporte de diferencias por cajero | P1 | 3 | Backlog |
| US-RT007-009 | Como admin, quiero configurar tolerancia de diferencias | P2 | 2 | Backlog |
| US-RT007-010 | Como auditor, quiero ver historial completo de movimientos de caja | P1 | 1 | Backlog |

**Total Story Points:** 28 SP

---

## Flujo de Caja

```
┌─────────────┐
│   CERRADA   │  ← Estado inicial
└──────┬──────┘
       │
       ▼ (Apertura con fondo)
┌─────────────┐
│   ABIERTA   │ ◄──────────┐
└──────┬──────┘            │
       │                   │
       ▼                   │
┌─────────────┐            │
│  OPERANDO   │────────────┤
│             │   Ventas   │
│  + Ventas   │   Retiros  │
│  - Retiros  │   Ingresos │
│  + Ingresos │            │
└──────┬──────┘            │
       │                   │
       ▼ (Corte)           │
┌─────────────┐            │
│   CORTE     │            │
│  - Conteo   │            │
│  - Diferenc │            │
└──────┬──────┘            │
       │                   │
       ├──── Si OK ────────┘ (Nueva apertura)
       │
       ▼ (Cierre)
┌─────────────┐
│   CERRADA   │
└─────────────┘
```

---

## Conteo por Denominación

```
┌─────────────────────────────────────────────────────────┐
│              DECLARACIÓN DE EFECTIVO                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  BILLETES                        MONEDAS                │
│  ┌────────┬─────┬──────────┐    ┌────────┬─────┬─────┐ │
│  │ Denom. │ Cant│   Total  │    │ Denom. │ Cant│Total│ │
│  ├────────┼─────┼──────────┤    ├────────┼─────┼─────┤ │
│  │ $1000  │  3  │  $3,000  │    │ $20    │  5  │$100 │ │
│  │ $500   │  5  │  $2,500  │    │ $10    │  8  │ $80 │ │
│  │ $200   │  8  │  $1,600  │    │ $5     │ 10  │ $50 │ │
│  │ $100   │ 12  │  $1,200  │    │ $2     │ 15  │ $30 │ │
│  │ $50    │ 10  │    $500  │    │ $1     │ 20  │ $20 │ │
│  │ $20    │ 15  │    $300  │    │ $0.50  │ 10  │  $5 │ │
│  └────────┴─────┴──────────┘    └────────┴─────┴─────┘ │
│                                                         │
│  TOTAL BILLETES: $9,100                                 │
│  TOTAL MONEDAS:    $285                                 │
│  ─────────────────────────                              │
│  TOTAL DECLARADO: $9,385                                │
│                                                         │
│  ESPERADO (sistema): $9,400                             │
│  DIFERENCIA:           -$15                             │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Apertura de caja con fondo
- [ ] Retiros e ingresos de efectivo
- [ ] Arqueos parciales
- [ ] Corte de caja con conteo
- [ ] Declaración por denominación
- [ ] Cálculo de diferencias
- [ ] Aprobación de cortes con diferencias
- [ ] Reportes de diferencias

**No Funcionales:**
- [ ] Operación < 3 clicks
- [ ] Historial de 1 año
- [ ] Auditoría completa

**Tecnicos:**
- [ ] Integración con módulo POS (ventas en efectivo)
- [ ] Bloqueo de caja durante corte
- [ ] Firmas/autorizaciones de supervisores

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-RT-001 Fundamentos | Backlog | Si |
| EPIC-RT-002 POS | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-RT-008 Reportes | Datos de caja para reportes |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `cash_register`
- [ ] Tablas: 6 (cash_sessions, cash_movements, cash_counts, count_denominations, cut_approvals, audit_log)
- [ ] Funciones: 3 (calculate_expected, calculate_difference, validate_cut)
- [ ] Indices: Por caja, cajero, fecha, estado

**Backend:**
- [ ] Modulo: `cash-register`
- [ ] Entities: 5 (CashSession, CashMovement, CashCount, CountDenomination, CutApproval)
- [ ] Endpoints: 12
- [ ] Tests: 25

**Frontend:**
- [ ] Paginas: 4 (CashDashboard, OpenClose, CashCount, Reports)
- [ ] Componentes: 10 (DenominationCounter, MovementForm, DifferenceAlert, etc.)
- [ ] Stores: 1 (cashStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/cash/sessions/open | Abrir caja |
| POST | /api/cash/sessions/:id/close | Cerrar caja |
| GET | /api/cash/sessions/current | Sesión actual |
| POST | /api/cash/movements | Registrar movimiento |
| POST | /api/cash/counts | Registrar arqueo |
| POST | /api/cash/counts/:id/denominations | Agregar denominaciones |
| POST | /api/cash/counts/:id/submit | Enviar para aprobación |
| POST | /api/cash/counts/:id/approve | Aprobar corte |
| GET | /api/cash/reports/differences | Reporte de diferencias |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Faltantes de efectivo | Media | Alto | Arqueos frecuentes |
| Manipulación de cortes | Baja | Alto | Doble aprobación |
| Errores de conteo | Media | Medio | Conteo por denominación |

---

## Nota Técnica

Este módulo es **100% nuevo** y no tiene equivalente en el ERP-Core. Es específico para operaciones de retail con manejo de efectivo.

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Denominaciones locales definidas
- [ ] Tolerancias de diferencia aprobadas

## Definition of Done (DoD)

- [ ] Flujo de apertura/cierre funcionando
- [ ] Conteo por denominación operativo
- [ ] Cálculo de diferencias correcto
- [ ] Reportes de auditoría
- [ ] Tests de integración pasando
- [ ] Documentación de API

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-08 | Creacion de epica | Claude-Agent |

---

**Creada por:** Claude-Agent
**Fecha:** 2025-12-08
**Ultima actualizacion:** 2025-12-08