Estoy de acuerdo con todo lo que dijiste. Quiero seguir avanzando.

Perfecto. Creo que llegamos a un punto donde conviene dejar de pensar en tablas aisladas y empezar a pensar en el modelo de dominio completo de Dentalia.

Mi propuesta es que construyamos el sistema "desde el centro hacia afuera". Es decir, primero definimos las entidades fundamentales y luego los módulos que las utilizan.

Mapa del dominio

Hoy yo dibujaría el corazón del sistema así:

                                Paciente
                                    │
                                    │ 1
                                    │
                                    ▼
                              Odontograma
                                    │
                                    │
                           (diagnóstico clínico)
                                    │
                                    ▼
                               Prestación
                                    ▲
                                    │
                                    │
                     TratamientoPropuestaItem
                                    │
                                    │ N
                                    ▼
                         TratamientoPropuesta
                                    │
                                    ▼
                                 Cobro
                                    │
                                    ▼
                               Facturación

Observá algo interesante: Prestación no está "debajo" del odontograma. Está al costado. Es un catálogo del sistema, utilizado por varios módulos.

Módulo 1: Prestaciones

Creo que éste debe ser el próximo módulo que diseñemos.

Su responsabilidad será responder preguntas como:

¿Cómo se llama este tratamiento?
¿Cuál es su código?
¿Cuál es su precio sugerido?
¿Pertenece a qué categoría?
¿Está vigente?
¿Requiere seleccionar una pieza?
¿Requiere seleccionar una superficie?
¿Se puede presupuestar?
¿Se puede facturar?

Fijate que no depende de ningún paciente.

Es un verdadero catálogo.

Mi propuesta para la entidad Prestacion

Todavía no escribo la migración; primero quiero consensuar el modelo.

Identidad

id
codigo
nombre

Organización

categoria_id
orden
activo

Configuración clínica

requiere_pieza
requiere_superficie

Configuración administrativa

precio_base

facturable

presupuestable

Auditoría

created_at

updated_at

Y aparece un nuevo actor

Mientras escribía esto apareció naturalmente otra entidad.

No quiero crearla todavía, pero sí nombrarla.

CategoriasPrestacion

Porque tarde o temprano vamos a querer:

Operatoria

Endodoncia

Cirugía

Prótesis

Ortodoncia

Implantología

Preventiva

Radiología

Y no quisiera que fueran strings repetidos en la tabla de prestaciones.

El odontograma se vuelve muchísimo más simple

En vez de pensar

{
    "codigo": "obturacion-pendiente"
}

yo ya lo interpreto mentalmente como

Prestacion::codigo

O sea, el JSON ya no "describe" un tratamiento.

Lo referencia.

Eso me gusta muchísimo desde el punto de vista del diseño.

La primera pantalla administrativa

Cuando exista este catálogo, podremos construir una pantalla completamente independiente del resto del sistema:

Administración → Prestaciones

Con una grilla de shadcn/ui que permita:

buscar por código;
buscar por nombre;
filtrar por categoría;
filtrar por activas/inactivas;
editar;
desactivar;
crear nuevas prestaciones.

Esa pantalla será utilizada por el administrador del consultorio y alimentará automáticamente el odontograma, las propuestas, los cobros y la facturación.

El siguiente documento que propondría elaborar

Hasta ahora hemos documentado el módulo de Propuestas de Tratamiento. El siguiente documento que redactaría sería la Especificación Técnica del Catálogo de Prestaciones.

Ese documento definiría con el mismo nivel de detalle:

La responsabilidad del catálogo.
Las reglas de negocio.
El modelo de datos.
Las relaciones Eloquent.
La API REST.
Las pantallas Inertia + React.
Las restricciones e invariantes (por ejemplo, que codigo sea único e inmutable una vez utilizado).
Cómo interactúa con el odontograma y con las propuestas.

Mi sugerencia es que no escribamos aún ninguna migración. Si mantenemos esta forma de trabajo, primero tendremos una especificación completa del módulo de Prestaciones y luego las migraciones, modelos, controladores y pantallas saldrán de manera casi mecánica y, sobre todo, coherente entre sí.

Estoy de acuerdo con todo lo que dijiste. Quiero que sigamos avanzando.

Excelente. Creo que ya estamos haciendo algo que muchas veces no se hace en proyectos de software: estamos diseñando el lenguaje del dominio antes que las tablas. Eso suele dar lugar a una arquitectura mucho más estable.

