Sistema de Rendiciones de Gastos

Documentación de negocio y de cómo están armados los flujos: carga del gasto, aprobación multinivel, firma hacia nómina, formularios custom por empresa (circuito Viáticos APSV), notificaciones, reportes Excel, multiempresa, import de personas e IA opcional.

1. Resumen ejecutivo

El sistema permite a empleados de una empresa (o de sus subempresas) cargar rendiciones de gastos con fecha, monto, observaciones y comprobantes; pasarlas por un workflow de aprobación configurable de N niveles; listar el proceso completo; exportar a Excel; e integrar el resultado con nómina u otros sistemas vía la misma API REST.

Capacidades Must

1. Carga de rendición (fecha, observaciones, monto, adjuntos imagen/PDF).
2. Workflow con N niveles configurables y avance secuencial.
3. Listados con cabecera + adjuntos + historial por nivel.
4. Exportación Excel del listado (mismo alcance de filtros).
5. Multiempresa nativo + subempresas (árbol parentId).
6. API-first / todo en services; mismo contrato para front e integradores.
7. Importación de personas (API + front), scoped al tenant.
8. IA externa opcional (análisis de comprobante → sugerencia o alta vía services).
9. Seed demo reproducible (database/seeds/), incl. empresa APSV.
10. Formularios custom por empresa (standard | viaticos_apsv).
11. Circuito Viáticos APSV: borrador → aprobación → rendición → liquidación (estados 4–10).
12. Notificaciones in-app + email SMTP opcional (NotificationService).
13. Reportes Excel §11 (ReportService), distintos del export de listado.

2. Negocio: qué problema resuelve

En operaciones (sucursales, fuerza de campo, admin), las personas gastan y necesitan rendir el gasto con evidencia. Sin un proceso claro aparecen demoras, rechazos opacos y datos que no llegan a nómina. Este producto estandariza:

• Quién pide (empleado, siempre dueño de su rendición).
• Quién decide (aprobadores por nivel, en orden).
• Qué se ve (estado + historial + adjuntos en un solo detalle).
• Cómo se cierra (firma / externalId → pendiente de pago → pagada).
• Cómo se aísla (cada dato lleva companyId; no se cruza entre tenants).

KPIs de producto (referencia)

3. Roles y capacidades

Mapeo roles APSV (documento → sistema)

4. Multiempresa y subempresas

Company (raíz / holding)          parentId = NULL
 ├── Subcompany A                 parentId = raíz
 │    └── Subcompany A.1          parentId = A
 └── Subcompany B                 parentId = raíz

API empresas

5. Máquina de estados

5.1 Estados de la rendición

Estados 0–3 son el circuito formCode=standard (sin regresión). Estados 4–10 solo aplican a formCode=viaticos_apsv; las empresas standard no los usan en el flujo diario.

Formularios custom: cada empresa declara su formulario en company_form_configs (formCode + schemaJson + viaticoRulesJson) vía GET/PUT /companies/:id/form-config. El front renderiza y valida según ese schema; la lógica de transiciones vive en ReimbursementService según formCode.

Diagrama standard (0–3)

                    ┌──────────────┐
   create ─────────►│   PENDING    │
                    └──────┬───────┘
           reject/cancel   │    último nivel APPROVED
                │          │    (+ firma / externalId local)
                ▼          ▼
         ┌──────────┐  ┌──────────────────┐
         │ DISMISSED│  │ PENDING_PAYMENT  │──► PAID
         └──────────┘  └──────────────────┘
                              ▲
                         /signature
                    (niveles todos APPROVED)

Diagrama APSV (4–10)

DRAFT ──submit──► SUBMITTED (+ workflow N niveles)
                      │
           reject ────┼──► DISMISSED
                      │
              all approve ──► APPROVED ──► PENDING_SETTLEMENT
                                              │
                                    settlement ┼──► SETTLED
                                              │         │
                                         observe        liquidate
                                              ▼         ▼
                                          OBSERVED   LIQUIDATED
                                              │
                                    re-settlement ──► SETTLED

