@ -438,35 +438,301 @@ Con estos 3 archivos podremos definir cambios mínimos para tener un typecheck l
## Fase D — Documentación (nueva)
## Fase D — Documentación (nueva)
- Principios:
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.
- 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).
- 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.
### D0: Reset estructural y guía de estilo
- Í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.
Objetivo: redefinir la estructura de documentación y marcar qué es canónico vs histórico, sin perder información.
- PR D1: Referencia de variables de entorno
- Tabla completa: nombre, descripción, tipo, por defecto, requerido/optativo, ámbito (core/web), sensibilidad, recarga dinámica.
Cambios:
- Generar .env.example coherente con la tabla.
- Aceptación: 100% de variables de entorno documentadas.
- **README raíz (del repo)**:
- PR D2: Quickstart e instalación
- Reescribirlo con foco en:
- Pasos desde cero a “todo funcionando” (core + web).
- Tagline y pitch corto (qué resuelve, para quién).
- Matriz de comandos: typecheck core/web, dev, build, test, coverage.
- Casos de uso y “no es para ti si…”.
- Aceptación: reproducible en máquina limpia.
- Requisitos para desplegarlo (Evolution API, hosting, etc.).
- PR D3: Uso (web + comandos)
- Vista de alto nivel de cómo funciona.
- Catálogo de comandos (nueva, tomar, soltar, ver, web…): expectativas y ejemplos.
- Enlace claro a `docs/` (Quickstart, Guía de uso, Arquitectura, etc.).
- Guía de la interfaz web (navegación, calendarios ICS, preferencias).
- Aceptación: ejemplos probados manualmente.
- **Definir documentos canónicos en `docs/`** (columna vertebral “v2”):
- PR D4: Operaciones y despliegue
- `docs/README.md` — índice general y guía de estilo.
- Endpoints /health y /metrics, migraciones, copias de seguridad, rotación de claves, runbooks de incidencias.
- `docs/overview.md` — visión general y flujos clave (evaluación).
- Aceptación: runbooks accionables.
- `docs/quickstart.md` — de cero a bot funcionando (dev/prod).
- PR D5: Arquitectura y DB
- `docs/config/env.md` — referencia única de variables de 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).
- 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.
borja