diff --git a/docs/2025-11-01-plan-refactor-tecnico.md b/docs/2025-11-01-plan-refactor-tecnico.md index 8073b28..ef74fad 100644 --- a/docs/2025-11-01-plan-refactor-tecnico.md +++ b/docs/2025-11-01-plan-refactor-tecnico.md @@ -438,35 +438,301 @@ Con estos 3 archivos podremos definir cambios mínimos para tener un typecheck l ## Fase D — Documentación (nueva) -- Principios: - - Markdown en /docs como fuente de verdad; sin dependencias nuevas; build opcional más adelante. - - Verificación simple en CI para comprobar “completitud” (p. ej., grep de variables de entorno usadas vs documentadas). -- PR D0: Estructura y guía de estilo - - docs/README (mapa de contenidos), guía de estilo y convenciones. - - Índice propuesto: Quickstart, Instalación, Configuración (ENV), Uso web, Uso por chat/comandos, Operaciones, Arquitectura, Seguridad, Contribución, Troubleshooting/FAQ. - - Aceptación: esqueleto aprobado y navegación clara. -- PR D1: Referencia de variables de entorno - - Tabla completa: nombre, descripción, tipo, por defecto, requerido/optativo, ámbito (core/web), sensibilidad, recarga dinámica. - - Generar .env.example coherente con la tabla. - - Aceptación: 100% de variables de entorno documentadas. -- PR D2: Quickstart e instalación - - Pasos desde cero a “todo funcionando” (core + web). - - Matriz de comandos: typecheck core/web, dev, build, test, coverage. - - Aceptación: reproducible en máquina limpia. -- PR D3: Uso (web + comandos) - - Catálogo de comandos (nueva, tomar, soltar, ver, web…): expectativas y ejemplos. - - Guía de la interfaz web (navegación, calendarios ICS, preferencias). - - Aceptación: ejemplos probados manualmente. -- PR D4: Operaciones y despliegue - - Endpoints /health y /metrics, migraciones, copias de seguridad, rotación de claves, runbooks de incidencias. - - Aceptación: runbooks accionables. -- PR D5: Arquitectura y DB - - Visión por capas (core, servicios, web), flujos (webhook → colas → tareas), esquema SQLite principal. - - Aceptación: suficiente para nuevos contribuidores. -- PR D6: Contribución y ADRs - - Cómo proponer cambios, estándares TS/UTC/ICS, política de versiones. - - ADRs para decisiones clave (UTC, DB locator, ICS all-day). - - Aceptación: plantilla de PR y guía de contribución listas. +El objetivo de esta fase es frenar la “entropía documental” actual, ofrecer una narración clara para quien llega nuevo y, a la vez, dejar una base sólida para seguir evolucionando el sistema sin añadir deuda técnica. + +### Principios + +- Markdown en /docs como fuente de verdad; sin dependencias nuevas; build opcional más adelante. +- Documentación estructurada por **qué quiere hacer la persona lectora** (evaluar, desplegar, operar, contribuir), no por “lista de archivos existentes”. +- README raíz orientado a adopción (pitch, casos de uso, requisitos), con enlaces claros a la documentación detallada. +- Documentación “v2” claramente separada de planes históricos y documentos de trabajo. +- Verificación simple en CI para comprobar “completitud” (p. ej., grep de variables de entorno usadas vs documentadas). + +### D0: Reset estructural y guía de estilo + +Objetivo: redefinir la estructura de documentación y marcar qué es canónico vs histórico, sin perder información. + +Cambios: + +- **README raíz (del repo)**: + - Reescribirlo con foco en: + - Tagline y pitch corto (qué resuelve, para quién). + - Casos de uso y “no es para ti si…”. + - Requisitos para desplegarlo (Evolution API, hosting, etc.). + - Vista de alto nivel de cómo funciona. + - Enlace claro a `docs/` (Quickstart, Guía de uso, Arquitectura, etc.). + +- **Definir documentos canónicos en `docs/`** (columna vertebral “v2”): + - `docs/README.md` — índice general y guía de estilo. + - `docs/overview.md` — visión general y flujos clave (evaluación). + - `docs/quickstart.md` — de cero a bot funcionando (dev/prod). + - `docs/config/env.md` — referencia única de variables de entorno. + - `docs/usage/commands.md` — uso por WhatsApp (comandos). + - `docs/usage/web.md` — uso de la interfaz web. + - `docs/architecture.md` — arquitectura lógica y DB locator. + - `docs/operations.md` — operación, métricas, backups, health/metrics. + - `docs/contributing.md` — cómo tocar el código sin romper convenciones. + +- **Crear un área de documentación histórica**: + - Nuevo directorio: `docs/legacy/` (o similar). + - Mover allí: + - Planes antiguos (`plan-*.md`, `*-plan.md`) que ya no encajen con el estado actual. + - Documentos de trabajo y notas de diseño que han quedado superadas por este plan. + - Añadir `docs/legacy/README.md` explicando que: + - Son documentos históricos, útiles como contexto, pero **no** representan el estado actual ni la decisión vigente. + +- **Guía de estilo mínima en `docs/README.md`**: + - Idioma principal: español para texto narrativo; identificadores y nombres técnicos en inglés. + - Convenciones de nombres de archivos (kebab-case, sufijos como `-guide`, etc.). + - Expectativas por documento (público objetivo y nivel técnico). + +Métricas de aceptación: + +- README raíz reescrito y enlazando a la nueva estructura. +- `docs/README.md` actualizado con el índice “v2” y la guía de estilo. +- Todos los planes/documentos obsoletos movidos a `docs/legacy/` y etiquetados como históricos. + +### D1: Referencia de variables de entorno + +Objetivo: consolidar una tabla única y fiable de configuración por entorno. + +Cambios: + +- Construir un inventario completo: + - Partir del `git grep process.env` (ya recogido en este documento). + - Complementar con las variables definidas en `.env.example`. + - Identificar: + - variables usadas en código pero ausentes en `.env.example`, + - variables presentes en `.env.example` que ya no se usan. + +- Crear `docs/config/env.md`: + - Tabla con columnas: + - **VARIABLE** | **Descripción** | **Tipo** | **Por defecto** | **Obligatoria** | **Ámbito (core/web)** | **Sensible (sí/no)**. + - Sección explicando: + - cómo se cargan (ficheros `.env` vs entorno), + - qué variables son imprescindibles para arrancar, + - particularidades en test (variables que los tests fuerzan o suponen). + +- Sincronizar `.env.example` con la tabla: + - Mismas variables. + - Comentarios alineados con la descripción de `docs/config/env.md`. + - README raíz solo enumera un subconjunto (“configuración esencial”) y enlaza a este documento para el resto. + +Métricas de aceptación: + +- `docs/config/env.md` cubre el 100% de las variables utilizadas en código. +- `.env.example` sin variables huérfanas ni faltantes respecto al inventario. +- Potencial check de CI: script simple que compare nombres de variables entre código, `env.md` y `.env.example`. + +### D2: Quickstart e instalación + +Objetivo: permitir que alguien nuevo pase de “clonar el repo” a “tengo el bot funcionando” sin leer todo el resto. + +Cambios: + +- Crear/actualizar `docs/quickstart.md`: + - Requisitos: + - Bun/Node versión recomendada. + - Instancia de Evolution API. + - Almacenamiento para SQLite. + - Pasos: + - Clonar repositorio e instalar dependencias. + - Copiar `.env.example` y rellenar variables mínimas. + - Arrancar en desarrollo (core + web). + - Arrancar en producción (comandos de build + start). + - “Happy path”: + - ejemplo de mensaje de WhatsApp para crear una tarea, + - cómo verla en la web (/app), + - cómo confirmar que /health y /metrics responden. + +- Alinear README raíz con este quickstart: + - Sección “Instalación rápida” condensando los pasos principales. + - Enlace explícito a `docs/quickstart.md` para detalles. + +Métricas de aceptación: + +- Una persona que no conoce el proyecto puede seguir `docs/quickstart.md` en una máquina limpia y terminar con: + - webhook recibiendo eventos, + - tareas visibles en /app, + - métricas en /metrics. + +### D3: Uso (web + comandos) + +Objetivo: documentar claramente la experiencia de uso, separando canales (WhatsApp vs web) y evitando duplicidad. + +Cambios: + +- Reorganizar la documentación de uso actual en dos archivos: + + - `docs/usage/commands.md`: + - Basado en `docs/USER_GUIDE.md` y `docs/commands-inventory.md`. + - Contenido: + - prefijo de comandos y principios (DM vs grupo, fechas, rate limit), + - catálogo de comandos con alias, parámetros y ejemplos, + - notas sobre: + - interpretación de fechas (“hoy”, “mañana”, YYYY-MM-DD), + - menciones reales vs tokens `@número`, + - comportamiento en grupo vs DM, + - sección de administración (/admin…). + + - `docs/usage/web.md`: + - Basado en `plan-diseno-web.md`, `plan-web-fases.md` y el estado actual de la UI. + - Contenido: + - estructura de `/app` (lista de tareas, grupos, preferencias), + - flujo típico de uso desde web (reclamar/soltar, editar, completar), + - relación entre lo que ves en WhatsApp y lo que ves en la web, + - vistas de calendario/ICS y cómo se consumen. + +- Dejar `docs/USER_GUIDE.md` como entrada que redirige: + - Puede convertirse en un índice breve que apunte a `usage/commands.md` y `usage/web.md`, o bien moverse a `docs/legacy/` cuando la nueva estructura esté madura. + +Métricas de aceptación: + +- No hay duplicación significativa de contenido entre README, `USER_GUIDE`, `usage/commands` y `usage/web`. +- Los ejemplos de comandos están actualizados y probados manualmente (al menos los principales). + +### D4: Operaciones y despliegue + +Objetivo: facilitar la vida a quien opera Taskbot en producción (observabilidad, mantenimiento, CI/CD). + +Cambios: + +- Crear/actualizar `docs/operations.md`: + - Basado en `operations.md`, `metrics-plan.md`, `CI-CD-PLAN.md` y `docs/grafana/`. + - Contenido: + - **Despliegue**: + - opciones típicas (proceso único vs supervisado por systemd, contenedores, etc.), + - recomendaciones de recursos y almacenamiento, + - interacción con Evolution API (timeouts, health checks). + - **Migraciones y base de datos**: + - cómo y cuándo se ejecutan migraciones, + - política de WAL y PRAGMAs más importantes, + - estrategias de backup/restore de SQLite. + - **Observabilidad**: + - uso de `/health` (qué comprueba, señales de fallo), + - uso de `/metrics` (Prometheus/JSON, flags de configuración), + - referencia al dashboard de Grafana (`docs/grafana/taskbot-metrics.json`): qué gráficos hay y qué significan. + - **Schedulers y tareas periódicas**: + - sincronización de grupos, + - recordatorios, + - limpieza de cola de respuestas, + - cómo ajustar intervalos y qué implicaciones tienen. + +- Conectar con variables de entorno: + - Enlazar a `docs/config/env.md` para cada opción relevante (p. ej. `GROUP_SYNC_INTERVAL_MS`, `RQ_*`, `METRICS_*`). + +Métricas de aceptación: + +- Operador externo puede entender: + - qué mirar en caso de problemas (health/metrics/logs), + - cómo hacer backup/restore sin corromper la DB, + - cómo cambiar la frecuencia de tareas periódicas con seguridad. + +### D5: Arquitectura y DB + +Objetivo: ofrecer una visión clara de cómo está organizado el sistema internamente, especialmente tras el refactor (servicios extraídos, DB locator, ICS central). + +Cambios: + +- Consolidar `docs/architecture.md`: + - Integrar/actualizar contenido de `architecture.md`, `overview.md`, `database.md` y este propio plan. + - Contenido: + - **Componentes principales**: + - servidor HTTP (WebhookServer y handlers /webhook, /health, /metrics), + - servicios de dominio (TaskService, ResponseQueue, GroupSync, Reminders, Admin…), + - cola de respuestas y cliente Evolution, + - app web SvelteKit. + - **DB Locator**: + - motivación, + - API básica (`getDb`/`setDb`/`withDb`), + - cómo se usa en servicios y tests. + - **Flujos clave**: + - mensaje entrante → comando → creación/actualización de tarea → encolado de respuesta/reacción, + - sincronización de grupos y membresías, + - recordatorios. + - **Base de datos**: + - tablas principales (tasks, task_assignments, groups, group_members, response_queue, user_preferences…), + - invariantes importantes, + - decisiones de diseño (WAL, migraciones up-only). + +- Mantener `docs/database.md` como detalle de esquema: + - Puede centrarse en: + - descripción tabla a tabla, + - índices relevantes, + - ejemplos de consultas típicas, + - enlazado desde `docs/architecture.md`. + +Métricas de aceptación: + +- Contributors nuevos pueden entender dónde “colgar” código nuevo (por ejemplo, un nuevo servicio, una nueva tabla o un nuevo comando). +- Este plan de refactor técnico se percibe como coherente con la arquitectura documentada (no como un documento separado y divergente). + +### D6: Contribución y ADRs + +Objetivo: ayudar a futuras personas contribuidoras (incluido tú mismo “del futuro”) a cambiar el sistema sin romper las convenciones ni repetir debates ya resueltos. + +Cambios: + +- Crear/actualizar `docs/contributing.md`: + - Contenido: + - cómo montar entorno de desarrollo (dependencias, comandos básicos), + - cómo ejecutar: + - typecheck core (`bun run typecheck:core`), + - typecheck web (`bun run typecheck:web`), + - tests y cobertura (`bun test --coverage`), + - convenciones de código: + - UTC y formato de timestamps en SQLite, + - uso de helpers centralizados (datetime, crypto, helpers de test), + - tipos estrictos en TS (flags activados y expectativas), + - uso del DB locator. + - criterios para abrir PRs: + - tests verdes, + - sin cambios funcionales en lotes que se declaran “refactor internos”, + - cuándo y cómo añadir un ADR. + - referencia rápida a how-tos existentes: + - `how-to/adding-command.md`, + - `how-to/adding-migration.md`, + - `how-to/adjusting-group-sync.md`, + - `how-to/adding-env.md`. + +- Consolidar ADRs: + - Mantener `docs/adr/*.md` como registro de decisiones de arquitectura. + - Añadir ADRs nuevos cuando: + - se tomen decisiones de largo plazo (p. ej., i18n, políticas de rate limiting, cambios de almacenamiento). + - Desde `docs/contributing.md`, explicar: + - cuándo merece la pena un ADR, + - cómo estructurarlo (título, contexto, decisión, consecuencias). + +Métricas de aceptación: + +- Contributors pueden: + - saber qué comandos ejecutar antes de abrir PR, + - entender las decisiones ya tomadas (UTC, DB locator, ICS, estructura de servicios), + - no tener que “descubrirlas” leyendo código o este plan. + +### Orden recomendado de ejecución para Fase D + +1. Ejecutar **D0** (reset estructural): + - nuevo README raíz orientado a adopción, + - índice v2 en `docs/README.md`, + - movimiento de documentos antiguos a `docs/legacy/`. + +2. Ejecutar **D1** (env) y **D2** (quickstart) en paralelo: + - cerrar la historia de “cómo configuro esto” y “cómo lo echo a andar”. + +3. Completar **D3** (uso commands/web) apoyándose en la guía de usuario actual, reorganizando sin perder contenido útil. + +4. Redondear con **D4** (operaciones) y **D5** (arquitectura/DB) usando este plan de refactor como referencia. + +5. Cerrar con **D6** (contribución+ADRs), conectando: + - decisiones técnicas ya tomadas, + - how-tos existentes, + - y el pipeline de typecheck/tests. + +Esta Fase D se coordina con los lotes técnicos previo/posteriores: + +- depende de que el estado del core/web esté relativamente estable (Lotes 0–6), +- y sirve como preparación explícita antes de acometer cambios más invasivos (i18n, nuevos comandos, cambios de esquema), reduciendo el riesgo de deuda técnica futura. ## Fase I — Internacionalización (nueva)