erp-core/docs/02-definicion-modulos/ALCANCE-POR-MODULO.md

# ALCANCE DETALLADO POR MÓDULO

**Fecha:** 2025-11-23
**Versión:** 1.0
**Basado en:** LISTA-MODULOS-ERP-GENERICO.md + Análisis Fase 0

---

## Introducción

Este documento define el alcance detallado de cada uno de los 14 módulos del ERP Genérico.

**Objetivo:** Establecer claramente qué incluye y qué NO incluye cada módulo para evitar:
- Scope creep (agregar funcionalidades innecesarias)
- Over-engineering (generalizar lo que debe ser específico)
- Conflictos entre módulos (límites difusos)

**Metodología:**
- ✅ **Incluido:** Funcionalidades que son genéricas y reutilizables en 70%+ de proyectos
- ❌ **Excluido:** Funcionalidades específicas de industria (construcción, vidrio, etc.)
- 🔧 **Límites:** Dónde termina un módulo y empieza otro

---

## MGN-001: Fundamentos

### Descripción

Módulo base que proporciona autenticación, autorización, gestión de usuarios y multi-tenancy. Es la columna vertebral de seguridad del ERP.

### Alcance Incluido (✅ Dentro del Alcance)

**Autenticación:**
- Login con email/password
- Generación de JWT tokens (access token + refresh token)
- Logout (invalidación de tokens)
- Registro de usuarios (signup) con validación de email
- Reset password (envío de token por email, expiración 24h)
- Cambio de contraseña (validación de contraseña fuerte: 8+ chars, mayúsculas, números, símbolos)
- Verificación de email (token de verificación)
- Política de contraseñas (longitud mínima, complejidad, expiración)

**Gestión de Usuarios:**
- CRUD de usuarios (create, read, update, soft delete)
- Perfiles de usuario (nombre, email, teléfono, foto, idioma preferido)
- Activación/desactivación de usuarios (active=true/false)
- Asignación de roles a usuarios (muchos a muchos)
- Historial de sesiones (last login, login count, IPs)

**Roles y Permisos (RBAC):**
- CRUD de roles (Administrator, Accountant, Supervisor, etc.)
- Permisos granulares CRUD por modelo (create, read, update, delete)
- Herencia de roles (ej: Supervisor hereda permisos de Employee)
- Permisos por campo (field-level permissions - opcional P1)
- Record Rules (RLS policies) - Filtros SQL dinámicos por rol

**Multi-Tenancy:**
- Schema-level isolation (cada tenant un schema PostgreSQL)
- Context switching (cambio de tenant por request)
- Función `get_current_tenant_id()` para RLS
- Validación de acceso cruzado entre tenants (estrictamente prohibido)

**Seguridad:**
- Hash de contraseñas (bcrypt, 10 rounds)
- Rate limiting (login attempts: 5 intentos/15min)
- Session management (tokens con expiración)
- CORS configuration
- Helmet.js (security headers)

### Alcance Excluido (❌ Fuera del Alcance)

**Autenticación Avanzada:**
- ❌ Login con OAuth2/OIDC (Google, Facebook, Azure AD) - **Razón:** No es esencial para MVP, se puede agregar después (P2)
- ❌ Autenticación de dos factores (2FA/MFA) - **Razón:** Importante, pero no crítico para inicio (P1)
- ❌ Biometría (huella, Face ID) - **Razón:** Específico de mobile (P2)
- ❌ SSO (Single Sign-On) - **Razón:** Empresarial avanzado (P2)

**Gestión de Usuarios Avanzada:**
- ❌ Delegación de permisos (usuario A delega a usuario B temporalmente) - **Razón:** Caso de uso específico (P2)
- ❌ Grupos de usuarios (además de roles) - **Razón:** Los roles son suficientes para MVP
- ❌ Aprobaciones workflow (aprobar creación de usuarios) - **Razón:** Overhead innecesario para inicio

**Multi-Tenancy Avanzado:**
- ❌ Database-level isolation (cada tenant una DB) - **Razón:** Schema-level es suficiente y más eficiente
- ❌ Tenants con custom domains - **Razón:** Complejidad infraestructura (P2)

### Límites con Otros Módulos

**Con MGN-002 (Empresas):**
- **MGN-001 termina:** Gestión de usuarios y roles
- **MGN-002 empieza:** Gestión de empresas/organizaciones (users pueden acceder a múltiples empresas)
- **Límite:** Usuario puede tener un rol diferente en cada empresa

**Con MGN-014 (Mensajería):**
- **MGN-001 termina:** Autenticación de usuarios
- **MGN-014 empieza:** Notificaciones a usuarios, mensajes
- **Límite:** MGN-001 provee el contexto de usuario actual, MGN-014 lo usa para notificar

### Casos de Uso Principales

1. **UC-AUTH-001:** Usuario se registra en el sistema
2. **UC-AUTH-002:** Usuario inicia sesión
3. **UC-AUTH-003:** Usuario solicita reset de contraseña
4. **UC-AUTH-004:** Administrador crea un nuevo usuario
5. **UC-AUTH-005:** Administrador asigna roles a usuario
6. **UC-AUTH-006:** Administrador define permisos de un rol
7. **UC-AUTH-007:** Sistema valida permisos de usuario para acción (CRUD)
8. **UC-AUTH-008:** Sistema cambia de tenant (multi-tenancy)

### Actores

- **Administrador:** Gestiona usuarios, roles, permisos
- **Usuario:** Se autentica, usa el sistema
- **Sistema:** Valida permisos automáticamente

### Referencias

- **Odoo:** base (res.users, res.groups, ir.model.access, ir.rule)
- **Gamilit:** auth_management schema
- **ADR:** ADR-001 (Stack), ADR-003 (Multi-Tenancy), ADR-006 (RBAC)

---

## MGN-002: Empresas y Organizaciones

### Descripción

Módulo que gestiona empresas/organizaciones y configuración multi-empresa. Permite que usuarios trabajen con múltiples empresas y que documentos pertenezcan a empresas específicas.

### Alcance Incluido (✅ Dentro del Alcance)

**Gestión de Empresas:**
- CRUD de empresas (create, read, update, soft delete)
- Datos de empresa: nombre, nombre legal, RFC/NIT/Tax ID, logo, email, teléfono, sitio web
- Dirección de empresa (calle, ciudad, estado, país, código postal)
- Configuración fiscal (régimen fiscal, responsabilidades tributarias)
- Moneda principal de la empresa
- Empresa vinculada a partner (patrón Odoo: una empresa también es un partner)

**Multi-Empresa:**
- Usuario puede tener acceso a múltiples empresas (tabla de asignación users_companies)
- Usuario puede tener roles diferentes en cada empresa
- Context switching: cambiar empresa activa sin logout
- Filtrado automático de datos por empresa (RLS)
- Validación de acceso cruzado entre empresas (un usuario no puede ver datos de empresa sin acceso)

**Jerarquías Organizacionales:**
- Holdings (parent_id): una empresa puede ser parte de un grupo
- Visualización de organigrama de empresas (árbol jerárquico)

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Consolidación financiera (balance consolidado de holdings) - **Razón:** Funcionalidad contable avanzada, va en MGN-004 o extensión (P2)
- ❌ Transferencias inter-compañía automáticas - **Razón:** Complejidad contable, no esencial para MVP (P2)
- ❌ Configuración de permisos cruzados entre empresas - **Razón:** Caso de uso específico, no genérico
- ❌ Unidades de negocio (Business Units) dentro de empresa - **Razón:** Puede modelarse con departamentos en MGN-010

**Específico de Industria:**
- ❌ Sucursales con inventario independiente - **Razón:** Es lógica de inventario (MGN-005)
- ❌ Centros de costos - **Razón:** Es lógica de contabilidad analítica (MGN-008)

### Límites con Otros Módulos

**Con MGN-001 (Fundamentos):**
- **MGN-001 termina:** Usuarios y roles
- **MGN-002 empieza:** Empresas y asignación usuario-empresa
- **Límite:** Un usuario puede tener rol diferente en cada empresa

**Con MGN-003 (Catálogos):**
- **MGN-002 termina:** Datos de empresa
- **MGN-003 empieza:** Partners (empresa también es un partner)
- **Límite:** Empresa tiene relación con partner (company.partner_id)

**Con MGN-004, MGN-005, MGN-006, MGN-007 (Módulos Transaccionales):**
- **MGN-002 termina:** Definición de empresa
- **Módulos transaccionales empiezan:** Documentos (facturas, órdenes, etc.) con company_id
- **Límite:** Todos los documentos deben tener company_id (FK a companies)

