Plan de UX: Añadir Tratamientos al Plan de Tratamiento

Fecha: 2026-04-18 Estado: Propuesta (v2 — reescritura post-refactor, alcance reducido) Autor: Análisis UX Reemplaza: v1 (2026-04-17)

---

0. Cambios respecto a v1

La v1 se escribió antes de la refactorización del odontograma y del catálogo. Buena parte de la PARTE A original (multi-diente, estados visuales, roles de puente) ya está implementada. Este documento:

1. Reconoce qué quedó cubierto por la refactorización.
2. Es crítico con decisiones de v1 que no envejecieron bien (los "tres modos de añadir", la separación artificial "por diente / global / catálogo").
3. Reduce el alcance a dos mejoras que aportan valor inmediato sin sobrecargar el modelo:
   • Tratamientos globales como ciudadanos de primera clase.
   • Reordenar items del plan por drag & drop.
4. Documenta huecos menores del odontograma y los pospone explícitamente.

---

Índice

1. Estado actual tras la refactorización
2. Reflexión crítica sobre v1 y reducción de alcance
3. Principios de UX
4. Tratamientos globales (arcada / boca completa)
5. Reordenar items del plan con drag & drop
6. Huecos pendientes del odontograma (pospuestos)
7. Cambios en datos y API
8. Prioridades y fases
9. Riesgos

---

1. Estado actual tras la refactorización

1.1 Lo que ya está implementado

Área	Cobertura	Archivos clave
Multi-diente (puentes, férulas, carillas/coronas múltiples)	✅ Completo con roles (pilar/póntico/cantilever), arcada, mínimos por tipo	OdontogramChart.vue, MultiToothConfirmPopup.vue, odontogramConstants.ts
Catálogo con pricing strategies	✅ flat / per_tooth / per_surface / per_role + mapping odontograma	catalog/models.py, catalog/pricing.py, CatalogItemModal.vue
TreatmentBar modos	✅ full / diagnosis / planning (filtra terapéuticas)	TreatmentBar.vue
Estados visuales existing vs planned	✅ Con reglas de visualización (pulp fill, occlusal, lateral icon, pattern)	VISUALIZATION_RULES
Sincronización PlannedTreatmentItem ↔ Treatment	✅ 1:1 FK, perform marca completado, sync a existing	treatment_plan/models.py, useTreatments.ts
Hover bidireccional plan ↔ odontograma	✅	PlanDetailView.vue
Timeline / vista histórica	✅	useOdontogramTimeline.ts, TimelineSlider.vue
Vinculación Plan ↔ Presupuesto	✅ link-budget, sync-budget, generate-budget	treatment_plan/router.py
ClinicalTab con 4 modos	✅ history / diagnosis / plans / appointments	ClinicalTab.vue
ConditionsList (bloque diagnosticadas)	✅ Rediseñado, agrupa por diente con hover-link	ConditionsList.vue

1.2 Gaps reales

Gap	Decisión
No hay tratamientos globales (limpieza, blanqueamiento) como first-class	En alcance (§4)
Reordenar items del plan no es posible	En alcance (§5)
No hay búsqueda por nombre en catálogo desde editor	Fuera de alcance
No hay presupuesto en vivo en la vista de plan	Fuera de alcance (se resuelve con Budget actual)
No hay plantillas, alternativas, fases, sugerencias desde diagnóstico	Fuera de alcance (ver v1 archivada en git)
Selector superficies modal, no inline	Pospuesto (§6)
Micro-feedback y teclado	Pospuesto (§6)

---

2. Reflexión crítica sobre v1 y reducción de alcance

2.1 Decisiones de v1 que descartamos

