clinica-dental/docs/01-epicas/DENTAL-001-odontograma.md

# DENTAL-001: Odontograma Digital

## Metadata
- **Codigo:** DENTAL-001
- **Modulo:** Odontograma
- **Prioridad:** P0
- **Estado:** DDL Completado
- **Fase:** 1 - Core

## Descripcion

Sistema de odontograma digital interactivo que permite registrar y visualizar el estado de cada pieza dental del paciente, siguiendo la nomenclatura FDI (Federation Dentaire Internationale).

## Objetivos

1. Representacion grafica de dentadura completa
2. Registro de estado por pieza dental
3. Registro de afectaciones por cara dental
4. Historial de cambios por fecha
5. Comparativa entre odontogramas

## Alcance

### Incluido
- Vista grafica interactiva (32 piezas adulto + 20 deciduos)
- Estados por pieza: sano, caries, obturacion, endodoncia, corona, etc.
- Caras dentales: Mesial, Distal, Oclusal, Vestibular, Lingual
- Colores por estado (verde=sano, rojo=caries, gris=ausente)
- Historial cronologico
- Notas por pieza

### Excluido
- Edicion de imagen (dibujo libre)
- Generacion 3D
- Integracion directa con camaras intraorales

## Nomenclatura FDI

### Sistema de Numeracion (Adultos)

```
        SUPERIOR
    Derecho  |  Izquierdo
      18-11  |  21-28
    ---------|----------
      48-41  |  31-38
    Derecho  |  Izquierdo
        INFERIOR

Cuadrante 1: Superior derecho (11-18)
Cuadrante 2: Superior izquierdo (21-28)
Cuadrante 3: Inferior izquierdo (31-38)
Cuadrante 4: Inferior derecho (41-48)
```

### Dientes Deciduos (Ninos)

```
Cuadrante 5: Superior derecho deciduo (51-55)
Cuadrante 6: Superior izquierdo deciduo (61-65)
Cuadrante 7: Inferior izquierdo deciduo (71-75)
Cuadrante 8: Inferior derecho deciduo (81-85)
```

## Modelo de Datos

### Tablas

**dental.piezas_dentales** (Catalogo)
- id, numero, nombre, cuadrante, es_temporal

**dental.odontogramas**
- id, tenant_id, patient_id
- fecha_creacion, fecha_actualizacion
- notas

**dental.odontograma_piezas**
- id, tenant_id, odontograma_id, pieza_id
- estado (ENUM: sano, caries, obturacion, etc.)
- caras_afectadas (JSONB)
- observaciones

### Estados de Pieza (ENUM)

| Estado | Color | Descripcion |
|--------|-------|-------------|
| sano | Verde | Pieza sin alteraciones |
| caries | Rojo | Caries activa |
| obturacion | Azul | Restauracion existente |
| endodoncia | Morado | Tratamiento de conductos |
| corona | Dorado | Corona protesica |
| puente | Naranja | Parte de puente |
| implante | Plateado | Implante dental |
| ausente | Gris | Pieza faltante |
| extraccion_indicada | Rojo oscuro | Pendiente de extraccion |

### Caras Dentales

| Abreviatura | Nombre | Descripcion |
|-------------|--------|-------------|
| M | Mesial | Hacia el centro de la arcada |
| D | Distal | Alejandose del centro |
| O | Oclusal | Superficie de masticacion |
| V | Vestibular | Hacia labios/mejillas |
| L | Lingual | Hacia la lengua |
| P | Palatino | Hacia el paladar |

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /patients/:id/odontograma | Odontograma actual |
| GET | /patients/:id/odontogramas | Historial de odontogramas |
| POST | /patients/:id/odontograma | Crear nuevo odontograma |
| PUT | /odontogramas/:id | Actualizar odontograma |
| GET | /odontogramas/:id/piezas | Listar piezas |
| PUT | /odontogramas/:id/piezas/:piezaId | Actualizar pieza |
| GET | /odontogramas/:id/historial | Historial de cambios |
| GET | /odontogramas/comparar | Comparar dos fechas |

## Interfaz del Servicio

```typescript
interface OdontogramaService {
  getByPatient(patientId: string): Promise<Odontograma>;
  create(patientId: string): Promise<Odontograma>;
  updatePieza(odontogramaId: string, piezaId: string, data: PiezaUpdate): Promise<Pieza>;
  getHistorial(patientId: string): Promise<Odontograma[]>;
  compare(patientId: string, fecha1: Date, fecha2: Date): Promise<OdontogramaComparison>;
}

interface PiezaUpdate {
  estado: EstadoPieza;
  carasAfectadas?: Record<CaraDental, EstadoPieza>;
  observaciones?: string;
}
```

## Componente Frontend

### OdontogramaViewer

```typescript
interface OdontogramaViewerProps {
  patientId: string;
  editable: boolean;
  onPiezaClick: (pieza: Pieza) => void;
  showDeciduo: boolean;
}

// Colores por estado
const ESTADO_COLORS = {
  sano: '#22c55e',       // green-500
  caries: '#ef4444',     // red-500
  obturacion: '#3b82f6', // blue-500
  endodoncia: '#a855f7', // purple-500
  corona: '#f59e0b',     // amber-500
  ausente: '#9ca3af',    // gray-400
  implante: '#64748b'    // slate-500
};
```

### PiezaEditor (Modal)

```typescript
interface PiezaEditorProps {
  pieza: Pieza;
  onSave: (data: PiezaUpdate) => void;
  onClose: () => void;
}

// Vista de caras (5 cuadrados)
//     [V]
// [M] [O] [D]
//     [L]
```

## Flujos

### Ver Odontograma

```
1. Odontologo abre expediente de paciente
2. Sistema carga odontograma activo
3. Renderiza vista grafica con colores
4. Click en pieza muestra detalle
5. Puede ver historial de cambios
```

### Actualizar Estado

```
1. Odontologo hace click en pieza
2. Abre modal de edicion
3. Selecciona nuevo estado
4. Marca caras afectadas (si aplica)
5. Agrega observaciones
6. Guarda cambios
7. Sistema actualiza vista y registra historial
```

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL odontogramas | Completado | `database/schemas/01-dental-schema-ddl.sql` |
| Seeds piezas | Completado | 52 piezas FDI |
| odontograma.module.ts | Pendiente | `backend/modules/odontograma/` |
| odontograma.service.ts | Pendiente | `backend/services/` |
| OdontogramaViewer.tsx | Pendiente | `frontend/components/` |
| PiezaEditor.tsx | Pendiente | `frontend/components/` |

## Dependencias

### Depende de
- clinica.patients (erp-clinicas)
- Auth/Tenants (erp-core)

### Bloquea a
- DENTAL-002 (Tratamientos - asociacion a pieza)
- DENTAL-006 (Presupuestos - lineas por pieza)

## Criterios de Aceptacion

- [ ] Vista grafica de 32 piezas adulto
- [ ] Vista grafica de 20 piezas deciduo
- [ ] Click en pieza abre editor
- [ ] Estados se reflejan en colores
- [ ] Caras afectadas se registran
- [ ] Historial muestra cambios
- [ ] Comparativa entre fechas funciona

---

**Ultima actualizacion:** 2026-01-07