### Casos de Uso Principales

1. **UC-COMP-001:** Administrador crea una nueva empresa
2. **UC-COMP-002:** Administrador configura datos fiscales de empresa
3. **UC-COMP-003:** Administrador asigna usuarios a empresa
4. **UC-COMP-004:** Usuario cambia de empresa activa (context switching)
5. **UC-COMP-005:** Usuario con acceso a múltiples empresas ve lista de empresas permitidas
6. **UC-COMP-006:** Administrador crea holding (jerarquía de empresas)

### Actores

- **Administrador:** Gestiona empresas, configuración
- **Usuario Multi-Empresa:** Trabaja con varias empresas
- **Sistema:** Filtra datos por empresa automáticamente

### Referencias

- **Odoo:** base (res.company)
- **Gamilit:** core schema (companies table)
- **ADR:** ADR-002 (Arquitectura Modular), ADR-003 (Multi-Tenancy)

---

## MGN-003: Catálogos Maestros

### Descripción

Módulo que gestiona catálogos maestros universales: partners, países, monedas, unidades de medida, categorías de productos. Son datos de referencia compartidos por todos los módulos transaccionales.

### Alcance Incluido (✅ Dentro del Alcance)

**Partners Universales:**
- CRUD de partners (patrón Odoo: un partner puede ser cliente, proveedor, empleado, contacto)
- Flags: is_customer, is_supplier, is_employee, is_contact
- Datos generales: nombre, nombre legal, email, teléfono, sitio web
- Dirección (calle, ciudad, estado, país, código postal)
- Datos fiscales (Tax ID, régimen fiscal)
- Jerarquía (parent_id): un partner puede tener contactos hijos
- Condiciones de pago (payment terms)
- Calificación de partner (customer rank, supplier rank)

**Países y Regiones:**
- Catálogo de países (ISO 3166-1: código 2 letras, código 3 letras, código numérico)
- Estados/Provincias por país
- Ciudades (opcional, puede ser texto libre)
- Códigos postales
- Formatos de dirección por país (ej: USA → ZIP, México → CP)

**Monedas:**
- Catálogo de monedas (ISO 4217: USD, MXN, EUR, etc.)
- Tasas de cambio (con vigencia temporal: fecha inicio, fecha fin)
- Actualización manual de tasas (en MVP, automática en P1)
- Moneda de visualización vs moneda de registro

**Unidades de Medida (UoM):**
- Categorías de UoM (longitud, peso, volumen, tiempo, unidades)
- UoM por categoría (kg, g, ton / m, cm, km / L, mL / etc.)
- Factor de conversión (ej: 1 kg = 1000 g)
- UoM de referencia por categoría
- Conversiones automáticas dentro de categoría

**Categorías de Productos:**
- Jerarquía de categorías (parent_id)
- Categorías genéricas (materiales, servicios, etc.)
- Asignación de cuenta contable por categoría (opcional, integración con MGN-004)

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ CRM avanzado de partners (scoring, segmentación) - **Razón:** Va en MGN-009 (CRM)
- ❌ Portal de proveedores/clientes - **Razón:** Va en MGN-013 (Portal)
- ❌ Actualización automática de tasas de cambio (API externa) - **Razón:** No esencial para MVP (P1)
- ❌ Conversiones de UoM entre categorías - **Razón:** No tiene sentido (kg a metros)
- ❌ UoM compuestas (kg/m², m³/h) - **Razón:** Complejidad innecesaria (P2)

**Específico de Industria:**
- ❌ Partners con clasificación por industria (construcción, vidrio, etc.) - **Razón:** Específico de proyecto
- ❌ Catálogo de productos - **Razón:** Va en MGN-005 (Inventario), aquí solo categorías

### Límites con Otros Módulos

**Con MGN-002 (Empresas):**
- **MGN-002 termina:** Empresa
- **MGN-003 empieza:** Empresa también es un partner (company.partner_id)
- **Límite:** Empresa tiene relación 1-1 con partner

**Con MGN-004 (Financiero):**
- **MGN-003 termina:** Partners, monedas
- **MGN-004 empieza:** Facturas a partners, asientos con moneda
- **Límite:** MGN-003 provee catálogos, MGN-004 los usa

**Con MGN-005 (Inventario):**
- **MGN-003 termina:** Categorías de productos, UoM
- **MGN-005 empieza:** Productos (con categoría y UoM)
- **Límite:** MGN-003 provee categorías y UoM, MGN-005 crea productos

**Con MGN-006 (Compras) y MGN-007 (Ventas):**
- **MGN-003 termina:** Partners (proveedores, clientes)
- **MGN-006/007 empiezan:** Órdenes con partners
- **Límite:** MGN-003 gestiona partners, MGN-006/007 crean transacciones

### Casos de Uso Principales

1. **UC-CAT-001:** Usuario crea un nuevo cliente/proveedor (partner)
2. **UC-CAT-002:** Usuario busca un partner por nombre/email/Tax ID
3. **UC-CAT-003:** Usuario configura condiciones de pago de partner
4. **UC-CAT-004:** Administrador actualiza tasas de cambio de monedas
5. **UC-CAT-005:** Usuario convierte cantidades entre UoM (kg a g)
6. **UC-CAT-006:** Administrador crea jerarquía de categorías de productos
7. **UC-CAT-007:** Usuario agrega contactos a un partner (parent_id)

### Actores

- **Administrador:** Configura catálogos maestros
- **Usuario Ventas:** Gestiona clientes (partners con is_customer=true)
- **Usuario Compras:** Gestiona proveedores (partners con is_supplier=true)
- **Usuario RRHH:** Gestiona empleados (partners con is_employee=true)
- **Sistema:** Usa catálogos para validaciones y conversiones

### Referencias

- **Odoo:** base (res.partner, res.country, res.currency, uom.uom)
- **Gamilit:** core schema (partners, currencies, countries)
- **ADR:** ADR-007 (Database Design)

---

## MGN-004: Financiero Básico

### Descripción

Módulo de contabilidad general. Gestiona plan de cuentas, asientos contables, facturas, pagos, conciliación y reportes financieros básicos.

### Alcance Incluido (✅ Dentro del Alcance)

**Plan de Cuentas:**
- CRUD de cuentas contables (activo, pasivo, capital, ingresos, egresos)
- Jerarquía de cuentas (parent_id)
- Tipos de cuenta (view, payable, receivable, bank, cash, etc.)
- Código de cuenta (numérico o alfanumérico)
- Cuentas específicas por empresa (multi-empresa)
- Templates de plan de cuentas por país (México, USA)

**Asientos Contables:**
- Creación de asientos (journal entries) con líneas (débito/crédito)
- Validación débito = crédito (fundamental)
- Estados: draft → posted (no editable después de posted)
- Cancelación de asientos (reversing entry)
- Asientos por journal (ventas, compras, banco, misceláneos)
- Fecha de asiento vs fecha de registro
- Asientos automáticos desde módulos transaccionales (facturas, pagos)

**Facturas:**
- Facturas de cliente (customer invoices)
- Facturas de proveedor (vendor bills)
- Notas de crédito (credit notes)
- Estados: draft → open → paid → cancelled
- Líneas de factura (productos/servicios, cantidad, precio, impuestos)
- Cálculo automático de impuestos (IVA, retenciones)
- Generación automática de asientos contables al validar factura
- Multi-moneda (factura en USD, registro en MXN)

**Pagos:**
- Registro de pagos (customer payments, vendor payments)
- Métodos de pago (efectivo, transferencia, cheque, tarjeta)
- Pagos parciales
- Conciliación de pagos con facturas (payment reconciliation)
- Diferencias de pago (descuentos, redondeos)
- Pagos anticipados (advance payments)

**Reportes Financieros:**
- Balance General (Balance Sheet)
- Estado de Resultados (Profit & Loss / P&L)
- Filtros: por empresa, por fecha, por moneda
- Exportación: PDF, Excel

**Multi-Moneda:**
- Transacciones en moneda extranjera
- Conversión automática a moneda de empresa
- Gain/Loss por diferencia cambiaria
- Reportes en múltiples monedas

### Alcance Excluido (❌ Fuera del Alcance)