• "Tres modos de añadir (🦷 Por Diente / 🌐 Boca Completa / 📋 Del Catálogo)". Obliga al usuario a clasificar la intención antes de saber el tratamiento. El catálogo ya determina treatment_scope y pricing_strategy; la UI debería derivar el modo de interacción del item seleccionado, no al revés. El "modo catálogo" es en realidad cómo funciona el sistema siempre, no un modo aparte.
• "Panel lateral fijo al 35%". El layout actual (odontograma 3/5, lista 2/5, barra abajo) funciona. Reabrirlo sin razón ergonómica concreta es churn.
• "Sincronización dura: eliminar item del plan elimina ToothTreatment". Un Treatment planned puede ser referenciado por otros planes futuros. La regla correcta: borrar item solo limpia el Treatment si queda huérfano y está en planned. Si está performed, se conserva como historia clínica. Ver §7.

2.2 Por qué reducimos el alcance a dos features

Los grandes añadidos que barajamos (plantillas, fases, sugerencias, alternativas, búsqueda, presupuesto vivo, vista paciente) aportan valor, pero:

• Requieren nuevas entidades y endpoints.
• Empujan complejidad conceptual a la UI (fases colapsables, alternativas agrupadas, etc.).
• No los valida nadie aún con uso real.

Las dos mejoras que sí conservamos desbloquean casos reales frecuentes (limpieza = la mayoría de pacientes; reordenar = esperable en cualquier lista larga) sin inflar el modelo.

Todo lo demás queda documentado en el historial de git (v1 y primera versión de v2) por si se quiere recuperar.

2.3 Sin datos a preservar

La aplicación aún no está en producción. Esto libera decisiones:

• Podemos redefinir enums limpiamente en lugar de extender con valores nuevos por compatibilidad.
• Podemos cambiar columnas a opcionales sin migración condicionada.
• El seeder de catálogo puede rehacerse desde cero con la taxonomía correcta (incluyendo globales).
• No se escribe código de compatibilidad hacia atrás en servicios ni en el frontend.

Las reglas de borrado de Treatment al quitar items del plan (§7.3) no son legacy — son corrección arquitectónica: un tratamiento ya realizado es historia clínica y no se borra aunque se quite del plan. Eso se conserva.

---

3. Principios de UX

Guías que resuelven ambigüedades:

1. Una sola vía, contextual. El modo de interacción se deriva del tratamiento elegido. Limpieza no pide diente; puente pide rango. Sin botones para clasificar intención por adelantado.
2. Catálogo como fuente de verdad. No crear conceptos de UI que dupliquen lo que ya modela el catálogo.
3. Odontograma es visualización, no formulario. Cualquier acción que lleve más de dos clics en el odontograma sugiere que el punto de entrada correcto es otro.
4. Reversibilidad por defecto. Añadir, quitar y reordenar en el plan no requieren confirmación. Completar un tratamiento (cambia historia clínica) sí.
5. Planning ≠ Diagnóstico. Estados planned vs existing no se mezclan en los mismos controles; ya están separados por modo.

---

4. Tratamientos globales (arcada / boca completa)

4.1 Problema

Limpieza, blanqueamiento, flúor, férula de descarga, ortodoncia global no encajan en el modelo actual: Treatment requiere al menos un TreatmentTooth. El dentista acaba añadiéndolos como notas sueltas al budget o fuera del sistema.

4.2 Decisión de modelo

Extender Treatment.scope con dos valores nuevos: global_mouth y global_arch.

• global_mouth → 0 TreatmentTooth. Aplica a todo.
• global_arch → 0 TreatmentTooth; campo arch (upper / lower) indica la arcada.

TreatmentTooth pasa a ser opcional (count 0 válido cuando el scope es global).

Alternativa descartada: entidad GlobalTreatment separada. Duplica precios, estados y pertenencia al plan; rompe la unificación actual.

4.3 UI

En la barra de tratamientos, botón "Boca completa ▸" despliega un panel vertical con los items globales del catálogo:

┌────────────────────────────────┐
│ BOCA COMPLETA                  │
│                                │
│ 🪥 Limpieza dental       €60   │
│ ✨ Blanqueamiento       €180   │
│ 🦷 Fluorización          €25   │
│ 📋 Revisión             €30   │
│                                │
│ ARCADA                         │
│ 🔧 Férula descarga sup. €120   │
│ 🔧 Férula descarga inf. €120   │
└────────────────────────────────┘

Interacciones:

• Clic en item global de boca completa → se añade directamente al plan, sin interactuar con el odontograma. Feedback: toast + item con icono 🌐 en la lista.
• Clic en item de arcada → banner pide seleccionar arcada con dos botones grandes sobre el odontograma (Superior / Inferior). No requiere selección diente a diente.

Visualización en odontograma:

• Items global_mouth no se pintan sobre dientes concretos. Aparecen en una cinta inferior del odontograma con el icono del tratamiento y un badge numérico si hay varios. Hover del item en la lista → parpadeo sutil de todo el odontograma (o de la arcada) para indicar pertenencia.
• Items global_arch pintan una línea/cinta sobre la arcada afectada.

4.4 Catálogo

Los items de catálogo globales ya pueden existir con treatment_scope apropiado; añadir global (y opcionalmente global_arch) al enum del catálogo y permitir su creación desde CatalogItemModal. El seeder de catálogo por defecto debería incluir limpieza, blanqueamiento, fluorización y revisión como globales de boca completa.

---

5. Reordenar items del plan con drag & drop

5.1 Problema

El orden de los items del plan no se puede modificar desde la UI. El campo sequence_order existe en PlannedTreatmentItem pero no se expone en el frontend. El orden importa cuando el plan se usa como guía de ejecución.

5.2 UI

En la lista del plan (PlanTreatmentList):

• Cada fila de pendientes muestra un handle de arrastre (⋮⋮ o i-lucide-grip-vertical) a la izquierda.
• Drag para reordenar dentro de la sección "Pendientes". Mientras se arrastra, fila semitransparente + drop indicator entre filas.
• Los items completados no se reordenan (orden por completed_at).
• Soltar → PATCH al backend con el nuevo orden.

Accesibilidad: no abandonar teclado. Flechas Alt+↑ / Alt+↓ sobre una fila enfocada la mueven una posición.

Feedback: sin toast (sería ruido). Animación de reacomodo de la lista.

5.3 Backend

Nuevo endpoint:

PATCH /treatment-plans/{id}/items/reorder
Body: { "item_ids": ["...", "...", "..."] }

Recalcula sequence_order para los items listados (persistente). Valida que todos los item_ids pertenecen al plan. Un solo round-trip por reordenación.

Alternativa: mandar PATCH por cada item movido. Descartada: varios round-trips, estado inconsistente en fallos parciales.

5.4 Ordenación por defecto

GET /treatment-plans/{id} ya devuelve items ordenados por sequence_order. Al crear un item, sequence_order = max(siblings) + 1. Sin cambios aquí.

---

6. Huecos pendientes del odontograma (pospuestos)

Puntos menores de v1 que siguen abiertos. Se documentan para trazabilidad; no se incluyen en este alcance. Revisitar tras uso real si generan fricción.

• Selector de superficies inline. Actual: SurfaceSelectorPopup modal. Ideal: popover anclado al diente, sin bloquear el resto del odontograma.
• Accesibilidad de teclado. / buscador (no aplica hasta que exista búsqueda), Esc cancela modo armado (existe parcialmente), Tab ordenado.
• Micro-feedback al añadir / eliminar. Slide-in animado y deshacer rápido en toast.

---

7. Cambios en datos y API

Sin legacy, redefiniciones limpias.

7.1 Backend — modelos

odontogram.Treatment

Redefinir scope como enum unificado (reemplaza el actual mode: single/bridge/uniform):