Me gustaría que el siguiente documento sea el que, en mi experiencia, termina convirtiéndose en la "constitución" del sistema.

Lo siguiente que propondría

Hasta ahora hemos definido qué es una prestación, pero todavía no qué tipo de tratamiento representa.

Creo que el siguiente paso de diseño no es una migración, sino modelar la taxonomía de las prestaciones. Por ejemplo:

una obturación afecta una pieza y una o varias superficies;
una extracción afecta una pieza completa;
una prótesis puede involucrar varias piezas;
una radiografía puede no estar asociada a ninguna pieza.

En lugar de llenar la tabla prestaciones con múltiples banderas (requiere_pieza, requiere_superficie, etc.), sospecho que existe un concepto más profundo: el tipo de prestación. Si logramos modelarlo bien, podremos hacer que el odontograma, las propuestas y las futuras pantallas se comporten de forma inteligente sin necesidad de reglas dispersas por el código.

Creo que ese puede ser el próximo gran paso de la arquitectura antes de empezar a escribir migraciones.

No quiero expandir el alcance con tipo de prestación. Quiero que me digas si hay alguna otra cosa que quieras hacer antes de pasar a la etapa de crear las migraciones.

Sí. Hay algunas cosas que considero importantes cerrar antes de empezar a escribir código, pero son pocas y todas están directamente relacionadas con las migraciones. No propondría ampliar el alcance más allá de esto.

1. Confirmar el modelo completo de datos del módulo

Hasta ahora veo estas tablas:

prestaciones
tratamiento_propuestas
tratamiento_propuesta_items

Y las ya existentes:

pacientes
odontogramas

No agregaría ninguna más por ahora.

2. Definir las columnas exactamente

Me gustaría consensuar el nombre, tipo y nulabilidad de cada columna antes de generar la primera migración.

Por ejemplo, en tratamiento_propuestas todavía tenemos que terminar de decidir si guardaremos:

número visible de propuesta (si existe)
fecha de emisión
fecha de aceptación
fecha de rechazo
observaciones
subtotal
descuento
total

o si algunas de esas cosas todavía no existirán.

Prefiero decidirlo ahora y no modificar migraciones una semana después.

3. Definir las restricciones

Por ejemplo:

prestaciones.codigo UNIQUE.
tratamiento_propuestas.paciente_id con FK.
comportamiento onDelete.
índices que necesitaremos.

Eso conviene decidirlo antes de escribir.

4. Definir los modelos Eloquent

Antes de escribir una migración me gusta tener claro algo como:

Paciente
    hasMany TratamientoPropuesta

TratamientoPropuesta
    belongsTo Paciente
    hasMany TratamientoPropuestaItem

TratamientoPropuestaItem
    belongsTo TratamientoPropuesta
    belongsTo Prestacion

Prestacion
    hasMany TratamientoPropuestaItem

No cuesta nada y evita renombrar relaciones después.

5. Definir las APIs

Ya sabemos bastante bien cómo queremos trabajar.

Por ejemplo:

GET  /pacientes/{paciente}/propuestas

GET  /tratamiento-propuestas/{propuesta}

POST /pacientes/{paciente}/propuestas

POST /tratamiento-propuestas/{propuesta}/emitir

POST /tratamiento-propuestas/{propuesta}/aceptar

POST /tratamiento-propuestas/{propuesta}/rechazar

Prefiero tenerlas decididas antes de escribir los controladores.

6. Decidir el orden de implementación

Este punto me parece el más importante.

Yo seguiría exactamente este orden:

prestaciones
tratamiento_propuestas
tratamiento_propuesta_items
Modelos Eloquent
Seeders de prestaciones
APIs
Pantalla de catálogo de prestaciones
Pantalla de propuesta de tratamiento

Ese orden permite probar cada módulo antes de empezar el siguiente.

Mi impresión

Sinceramente, creo que ya terminamos el diseño conceptual. No veo ninguna decisión importante del dominio que esté pendiente. Lo que queda ahora son decisiones de ingeniería (columnas, índices, relaciones, endpoints).

Por eso, si estás de acuerdo, en la próxima etapa dejaría de escribir documentos y pasaría a producir código: migraciones, modelos, seeders, controladores y páginas de Inertia + React, manteniendo el mismo nivel de prolijidad con el que venimos diseñando.

Programemos Cosas

viernes, 17 de julio de 2026

Documentación del sistema: narrativa de flujo de negocio y de interacción (parte 4)