**Contabilidad Avanzada:**
- ❌ Presupuestos financieros - **Razón:** Va en módulo específico o MGN-012 (P2)
- ❌ Consolidación multi-empresa - **Razón:** Funcionalidad avanzada (P2)
- ❌ Flujo de caja (Cash Flow) - **Razón:** Reporte avanzado (P1)
- ❌ Activos fijos (depreciación) - **Razón:** Módulo especializado (P2)
- ❌ Nómina contable - **Razón:** Va en MGN-010 (RRHH)
- ❌ Facturación electrónica (CFDI México, e-invoicing) - **Razón:** Específico de país (extensión)

**Reportes Avanzados:**
- ❌ Reportes IFRS/GAAP específicos - **Razón:** Requiere consultoría contable (P2)
- ❌ Dashboards financieros - **Razón:** Va en MGN-012 (Reportes y Analytics)
- ❌ Análisis de varianzas - **Razón:** Reporte avanzado (P2)

**Integraciones:**
- ❌ Integración con SAT México (timbrado CFDI) - **Razón:** Específico de país (extensión)
- ❌ Integración con bancos (conciliación automática) - **Razón:** Requiere APIs bancarias (P1)

### Límites con Otros Módulos

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Partners, monedas
- **MGN-004 empieza:** Facturas a partners, conversión de monedas
- **Límite:** MGN-004 usa partners y monedas de MGN-003

**Con MGN-006 (Compras) y MGN-007 (Ventas):**
- **MGN-006/007 terminan:** Órdenes de compra/venta
- **MGN-004 empieza:** Facturas generadas desde órdenes, asientos contables
- **Límite:** Órdenes pueden generar facturas, pero la factura es documento contable (MGN-004)

**Con MGN-008 (Analítica):**
- **MGN-004 termina:** Asientos contables en plan de cuentas general
- **MGN-008 empieza:** Asientos con distribución analítica (por proyecto)
- **Límite:** MGN-004 registra contabilidad general, MGN-008 registra contabilidad analítica (paralela)

### Casos de Uso Principales

1. **UC-FIN-001:** Contador crea asiento contable manual
2. **UC-FIN-002:** Sistema genera asiento automático al validar factura de venta
3. **UC-FIN-003:** Usuario crea factura de cliente
4. **UC-FIN-004:** Usuario registra pago de cliente
5. **UC-FIN-005:** Usuario concilia pago con factura
6. **UC-FIN-006:** Contador genera Balance General
7. **UC-FIN-007:** Contador genera Estado de Resultados
8. **UC-FIN-008:** Usuario crea factura de proveedor en USD (empresa en MXN)

### Actores

- **Contador:** Gestiona plan de cuentas, asientos, reportes
- **Usuario Ventas:** Crea facturas de cliente
- **Usuario Compras:** Registra facturas de proveedor
- **Usuario Tesorería:** Registra pagos, concilia
- **Sistema:** Genera asientos automáticos, calcula impuestos

### Referencias

- **Odoo:** account (account.account, account.move, account.payment)
- **Gamilit:** financial_management schema
- **ADR:** ADR-007 (Database Design)

---

## MGN-005: Inventario Básico

### Descripción

Módulo de gestión de inventario. Maneja productos, almacenes, ubicaciones, movimientos de stock, trazabilidad y valoración de inventario.

### Alcance Incluido (✅ Dentro del Alcance)

**Productos:**
- CRUD de productos (bienes físicos y servicios)
- Tipos de producto: almacenable (storable), consumible (consumable), servicio (service)
- Datos de producto: nombre, descripción, código interno, código de barras
- Categoría de producto (FK a MGN-003)
- Unidad de medida (UoM) - FK a MGN-003
- Variantes de producto (producto con múltiples atributos: talla, color)
- Precio de costo (para valoración)
- Precio de venta (sugerido)

**Almacenes y Ubicaciones:**
- CRUD de almacenes (warehouses)
- Ubicaciones jerárquicas (warehouse → zone → aisle → rack → level)
- Tipos de ubicación: física, virtual (proveedores, clientes, producción, pérdidas)
- Ubicación por defecto por almacén
- Inventario por ubicación

**Movimientos de Stock:**
- Movimientos de stock (stock moves): origen → destino
- Estados: draft → confirmed → done → cancelled
- Cantidad movida, UoM
- Doble movimiento (origen → tránsito → destino) para movimientos complejos
- Movimientos automáticos desde órdenes de compra/venta
- Movimientos manuales (ajustes, transferencias)

**Pickings (Albaranes):**
- Agrupación de movimientos: picking de recepción, entrega, interno
- Estados: draft → ready → done
- Validación parcial (recibir parte de una orden)
- Impresión de albaranes (PDF)

**Trazabilidad:**
- Lotes (batch/lot): productos con fecha de lote (ej: lote de producción)
- Números de serie (serial numbers): productos con número único (ej: computadoras)
- Trazabilidad completa (de dónde vino, a dónde fue)

**Valoración de Inventario:**
- Métodos: FIFO (First In First Out), LIFO (Last In First Out), Costo Promedio
- Cálculo automático de costo de producto
- Asientos contables automáticos (si valoración automática activada)

**Inventario Físico:**
- Conteos de inventario (inventory adjustments)
- Diferencias entre conteo físico y sistema
- Generación de ajustes automáticos

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Producción/Manufactura (MRP) - **Razón:** Módulo independiente (P2)
- ❌ Kits/Bundles (productos compuestos) - **Razón:** Complejidad (P1)
- ❌ Rutas de inventario complejas (push/pull rules) - **Razón:** Odoo avanzado (P2)
- ❌ Estrategias de picking (FIFO, LIFO, FEFO) - **Razón:** Warehouse management avanzado (P2)
- ❌ Codificación automática de productos - **Razón:** No es genérico
- ❌ Imágenes de productos (galería) - **Razón:** P1, inicialmente 1 imagen

**Específico de Industria:**
- ❌ Productos con ficha técnica (construcción) - **Razón:** Específico de industria
- ❌ Productos con explosión de insumos (APU) - **Razón:** Específico de construcción
- ❌ Control de caducidad (FEFO) - **Razón:** Específico de alimentos/farmacia (P1)

### Límites con Otros Módulos

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Categorías de productos, UoM
- **MGN-005 empieza:** Productos con categoría y UoM
- **Límite:** MGN-005 usa catálogos de MGN-003

**Con MGN-004 (Financiero):**
- **MGN-005 termina:** Valoración de inventario (costo de producto)
- **MGN-004 empieza:** Asientos contables de valoración
- **Límite:** Si valoración automática activada, MGN-005 genera asientos en MGN-004

**Con MGN-006 (Compras):**
- **MGN-006 termina:** Orden de compra confirmada
- **MGN-005 empieza:** Picking de recepción, movimientos de stock
- **Límite:** Confirmación de PO genera picking automáticamente

**Con MGN-007 (Ventas):**
- **MGN-007 termina:** Orden de venta confirmada
- **MGN-005 empieza:** Picking de entrega, movimientos de stock
- **Límite:** Confirmación de SO genera picking automáticamente

### Casos de Uso Principales

1. **UC-INV-001:** Usuario crea un nuevo producto almacenable
2. **UC-INV-002:** Usuario crea un almacén con ubicaciones
3. **UC-INV-003:** Usuario realiza transferencia interna de stock
4. **UC-INV-004:** Usuario recibe productos (desde orden de compra)
5. **UC-INV-005:** Usuario entrega productos (desde orden de venta)
6. **UC-INV-006:** Usuario realiza conteo de inventario físico
7. **UC-INV-007:** Sistema calcula valoración de inventario (FIFO)
8. **UC-INV-008:** Usuario consulta trazabilidad de lote/número de serie

### Actores

- **Usuario Almacén:** Gestiona movimientos, recepciones, entregas
- **Usuario Compras:** Recibe productos de proveedores
- **Usuario Ventas:** Entrega productos a clientes
- **Contador:** Consulta valoración de inventario
- **Sistema:** Genera movimientos automáticos, calcula valoración

### Referencias

- **Odoo:** stock (stock.warehouse, stock.location, stock.move, stock.picking, stock.quant)
- **Gamilit:** inventory_management schema
- **ADR:** ADR-007 (Database Design)

---

## MGN-006: Compras Básico

### Descripción

Módulo de gestión de compras. Maneja proveedores, solicitudes de cotización, órdenes de compra, recepciones y facturación de proveedores.

### Alcance Incluido (✅ Dentro del Alcance)

