# EFINTEL | ERP Interno I+D+i — Sistema de Control de Gastos

**Sistema Django de Control Financiero, Operaciones, Talento y Proyectos**

Dashboard corporativo para la gestión financiera del Área de Investigación, Desarrollo e Innovación (I+D+i) de EFINTEL. Construido con Django 6.1, autenticación por roles, base de datos SQLite, y WebSockets en tiempo real.

---

## Requisitos del Sistema

| Componente | Versión | ¿Necesario? |
|---|---|---|
| **Python** | 3.10 o superior | ✅ Obligatorio |
| **pip** | (viene con Python) | ✅ Obligatorio |
| **macOS** | 12 Monterey o superior | 💡 Recomendado |
| Node.js / npm | — | ❌ No necesario |
| PostgreSQL | — | ❌ No necesario (usa SQLite) |
| Redis | — | ❌ No necesario (usa InMemoryChannelLayer) |

### Instalación de Python en macOS (si no lo tienes)

```bash
# 1. Instalar Homebrew (si no lo tienes)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Para Apple Silicon (M1/M2/M3/M4), agregar al PATH:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 2. Instalar Python 3.12
brew install python@3.12

# 3. Verificar
python3 --version && pip3 --version
```

---

## Arranque Rápido

### Opción A: Script automático (recomendado)

```bash
# Solo la primera vez — dar permisos:
chmod +x start.sh

# Iniciar el sistema:
./start.sh
```

El script automáticamente:
1. ✅ Verifica Python 3
2. ✅ Crea entorno virtual (`venv`) si no existe
3. ✅ Instala las 29 dependencias (Django, Channels, Daphne, etc.)
4. ✅ Ejecuta migraciones de base de datos
5. ✅ Crea usuarios y roles (primera ejecución)
6. ✅ Inicia el servidor Daphne en `http://localhost:8000`
7. ✅ Abre el navegador automáticamente (macOS)

### Opción B: Manual

```bash
# 1. Crear entorno virtual
python3 -m venv venv

# 2. Activar
source venv/bin/activate

# 3. Instalar dependencias
pip install -r requirements.txt

# 4. Migraciones
python manage.py migrate

# 5. Crear usuarios (solo la primera vez)
python setup_roles.py

# 6. Iniciar servidor
python -m daphne -b 0.0.0.0 -p 8000 config.asgi:application
```

Abrir en el navegador: **http://localhost:8000**

Para detener: **Ctrl + C**

---

## Cuentas de Usuario

| Usuario | Contraseña | Rol | Acceso |
|---|---|---|---|
| `admin` | `admin` | Administrador | ✅ Panel de Gestión + Admin Django |
| `ginevra_ortega` | `ginevra123` | Administrador | ✅ Panel de Gestión + Admin Django |
| `finanzas` | `finanzas123` | Administrador Finanzas | 💰 Liberación de pagos |
| `miguel_contreras` | `miguel123` | Director de Proyecto | 📋 Gestión de proyectos |

### Acceso al panel Admin Django
URL: **http://localhost:8000/admin/**
Usuarios: `admin` o `ginevra_ortega`

---

## Estructura del Proyecto

```
├── manage.py                    → CLI de Django
├── requirements.txt             → 29 dependencias Python
├── setup_roles.py               → Creación de usuarios y roles
├── start.sh                     → Script de arranque automático
├── db.sqlite3                   → Base de datos SQLite (se genera automáticamente)
├── .gitignore                   → Exclusiones para Git
├── README.md                    → Este archivo
│
├── config/                      → Configuración Django
│   ├── settings.py              → Settings (SQLite, Channels, ASGI)
│   ├── urls.py                  → Rutas raíz
│   ├── asgi.py                  → Config ASGI (Daphne + WebSockets)
│   └── wsgi.py                  → Config WSGI (fallback)
│
├── expenses/                    → App principal del ERP
│   ├── models.py                → 8 modelos de datos
│   ├── views.py                 → 16 vistas (dashboard, CRUD, aprobación)
│   ├── forms.py                 → 5 formularios
│   ├── urls.py                  → 18 rutas
│   ├── admin.py                 → Admin Django registrado
│   ├── decorators.py            → Decorator @role_required
│   ├── signals.py               → WebSocket signals
│   ├── consumers.py             → WebSocket consumer
│   └── routing.py               → WebSocket routing
│
├── templates/                   → Templates HTML
│   ├── base.html                → Layout base con navegación
│   ├── registration/
│   │   └── login.html           → Pantalla de login
│   └── expenses/
│       ├── dashboard.html       → Resumen financiero
│       ├── expense_list.html    → Lista de gastos con filtros
│       ├── expense_form.html    → Formulario de gasto
│       ├── project_list.html    → Lista de proyectos
│       ├── project_form.html    → Formulario de proyecto
│       ├── gestion.html         → Panel de gestión (admin)
│       ├── responsable_form.html→ Formulario de responsable
│       └── settings_form.html   → Config del sistema
│
├── static/                      → Archivos estáticos
│   ├── css/style.css            → Estilos CSS corporativos EFINTEL
│   ├── js/app.js                → JavaScript del frontend
│   └── img/
│       ├── efintel_logo.png
│       └── efintel_logo.svg
│
└── venv/                        → Entorno virtual (generado, no se sube a Git)
```

