1 Principios (aplicables a todo el manual)
- Fuente de verdad única: cada proceso, métrica o dato tiene un único documento/owner reconocido.
- Mínimo privilegio: accesos otorgados por rol y tarea, revisados trimestralmente.
- Compatibilidad controlada: contratos de API versionados; cambios breaking sólo en versiones mayores.
- Observabilidad por diseño: logs estructurados, trazas por GUID y métricas por dominio.
- Automatizar primero: evitar tareas manuales repetibles; si es manual, documentar runbook.
- Datos de calidad: validaciones a la entrada; catálogos y tipos canónicos compartidos.
- Reutilización: componentes, plantillas y librerías comunes antes que soluciones ad‑hoc.
- Auditable: decisiones y cambios con ticket, aprobación y changelog.
2 Definiciones y glosario mínimo
| Término | Definición | Ejemplo / Nota |
|---|---|---|
| Tenant | Instancia lógica de un cliente, con config. y datos aislados. | tenant_id=rtimadrid |
| Servicio | Solicitud de transporte (unidad operativa) con ciclo de vida. | Creado → Asignado → En curso → Completado/Cancelado |
| Despacho | Proceso de asignación de servicios a vehículos/conductores. | Algoritmo + reglas por tenant |
| Evento | Registro puntual con sello de tiempo, actor y payload. | SERVICE.ASSIGNED, DRIVER.LOCATION.UPDATE |
| GUID | Identificador global único, usado para traza end‑to‑end. | guid=7f9f… propagado en headers |
| SLA | Compromiso de nivel de servicio (respuesta/solución, cobertura). | SLA.incidentes=P1<15m, P2<2h |
| Runbook | Procedimiento repetible, paso a paso. | “Rotación de credenciales” |
| Playbook | Guía para decisiones/escalados. | “Incidencias de geolocalización” |
| PII | Datos personales identificables (RGPD). | Teléfono, matrícula asociada a persona |
| Changelog | Historial de cambios publicados. | v1.2: nuevo webhook SERVICE.CANCELLED |
3 Convenciones de nombres y formatos
Identificadores
tenant_id:^[a-z0-9-]{3,32}$(kebab‑case, sin espacios).service_id,vehicle_id,driver_id: UUID v4 (36 chars) o ULID.
Eventos y tópicos
- Nombres en MAYÚSCULAS.PRESENTE con dominio:
SERVICE.CREATED,PAYMENT.AUTHORIZED. - Campos obligatorios en payload de evento:
guid,tenant_id,occurred_at(ISO‑8601 UTC),source,version.
Fechas y horas
- ISO‑8601 UTC (
2025-10-07T18:30:00Z). Almacenar en UTC; convertir sólo en presentación.
Unidades
- Distancia metros/km; tiempo en segundos; precios en EUR (minor units = céntimos).
Códigos de estado (HTTP‑like)
2xxéxito,4xxerror de cliente (validación, permisos),5xxerror servidor.
4 Estados y ciclos de vida
Servicio
CREATED → DISPATCHING → ASSIGNED → EN_ROUTE → ON_BOARD → COMPLETED- Cancelaciones:
CANCELLED_BY_USER | CANCELLED_BY_OPERATOR | NO_SHOW(todas terminales)
Conductor
OFFLINE → STANDBY → BUSY → BREAK → OFFLINE
Incidencia
OPEN → IN_PROGRESS → WAITING_INPUT → RESOLVED → CLOSED- Severidad:
P1 (bloqueante), P2 (alta), P3 (media), P4 (baja)
5 Criterios de calidad (Do / Don’t)
Do
- Validar payloads contra esquemas (JSON Schema v2020‑12).
- Registrar
guidytenant_iden cada log/trace. - Definir precondiciones/postcondiciones en procesos.
Don’t
- No usar timestamps locales en almacenamiento.
- No introducir campos sin owner ni versión.
- No exponer PII en logs.
6 RACI (responsabilidades sobre definiciones)
| Artefacto | R | A | C | I |
| Glosario y catálogos | Datos | PMO | Ingeniería | Operaciones |
| Esquemas de evento | Ingeniería | Producto | Operaciones | Soporte |
| Estados/ciclos de vida | Producto | PMO | Ingeniería | Clientes |
7 Mantenimiento del glosario
- Cambios vía ticket con plantilla (término, definición, owner, impacto).
- Revisión mensual en Comité de Datos.
- Publicación con versión y fecha; difundir en canal
#manuales.