**Gestión de Proveedores:**
- Proveedores son partners con is_supplier=true (MGN-003)
- Condiciones de pago de proveedor
- Lead time (tiempo de entrega)
- Calificación de proveedor (supplier rank)

**Solicitudes de Cotización (RFQ):**
- Creación de RFQ a proveedores
- Líneas de RFQ (productos, cantidades, precios esperados)
- Envío de RFQ por email (PDF)
- Estados: draft → sent → bid → cancelled

**Órdenes de Compra:**
- Creación de órdenes de compra (purchase orders)
- Conversión de RFQ a PO
- Líneas de PO (productos, cantidades, precio unitario, subtotal, impuestos, total)
- Estados: draft → confirmed → received → billed → cancelled
- Fechas: fecha de orden, fecha de entrega esperada
- Términos de pago
- Notas de orden

**Workflow de Aprobación:**
- Aprobación manual de órdenes (si monto > umbral)
- Estados de aprobación: pending_approval → approved → rejected
- Historial de aprobaciones

**Recepciones:**
- Integración con MGN-005 (Inventario)
- Generación automática de picking de recepción al confirmar PO
- Validación de recepción (parcial o total)
- Control de cantidades recibidas vs ordenadas

**Facturación de Proveedores:**
- Integración con MGN-004 (Financiero)
- Creación de factura de proveedor desde PO
- Control de cantidades facturadas vs recibidas vs ordenadas (3-way match)
- Validación de factura (genera asiento contable)

**Reportes Básicos:**
- Reporte de compras por proveedor
- Reporte de compras por producto
- Reporte de órdenes pendientes de recepción

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Requisiciones de compra (purchase requisitions) - **Razón:** Proceso adicional (P1)
- ❌ Acuerdos marco con proveedores (blanket orders) - **Razón:** Complejidad (P2)
- ❌ Subastas inversas - **Razón:** No es común en mayoría de industrias (P2)
- ❌ Comparación automática de cotizaciones - **Razón:** Funcionalidad avanzada (P1)
- ❌ Integración con catálogos de proveedores (punchout) - **Razón:** Requiere integraciones externas (P2)
- ❌ Workflow de aprobación complejo (múltiples niveles) - **Razón:** Inicialmente 1 nivel es suficiente (P1)

**Específico de Industria:**
- ❌ Gestión de contratos de construcción - **Razón:** Específico de industria
- ❌ Retenciones de garantía - **Razón:** Puede ser específico de construcción

### Límites con Otros Módulos

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Partners (proveedores)
- **MGN-006 empieza:** Órdenes de compra a proveedores
- **Límite:** MGN-006 usa proveedores de MGN-003

**Con MGN-004 (Financiero):**
- **MGN-006 termina:** Orden de compra, recepción
- **MGN-004 empieza:** Factura de proveedor (genera asiento contable)
- **Límite:** PO puede generar factura de proveedor (vendor bill en MGN-004)

**Con MGN-005 (Inventario):**
- **MGN-006 termina:** Orden de compra confirmada
- **MGN-005 empieza:** Picking de recepción, movimientos de stock
- **Límite:** Confirmación de PO genera picking en MGN-005

**Con MGN-008 (Analítica):**
- **MGN-006 termina:** Líneas de orden de compra
- **MGN-008 empieza:** Distribución analítica de costos por proyecto
- **Límite:** Líneas de PO pueden tener analytic_account_id

### Casos de Uso Principales

1. **UC-COM-001:** Usuario crea RFQ y envía a proveedores
2. **UC-COM-002:** Usuario convierte RFQ a orden de compra
3. **UC-COM-003:** Usuario crea orden de compra directamente
4. **UC-COM-004:** Sistema genera picking de recepción al confirmar PO
5. **UC-COM-005:** Usuario valida recepción de productos
6. **UC-COM-006:** Usuario crea factura de proveedor desde PO
7. **UC-COM-007:** Sistema valida 3-way match (PO vs Recepción vs Factura)
8. **UC-COM-008:** Aprobador aprueba/rechaza orden de compra

### Actores

- **Usuario Compras:** Crea RFQ, órdenes de compra
- **Aprobador Compras:** Aprueba órdenes > umbral
- **Usuario Almacén:** Valida recepciones
- **Contador:** Registra facturas de proveedor
- **Sistema:** Genera pickings, valida 3-way match

### Referencias

- **Odoo:** purchase (purchase.order, purchase.order.line)
- **Gamilit:** purchasing_management schema
- **ADR:** ADR-007 (Database Design)

---

## MGN-007: Ventas Básico

### Descripción

Módulo de gestión de ventas. Maneja clientes, cotizaciones, órdenes de venta, entregas y facturación de clientes.

### Alcance Incluido (✅ Dentro del Alcance)

**Gestión de Clientes:**
- Clientes son partners con is_customer=true (MGN-003)
- Condiciones de pago de cliente
- Límite de crédito
- Calificación de cliente (customer rank)

**Cotizaciones:**
- Creación de cotizaciones (quotations)
- Líneas de cotización (productos, cantidades, precio unitario, descuentos, subtotal, impuestos, total)
- Estados: draft → sent → sale → cancelled
- Envío de cotización por email (PDF)
- Validez de cotización (fecha de expiración)
- Términos y condiciones

**Órdenes de Venta:**
- Conversión de cotización a orden de venta (sale order)
- Creación directa de orden de venta
- Líneas de SO (productos/servicios, cantidades, precio, descuentos, impuestos)
- Estados: quotation → sale → delivery → invoice → done
- Fechas: fecha de orden, fecha de entrega esperada
- Notas de orden

**Entregas:**
- Integración con MGN-005 (Inventario)
- Generación automática de picking de entrega al confirmar SO
- Validación de entrega (parcial o total)
- Control de cantidades entregadas vs ordenadas

**Facturación de Clientes:**
- Integración con MGN-004 (Financiero)
- Creación de factura de cliente desde SO
- Control de cantidades facturadas vs entregadas vs ordenadas
- Validación de factura (genera asiento contable)
- Facturación anticipada (down payment)

**Portal de Clientes Básico:**
- Cliente puede ver sus cotizaciones
- Cliente puede aprobar cotización online
- Firma electrónica de cotización (canvas HTML5)
- (Funcionalidad completa en MGN-013)

**Reportes Básicos:**
- Reporte de ventas por cliente
- Reporte de ventas por producto
- Reporte de órdenes pendientes de entrega

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Subscripciones/Ventas recurrentes - **Razón:** Modelo de negocio específico (P2)
- ❌ Órdenes de venta con múltiples entregas (delivery schedules) - **Razón:** Complejidad (P1)
- ❌ Pricing rules complejos (descuentos escalonados) - **Razón:** Funcionalidad avanzada (P1)
- ❌ Comisiones de ventas - **Razón:** Módulo independiente (P2)
- ❌ Contratos de venta - **Razón:** Complejidad (P2)
- ❌ Integración con e-commerce - **Razón:** Requiere plataforma externa (extensión)

**Específico de Industria:**
- ❌ Gestión de proyectos de venta - **Razón:** Va en MGN-011 (Proyectos)
- ❌ Venta de servicios profesionales con timesheet - **Razón:** Combina MGN-007 + MGN-011

### Límites con Otros Módulos

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Partners (clientes)
- **MGN-007 empieza:** Cotizaciones y órdenes de venta a clientes
- **Límite:** MGN-007 usa clientes de MGN-003

**Con MGN-004 (Financiero):**
- **MGN-007 termina:** Orden de venta, entrega
- **MGN-004 empieza:** Factura de cliente (genera asiento contable)
- **Límite:** SO puede generar factura de cliente (customer invoice en MGN-004)

**Con MGN-005 (Inventario):**
- **MGN-007 termina:** Orden de venta confirmada
- **MGN-005 empieza:** Picking de entrega, movimientos de stock
- **Límite:** Confirmación de SO genera picking en MGN-005

**Con MGN-008 (Analítica):**
- **MGN-007 termina:** Líneas de orden de venta
- **MGN-008 empieza:** Distribución analítica de ingresos por proyecto
- **Límite:** Líneas de SO pueden tener analytic_account_id

**Con MGN-009 (CRM):**
- **MGN-009 termina:** Oportunidad de venta (lead)
- **MGN-007 empieza:** Cotización creada desde oportunidad
- **Límite:** Lead puede convertirse en quotation

**Con MGN-013 (Portal):**
- **MGN-007 termina:** Creación de cotización
- **MGN-013 empieza:** Vista de cotización en portal, aprobación
- **Límite:** MGN-007 tiene portal básico, MGN-013 tiene portal completo

