diff --git a/tasks.md b/tasks.md index 3ab08d6..8db0ad3 100644 --- a/tasks.md +++ b/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: @@ -10,266 +10,96 @@ Principio rector: ## 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 - -* Crear estructura de carpetas según README. -* Configurar entorno virtual. -* Instalar dependencias. -* FastAPI levantando correctamente. - -Resultado: API viva sin lógica de negocio. - ---- - -### 1.2 Variables de Entorno - -Definir `.env` con: - -* 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. +- [x] **1.1 Bootstrap del Proyecto** + - [x] Crear estructura de carpetas según README. + - [x] Configurar entorno virtual. + - [x] Instalar dependencias. + - [x] FastAPI levantando correctamente. +- [x] **1.2 Variables de Entorno** + - [x] Definir `.env.example` con las variables necesarias. +- [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.4 Input Handler** + - [ ] Implementar `input_handler.py`. + - [ ] Normalizar texto. + - [ ] Implementar stubs para voz, imagen y PDF. --- ## 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 - -Crear modelos: - -* 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. +- [ ] **2.1 Modelos Pydantic** + - [ ] Crear modelos: `RawInput`, `ExtractedExpense`, `ProvisionalExpense`, `FinalExpense`. +- [ ] **2.2 Estados del Gasto** + - [ ] Definir estados explícitos: `RECEIVED`, `ANALYZED`, `AWAITING_CONFIRMATION`, `CONFIRMED`, `CORRECTED`, `STORED`. --- ## 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 - -Implementar `config_loader.py`: - -* Cargar CSV y JSON. -* Normalizar texto. -* 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. +- [ ] **3.1 Loader de Configuración** + - [ ] Implementar `config_loader.py`. +- [ ] **3.2 Matching de Proveedores** + - [ ] Implementar matching por nombre y aliases. +- [ ] **3.3 Matching de Keywords** + - [ ] Implementar búsqueda de keywords en descripciones. --- ## 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) - -* Voz → transcripción IA. -* Imagen → OCR IA. -* PDF → extracción semiestructurada. - -Unificar todo en texto limpio. - ---- - -### 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. +- [ ] **4.1 Extracción Multimodal (Completa)** + - [ ] Voz → transcripción IA. + - [ ] Imagen → OCR IA. + - [ ] PDF → extracción semiestructurada. +- [ ] **4.2 Clasificación en Cascada** + - [ ] Implementar pipeline: Proveedores → Keywords → IA. +- [ ] **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. --- ## 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 - -Enviar al usuario: - -* Proveedor -* Monto -* 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. +- [ ] **5.1 Mensaje de Confirmación** + - [ ] Enviar resumen del gasto procesado al usuario. +- [ ] **5.2 Parsing de Correcciones** + - [ ] Implementar la capacidad de aceptar correcciones en lenguaje natural. +- [ ] **5.3 The Auditor** + - [ ] Implementar el agente "Auditor" para registrar todos los cambios. --- ## 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 - -* Hojas separadas: personal / negocio. -* Append-only. -* Manejo de errores de red. - ---- - -### 6.2 Limpieza de Estados Temporales - -* Eliminar colas provisionales. -* Asegurar idempotencia. - -Resultado: gasto almacenado y ciclo cerrado. +- [ ] **6.1 Google Sheets** + - [ ] Implementar la escritura de datos en Google Sheets. +- [ ] **6.2 Limpieza de Estados Temporales** + - [ ] Asegurar la limpieza de datos temporales tras el procesamiento. --- ## Fase 7 – Hardening y Preparación a Futuro -### 7.1 Logs y Errores +**Objetivo:** Fortalecer el sistema y prepararlo para escalar. -* Logs estructurados. -* DEBUG solo en dev. -* Mensajes claros al usuario. - -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. +- [ ] **7.1 Logs y Errores** + - [ ] Implementar logs estructurados y un manejo de errores robusto. +- [ ] **7.2 Preparación para Escalar** + - [ ] Diseñar el sistema para soportar múltiples usuarios en el futuro.