clinica-dental/docs/01-epicas/DENTAL-003-ortodoncia.md

# DENTAL-003: Ortodoncia

## Metadata
- **Codigo:** DENTAL-003
- **Modulo:** Ortodoncia
- **Prioridad:** P1
- **Estado:** DDL Completado
- **Fase:** 3 - Especialidades

## Descripcion

Sistema de gestion de tratamientos de ortodoncia: registro de casos, tipos de aparatologia, seguimiento de citas de ajuste, control de progreso, planes de pago, y finalizacion con retenedores.

## Objetivos

1. Registro de casos de ortodoncia
2. Tipos de aparatologia (brackets, alineadores)
3. Citas de ajuste mensuales
4. Seguimiento de progreso
5. Plan de pagos (enganche + mensualidades)

## Alcance

### Incluido
- Tipos: brackets metalicos, esteticos, linguales, alineadores
- Registro de fecha inicio/fin estimada
- Citas de control con detalles de ajuste
- Fotos de progreso (vinculo a storage)
- Control de arcos, ligas, elasticos
- Plan de pago con financiamiento

### Excluido
- Cefalometria digital
- Simulacion de resultados
- Analisis de modelos 3D

## Tipos de Ortodoncia

| Tipo | Descripcion | Duracion Tipica |
|------|-------------|-----------------|
| brackets_metalicos | Brackets tradicionales | 18-24 meses |
| brackets_esteticos | Brackets ceramicos/zafiro | 18-24 meses |
| brackets_linguales | Brackets en cara interna | 18-30 meses |
| alineadores | Alineadores transparentes | 12-18 meses |
| removible | Aparatos removibles | Variable |
| retenedor | Post-tratamiento | Indefinido |

## Modelo de Datos

### Tablas

**dental.ortodoncia**
- id, tenant_id, patient_id, odontologo_id
- tipo (ENUM), marca
- fecha_inicio, fecha_estimada_fin, fecha_real_fin
- estado, meses_estimados
- costo_total, enganche, mensualidad
- notas

**dental.ortodoncia_citas**
- id, tenant_id, ortodoncia_id
- appointment_id
- fecha, numero_cita
- procedimiento
- arco_superior, arco_inferior, ligas
- observaciones, proxima_cita

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /ortodoncia | Listar casos activos |
| GET | /ortodoncia/:id | Detalle de caso |
| POST | /ortodoncia | Crear caso |
| PUT | /ortodoncia/:id | Actualizar caso |
| PUT | /ortodoncia/:id/finalizar | Finalizar tratamiento |
| GET | /ortodoncia/:id/citas | Historial de citas |
| POST | /ortodoncia/:id/citas | Registrar cita |
| GET | /patients/:id/ortodoncia | Casos del paciente |
| GET | /ortodoncia/proximas-citas | Citas proximas |

## Interfaz del Servicio

```typescript
interface OrtodonticService {
  getCasosActivos(): Promise<CasoOrtodoncia[]>;
  getById(id: string): Promise<CasoOrtodoncia>;
  create(data: CreateCasoOrtodoncia): Promise<CasoOrtodoncia>;
  registrarCita(casoId: string, data: CitaOrtodoncia): Promise<CitaOrtodoncia>;
  finalizar(id: string, data: FinalizarOrtodoncia): Promise<CasoOrtodoncia>;
  getProximasCitas(dias: number): Promise<CitaOrtodoncia[]>;
}

interface CreateCasoOrtodoncia {
  patientId: string;
  odontologoId: string;
  tipo: TipoOrtodoncia;
  marca?: string;
  fechaInicio: Date;
  mesesEstimados: number;
  costoTotal: number;
  enganche?: number;
  mensualidad?: number;
}

interface CitaOrtodoncia {
  fecha: Date;
  numeroCita: number;
  procedimiento: string;
  arcoSuperior?: string;
  arcoInferior?: string;
  ligas?: string;
  observaciones?: string;
  proximaCita?: Date;
}
```

## Flujos

### Iniciar Caso de Ortodoncia

```
1. Consulta de valoracion ortodontica
2. Estudios iniciales (Rx panoramica, fotos, modelos)
3. Diagnostico y plan de tratamiento
4. Presentar presupuesto al paciente
5. Paciente acepta y paga enganche
6. Crear caso de ortodoncia en sistema
7. Agendar cita de colocacion
8. Colocar aparatologia
9. Registrar primera cita
```

### Cita de Ajuste Mensual

```
1. Paciente llega a cita programada
2. Revision de aparatologia
3. Cambio de arcos/ligas si necesario
4. Registrar procedimiento realizado
5. Tomar fotos de progreso (opcional)
6. Agendar proxima cita
7. Cobrar mensualidad
```

### Finalizacion

```
1. Tratamiento activo completo
2. Retiro de aparatologia
3. Colocacion de retenedores
4. Marcar caso como "finalizado"
5. Crear nuevo caso tipo "retenedor"
6. Programar citas de revision (3, 6, 12 meses)
```

## Plan de Pagos

```typescript
interface PlanPagoOrtodoncia {
  costoTotal: number;      // $45,000
  enganche: number;        // $10,000
  saldoPendiente: number;  // $35,000
  numeroPagos: number;     // 18
  montoPago: number;       // $1,944.44
  fechaInicio: Date;
  pagosRealizados: number;
  saldoActual: number;
}
```

## Componentes Frontend

### OrtodonciaTimeline

```typescript
// Visualizacion de progreso del tratamiento
interface OrtodonciaTimelineProps {
  caso: CasoOrtodoncia;
  citas: CitaOrtodoncia[];
}

// Muestra:
// - Linea de tiempo con citas
// - Progreso vs estimado
// - Proxima cita destacada
// - Fotos de progreso
```

### CitaOrtodonticaForm

```typescript
interface CitaOrtodonticaFormProps {
  casoId: string;
  numeroCita: number;
  onSave: (data: CitaOrtodoncia) => void;
}

// Campos:
// - Procedimiento realizado
// - Arco superior/inferior
// - Ligas/elasticos
// - Observaciones
// - Fecha proxima cita
```

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL ortodoncia | Completado | `database/schemas/01-dental-schema-ddl.sql` |
| ortodoncia.module.ts | Pendiente | `backend/modules/ortodoncia/` |
| ortodoncia.service.ts | Pendiente | `backend/services/` |
| OrtodonciaTimeline.tsx | Pendiente | `frontend/components/` |
| CitaOrtodonticaForm.tsx | Pendiente | `frontend/components/` |

## Dependencias

### Depende de
- clinica.patients (erp-clinicas)
- clinica.appointments (erp-clinicas)
- DENTAL-006 (Presupuestos - para plan de pago)

### Bloquea a
- Reportes de ortodoncia
- Recordatorios automaticos

## Criterios de Aceptacion

- [ ] CRUD de casos de ortodoncia
- [ ] Tipos de aparatologia correctos
- [ ] Citas de ajuste se registran
- [ ] Progreso visual en timeline
- [ ] Plan de pago funciona
- [ ] Finalizacion crea caso retenedor
- [ ] Proximas citas se listan

## Metricas

| Metrica | Descripcion |
|---------|-------------|
| Casos activos | Tratamientos en curso |
| Tasa finalizacion | % que completan tratamiento |
| Duracion promedio | Meses reales vs estimados |
| Desercion | Pacientes que abandonan |

---

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