### Casos de Uso Principales

1. **UC-VEN-001:** Usuario crea cotización y envía a cliente
2. **UC-VEN-002:** Cliente aprueba cotización online (portal básico)
3. **UC-VEN-003:** Usuario convierte cotización a orden de venta
4. **UC-VEN-004:** Sistema genera picking de entrega al confirmar SO
5. **UC-VEN-005:** Usuario valida entrega de productos
6. **UC-VEN-006:** Usuario crea factura de cliente desde SO
7. **UC-VEN-007:** Usuario registra pago de cliente (MGN-004)
8. **UC-VEN-008:** Usuario consulta reporte de ventas por cliente

### Actores

- **Usuario Ventas:** Crea cotizaciones, órdenes de venta
- **Usuario Almacén:** Valida entregas
- **Contador:** Genera facturas de cliente
- **Cliente (Portal):** Aprueba cotizaciones online
- **Sistema:** Genera pickings, facturas

### Referencias

- **Odoo:** sale (sale.order, sale.order.line)
- **Gamilit:** sales_management schema
- **ADR:** ADR-007 (Database Design)

---

## MGN-008: Contabilidad Analítica

### Descripción

Módulo de contabilidad analítica. Permite tracking de costos e ingresos por proyecto, departamento, centro de costo. Es paralelo a la contabilidad general (MGN-004).

### Alcance Incluido (✅ Dentro del Alcance)

**Cuentas Analíticas:**
- CRUD de cuentas analíticas (analytic accounts)
- Tipos: proyecto, departamento, centro de costo, cliente
- Jerarquía (parent_id): proyectos con sub-proyectos
- Estado: activo/inactivo
- Presupuesto asignado (opcional)
- Vinculación con company_id (multi-empresa)

**Líneas Analíticas:**
- Registro automático de líneas analíticas desde transacciones
- Líneas con: cuenta analítica, monto, fecha, descripción, documento origen
- Líneas de costo (negativas) e ingreso (positivas)
- Agrupación por cuenta analítica

**Distribución Analítica:**
- Una transacción puede distribuirse a múltiples cuentas analíticas
- Porcentaje de distribución (ej: 60% Proyecto A, 40% Proyecto B)
- Validación: suma de porcentajes = 100%

**Integración con Módulos Transaccionales:**
- Campo `analytic_account_id` en:
  - Líneas de factura (MGN-004)
  - Líneas de orden de compra (MGN-006)
  - Líneas de orden de venta (MGN-007)
  - Timesheet de empleados (MGN-010)
  - Tareas de proyectos (MGN-011)
- Generación automática de líneas analíticas al confirmar documentos

**Tags Analíticos:**
- Etiquetas adicionales (ej: torre, etapa, fase)
- Múltiples tags por línea analítica
- Filtros por tags en reportes

**Reportes Analíticos:**
- Balance por cuenta analítica (costos vs ingresos)
- P&L por proyecto
- Comparación presupuesto vs real
- Reporte de rentabilidad por proyecto
- Filtros: por fecha, empresa, tipo de cuenta

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Presupuestos complejos (revisiones, versiones) - **Razón:** Funcionalidad avanzada (P1)
- ❌ Alertas de sobre-presupuesto - **Razón:** Funcionalidad avanzada (P1)
- ❌ Forecast (proyecciones) - **Razón:** Requiere algoritmos (P2)
- ❌ Cross-charging (facturación inter-proyectos) - **Razón:** Complejidad (P2)

**Específico de Industria:**
- ❌ APU (Análisis de Precio Unitario) construcción - **Razón:** Específico de construcción
- ❌ Curva S - **Razón:** Específico de construcción
- ❌ Costos por fase de obra - **Razón:** Puede modelarse con tags analíticos

### Límites con Otros Módulos

**Con MGN-004 (Financiero):**
- **MGN-004 termina:** Asientos en contabilidad general
- **MGN-008 empieza:** Distribución analítica de asientos
- **Límite:** Contabilidad general y analítica son paralelas (una transacción genera asiento en ambas)

**Con MGN-006 (Compras) y MGN-007 (Ventas):**
- **MGN-006/007 terminan:** Líneas de órdenes
- **MGN-008 empieza:** Campo analytic_account_id en líneas
- **Límite:** Órdenes registran costos/ingresos en cuentas analíticas

**Con MGN-011 (Proyectos):**
- **MGN-011 termina:** Proyecto como entidad
- **MGN-008 empieza:** Proyecto tiene cuenta analítica asociada (1-1)
- **Límite:** Un proyecto MGN-011 = una cuenta analítica MGN-008

**Con MGN-012 (Reportes):**
- **MGN-008 termina:** Datos de líneas analíticas
- **MGN-012 empieza:** Reportes consolidados, dashboards
- **Límite:** MGN-012 consume datos de MGN-008

### Casos de Uso Principales

1. **UC-ANA-001:** Administrador crea cuenta analítica para proyecto
2. **UC-ANA-002:** Usuario asigna cuenta analítica a línea de orden de compra
3. **UC-ANA-003:** Sistema genera líneas analíticas al validar factura
4. **UC-ANA-004:** Usuario distribuye costo a múltiples cuentas analíticas
5. **UC-ANA-005:** Usuario consulta balance por cuenta analítica (P&L por proyecto)
6. **UC-ANA-006:** Usuario compara presupuesto vs real
7. **UC-ANA-007:** Usuario filtra líneas analíticas por tags

### Actores

- **Administrador Proyectos:** Crea cuentas analíticas
- **Usuario Compras/Ventas:** Asigna cuentas analíticas a transacciones
- **Gerente de Proyecto:** Consulta rentabilidad de proyecto
- **Contador:** Genera reportes analíticos
- **Sistema:** Genera líneas analíticas automáticamente

### Referencias

- **Odoo:** analytic (account.analytic.account, account.analytic.line)
- **ADR:** ADR-007 (Database Design)
- **Importancia:** ⭐⭐⭐⭐⭐ CRÍTICO para ERPs de proyectos

---

## MGN-009: CRM Básico

### Descripción

Módulo de gestión de relaciones con clientes (CRM). Maneja leads, oportunidades, pipeline de ventas, actividades y conversión a cotizaciones.

### Alcance Incluido (✅ Dentro del Alcance)

**Gestión de Leads/Oportunidades:**
- CRUD de leads (contactos interesados)
- Datos de lead: nombre, empresa, email, teléfono, fuente (website, referral, etc.)
- Conversión de lead a oportunidad
- Oportunidades con: monto estimado, probabilidad de cierre, fecha esperada
- Vinculación con partner (MGN-003)

**Pipeline de Ventas:**
- Stages personalizables (ej: Prospección → Calificación → Propuesta → Negociación → Ganado/Perdido)
- Drag-and-drop entre stages (kanban)
- Probabilidad de cierre por stage
- Revenue estimado por stage

**Actividades y Seguimiento:**
- Programación de actividades (llamadas, reuniones, emails)
- Estados: pendiente → completada → vencida
- Recordatorios
- Notas de actividad

**Lead Scoring:**
- Scoring automático basado en criterios (ej: tamaño empresa, industria, interacción)
- Calificación: hot, warm, cold

**Teams de Ventas:**
- CRUD de equipos de ventas
- Asignación de leads a equipos
- Objetivos de ventas por equipo (opcional)

**Conversión a Cotización:**
- Botón "Crear Cotización" desde oportunidad
- Pre-llenado de datos (cliente, productos, monto)
- Vínculo entre oportunidad (MGN-009) y cotización (MGN-007)

**Reportes CRM:**
- Reporte de oportunidades por stage
- Reporte de conversión rate
- Reporte de rendimiento por vendedor
- Embudo de ventas (funnel)

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Marketing automation (campaigns, email marketing) - **Razón:** Módulo independiente (P2)
- ❌ Integración con redes sociales - **Razón:** Requiere APIs externas (P2)
- ❌ Predicción de cierre con ML - **Razón:** Complejidad (P3)
- ❌ CRM avanzado (customer journey, customer lifetime value) - **Razón:** Funcionalidad avanzada (P2)
- ❌ Atención al cliente (tickets, helpdesk) - **Razón:** Módulo independiente (P2)

**Integraciones:**
- ❌ Integración con email (Gmail, Outlook) - **Razón:** Requiere APIs externas (P1)
- ❌ Integración con teléfono (VoIP) - **Razón:** Requiere infraestructura (P2)