Valor	Dientes asociados	Uso
tooth	1 TreatmentTooth, surfaces opcional	Empaste, corona, endo, implante, etc.
multi_tooth	N TreatmentTooth con role opcional	Puente, férula, carillas/coronas múltiples
global_mouth	0 TreatmentTooth	Limpieza, blanqueamiento, flúor, revisión
global_arch	0 TreatmentTooth, arch requerido (upper/lower)	Férula de descarga, ortodoncia global por arcada

Cambios concretos:

• Nueva columna scope (enum arriba). Reemplaza mode.
• Nueva columna arch (enum nullable upper/lower). Obligatoria si scope == global_arch.
• TreatmentTooth ya no es obligatorio (cero filas válido).
• TreatmentTooth.surfaces sigue siendo el único portador de superficies; no se añade campo surface a nivel Treatment.

catalog.TreatmentCatalogItem

Redefinir treatment_scope con los mismos 4 valores (tooth / multi_tooth / global_mouth / global_arch). Sustituye los actuales surface / whole_tooth. El flag requires_surfaces se mantiene como bool independiente (aplicable solo a tooth).

7.2 Backend — endpoints nuevos

Endpoint	Propósito
PATCH /treatment-plans/{id}/items/reorder { item_ids: [...] }	Reordenar items del plan

El flujo de añadir tratamiento global reusa POST /patients/{id}/treatments con scope y arch, sin teeth. El POST /treatment-plans/{id}/items existente basta para enlazar al plan.

7.3 Regla de borrado de Treatment al quitar item del plan

• Si el Treatment está referenciado por otro PlannedTreatmentItem activo → no tocar.
• Si es huérfano y status == 'planned' → borrar Treatment.
• Si es huérfano y status == 'performed' → mantener (historia clínica).

Encapsular en TreatmentPlanService.remove_item, no en el router.

7.4 Frontend — composables y tipos

• useTreatmentPlans → añadir reorderItems(planId, itemIds).
• useTreatments → ajustar createTreatment para aceptar scope global y arch sin tooth_numbers.
• TreatmentBar → nuevo botón "Boca completa" con panel desplegable de items globales.
• PlanTreatmentList → handle de drag, lógica de reorder con librería drag & drop ya usada en el proyecto si existe (buscar antes de añadir dep nueva).
• OdontogramChart → cinta inferior para globales (global_mouth) y highlight de arcada (global_arch).
• Tipos Treatment, TreatmentCatalogItem y PlannedTreatmentItem en types/index.ts → ampliar scope y añadir arch.

---

8. Prioridades y fases

ID	Feature	Valor	Esfuerzo	Orden
G1	Tratamientos globales en modelo + catálogo	Alto	Medio	1
G2	UI de globales en TreatmentBar + visualización en odontograma	Alto	Medio	2
G3	Seeder de catálogo con globales por defecto	Medio	Bajo	3
R1	Endpoint reorder + reorderItems en composable	Alto	Bajo	4
R2	Drag & drop en PlanTreatmentList (handle, animación, atajos teclado)	Alto	Medio	5

Fase única, sin paralelización estricta. G1–G3 y R1–R2 pueden hacerse en PRs independientes. G2 depende de G1; R2 depende de R1.

---

9. Riesgos

• Código que asume TreatmentTooth no vacío. Servicios, response builders, visualización y reportes. Auditar usos y ajustar a listas posiblemente vacías. No es un tema de datos (no hay prod), es de corrección de código.
• Dep de drag & drop. Si no hay librería ya en el proyecto, evaluar vue-draggable-plus o HTML5 nativo. Preferir nativo si el caso es simple (lista plana, sin anidamiento); librería si aparece complejidad.
• Reorder con carrera en red. Si dos usuarios reordenan a la vez, el último gana. Aceptable por el volumen esperado; no invertir en locking optimista.

---

Siguientes pasos

1. Plan técnico con desglose de PRs (G1 aislado, G2+G3 juntos, R1+R2 juntos).
2. Decidir librería drag & drop antes de empezar R2.
3. Rehacer el seeder de catálogo con la taxonomía de treatment_scope nueva, incluyendo globales por defecto.