mirror of
https://github.com/marcogll/telegram_expenses_controller.git
synced 2026-01-13 21:35:15 +00:00
Merge pull request #2 from marcogll/feat-initial-project-structure-14463650289909895681
Update tasks.md to a to-do list
This commit is contained in:
Marco Gallegos
286
tasks.md
286
tasks.md
@@ -1,6 +1,6 @@
|
|||||||
# TASKS.md
|
# TASKS.md - To-Do List
|
||||||
|
|
||||||
Este documento define un **plan de ejecución secuencial**, con **menos fases pero más coherentes**, pensadas para ejecutarse **una tras otra sin ambigüedad**, ideal para un agente de IA desarrollador o un equipo técnico.
|
Este documento define el plan de ejecución del proyecto.
|
||||||
|
|
||||||
Principio rector:
|
Principio rector:
|
||||||
|
|
||||||
@@ -10,266 +10,96 @@ Principio rector:
|
|||||||
|
|
||||||
## Fase 1 – Base del Sistema (Infraestructura + Entrada)
|
## Fase 1 – Base del Sistema (Infraestructura + Entrada)
|
||||||
|
|
||||||
**Objetivo:** recibir mensajes de Telegram y dejarlos listos para procesar.
|
**Objetivo:** Recibir datos de gastos y dejarlos listos para procesar.
|
||||||
|
|
||||||
### 1.1 Bootstrap del Proyecto
|
- [x] **1.1 Bootstrap del Proyecto**
|
||||||
|
- [x] Crear estructura de carpetas según README.
|
||||||
* Crear estructura de carpetas según README.
|
- [x] Configurar entorno virtual.
|
||||||
* Configurar entorno virtual.
|
- [x] Instalar dependencias.
|
||||||
* Instalar dependencias.
|
- [x] FastAPI levantando correctamente.
|
||||||
* FastAPI levantando correctamente.
|
- [x] **1.2 Variables de Entorno**
|
||||||
|
- [x] Definir `.env.example` con las variables necesarias.
|
||||||
Resultado: API viva sin lógica de negocio.
|
- [x] **1.3 Webhook y Entrada de Datos**
|
||||||
|
- **NOTA:** Se ha modificado el enfoque. En lugar de un webhook directo de Telegram, se utiliza **n8n** para manejar la recepción de datos. La aplicación expone un endpoint genérico `/process-expense` para este propósito.
|
||||||
---
|
- [x] Endpoint `/process-expense` implementado en FastAPI.
|
||||||
|
- [x] El endpoint recibe y loguea el payload.
|
||||||
### 1.2 Variables de Entorno
|
- [ ] **1.4 Input Handler**
|
||||||
|
- [ ] Implementar `input_handler.py`.
|
||||||
Definir `.env` con:
|
- [ ] Normalizar texto.
|
||||||
|
- [ ] Implementar stubs para voz, imagen y PDF.
|
||||||
* TELEGRAM_BOT_TOKEN
|
|
||||||
* OPENAI_API_KEY
|
|
||||||
* GOOGLE_APPLICATION_CREDENTIALS
|
|
||||||
* SPREADSHEET_ID
|
|
||||||
* ENV (dev / prod)
|
|
||||||
|
|
||||||
El sistema **no debe arrancar** si falta alguna.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 1.3 Webhook de Telegram
|
|
||||||
|
|
||||||
* Endpoint `/telegram/webhook`.
|
|
||||||
* Validar origen del mensaje.
|
|
||||||
* Log completo del payload en modo dev.
|
|
||||||
|
|
||||||
Resultado: mensajes entran y se registran.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 1.4 Input Handler
|
|
||||||
|
|
||||||
Implementar `input_handler.py`:
|
|
||||||
|
|
||||||
* Texto.
|
|
||||||
* Voz (solo stub inicialmente).
|
|
||||||
* Imagen (solo stub inicialmente).
|
|
||||||
* PDF (solo stub).
|
|
||||||
|
|
||||||
Todo debe normalizarse a texto crudo.
|
|
||||||
|
|
||||||
Resultado: cualquier input termina como texto limpio.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fase 2 – Modelo de Datos y Estados
|
## Fase 2 – Modelo de Datos y Estados
|
||||||
|
|
||||||
**Objetivo:** tener claridad absoluta sobre qué es un gasto y en qué estado vive.
|
**Objetivo:** Tener claridad absoluta sobre qué es un gasto y en qué estado vive.
|
||||||
|
|
||||||
### 2.1 Modelos Pydantic
|
- [ ] **2.1 Modelos Pydantic**
|
||||||
|
- [ ] Crear modelos: `RawInput`, `ExtractedExpense`, `ProvisionalExpense`, `FinalExpense`.
|
||||||
Crear modelos:
|
- [ ] **2.2 Estados del Gasto**
|
||||||
|
- [ ] Definir estados explícitos: `RECEIVED`, `ANALYZED`, `AWAITING_CONFIRMATION`, `CONFIRMED`, `CORRECTED`, `STORED`.
|
||||||
* RawInput
|
|
||||||
* ExtractedExpense
|
|
||||||
* ProvisionalExpense
|
|
||||||
* FinalExpense
|
|
||||||
|
|
||||||
Cada modelo debe validar su propio dominio.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2.2 Estados del Gasto
|
|
||||||
|
|
||||||
Definir estados explícitos:
|
|
||||||
|
|
||||||
* RECEIVED
|
|
||||||
* ANALYZED
|
|
||||||
* AWAITING_CONFIRMATION
|
|
||||||
* CONFIRMED
|
|
||||||
* CORRECTED
|
|
||||||
* STORED
|
|
||||||
|
|
||||||
No se permiten saltos implícitos.
|
|
||||||
|
|
||||||
Resultado: máquina de estados clara.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fase 3 – Configuración como Lógica
|
## Fase 3 – Configuración como Lógica
|
||||||
|
|
||||||
**Objetivo:** mover la inteligencia determinística fuera del código.
|
**Objetivo:** Mover la inteligencia determinística fuera del código.
|
||||||
|
|
||||||
### 3.1 Loader de Configuración
|
- [ ] **3.1 Loader de Configuración**
|
||||||
|
- [ ] Implementar `config_loader.py`.
|
||||||
Implementar `config_loader.py`:
|
- [ ] **3.2 Matching de Proveedores**
|
||||||
|
- [ ] Implementar matching por nombre y aliases.
|
||||||
* Cargar CSV y JSON.
|
- [ ] **3.3 Matching de Keywords**
|
||||||
* Normalizar texto.
|
- [ ] Implementar búsqueda de keywords en descripciones.
|
||||||
* Cachear en memoria.
|
|
||||||
* Validar esquema mínimo.
|
|
||||||
|
|
||||||
Fallar rápido si algo está mal configurado.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.2 Matching de Proveedores
|
|
||||||
|
|
||||||
* Matching por nombre y aliases.
|
|
||||||
* Coincidencia parcial, case-insensitive.
|
|
||||||
* Retornar score de match.
|
|
||||||
|
|
||||||
Regla dura: si hay match fuerte, **no usar IA**.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.3 Matching de Keywords
|
|
||||||
|
|
||||||
* Buscar keywords en descripciones.
|
|
||||||
* Permitir múltiples matches.
|
|
||||||
* Resolver conflictos por prioridad.
|
|
||||||
|
|
||||||
Resultado: clasificación determinística siempre que sea posible.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fase 4 – The Analyst (Procesamiento Inteligente)
|
## Fase 4 – The Analyst (Procesamiento Inteligente)
|
||||||
|
|
||||||
**Objetivo:** convertir texto crudo en un gasto provisional estructurado.
|
**Objetivo:** Convertir texto crudo en un gasto provisional estructurado.
|
||||||
|
|
||||||
### 4.1 Extracción Multimodal (Completa)
|
- [ ] **4.1 Extracción Multimodal (Completa)**
|
||||||
|
- [ ] Voz → transcripción IA.
|
||||||
* Voz → transcripción IA.
|
- [ ] Imagen → OCR IA.
|
||||||
* Imagen → OCR IA.
|
- [ ] PDF → extracción semiestructurada.
|
||||||
* PDF → extracción semiestructurada.
|
- [ ] **4.2 Clasificación en Cascada**
|
||||||
|
- [ ] Implementar pipeline: Proveedores → Keywords → IA.
|
||||||
Unificar todo en texto limpio.
|
- [ ] **4.3 Validación Fiscal Básica**
|
||||||
|
- [ ] Implementar detección de CFDI y validación de RFC.
|
||||||
---
|
- [ ] **4.4 Score de Confianza**
|
||||||
|
- [ ] Calcular y persistir el score de confianza del análisis.
|
||||||
### 4.2 Clasificación en Cascada
|
|
||||||
|
|
||||||
Pipeline obligatorio:
|
|
||||||
|
|
||||||
1. Proveedores
|
|
||||||
2. Keywords
|
|
||||||
3. Inferencia IA (último recurso)
|
|
||||||
|
|
||||||
Registrar siempre **por qué camino** se tomó la decisión.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4.3 Validación Fiscal Básica
|
|
||||||
|
|
||||||
* Detectar CFDI.
|
|
||||||
* Extraer RFC receptor.
|
|
||||||
* Comparar con `user_config.json`.
|
|
||||||
* Anotar observaciones, no bloquear.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4.4 Score de Confianza
|
|
||||||
|
|
||||||
* Regla directa → alta.
|
|
||||||
* Keywords → media.
|
|
||||||
* IA pura → baja.
|
|
||||||
|
|
||||||
Persistir el score.
|
|
||||||
|
|
||||||
Resultado: gasto provisional listo para revisión humana.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fase 5 – Interacción y Auditoría
|
## Fase 5 – Interacción y Auditoría
|
||||||
|
|
||||||
**Objetivo:** asegurar control humano y trazabilidad.
|
**Objetivo:** Asegurar control humano y trazabilidad.
|
||||||
|
|
||||||
### 5.1 Mensaje de Confirmación
|
- [ ] **5.1 Mensaje de Confirmación**
|
||||||
|
- [ ] Enviar resumen del gasto procesado al usuario.
|
||||||
Enviar al usuario:
|
- [ ] **5.2 Parsing de Correcciones**
|
||||||
|
- [ ] Implementar la capacidad de aceptar correcciones en lenguaje natural.
|
||||||
* Proveedor
|
- [ ] **5.3 The Auditor**
|
||||||
* Monto
|
- [ ] Implementar el agente "Auditor" para registrar todos los cambios.
|
||||||
* Categoría
|
|
||||||
* Tipo (personal / negocio)
|
|
||||||
* Observaciones
|
|
||||||
* Score de confianza
|
|
||||||
|
|
||||||
Formato corto, claro y editable.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5.2 Parsing de Correcciones
|
|
||||||
|
|
||||||
Aceptar lenguaje natural:
|
|
||||||
|
|
||||||
* "el monto es 180"
|
|
||||||
* "es personal"
|
|
||||||
* "la fecha fue ayer"
|
|
||||||
|
|
||||||
No asumir intención: solo cambios explícitos.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5.3 The Auditor
|
|
||||||
|
|
||||||
* Comparar estado previo vs nuevo.
|
|
||||||
* Aplicar solo cambios solicitados.
|
|
||||||
* Registrar auditoría:
|
|
||||||
|
|
||||||
```
|
|
||||||
AUDITORÍA: campo X cambió de A a B (timestamp)
|
|
||||||
```
|
|
||||||
|
|
||||||
Nada se sobreescribe silenciosamente.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fase 6 – Persistencia y Cierre
|
## Fase 6 – Persistencia y Cierre
|
||||||
|
|
||||||
**Objetivo:** guardar datos finales de forma segura y limpia.
|
**Objetivo:** Guardar datos finales de forma segura y limpia.
|
||||||
|
|
||||||
### 6.1 Google Sheets
|
- [ ] **6.1 Google Sheets**
|
||||||
|
- [ ] Implementar la escritura de datos en Google Sheets.
|
||||||
* Hojas separadas: personal / negocio.
|
- [ ] **6.2 Limpieza de Estados Temporales**
|
||||||
* Append-only.
|
- [ ] Asegurar la limpieza de datos temporales tras el procesamiento.
|
||||||
* Manejo de errores de red.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 6.2 Limpieza de Estados Temporales
|
|
||||||
|
|
||||||
* Eliminar colas provisionales.
|
|
||||||
* Asegurar idempotencia.
|
|
||||||
|
|
||||||
Resultado: gasto almacenado y ciclo cerrado.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fase 7 – Hardening y Preparación a Futuro
|
## Fase 7 – Hardening y Preparación a Futuro
|
||||||
|
|
||||||
### 7.1 Logs y Errores
|
**Objetivo:** Fortalecer el sistema y prepararlo para escalar.
|
||||||
|
|
||||||
* Logs estructurados.
|
- [ ] **7.1 Logs y Errores**
|
||||||
* DEBUG solo en dev.
|
- [ ] Implementar logs estructurados y un manejo de errores robusto.
|
||||||
* Mensajes claros al usuario.
|
- [ ] **7.2 Preparación para Escalar**
|
||||||
|
- [ ] Diseñar el sistema para soportar múltiples usuarios en el futuro.
|
||||||
Nunca perder un gasto silenciosamente.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 7.2 Preparación para Escalar
|
|
||||||
|
|
||||||
* Aislar config por `user_id`.
|
|
||||||
* Preparar soporte multiusuario.
|
|
||||||
* Dejar hooks para reportes futuros.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Regla Final para el Agente
|
|
||||||
|
|
||||||
* Ejecutar fases en orden.
|
|
||||||
* No adelantar optimizaciones.
|
|
||||||
* Si una decisión no es obvia, documentarla.
|
|
||||||
|
|
||||||
El sistema debe sentirse **confiable, explicable y humano**, antes que impresionante.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user