### Límites con Otros Módulos

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Partners (clientes potenciales)
- **MGN-009 empieza:** Leads que se convierten en partners
- **Límite:** Un lead puede crear un partner al calificarse

**Con MGN-007 (Ventas):**
- **MGN-009 termina:** Oportunidad
- **MGN-007 empieza:** Cotización creada desde oportunidad
- **Límite:** Oportunidad puede generar cotización (sale.order)

**Con MGN-014 (Mensajería):**
- **MGN-009 termina:** Lead, oportunidad
- **MGN-014 empieza:** Actividades, recordatorios, notificaciones
- **Límite:** MGN-009 usa sistema de actividades de MGN-014

### Casos de Uso Principales

1. **UC-CRM-001:** Usuario crea un nuevo lead
2. **UC-CRM-002:** Usuario califica lead y convierte a oportunidad
3. **UC-CRM-003:** Usuario mueve oportunidad entre stages (drag-and-drop)
4. **UC-CRM-004:** Usuario programa llamada de seguimiento
5. **UC-CRM-005:** Usuario convierte oportunidad a cotización
6. **UC-CRM-006:** Usuario marca oportunidad como ganada/perdida
7. **UC-CRM-007:** Gerente consulta embudo de ventas (funnel)

### Actores

- **Vendedor:** Gestiona leads, oportunidades, actividades
- **Gerente de Ventas:** Consulta reportes, gestiona equipos
- **Sistema:** Calcula scoring, envía recordatorios

### Referencias

- **Odoo:** crm (crm.lead, crm.stage, crm.team)
- **ADR:** ADR-007 (Database Design)

---

## MGN-010: RRHH Básico

### Descripción

Módulo de recursos humanos. Maneja empleados, departamentos, contratos, asistencias, ausencias y timesheet básico.

### Alcance Incluido (✅ Dentro del Alcance)

**Gestión de Empleados:**
- CRUD de empleados
- Datos personales: nombre, email, teléfono, dirección, fecha de nacimiento
- Datos laborales: puesto (job position), departamento, manager, fecha de ingreso
- Empleado vinculado a partner (is_employee=true) y user (opcional)
- Estado: activo/inactivo
- Foto de empleado

**Departamentos y Puestos:**
- CRUD de departamentos
- Jerarquía de departamentos (parent_id)
- Jefe de departamento (manager)
- CRUD de puestos de trabajo (job positions)
- Descripción de puesto

**Contratos Laborales:**
- CRUD de contratos
- Tipos de contrato: indefinido, temporal, honorarios
- Datos de contrato: salario, fecha inicio, fecha fin (opcional), puesto, tipo de jornada
- Estados: draft → running → expired → cancelled

**Asistencias:**
- Check-in/Check-out (registro de entrada/salida)
- Cálculo automático de horas trabajadas
- Reporte de asistencias por empleado
- Reporte de asistencias por departamento

**Ausencias y Permisos:**
- CRUD de tipos de ausencia (vacaciones, incapacidad, permiso sin goce)
- Solicitudes de ausencia (leave requests)
- Estados: draft → pending_approval → approved → refused
- Workflow de aprobación (manager aprueba)
- Saldo de días de vacaciones

**Organigrama:**
- Visualización jerárquica de empleados (por manager)
- Visualización por departamento

**Timesheet Básico:**
- Registro de horas trabajadas por día
- Asignación de horas a cuenta analítica (MGN-008)
- Validación de horas (manager aprueba)

### Alcance Excluido (❌ Fuera del Alcance)

**Nómina:**
- ❌ Cálculo de nómina (salario, deducciones, impuestos) - **Razón:** Módulo especializado, específico de país (P1)
- ❌ Recibos de nómina - **Razón:** Va con módulo de nómina (P1)
- ❌ Integración con bancos (pago de nómina) - **Razón:** Requiere APIs bancarias (P2)

**Funcionalidades Avanzadas:**
- ❌ Evaluaciones de desempeño - **Razón:** Módulo independiente (P2)
- ❌ Reclutamiento (job postings, applicants) - **Razón:** Módulo independiente (P2)
- ❌ Capacitación y desarrollo - **Razón:** Módulo independiente (P2)
- ❌ Gestión de beneficios - **Razón:** Complejidad (P2)
- ❌ Gastos de empleados (expense reports) - **Razón:** Módulo independiente (P1)

### Límites con Otros Módulos

**Con MGN-001 (Fundamentos):**
- **MGN-001 termina:** Users
- **MGN-010 empieza:** Empleados vinculados a users
- **Límite:** Un user puede ser empleado (employee_id)

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Partners
- **MGN-010 empieza:** Empleados vinculados a partners (is_employee=true)
- **Límite:** Un empleado es un partner

**Con MGN-008 (Analítica):**
- **MGN-010 termina:** Timesheet (horas trabajadas)
- **MGN-008 empieza:** Líneas analíticas desde timesheet
- **Límite:** Horas de timesheet generan líneas analíticas

**Con MGN-011 (Proyectos):**
- **MGN-010 termina:** Timesheet de empleado
- **MGN-011 empieza:** Timesheet asignado a tareas
- **Límite:** Timesheet puede vincularse a tareas de proyectos

### Casos de Uso Principales

1. **UC-HR-001:** RRHH crea un nuevo empleado
2. **UC-HR-002:** RRHH asigna empleado a departamento y puesto
3. **UC-HR-003:** RRHH crea contrato de trabajo
4. **UC-HR-004:** Empleado registra check-in/check-out
5. **UC-HR-005:** Empleado solicita vacaciones
6. **UC-HR-006:** Manager aprueba/rechaza solicitud de vacaciones
7. **UC-HR-007:** Empleado registra timesheet (horas trabajadas por proyecto)
8. **UC-HR-008:** Manager valida timesheet de empleado

### Actores

- **RRHH:** Gestiona empleados, contratos, ausencias
- **Manager:** Aprueba ausencias, valida timesheet
- **Empleado:** Registra asistencias, solicita ausencias, registra timesheet
- **Sistema:** Calcula horas trabajadas, saldo de vacaciones

### Referencias

- **Odoo:** hr (hr.employee, hr.contract, hr.attendance, hr.leave)
- **Gamilit:** hr_management schema
- **ADR:** ADR-007 (Database Design)

---

## MGN-011: Proyectos Genéricos

### Descripción

Módulo de gestión de proyectos genéricos. Maneja proyectos, tareas, milestones, timesheet y portal de proyectos para clientes.

### Alcance Incluido (✅ Dentro del Alcance)

**Gestión de Proyectos:**
- CRUD de proyectos
- Datos de proyecto: nombre, descripción, cliente (partner), manager, fecha inicio/fin
- Estados: draft → active → completed → cancelled
- Proyecto vinculado a cuenta analítica (1-1) - MGN-008
- Proyecto vinculado a empresa (company_id)

**Tareas:**
- CRUD de tareas (tasks)
- Datos de tarea: nombre, descripción, proyecto, asignado a, fecha límite, prioridad
- Estados configurables por proyecto (stages): To Do → In Progress → Review → Done
- Kanban de tareas (drag-and-drop entre stages)
- Subtareas (parent_id)
- Dependencias entre tareas (opcional P1)

**Milestones:**
- CRUD de milestones (hitos importantes)
- Fecha de milestone, estado (pendiente, completado)
- Tareas asociadas a milestone

**Timesheet:**
- Integración con MGN-010 (RRHH)
- Registro de horas trabajadas por tarea
- Validación de horas (manager aprueba)
- Horas generan líneas analíticas (MGN-008)

**Gantt:**
- Vista de timeline de tareas
- Visualización de dependencias
- Drag-and-drop para reprogramar

**Portal de Proyectos:**
- Cliente puede ver sus proyectos
- Cliente puede ver tareas (read-only)
- Cliente puede comentar en tareas
- (Funcionalidad completa en MGN-013)

**Reportes Básicos:**
- Reporte de tareas por proyecto
- Reporte de horas trabajadas por proyecto
- Reporte de milestones cumplidos vs pendientes

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Gestión de recursos (resource allocation) - **Razón:** Complejidad (P2)
- ❌ Critical Path Method (CPM) - **Razón:** Algoritmo complejo (P2)
- ❌ Baseline de proyectos (versiones de plan) - **Razón:** Funcionalidad avanzada (P2)
- ❌ Issues/Bugs tracking - **Razón:** Puede ser módulo independiente (P2)
- ❌ Wiki de proyecto - **Razón:** Requiere editor avanzado (P2)