En la respuesta JSON cada estado viene como objeto { id, name, label } (name en inglés, label en español) para no acoplar la UI a códigos mágicos.

5.2 Estados de cada nivel (workflow_details)

El nivel activo es el de menor level que sigue en PENDING. Solo ese nivel puede decidir. Tras aprobarlo, se desbloquea el siguiente.

6. Circuito Viáticos APSV

Empresa demo APSV (id=4) con formCode=viaticos_apsv. Schema: database/seeds/forms/viaticos_apsv.schema.json. Holding / Sur / Norte siguen en standard sin regresión. IA off por defecto en APSV (aiScanEnabled=false).

6.1 Wizard UI en 2 etapas

1. Solicitud / planilla de liquidación de viáticos — destino, motivo, fechas, agentes, vehículo, cuotas; se guarda como DRAFT y se confirma con POST .../submit.
2. Rendición de viáticos + gastos — tras aprobación completa (PENDING_SETTLEMENT): líneas de viáticos/gastos, adjuntos, envío con POST .../settlement.

6.2 Transiciones (services)

* En OBSERVED se reenvía settlement tras corrección; DRAFT es editable/cancelable sin workflow activo.

6.3 Cadena de aprobación seed

Solicitante → Jefe Directo (L1) → Gerente (L2) → Administración (L3) → PENDING_SETTLEMENT

6.4 Services de dominio APSV

6.5 Invariantes APSV

1. Empresas standard: endpoints settlement/observe/liquidate rechazan si formCode ≠ viaticos_apsv.
2. DRAFT: sin workflow activo; editable/cancelable por el dueño.
3. Submit crea workflow; rechazo de nivel → DISMISSED.
4. Settlement solo desde PENDING_SETTLEMENT u OBSERVED.
5. Liquidate solo desde SETTLED (rol autorizado).
6. Notificaciones y reportes scoped por tenant; sin cruzar empresas.
7. Tras mutaciones relevantes: reimbursement_events + NotificationService.notify.

7. Flujo extremo a extremo — formCode standard

1. Admin configura empresa/subempresa + plantilla workflow (niveles + aprobadores)
2. Admin importa / da de alta personas (employee, approver) en la empresa destino
3. Empleado inicia sesión → Nueva rendición
      · Fecha del gasto (obligatoria)
      · Monto (obligatorio)
      · Observaciones (obligatorias)
      · ≥1 adjunto (imagen o documento allowlist)
   Opcional: asistente IA (suggest) → confirma → create
4. Sistema crea reimbursement PENDING + adjuntos + workflow con N details PENDING
5. Aprobador L1 ve bandeja (inbox) → aprueba o rechaza (+ motive si rechazo)
6. Si rechazo → rendición DISMISSED; niveles pendientes restantes se cancelan
7. Si aprueba → desbloquea L2 … Ln
8. Último nivel aprobado → PENDING_PAYMENT (+ signature/externalId locales si aplica)
9. Empleado/admin puede firmar explícitamente (/signature) si aún PENDING con niveles OK
10. Nómina / integración marca PAID (callback) — no puede volver a PENDING
11. Auditoría / control: listado proceso completo + export Excel

8. Flujos por rol (UX)

Navegación del front: Rendiciones · Aprobar · Empresas · Personas · Plantillas · Reportes · Campana · Salir, con selector de empresa/rama. La UI se adapta al formCode de la empresa activa.

9. Workflow multinivel — cómo está armado

9.1 Piezas

9.2 Reglas de avance (implementadas en ReimbursementService)

