Documentación del sistema: narrativa de flujo de negocio y de interacción

No estoy seguro de lo que quiero, pero me parece que está cerca de una narrativa de un recorrido por las pantallas de plan de tratamiento, presupuesto, cobro y facturación, narrando lo que va haciendo el usuario en cada paso, cómo se refleja esto en el modelo de datos, las características más importantes de las pantallas y del modelo de datos (diseño), hasta llegar al final de flujo completo.

Sí, creo que lo que estás buscando es exactamente eso: una narrativa de flujo de negocio y de interacción, donde se cuenta qué hace el usuario, qué pantalla ve, qué entidades se crean o modifican y por qué existen. Ese tipo de documento es muy valioso porque conecta la experiencia del usuario con el diseño del modelo de datos.

Recorrido completo: del odontograma a la factura

1. Pantalla de Odontograma — El diagnóstico

Lo que hace el usuario

El odontólogo abre la ficha del paciente y observa el odontograma. Marca caries, ausencias, restauraciones y tratamientos indicados.

Lo que ve

• Dientes dibujados.
• Caras dentarias.
• Colores y símbolos.
• Lista de tratamientos sugeridos.

Lo que ocurre en el modelo de datos

Se guarda o actualiza un único registro odontogramas asociado al paciente.

odontogramas
------------
id
paciente_id
schema_version
revision
json

El documento JSON contiene el estado clínico y los tratamientos indicados.

Idea clave

El odontograma responde a la pregunta:

¿Qué tiene el paciente?

Todavía no hay precios ni cobros.

---

2. Pantalla de Plan de Tratamiento — La propuesta clínica

Lo que hace el usuario

El odontólogo selecciona cuáles de los tratamientos indicados realmente propone realizar.

Por ejemplo:

• Restauración pieza 11.
• Endodoncia pieza 26.
• Corona pieza 26.

Lo que ve

• Lista de tratamientos pendientes.
• Prioridad.
• Observaciones.
• Estado (propuesto, aceptado, rechazado).

Lo que ocurre en el modelo de datos

treatment_plans
---------------
id
paciente_id
estado
fecha

treatment_plan_items
--------------------
id
treatment_plan_id
prestacion_id
pieza
cantidad

Idea clave

El plan responde a:

¿Qué proponemos hacer?

Puede haber más de un plan para un mismo paciente.

---

3. Pantalla de Presupuesto — La propuesta económica

Lo que hace el usuario

Presiona “Generar presupuesto desde el plan”.

El sistema toma los tratamientos y busca sus precios vigentes.

Lo que ve

• Prestación.
• Pieza.
• Cantidad.
• Precio unitario.
• Total.
• Descuentos.
• Vigencia.

Lo que ocurre en el modelo de datos

presupuestos
-------------
id
paciente_id
treatment_plan_id
fecha
estado
subtotal
descuento
total

presupuesto_items
-----------------
id
presupuesto_id
prestacion_id
pieza
cantidad
precio_unitario
importe

Idea clave

El presupuesto responde a:

¿Cuánto costará?

Los precios quedan congelados para preservar el histórico.

---

4. Pantalla de Aceptación — La decisión del paciente

Lo que hace el usuario

El paciente acepta parcial o totalmente el presupuesto.

Lo que ve

• Presupuesto original.
• Firma o aceptación.
• Fecha.

Lo que ocurre en el modelo de datos

Se actualiza:

presupuestos.estado = 'aceptado'

o se registran ítems aceptados.

Idea clave

No todo presupuesto termina realizándose.

---

5. Pantalla de Cobro — El dinero recibido

Lo que hace el usuario

La recepcionista registra un pago.

Lo que ve

• Importe.
• Medio de pago.
• Fecha.
• Observaciones.

Lo que ocurre en el modelo de datos

cobros
------
id
paciente_id
presupuesto_id
fecha
importe
medio_pago

Idea clave

El cobro responde a:

¿Cuánto dinero entró?

Un presupuesto puede tener muchos cobros.

---

6. Pantalla de Facturación — El comprobante fiscal

Lo que hace el usuario

Selecciona qué prestaciones efectivamente factura.

Lo que ve

• Datos fiscales.
• Ítems facturados.
• Totales.
• Número de comprobante.

Lo que ocurre en el modelo de datos

facturas
--------
id
paciente_id
fecha
numero
tipo
subtotal
total

