Documentación del Sistema

Appearance

Fase 3.4: Documentación ​

← Anterior: 3.3 Systemd | Índice General →

Actualizar server/CLAUDE.md ​

Archivo: */backend/background-jobs-system.md

Rama: docs/background-jobs-claudemd

Fase: 3.4: Documentación

Estimación: 3 horas

Dependencias: Todas tareas Fase 3.1-3.3

Deliverables ​

  • [ ] Sección: "Background Jobs System"
    • [ ] Overview (qué son, cuándo usarlos)
    • [ ] Architecture (JobDispatcher, JobRunner, Handlers)
    • [ ] Multi-tenancy (schema isolation)
    • [ ] Creating custom handlers (pasos, ejemplo)
  • [ ] Workflow: "Working on Background Jobs"
    • [ ] Crear handler → test → integrar
  • [ ] Configuration section (env vars, flags)
  • [ ] Troubleshooting (worker no arranca, stuck jobs, etc)
  • [ ] Update version info si necesario

Crear docs/backend/background-jobs-system.md ​

Archivo: */backend/background-jobs-system.md

Rama: docs/background-jobs-technical

Fase: 3.4: Documentación

Estimación: 4 horas

Dependencias: Todas tareas Fase 3.1-3.3

Deliverables ​

  • [ ] Architecture section
    • [ ] 5-layer mapping (jobController → service → domain logic)
    • [ ] Database schema diagram (Mermaid)
    • [ ] Sequence diagrams: dispatch, execute, notify
  • [ ] API Documentation
    • [ ] POST /jobs (request/response examples)
    • [ ] GET /jobs/:id (query params)
    • [ ] GET /jobs/stream/:id (SSE format)
    • [ ] GET /admin/jobs/failed (filtering/pagination)
    • [ ] GET /jobs/metrics (Prometheus format)
    • [ ] GET /jobs/health (response format)
  • [ ] Database Schema
    • [ ] background_jobs table (columns, types, constraints)
    • [ ] notifications table
  • [ ] Creating Custom Handlers
    • [ ] Step-by-step guide
    • [ ] Template code
    • [ ] Error handling patterns
    • [ ] Logging patterns
    • [ ] Progress tracking
  • [ ] Multi-tenancy
    • [ ] Schema isolation guarantees
    • [ ] Testing multi-tenant scenarios
  • [ ] Deployment & Operations
    • [ ] Installing systemd service
    • [ ] Viewing/monitoring logs
    • [ ] Handling failed jobs
    • [ ] Performance tuning
    • [ ] Backup strategy
  • [ ] Examples
    • [ ] BatchInvoicingJobHandler walkthrough
    • [ ] Custom email handler example
    • [ ] Custom report generation example

Crear docs/architecture/background-jobs-architecture.md ​

Archivo: */architecture/background-jobs-architecture.md

Rama: docs/background-jobs-architecture

Fase: 3.4: Documentación

Estimación: 3 horas

Dependencias: Todas tareas Fase 3.1-3.3

Deliverables ​

  • [ ] Conceptual Overview
    • [ ] Why background jobs (offload long-running tasks)
    • [ ] Trade-offs vs real-time processing
    • [ ] MVP → Real-time → Production evolution
  • [ ] Polling vs SSE vs Future Options
    • [ ] Phase 1 MVP: Polling advantages/disadvantages
    • [ ] Phase 2 SSE: Real-time, reliability, fallback
    • [ ] Future: Message queues (RabbitMQ, Redis)
  • [ ] Failure Handling Strategy
    • [ ] Exponential backoff rationale
    • [ ] Max retries configuration
    • [ ] Stale job cleanup
  • [ ] Monitoring & Observability
    • [ ] Metrics to track
    • [ ] Alert strategies
    • [ ] Logging aggregation options
  • [ ] Multi-Tenancy Considerations
    • [ ] Schema isolation at job level
    • [ ] Job isolation guarantees
    • [ ] Testing multi-tenant scenarios
  • [ ] Future Enhancements
    • [ ] Message queues
    • [ ] Job scheduling (cron-like jobs)
    • [ ] Webhooks for notifications
    • [ ] Job dependencies/workflows
  • [ ] Decision Records
    • [ ] Why PostgreSQL NOTIFY vs Redis
    • [ ] Why exponential backoff vs fixed delay
    • [ ] Why systemd vs container orchestration

Actualizar OpenAPI documentation ​

Archivo: */backend/background-jobs-system.md

Rama: docs/background-jobs-openapi

Fase: 3.4: Documentación

Estimación: 3 horas

Dependencias: Crear docs técnico

Deliverables ​

  • [ ] Agregar paths a OpenAPI spec (server/docs/openapi.yaml o generado)
    • [ ] POST /jobs
    • [ ] GET /jobs/:id
    • [ ] GET /jobs
    • [ ] GET /jobs/:id/stream (SSE)
    • [ ] POST /admin/jobs/:id/retry
    • [ ] GET /admin/jobs/failed
    • [ ] GET /jobs/metrics
    • [ ] GET /jobs/health
  • [ ] Schemas: BackgroundJob, Notification, MetricsResponse
  • [ ] Examples con payloads reales
  • [ ] Security schemes (JWT)
  • [ ] Validar generación de cliente (si automated)

Actualizar CHANGELOG.md ​

Archivo: */backend/background-jobs-system.md

Rama: docs/background-jobs-changelog

Fase: 3.4: Documentación

Estimación: 2 horas

Dependencias: Actualizar OpenAPI documentation

Deliverables ​

  • [ ] Agregar entrada versión (ej: v3.11.0)
    • [ ] Features
      • [ ] Background Jobs system (MVP polling)
      • [ ] SSE real-time updates
      • [ ] Retry logic with exponential backoff
      • [ ] Health checks y monitoring
    • [ ] Breaking Changes: Ninguno (feature compatible)
    • [ ] Migration Guide: Cómo habilitar/usar
    • [ ] Performance: Benchmarks antes/después
  • [ ] Commit message format

← Anterior: 3.3 Systemd | Índice General →