# EPICA: EPIC-MGN-005 - Catalogos Maestros

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-005 |
| **Nombre** | Catalogos Maestros |
| **Modulo** | catalogs |
| **Fase** | Fase 2 - Core Business |
| **Prioridad** | P1 |
| **Estado** | Backlog |
| **Story Points** | 34 |
| **Sprint(s)** | Sprint 4-5 |

---

## Descripcion

Sistema centralizado de catalogos maestros que incluye paises, estados, monedas, tipos de cambio, unidades de medida, categorias genericas e impuestos base. Estos catalogos son la base de datos referencial que utilizan todos los demas modulos del sistema.

Incluye gestion de Partners (clientes/proveedores) y Products (productos/servicios).

---

## Objetivo de Negocio

Proveer catalogos maestros unificados que:
- Estandaricen datos entre modulos
- Reduzcan duplicidad de informacion
- Faciliten integracion con sistemas externos
- Soporten operaciones multi-pais

---

## Stakeholders

| Rol | Nombre/Equipo | Responsabilidad |
|-----|---------------|-----------------|
| Product Owner | Equipo Producto | Definicion de catalogos |
| Tech Lead | Equipo Backend | Estructura de datos |
| Usuarios | Operaciones | Uso de catalogos |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN005-001 | Como admin, quiero gestionar el catalogo de paises y estados | P0 | 3 | Backlog |
| US-MGN005-002 | Como admin, quiero gestionar monedas y tipos de cambio | P0 | 5 | Backlog |
| US-MGN005-003 | Como admin, quiero gestionar unidades de medida | P0 | 3 | Backlog |
| US-MGN005-004 | Como usuario, quiero gestionar categorias de productos | P0 | 3 | Backlog |
| US-MGN005-005 | Como admin, quiero configurar impuestos base (IVA, ISR) | P0 | 5 | Backlog |
| US-MGN005-006 | Como usuario, quiero crear y gestionar partners (clientes/proveedores) | P0 | 8 | Backlog |
| US-MGN005-007 | Como usuario, quiero crear y gestionar productos/servicios | P0 | 8 | Backlog |

**Total Story Points:** 35 SP (ajustado a 34)

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] CRUD de paises, estados, ciudades
- [ ] CRUD de monedas con tipos de cambio historicos
- [ ] CRUD de unidades de medida con conversiones
- [ ] Categorias jerarquicas para productos
- [ ] Configuracion de impuestos por pais
- [ ] Partners con direcciones multiples
- [ ] Productos con variantes

**No Funcionales:**
- [ ] Performance: Consultas de catalogos < 50ms
- [ ] Datos precargados para paises principales
- [ ] Sincronizacion con fuentes externas (SAT, Banxico)

**Tecnicos:**
- [ ] Cobertura de tests > 80%
- [ ] Seeders para datos iniciales
- [ ] Cache de catalogos frecuentes

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MGN-004 Tenants | Ready | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-MGN-010 Financial | Monedas, impuestos |
| EPIC-MGN-011 Inventory | Productos, UoM |
| EPIC-MGN-012 Purchasing | Partners, productos |
| EPIC-MGN-013 Sales | Partners, productos |
| EPIC-MGN-014 CRM | Partners |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `core_catalogs`
- [ ] Tablas: 15+ (countries, states, currencies, uom, categories, taxes, partners, products, etc.)
- [ ] Funciones: 3 (convertir_moneda, convertir_uom, calcular_impuesto)
- [ ] RLS Policies: Mixto (catalogos globales + datos por tenant)

**Backend:**
- [ ] Modulo: `catalogs`
- [ ] Submodulos: geo, currencies, uom, categories, taxes, partners, products
- [ ] Entities: 15+
- [ ] Endpoints: 40+
- [ ] Tests: 60+

**Frontend:**
- [ ] Paginas: 8 (catalogos varios)
- [ ] Componentes: 20+ (selectores, formularios, tablas)
- [ ] Stores: 3 (catalogsStore, partnersStore, productsStore)

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Volumen de datos iniciales | Media | Medio | Seeders optimizados, carga diferida |
| Sincronizacion con SAT | Media | Alto | API tolerante a fallos, cache |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Estructura de catalogos aprobada
- [x] Sin bloqueadores activos

## Definition of Done (DoD)

- [ ] Codigo implementado y revisado
- [ ] Tests pasando
- [ ] Seeders ejecutados
- [ ] Documentacion actualizada
- [ ] Demo realizada
- [ ] Product Owner aprobo

---

## Documentacion Relacionada

- Requerimientos: `docs/03-requerimientos/RF-catalogs/`
- User Stories: `docs/05-user-stories/MGN-005/`
- DDL Spec: `docs/04-modelado/database-design/DDL-SPEC-core_catalogs.md`

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05