**Específico de Industria:**
- ❌ Proyectos de construcción (manzanas, lotes, prototipos) - **Razón:** Específico de construcción (extensión)
- ❌ Curva S, APU - **Razón:** Específico de construcción
- ❌ Control de avances físicos - **Razón:** Específico de construcción

### Límites con Otros Módulos

**Con MGN-003 (Catálogos):**
- **MGN-003 termina:** Partners (clientes)
- **MGN-011 empieza:** Proyectos con cliente (partner_id)
- **Límite:** Proyecto tiene cliente

**Con MGN-008 (Analítica):**
- **MGN-011 termina:** Proyecto como entidad de gestión
- **MGN-008 empieza:** Proyecto tiene cuenta analítica (1-1)
- **Límite:** Un proyecto MGN-011 = una cuenta analítica MGN-008

**Con MGN-010 (RRHH):**
- **MGN-010 termina:** Timesheet de empleado
- **MGN-011 empieza:** Timesheet asignado a tareas
- **Límite:** Horas de timesheet se asignan a tareas

**Con MGN-013 (Portal):**
- **MGN-011 termina:** Proyecto y tareas
- **MGN-013 empieza:** Vista de proyecto en portal para cliente
- **Límite:** MGN-011 tiene portal básico, MGN-013 tiene portal completo

### Casos de Uso Principales

1. **UC-PRO-001:** Manager crea un nuevo proyecto
2. **UC-PRO-002:** Manager crea tareas en proyecto
3. **UC-PRO-003:** Usuario asignado mueve tarea entre stages (kanban)
4. **UC-PRO-004:** Empleado registra horas trabajadas en tarea
5. **UC-PRO-005:** Manager valida timesheet de tarea
6. **UC-PRO-006:** Manager crea milestone y asocia tareas
7. **UC-PRO-007:** Cliente ve avance de proyecto en portal
8. **UC-PRO-008:** Usuario consulta Gantt de proyecto

### Actores

- **Manager de Proyecto:** Gestiona proyectos, tareas, milestones
- **Usuario Asignado:** Trabaja en tareas, registra horas
- **Cliente (Portal):** Ve avance de proyecto
- **Sistema:** Genera líneas analíticas desde timesheet

### Referencias

- **Odoo:** project (project.project, project.task, project.milestone)
- **Gamilit:** projects_management schema
- **ADR:** ADR-007 (Database Design)

---

## MGN-012: Reportes y Analytics

### Descripción

Módulo de reportes y analytics avanzados. Proporciona dashboards, reportes configurables, exportación de datos y visualizaciones.

### Alcance Incluido (✅ Dentro del Alcance)

**Dashboards:**
- Dashboard genérico con widgets configurables
- Widgets: KPIs (números), gráficos (línea, barra, pie), tablas
- Configuración por rol (cada rol ve su dashboard)
- Filtros globales (fecha, empresa, proyecto)

**Reportes Configurables:**
- Query builder visual (sin SQL)
- Selección de campos, filtros, agrupaciones, ordenamiento
- Guardado de reportes personalizados
- Compartir reportes con otros usuarios

**Reportes Financieros Estándar:**
- Balance General (integración con MGN-004)
- Estado de Resultados / P&L (integración con MGN-004)
- Flujo de Caja (Cash Flow) - P1

**Reportes Analíticos:**
- P&L por proyecto (integración con MGN-008)
- Balance por cuenta analítica
- Comparación presupuesto vs real