1. Al crear, se lee la plantilla activa de companyId y se materializan N details en PENDING.
2. Solo el nivel activo (menor level aún PENDING) puede decidir.
3. El decisor debe ser el userId del detail (o admin).
4. Aprobar → detail APPROVED + decidedAt; si quedan pendientes, la rendición sigue PENDING.
5. Si era el último nivel en standard → rendición y workflow pasan a PENDING_PAYMENT; se setean signature / externalId locales si faltaban.
6. Si era el último nivel en viaticos_apsv → APPROVED y luego PENDING_SETTLEMENT (sin pasar por firma/nómina standard).
7. Rechazar → motive obligatorio; detail REJECTED; restantes PENDING → REJECTED; rendición DISMISSED.
8. Cancelar (dueño/admin) solo si PENDING y todos los details aún PENDING → DISMISSED.
9. Editar mismas precondiciones que cancelar; ownership (propia o admin).
10. Firmar (/signature): dueño o admin/API Key; todos los niveles APPROVED; pasa a PENDING_PAYMENT.

9.3 Diagrama secuencia — aprobación (standard)

Empleado          API/Service              Aprobador L1         Aprobador L2
   │  POST /reimbursements                      │                     │
   │─────────────────────────► create + WF L1,L2 PENDING              │
   │                  PENDING                   │                     │
   │                                            │  POST .../approve   │
   │                                            │◄────────────────────┤
   │                               L1 APPROVED  │                     │
   │                               L2 sigue PENDING                   │
   │                                            │                     │  POST approve
   │                                            │                     │◄──
   │                         PENDING_PAYMENT (último OK)              │
   │  (opcional) POST .../signature                                   │
   │─────────────────────────► PENDING_PAYMENT + externalId           │

10. Adjuntos