---

## Módulos del ERP

| Ruta | Módulo | Descripción |
|---|---|---|
| `/` | Dashboard | KPIs financieros, gastos del mes, presupuesto restante |
| `/gastos/` | Operaciones y Gastos | Lista completa con filtros por proyecto y categoría |
| `/gastos/nuevo/` | Registrar Gasto | Formulario multimoneda CLP/USD |
| `/proyectos/` | Control de Proyectos | Proyectos con presupuesto y gastos acumulados |
| `/gestion/` | Panel de Gestión | CRUD de proyectos, responsables y configuración (solo Admin) |
| `/gastos/exportar/csv/` | Exportar CSV | Descarga matriz para Excel / Power BI |
| `/admin/` | Admin Django | Panel administrativo completo |

### Flujo de Aprobación de Gastos (3 pasos)

1. **Paso 1 — Revisión Documental**: El gasto entra en estado "En Revisión"
2. **Paso 2 — Elevar a Finanzas**: Un admin/director solicita el pago
3. **Paso 3 — Liberar Pago**: Finanzas aprueba y ejecuta la transferencia

---

## Stack Tecnológico

| Componente | Tecnología |
|---|---|
| **Backend** | Django 6.1 |
| **Servidor ASGI** | Daphne (para WebSockets) |
| **WebSockets** | Django Channels |
| **Base de datos** | SQLite3 |
| **Frontend** | HTML + CSS + JS vanilla |
| **Gráficos** | Chart.js (CDN) |
| **Iconos** | Lucide Icons (CDN) |
| **Fuentes** | Inter + JetBrains Mono (Google Fonts) |

---

## Equipo EFINTEL I+D+i

- **Miguel Angel Contreras Orozco** — Jefe de Área I+D+i
- **Ginevra Ortega Acuña** — Encargada de Contratos y Auditoría Documental
- **Samuel Abdias Contreras Orozco** — Encargado de Desarrollo Comercial

---

## Estándar de Control de Versiones

Este proyecto utiliza **GitHub Flow** y **Conventional Commits** para mantener un historial limpio y trazabilidad.

### 1. Flujo de Trabajo (GitHub Flow)
- La rama `main` contiene el código estable y de producción.
- Para cada nueva funcionalidad o corrección, se crea una rama nueva a partir de `main` (ej: `feature/agregar-modulo-nomina`).
- Una vez terminado el desarrollo en la rama, se realiza un Pull Request hacia `main`.

### 2. Formato de Commits
Los mensajes de commit deben estar en español, ser descriptivos y concentrarse en los cambios verdaderamente importantes. Seguiremos esta convención adaptada:
`[Tipo] (<alcance opcional>): <Descripción clara del cambio>`

**Tipos permitidos:**
- `NUEVO:` Añade una funcionalidad importante o un nuevo módulo.
- `CORRECCIÓN:` Soluciona un error (bug) en el sistema.
- `MEJORA:` Refactorización o mejora técnica que no añade funcionalidades nuevas ni corrige errores, pero optimiza el código (ej. aplicar POO o hacer consultas más rápidas).
- `CONFIG:` Cambios en configuraciones de infraestructura, Docker, dependencias o variables de entorno.
- `DOCS:` Adiciones importantes a la documentación o manuales.

*Ejemplo:* `NUEVO (gastos): añade soporte multidivisa al momento de pagar a proveedores`

---

## Documentación y Manuales

- [Manual de Usuario Final](docs/MANUAL_USUARIO.md): Guía paso a paso sobre cómo utilizar el ERP, registrar gastos, el flujo de aprobación y monitorear proyectos.

- [Arquitectura y Stack Tecnológico](docs/STACK_ARCHITECTURE.md): Documentación del stack técnico elegido (HTMX, Alpine, Supabase, Django Asíncrono, Celery) y la hoja de ruta de implementación.