factura_items
-------------
id
factura_id
prestacion_id
cantidad
precio_unitario
importe

Idea clave

La factura responde a:

¿Qué se facturó realmente?

No necesariamente coincide con el presupuesto original.

---

El flujo completo

Paciente llega
      │
      ▼
Odontograma
“¿Qué tiene?”
      │
      ▼
Plan de Tratamiento
“¿Qué proponemos hacer?”
      │
      ▼
Presupuesto
“¿Cuánto costará?”
      │
      ▼
Aceptación
“¿El paciente acepta?”
      │
      ▼
Cobros
“¿Cuánto dinero ingresó?”
      │
      ▼
Factura
“¿Qué se facturó?”

La idea más importante del diseño

Cada etapa crea una fotografía histórica:

• El odontograma conserva el diagnóstico.
• El plan conserva la propuesta clínica.
• El presupuesto conserva los precios ofrecidos.
• El cobro conserva el dinero recibido.
• La factura conserva el comprobante emitido.

Por eso las entidades son separadas. Aunque el usuario las recorra como un único flujo, el sistema necesita guardar cada fotografía para que el historial siga siendo correcto aunque cambien tratamientos, precios o decisiones del paciente.

Creo que este documento ya está muy cerca de lo que terminaría siendo la documentación funcional principal de Dentalia, porque describe simultáneamente las pantallas, el comportamiento del usuario y el modelo de datos. Esa combinación suele ser mucho más útil para desarrollar el sistema que una descripción puramente técnica o puramente de negocio.

De hecho, 

En lugar de describir solo el flujo de negocio, podríamos convertirlo en un documento de diseño funcional, donde cada etapa se describe desde cuatro perspectivas.

Por ejemplo:

1. El odontólogo crea un plan de tratamiento

Objetivo

Registrar qué tratamientos recomienda realizar al paciente.

Pantalla

PlanTratamiento/Edit.tsx

Componentes shadcn/ui:

Card

Accordion (por cuadrantes o piezas)

Table

Checkbox

Badge

Dialog (agregar tratamiento)

Combobox (buscar práctica)

Calendar (fecha sugerida)

Modelo de datos

Se crea:

PlanTratamiento

y sus

PlanTratamientoItem

Cada ítem contiene:

pieza dental

práctica

cantidad

observaciones

prioridad

estado (propuesto, aceptado, realizado...)

2. El paciente acepta parte del tratamiento

Desde la pantalla del plan se seleccionan algunos ítems.

Acción:

Crear presupuesto

No se vuelven a escribir.

Simplemente se referencian.

Se crea:

Presupuesto

con

PresupuestoItem

que apuntan a los mismos tratamientos.

3. Se imprime o envía el presupuesto

La pantalla muestra:

subtotal

descuentos

impuestos (si aplican)

total

vigencia

observaciones

El presupuesto queda:

Pendiente

4. El paciente acepta

Botón:

Aceptar presupuesto

El sistema:

cambia el estado

registra fecha

permite comenzar los tratamientos

No duplica información.

5. El odontólogo realiza un tratamiento

Desde el odontograma o desde la agenda.

Marca:

Realizado

Automáticamente el plan refleja el avance.

6. Se registra un cobro

Pantalla:

Cobros

Componentes:

Select del paciente

Tabla de conceptos pendientes

Input de importe

Select de medio de pago

Date Picker

Botón Registrar

Se crea:

Cobro

y eventualmente

CobroAplicacion

para distribuir el pago entre varios conceptos.

7. Facturación

Si corresponde:

Generar factura

El sistema toma:

tratamientos realizados

presupuesto aceptado

cobros (según la política elegida)

y genera una factura.

Lo interesante

Lo que me gusta de este enfoque es que el documento no solo explica "qué hace el usuario", sino también por qué el modelo de datos tiene esa forma. Por ejemplo, en lugar de decir simplemente "existe una tabla presupuestos", la narrativa muestra que el presupuesto nace del plan de tratamiento, puede aceptarse parcialmente, da lugar a tratamientos realizados, luego a cobros y finalmente, cuando corresponde, a la facturación.

Creo que este tipo de documento puede convertirse en la especificación funcional de Dentalia. Si se escribe con suficiente detalle, prácticamente permite implementar el sistema pantalla por pantalla sin necesidad de volver a analizar el negocio en cada módulo.