**KPIs Genéricos:**
- KPIs de ventas (monto vendido, # órdenes, ticket promedio)
- KPIs de compras (monto comprado, # órdenes, proveedores activos)
- KPIs de inventario (valor de stock, rotación)
- KPIs financieros (cuentas por cobrar, cuentas por pagar, liquidez)

**Exportación:**
- Exportación a PDF (con header/footer de empresa)
- Exportación a Excel (con formato)
- Exportación a CSV
- Programación de reportes (envío por email automático) - P1

**Gráficos y Visualizaciones:**
- Librería de gráficos (Chart.js o Recharts)
- Tipos: línea, barra, pie, área, scatter
- Gráficos interactivos (zoom, tooltips)

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ BI avanzado (OLAP, cubos) - **Razón:** Complejidad (P3)
- ❌ Predicciones con ML - **Razón:** Requiere data science (P3)
- ❌ Integración con herramientas BI externas (Power BI, Tableau) - **Razón:** Requiere APIs (P2)
- ❌ Data warehouse - **Razón:** Infraestructura adicional (P3)

**Reportes Específicos:**
- ❌ Reportes específicos de industria - **Razón:** Van en extensiones específicas

### Límites con Otros Módulos

**Con MGN-004 (Financiero):**
- **MGN-004 termina:** Datos contables
- **MGN-012 empieza:** Reportes financieros (Balance, P&L)
- **Límite:** MGN-012 consume datos de MGN-004

**Con MGN-008 (Analítica):**
- **MGN-008 termina:** Datos analíticos
- **MGN-012 empieza:** Reportes analíticos (P&L por proyecto)
- **Límite:** MGN-012 consume datos de MGN-008

**Con Todos los Módulos:**
- **Otros módulos terminan:** Generación de datos
- **MGN-012 empieza:** Consumo y visualización de datos
- **Límite:** MGN-012 es capa de reporting sobre todos los módulos

### Casos de Uso Principales

1. **UC-REP-001:** Usuario consulta dashboard de ventas
2. **UC-REP-002:** Contador genera Balance General
3. **UC-REP-003:** Gerente genera P&L por proyecto
4. **UC-REP-004:** Usuario crea reporte personalizado con query builder
5. **UC-REP-005:** Usuario exporta reporte a Excel
6. **UC-REP-006:** Usuario programa envío de reporte por email (semanal)
7. **UC-REP-007:** Usuario visualiza gráfico de ventas por mes

### Actores

- **Contador:** Genera reportes financieros
- **Gerente:** Consulta dashboards, KPIs
- **Administrador:** Configura reportes por rol
- **Usuario:** Crea reportes personalizados

### Referencias

- **Odoo:** account (reports), reporting
- **Gamilit:** analytics module
- **ADR:** ADR-007 (Database Design)

---

## MGN-013: Portal de Usuarios

### Descripción

Módulo de portal para usuarios externos (clientes, proveedores). Permite acceso limitado a documentos, aprobación de cotizaciones, firma electrónica y vista de proyectos.

### Alcance Incluido (✅ Dentro del Alcance)

**Acceso Portal:**
- Usuarios con rol `portal_user` (is_portal=true)
- Login separado (subdomain o /portal)
- RLS estricto (usuario solo ve sus registros)
- Permisos read-only + acciones permitidas (aprobar, firmar)

**Vista de Documentos:**
- Cotizaciones (MGN-007): ver, aprobar, firmar
- Órdenes de venta (MGN-007): ver estado, entregas
- Facturas (MGN-004): ver, descargar PDF
- Pagos (MGN-004): ver estado
- Proyectos (MGN-011): ver avance, tareas, comentar

**Aprobación de Documentos:**
- Aprobación de cotizaciones online
- Estados: pending → approved → rejected
- Historial de aprobaciones

**Firma Electrónica:**
- Canvas HTML5 para firma
- Almacenamiento seguro de firma (base64 en DB o S3)
- Firma válida legalmente (con timestamp, IP, user agent)
- PDF firmado (con imagen de firma)

**Mensajería:**
- Integración con MGN-014
- Cliente puede comentar en documentos
- Cliente puede enviar mensajes a empresa
- Notificaciones por email

**Dashboard Personalizado:**
- Dashboard por rol (cliente ve sus órdenes, facturas, proyectos)
- KPIs básicos (monto pendiente, órdenes activas)

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Portal de proveedores (RFQ online, respuesta de cotización) - **Razón:** Caso de uso específico (P1)
- ❌ Portal de empleados - **Razón:** Puede ser extensión de MGN-010 (P2)
- ❌ Customización completa de portal por cliente - **Razón:** Complejidad (P2)
- ❌ White-label portal (custom branding por cliente) - **Razón:** Requiere infraestructura (P2)

**Integraciones:**
- ❌ Integración con e-signature providers (DocuSign, etc.) - **Razón:** Requiere APIs externas (P2)

### Límites con Otros Módulos

**Con MGN-001 (Fundamentos):**
- **MGN-001 termina:** Autenticación de usuarios
- **MGN-013 empieza:** Portal con rol portal_user
- **Límite:** Portal usa autenticación de MGN-001

**Con MGN-007 (Ventas):**
- **MGN-007 termina:** Cotizaciones, órdenes
- **MGN-013 empieza:** Vista de cotizaciones en portal, aprobación
- **Límite:** Portal consume datos de MGN-007

**Con MGN-011 (Proyectos):**
- **MGN-011 termina:** Proyectos, tareas
- **MGN-013 empieza:** Vista de proyectos en portal
- **Límite:** Portal consume datos de MGN-011

**Con MGN-014 (Mensajería):**
- **MGN-014 termina:** Sistema de mensajes
- **MGN-013 empieza:** Mensajes en portal
- **Límite:** Portal usa mensajería de MGN-014

### Casos de Uso Principales

1. **UC-POR-001:** Cliente inicia sesión en portal
2. **UC-POR-002:** Cliente ve sus cotizaciones pendientes
3. **UC-POR-003:** Cliente aprueba cotización online
4. **UC-POR-004:** Cliente firma cotización electrónicamente
5. **UC-POR-005:** Cliente ve avance de su proyecto
6. **UC-POR-006:** Cliente descarga factura en PDF
7. **UC-POR-007:** Cliente envía mensaje a empresa desde portal

### Actores

- **Cliente (Portal):** Ve documentos, aprueba, firma
- **Proveedor (Portal):** Ve órdenes de compra (opcional P1)
- **Empleado Empresa:** Responde mensajes de portal
- **Sistema:** Valida permisos, notifica aprobaciones

### Referencias

- **Odoo:** portal (portal.user, portal access)
- **ADR:** ADR-006 (RBAC), ADR-007 (Database Design)
- **Importancia:** ⭐⭐⭐⭐⭐ CRÍTICO para portal derechohabientes INFONAVIT

---

## MGN-014: Mensajería y Notificaciones

### Descripción

Módulo de mensajería y notificaciones. Proporciona sistema de mensajes (chatter), notificaciones, tracking automático de cambios, actividades y followers.

### Alcance Incluido (✅ Dentro del Alcance)

**Sistema de Mensajes (Chatter):**
- Patrón mail.thread de Odoo
- Chatter por registro (comentarios en facturas, órdenes, proyectos, etc.)
- Tipos de mensaje: note (interno), comment (visible a followers)
- Adjuntos en mensajes

**Notificaciones:**
- Notificaciones in-app (campana con badge de conteo)
- Notificaciones por email
- Push notifications (opcional P1, para mobile)
- Preferencias de notificación por usuario

**Tracking Automático de Cambios:**
- Decorador `@TrackChanges(['status', 'amount', 'assigned_to'])`
- Registro automático de cambios en campos configurados
- Mensaje automático en chatter: "Usuario X cambió Status de Draft a Confirmed"
- Auditoría sin código adicional

**Actividades Programadas:**
- CRUD de actividades (llamadas, reuniones, emails, tareas)
- Fecha/hora de actividad, asignado a, tipo, descripción
- Estados: pendiente → completada → vencida
- Recordatorios automáticos (1 día antes, 1 hora antes)
- Integración con calendario (opcional P1)

**Followers (Seguidores):**
- Usuarios pueden seguir registros (follow/unfollow)
- Followers reciben notificaciones automáticas de cambios
- Agregar followers automáticamente (ej: vendedor sigue sus órdenes)

**Templates de Email:**
- Templates configurables (Handlebars o similar)
- Variables: {{user.name}}, {{order.amount}}, etc.
- Envío de emails desde templates (cotizaciones, facturas, etc.)

**Mensajería en Tiempo Real:**
- WebSocket con Socket.IO
- Notificaciones push instantáneas
- Mejor UX vs polling

### Alcance Excluido (❌ Fuera del Alcance)

**Funcionalidades Avanzadas:**
- ❌ Chat en tiempo real (Slack-like) - **Razón:** Requiere infraestructura compleja (P2)
- ❌ Videollamadas - **Razón:** Requiere WebRTC (P3)
- ❌ Integración con email (Gmail, Outlook) - **Razón:** Requiere APIs externas (P1)
- ❌ SMS notifications - **Razón:** Requiere proveedor SMS (P2)
- ❌ Email marketing - **Razón:** Módulo independiente (P2)

### Límites con Otros Módulos

**Con Todos los Módulos:**
- **Otros módulos terminan:** Creación/actualización de registros
- **MGN-014 empieza:** Tracking de cambios, notificaciones
- **Límite:** MGN-014 es transversal, todos los módulos pueden usar chatter y notificaciones

### Casos de Uso Principales

1. **UC-NOT-001:** Usuario comenta en orden de venta (chatter)
2. **UC-NOT-002:** Sistema registra cambio automático (tracking)
3. **UC-NOT-003:** Usuario recibe notificación in-app
4. **UC-NOT-004:** Usuario configura preferencias de notificación
5. **UC-NOT-005:** Usuario programa actividad (llamada a cliente)
6. **UC-NOT-006:** Sistema envía recordatorio de actividad vencida
7. **UC-NOT-007:** Usuario sigue orden de compra (follow)
8. **UC-NOT-008:** Sistema envía email desde template

### Actores

- **Usuario:** Comenta, crea actividades, recibe notificaciones
- **Sistema:** Registra cambios automáticamente, envía notificaciones
- **Administrador:** Configura templates de email

### Referencias

- **Odoo:** mail (mail.thread, mail.message, mail.followers, mail.activity)
- **Gamilit:** notifications_management schema
- **ADR:** ADR-007 (Database Design)
- **Importancia:** ⭐⭐⭐⭐⭐ ESENCIAL para auditoría y colaboración

---

## Resumen de Alcance

### Total de Funcionalidades

| Módulo | Funcionalidades Incluidas | Funcionalidades Excluidas | Ratio Incluidas/Excluidas |
|--------|---------------------------|---------------------------|---------------------------|
| MGN-001 | 8 (Auth, Users, RBAC, Multi-tenancy) | 9 (OAuth, 2FA, SSO, etc.) | 47% |
| MGN-002 | 5 (Empresas, Multi-empresa, Holdings) | 4 (Consolidación, Transfers, etc.) | 56% |
| MGN-003 | 8 (Partners, Countries, Currencies, UoM) | 5 (CRM avanzado, Portal, etc.) | 62% |
| MGN-004 | 10 (Contabilidad general completa) | 7 (Presupuestos, Activos fijos, etc.) | 59% |
| MGN-005 | 10 (Inventario completo) | 6 (MRP, Kits, Rutas, etc.) | 63% |
| MGN-006 | 8 (Compras completo) | 5 (Requisiciones, Acuerdos marco, etc.) | 62% |
| MGN-007 | 9 (Ventas completo) | 6 (Subscripciones, Comisiones, etc.) | 60% |
| MGN-008 | 7 (Analítica completa) | 4 (Presupuestos avanzados, etc.) | 64% |
| MGN-009 | 8 (CRM básico) | 5 (Marketing automation, etc.) | 62% |
| MGN-010 | 9 (RRHH básico) | 6 (Nómina, Reclutamiento, etc.) | 60% |
| MGN-011 | 8 (Proyectos genéricos) | 5 (Resource allocation, CPM, etc.) | 62% |
| MGN-012 | 7 (Reportes y dashboards) | 4 (BI avanzado, ML, etc.) | 64% |
| MGN-013 | 6 (Portal básico) | 4 (Portal proveedores, White-label, etc.) | 60% |
| MGN-014 | 8 (Mensajería completa) | 5 (Chat, Videollamadas, SMS, etc.) | 62% |
| **TOTAL** | **111** | **75** | **60%** |

**Promedio:** 60% de funcionalidades incluidas vs 40% excluidas (para evitar over-engineering)

---

## Próximos Pasos

1. **Validar alcance con stakeholders:** Revisar que funcionalidades incluidas son suficientes para MVP
2. **Crear DEPENDENCIAS-MODULOS.md:** Documentar orden de implementación basado en dependencias
3. **Diseñar database schemas:** Crear DDL de cada módulo (Fase 2)
4. **Diseñar APIs:** Crear especificaciones OpenAPI 3.0 (Fase 2)

---

**Documento creado:** 2025-11-23
**Versión:** 1.0
**Autor:** Architecture-Analyst
**Estado:** ✅ Completado
**Próximo documento:** DEPENDENCIAS-MODULOS.md