• Al crear: al menos un archivo (imagen o documento).
• Tipos: image/* (jpg, png, webp) y documentos allowlist (pdf, xlsx, doc/docx según middleware).
• Metadatos: name, mimeType, size, path, kind (image | document).
• Storage: {uploadDir}/{companyId}/reimbursements/{id}/ — sin path traversal.
• En update editable se pueden agregar más adjuntos.
• Descarga: GET /reimbursements/:id/attachments/:attachmentId con scope tenant.

11. Importación de personas

Misma lógica para front e integradores (UserService). Persistencia solo vía services; siempre con companyId destino dentro del alcance del token.

Campos mínimos

email, firstName, lastName, documentId, docket (opc.), role(s), companyId, active.

Reglas de import

1. Validación fila a fila; respuesta con created, updated, skipped, errors[].
2. Upsert opcional por email+companyId o documentId+companyId.
3. continueOnError default true (no tumba el lote entero).
4. Roles y plantillas solo dentro del mismo tenant/rama.
5. Rate limit y tamaño máx. de archivo.

CSV de prueba: database/seeds/people-import-sample.csv.

12. Servicio de IA externa (n8n OCR)

Adapter configurable: mock, n8n (N8nOcrAdapter) o http genérico. Variables: AI_PROVIDER, AI_API_URL (o N8N_BASE_URL + N8N_WEBHOOK_PATH), N8N_USE_TEST, AI_ENABLED, AI_TIMEOUT_MS, AI_MIN_CONFIDENCE. Contrato: docs/ai-scanner-contract.md. Postman: docs/postman/Rendiciones-OCR.postman_collection.json.

El workflow n8n usa visión (Mistral): POST multipart con campo file → JSON con date, amount, merchant (nullable), currency, confidence, partial, retry_suggested. Si retry_suggested=true, la UI pide nueva foto antes de guardar (no se crea la rendición).

Además del kill switch global (AI_ENABLED), cada empresa se habilita desde el panel web: menú Scanner IA o Empresas → IA: encender (companies.aiScanEnabled). Seed: Sucursal Sur = on.

Schema n8n

{
  "date": "YYYY-MM-DD",
  "amount": 27.6,
  "merchant": "Casa Pepe",
  "currency": "ARS",
  "confidence": 0.9,
  "partial": false,
  "retry_suggested": false
}

• Persistencia solo vía ReimbursementService.
• Traza en ai_analysis_logs (sin secretos).
• Endpoints: POST /ai/analyze, POST /ai/analyze-and-create.

13. Listados, Excel y reportes §11

El listado (GET /reimbursements) incluye usuario, adjuntos y workflow/details (proceso completo). Filtros: fecha desde/hasta, statusId, companyId, paginación; empleados ven solo propias; inbox=1 filtra bandeja del aprobador.

13.1 Export del listado (proceso completo)

Export (GET /reimbursements/export): mismos filtros; genera .xlsx (ExcelExportService) con columnas del proceso:

• id, fecha gasto, empleado, empresa, monto, observaciones, status
• adjuntos (nombres / cantidad / tipos)
• por cada nivel: nivel, aprobador, estado, motivo, fecha decisión
• firma (sí/no), externalId, reviewer nómina, reviewerMotive, createdAt, updatedAt

13.2 Reportes Excel §11 (ReportService)

Distintos del export de listado. Catálogo: GET /reports. Descarga: GET /reports/:code/export (roles admin/approver; scoped por tenant).

13.3 PDF por rendición

GET /reimbursements/:id/pdf — APSV: planilla de liquidación + viáticos/gastos + imágenes adjuntas; standard: comprobante + adjuntos (PdfExportService).

14. Notificaciones (§10)

Canales: bandeja in-app (notifications) + email SMTP opcional. Disparo desde services tras mutaciones (submit, approve/reject, pendiente de rendición, observada, liquidada, etc.).

15. Arquitectura técnica

[ Front propio (public/) ] ──┐
[ ERP / portal / app ] ──────┼──► /api/v1/* ──► Controllers ──► Services ──► Sequelize ──► MSSQL
[ AI Provider externo ] ◄────┘                      │
                                      integrations/ai (adapter n8n/mock/…)
                                      integrations/paysheet (stub/opcional)
                                      NotificationService → SMTP (opcional)

Services de dominio (además de Reimbursement / Company / User)

• FormConfigService · ViaticoCalculationService
• NotificationService · ReportService · PdfExportService
• AiAnalysisService (adapter) · ExcelExportService

Estructura de carpetas

src/{config,models,migrations,seeders,routes,controllers,services,middlewares,integrations,utils}
public/          → front SPA ligera (sin Vite/Webpack)
landing/         → página comercial
docs/            → wiki, OpenAPI, DBML, pipeline, ENTREGA
database/seeds/  → dataset demo (+ forms/viaticos_apsv.schema.json)
uploads/         → adjuntos runtime
tests/           → unitarios críticos

16. Superficie API /api/v1

Contrato vivo OpenAPI 1.2.0 (~74 operaciones, cobertura completa de src/routes/v1.js): Swagger UI · /api/openapi.json · fuente docs/api/openapi.json.

Guía humana detallada (estados, flujos, tablas, ejemplos): docs/api/API.md. Colección Postman: docs/postman/.

Auth

Empresas y form-config

Rendiciones (standard + APSV)

Circuito Gastos (missions / person-settlements)

Notificaciones, reportes, users, AI, workflows

• Notifications: list / read / read-all
• Reports: GET /reports, GET /reports/:code/export, person-month
• Users: list / create / import / import/file · menú por usuario
• Workflow templates + person-workflows (override por persona)
• AI: POST /ai/analyze, POST /ai/analyze-and-create
• Health: GET /health

17. Modelo de datos (DER)

Fuente DBML: docs/schema.dbml (visualizar en dbdiagram.io).

Entidades centrales:

• companies — árbol multiempresa (aiScanEnabled, etc.)
• company_form_configs — formCode, schemaJson, viaticoRulesJson
• users — personas/roles por companyId (area, jobTitle)
• api_keys — integración server-to-server
• workflow_templates / workflow_template_levels
• reimbursements — cabecera (+ campos APSV: destination, motive, payloadJson, agentsJson, …)
• reimbursement_attachments (expenseLineId opcional)
• reimbursement_expense_lines / reimbursement_viatico_lines
• reimbursement_events — historial de acciones
• notifications — bandeja in-app
• workflows / workflow_details
• ai_analysis_logs

18. Autenticación e integración

Para embeber en otro sistema: apuntar el front con window.API_BASE_URL, configurar CORS_ORIGINS, usar la misma OpenAPI. Seed demo incluye demo-api-key-holding-001 (solo no-prod).

19. Reglas invariantes (checklist de negocio)

1. Empleado crea/edita/cancela/firma solo rendiciones propias.
2. Aprobadores actúan solo en su nivel asignado y cuando es el nivel activo.
3. No editar ni cancelar si algún nivel ya fue revisado (standard PENDING).
4. Firma solo con niveles completos APPROVED (standard; sin re-firmar si ya informada).
5. Callback nómina no puede devolver a PENDING.
6. Toda query operativa filtra por companyId / scopeCompanyIds.
7. Create / update / cancel / approve / signature / submit / settlement en transacciones.
8. IA nunca escribe directo en MSSQL ni saltea workflow.
9. Import personas no sale del árbol permitido del token/API Key.
10. parentId no puede formar ciclos.
11. Create standard exige plantilla de workflow activa; APSV exige plantilla al submit.
12. Settlement / observe / liquidate solo con formCode=viaticos_apsv y estados válidos.
13. Fallo de email no revierte la mutación de negocio.

20. Front propio

App estática en public/ (HTML/CSS/JS). No usa Vite ni Webpack (estándar del proyecto). Consume únicamente HTTP/JSON (+ multipart). Pantallas alineadas a los flujos de §8: listado con badges de estado, alta standard, wizard APSV (2 etapas), bandeja de aprobación, admin de empresas/form-config, import de personas, plantillas, asistente IA (si aiScanEnabled), campana de notificaciones, reportes §11, descarga PDF.

Landing comercial separada: landing/index.html (ruta típica /landing/).

21. Set de datos de prueba

Nunca usar en producción. Password demo documentada: Demo123!

Escenarios standard: PENDING sin revisar · PENDING con L1 OK · DISMISSED · aislamiento Norte/Sur · CSV import. APSV: casos en DRAFT, SUBMITTED, PENDING_SETTLEMENT, SETTLED, OBSERVED, LIQUIDATED; plantilla 3 niveles; schema en forms/viaticos_apsv.schema.json. Sur tiene aiScanEnabled=true; APSV off.

npx sequelize-cli db:migrate
npm run seed:demo
# fixtures adjuntos: npm run db:fixtures && npm run db:attachments

Detalle: database/seeds/README.md.

22. Seguridad (mínimo)

• Helmet, CORS, rate limiting, sanitización.
• Secretos solo en variables de entorno (JWT, DB, AI, SMTP); consultas parametrizadas (Sequelize).
• bcrypt + JWT con expiración.
• Uploads: allowlist MIME, tamaño máximo, path bajo companyId.
• IDOR prevenido por scopeCompanyIds + ownership en services (también notificaciones y reportes).
• IA: rate/timeout; sin PII innecesaria en logs; flag por empresa aiScanEnabled.
• Rate limit en import masivo y exports de reportes.

23. Operación y despliegue

cp .env.example .env   # DB_* → SQL Server externo; SMTP_* / AI_* según entorno
npm install
npx sequelize-cli db:migrate
npm run seed:demo
npm run dev            # o: docker compose up --build

• App: http://localhost:3000/
• Swagger: /api-docs
• Health: GET /health (independiente de SMTP)
• Wiki: este archivo (docs/wiki.html)
• Índice entrega: docs/ENTREGA.md
• Docker: backend-only; MSSQL externo vía DB_* (ver DOCKER.md)
• Contrato OCR n8n: docs/ai-scanner-contract.md · Postman OCR en docs/postman/

24. Troubleshooting