Matriz de Trazabilidad Técnica
Este documento garantiza que cada concepto definido en el Modelo de Dominio tenga una representación exacta en la arquitectura de software. Es la herramienta principal para el análisis de impacto y la auditoría de procesos.
1. Mapeo General (Entidad → API → Tabla)
| Entidad de Dominio | Microservicio (Go) | Endpoint Principal | Tabla PostgreSQL | Evento de Negocio | Use Case (Aplicación) |
|---|---|---|---|---|---|
| Identidad (User) | auth-service | POST /api/v1/auth/login | users | USER_LOGGED_IN | Login |
| Sesión/Refresh | auth-service | POST /api/v1/auth/refresh | refresh_tokens | SESSION_ROTATED | RefreshToken |
| Registro / OTP | auth-service | POST /api/v1/auth/register / POST /api/v1/auth/token/verify | verification_tokens | OTP_VERIFIED | RegisterUser, VerifyOtp |
| Doctor | profile-service | GET /api/v1/doctors/{public_id} | doctor_profiles | DOCTOR_VERIFIED | GetDoctor, UpdateDoctorProfile |
| Perfil de Usuario (común) | profile-service | PATCH /api/v1/profiles/me | user_profiles | USER_PROFILE_UPDATED | UpdateUserProfile |
| Paciente (vista/flags) | profile-service | PATCH /api/v1/profiles/patient | user_profiles | PATIENT_FLAGS_UPDATED | UpdatePatientFlags |
| Sede (Entidad) | entity-service | GET /api/v1/entities | health_entities | ENTITY_CREATED | ListEntities, CreateEntity, UpdateEntity |
| Geografía | catalog-service | GET /api/v1/admin/catalogs/geo | geography | CATALOG_UPDATED | GetGeo, CreateGeoNode |
| Taxonomía Médica | catalog-service | GET /api/v1/admin/catalogs/specialties | medical_taxonomy | CATALOG_UPDATED | GetSpecialties, CreateSpecialty |
| Seguro (Convenios) | entity-service | POST /api/v1/insurance-agreements | insurance_agreements | AGREEMENT_ENABLED | CreateInsuranceAgreement, ListInsuranceAgreements |
| Afiliación Doctor-Sede | entity-service | POST /api/v1/affiliations | affiliations | AFFILIATION_CREATED | AffiliateDoctor |
| Validación Triple | search-service | GET /api/v1/verify | insurance_agreements | CHECK_PERFORMED | TripleValidation |
| Buscador Entidades | search-service | GET /api/v1/search/entities | health_entities | SEARCH_PERFORMED | SearchEntities |
| Buscador Doctores | search-service | GET /api/v1/search/doctors | doctor_profiles | SEARCH_PERFORMED | SearchDoctors |
| Cita | appointments-service | POST /api/v1/appointments | appointments | APPOINTMENT_CONFIRMED | CreateAppointment, UpdateAppointment, GetAppointment |
| Disponibilidad | availability-service | GET /api/v1/availability | affiliations.schedule | SLOT_RESERVED | GetAvailability |
| Notificación | notification-service | POST /api/v1/notifications/send | notification_logs | NOTIF_SENT | SendNotification |
| Preferencias de Notificación | notification-service | PATCH /api/v1/notifications/preferences | notification_preferences | PREFERENCES_UPDATED | UpdateNotificationPreferences |
| Acreditación Doctor | profile-service | POST /api/v1/doctor-accreditations | doctor_accreditations | ACCREDITATION_APPROVED | CreateAccreditation |
| Reseña | review-service | POST /api/v1/reviews | reviews | REVIEW_SUBMITTED | SubmitReview, ListReviews |
| Cupones/Promociones | promotions-service | POST /api/v1/professional/coupons | coupons | COUPON_CREATED | CreateCoupon, UpdateCoupon, ValidateCoupon, ApplyCoupon |
| Blog Profesional | content-service | POST /api/v1/professional/posts | professional_posts | POST_PUBLISHED | CreatePost, UpdatePost, DeletePost, ListPosts |
| Auditoría de Perfiles | backoffice-service | POST /api/v1/admin/audits/{id}/decision | audit_logs | PROFILE_VERIFIED | ListPendingAudits, ReviewAudit, ResolveAudit |
2. Trazabilidad de Datos Sensibles (PII/PHI)
Siguiendo las recomendaciones de seguridad, los datos protegidos se gestionan bajo la siguiente matriz de cumplimiento:
| Atributo Sensible | Entidad | Nivel de Riesgo | Estrategia de Protección |
|---|---|---|---|
| User | Alto (PII) | Indexado, persistencia en texto claro (TLS). | |
| Teléfono | User | Alto (PII) | Cifrado AES-256 en capa de aplicación (Go). |
| Password | User | Crítico | Hash Argon2id (No recuperable). |
| Geolocalización | Entity | Medio | Lat/Lng protegidas; solo zona expuesta en listado. |
| MFA Secret | User | Crítico | Cifrado en reposo (RDS TDE). |
| OTP / Verification Code | VerificationToken | Crítico | Hash + TTL corto, no loggear el código; rotar refresh tras verify. |
| Appointment Reason | Appointment | Medio | No incluir diagnósticos; texto corto sin PHI. |
3. Mapeo de Infraestructura (AWS)
Para el análisis de costos y disponibilidad, se trazan los componentes hacia la infraestructura de nube:
4. Responsabilidades de Desarrollo (Owners)
| Componente | Líder Técnico | Equipo de Desarrollo |
|---|---|---|
| Capa Transaccional (Go) | Juan Chiquin / New Backend Dev | Backend Team |
| Interfaz Web (Next.js) | Jorge Colíndres / New Frontend Dev | Frontend Team |
| App Móvil (Flutter) | Jorge Colíndres | Mobile Team |
| Infraestructura (IaC) | Juan Chiquin / New Lead | DevOps Team |
| Agenda/Citas | Backend Lead | Backend + Frontend |
| Notificaciones | Backend Lead | Backend |
| Observabilidad | Tech Lead | DevOps + Todos |
| Auth (Login/Reset) | Tech Lead | Backend + DevOps |
5. Control de Cambios en la Matriz
Cualquier nuevo endpoint o tabla de base de datos DEBE ser registrado en esta matriz antes de que el Pull Request sea aprobado. Esto asegura que no existan recursos "huérfanos" en el sistema.
Checklist de actualización obligatoria:
- Endpoint nuevo/modificado en OpenAPI (
/swagger.htmlystatic/openapi.yaml). - Tabla nueva/modificada en
esquema-de-base-de-datos.md. - Entrada correspondiente en esta matriz (sección 1).
- Owner asignado en sección 4.
- Métrica/Evento en checklist de observabilidad (ver
arquitectura-y-seguridad.md5.8) si aplica. - SLO/SLI documentado en el módulo correspondiente (Auth/Registro/Agenda/Notifs).
- Diccionario UX/flujo referenciado en el módulo de producto (Auth o Registro) si afecta UI.
- Fila actualizada en
25-matriz-requisito-endpoint-test-dashboard.md.
6. Runbooks de incidentes por servicio
| Servicio | Trigger de incidente | Primer diagnóstico | Mitigación inicial | Escalamiento |
|---|---|---|---|---|
auth-service | Pico de 401/409, login fallando | Revisar rotación tokens, redis, proveedor oauth | Forzar logout global selectivo, fallback a login email/password | Tech Lead + Seguridad |
search-service | p95 > SLO, cero resultados anómalos | Verificar índices FTS, caché y filtros país | Desactivar filtros no críticos por feature flag | Backend Search + Data |
appointments-service | Conflictos de slot, doble reserva | Revisar locks e idempotencia | Bloquear creación temporal y reprocesar pendientes | Backend Agenda + Producto |
notification-service | Entrega OTP/push < SLO | Verificar cola, proveedor SMTP/SMS/push | Reintento exponencial + cambio de proveedor secundario | Backend + DevOps |
catalog-service | Catálogos vacíos/inconsistentes | Revisar últimas mutaciones admin y cache invalidation | Restaurar snapshot de catálogo + invalidar caché global | Backend + CATALOG_ADMIN |
Checklist mínimo por incidente:
-
trace_idraíz identificado. - Impacto y alcance documentado (usuarios/países/módulos).
- Mitigación aplicada con timestamp.
- RCA preliminar en <24h y RCA final en <5 días hábiles.