# Guía de Desarrollo - EMERGES TES

**Reglas, principios y buenas prácticas para desarrolladores y asistentes de código.**

---

## 🎯 Objetivo de este Documento

Este documento establece las **reglas de desarrollo**, **principios a respetar** y **qué puede y qué no puede modificar** un asistente de código o desarrollador humano.

**Regla de oro:** Si una funcionalidad no está implementada ni documentada explícitamente, debe considerarse **inexistente**.

---

## 🚫 Normas Fundamentales

### 1. NO Asumir Funcionalidades Inexistentes

**CRÍTICO:** Un asistente de código **NO debe**:

- ❌ Asumir que existe una funcionalidad que no está documentada
- ❌ Inventar sistemas de negocio no implementados
- ❌ Crear entidades que no existen en el dominio
- ❌ Añadir features "porque sería útil" sin documentación previa

**Ejemplo incorrecto:**
```typescript
// ❌ INCORRECTO: Asumir que existe un sistema de tickets de soporte
interface SupportTicket {
  id: string;
  // ... esto NO existe en el dominio
}
```

**Ejemplo correcto:**
```typescript
// ✅ CORRECTO: Usar entidades que existen en el dominio
import type { ContentItem } from '../domain/entities/ContentItem.js';
```

### 2. NO Confundir Tickets con Entidades

**IMPORTANTE:** Los "tickets" (TICKET-001, TICKET-002, etc.) son **tareas técnicas de desarrollo**, NO entidades del dominio.

- ❌ **NO crear** entidades llamadas "Ticket"
- ❌ **NO añadir** lógica de negocio para "tickets"
- ✅ **SÍ usar** tickets como referencia a tareas técnicas (ver `docs/QUE_FALTA.md`)

**Entidades reales del dominio:**
- `ContentItem` - Protocolos, guías, manuales
- `Drug` - Fármacos
- `GlossaryTerm` - Términos del glosario
- `MediaResource` - Medios audiovisuales
- `MedicalReview` - Revisiones médicas

### 3. NO Modificar Arquitectura sin Documentar

**Antes de cambiar la arquitectura:**

1. ✅ Documentar el cambio en `SPEC.md`
2. ✅ Actualizar `.cursorrules` si afecta reglas de código
3. ✅ Justificar el cambio con razones técnicas claras

---

## ✅ Qué SÍ Puede Hacer un Asistente

### 1. Implementar Funcionalidades Documentadas

Un asistente **SÍ puede** implementar funcionalidades que estén:

- ✅ Documentadas en `SPEC.md`
- ✅ Listadas en `docs/QUE_FALTA.md` como tarea pendiente
- ✅ Definidas en `README_TODO.md` con especificaciones claras

### 2. Mejorar Código Existente

Un asistente **SÍ puede**:

- ✅ Refactorizar código siguiendo `.cursorrules`
- ✅ Añadir tests para aumentar cobertura
- ✅ Corregir bugs documentados
- ✅ Optimizar rendimiento sin cambiar arquitectura

### 3. Añadir Tests

Un asistente **SÍ puede**:

- ✅ Crear tests unitarios para servicios
- ✅ Crear tests de integración para API
- ✅ Aumentar cobertura de tests frontend
- ✅ Añadir tests para casos edge

### 4. Documentar Código

Un asistente **SÍ puede**:

- ✅ Añadir comentarios JSDoc
- ✅ Documentar funciones complejas
- ✅ Actualizar READMEs con información precisa
- ✅ Crear documentación técnica

---

## ❌ Qué NO Puede Hacer un Asistente

### 1. Inventar Funcionalidades

**NO debe:**

- ❌ Crear sistemas de tickets de soporte sin documentación previa
- ❌ Añadir features no documentadas en SPEC.md
- ❌ Asumir funcionalidades "porque sería lógico"
- ❌ Crear entidades que no existen en el dominio

### 2. Cambiar Arquitectura sin Justificación

**NO debe:**

- ❌ Cambiar de Clean Architecture a otra arquitectura sin documentar
- ❌ Modificar reglas de dependencias entre capas sin justificar
- ❌ Introducir frameworks nuevos sin evaluar impacto

### 3. Ignorar Reglas de Código

**NO debe:**

- ❌ Usar `any` en TypeScript (prohibido en `.cursorrules`)
- ❌ Mutar objetos directamente (inmutabilidad requerida)
- ❌ Saltarse validación Zod en puntos de entrada
- ❌ Crear funciones de más de 30 líneas sin dividir

### 4. Modificar Entidades sin Entender el Dominio

**NO debe:**

- ❌ Cambiar nombres de entidades sin justificar
- ❌ Añadir campos a entidades sin documentar en SPEC.md
- ❌ Eliminar campos de entidades sin verificar dependencias

---

## 📋 Principios de Desarrollo

### 1. Type Safety Estricto

- ✅ **PROHIBIDO** el uso de `any`
- ✅ Todos los tipos deben ser explícitos
- ✅ Usar tipos del dominio (`ContentItem`, `Drug`, etc.)

### 2. Inmutabilidad

- ✅ Todas las propiedades de entidades son `readonly`
- ✅ No mutar objetos directamente
- ✅ Crear nuevos objetos en lugar de modificar existentes

### 3. Validación Estricta

- ✅ Validar todos los inputs con Zod
- ✅ Validaciones básicas en entidades (`create()`)
- ✅ Validaciones complejas en servicios

### 4. Clean Architecture (Backend)

- ✅ Domain Layer: NO depende de nadie
- ✅ Application Layer: Solo depende de Domain
- ✅ Infrastructure Layer: Depende de Domain y Application
- ✅ Presentation Layer: Depende de Application y Domain

### 5. Early Returns

- ✅ Usar guard clauses para errores
- ✅ Evitar anidación profunda
- ✅ Retornar temprano en casos de error

### 6. Funciones Pequeñas

- ✅ Máximo 20-30 líneas por función
- ✅ Una sola responsabilidad
- ✅ Nombres descriptivos

---

## 🔍 Instrucciones para Trabajar con Asistentes de IA

### Para el Desarrollador Humano

1. **Proporcionar contexto claro:**
   - Especificar qué funcionalidad implementar
   - Referenciar documentación relevante (SPEC.md, tickets)
   - Indicar restricciones arquitectónicas

2. **Validar propuestas:**
   - Revisar que no invente funcionalidades
   - Verificar que respete `.cursorrules`
   - Comprobar que no cambie arquitectura sin justificar

3. **Revisar código generado:**
   - Verificar tipos TypeScript (sin `any`)
   - Comprobar validación Zod en inputs
   - Revisar que siga Clean Architecture

### Para el Asistente de IA

1. **Antes de proponer cambios:**
   - Leer `SPEC.md` para entender el dominio
   - Revisar `.cursorrules` para reglas de código
   - Consultar `README_ARCHITECTURE.md` para arquitectura
   - Verificar `docs/QUE_FALTA.md` para tareas pendientes

2. **Al proponer funcionalidades nuevas:**
   - Documentar en SPEC.md primero
   - Justificar la necesidad
   - Explicar impacto arquitectónico

3. **Al implementar código:**
   - Seguir `.cursorrules` estrictamente
   - Usar tipos del dominio existentes
   - Añadir validación Zod donde corresponda
   - Crear tests para código nuevo

---

## ⚠️ Advertencias Importantes

### 1. No Introducir Sistemas de Negocio No Documentados

**Ejemplo de lo que NO hacer:**

```typescript
// ❌ INCORRECTO: Inventar sistema de tickets de soporte
interface SupportTicket {
  id: string;
  userId: string;
  // ... esto NO existe en el dominio
}
```

**Si se necesita esta funcionalidad:**

1. Documentar en `SPEC.md` primero
2. Definir entidades en `domain/entities/`
3. Crear repositorios y servicios
4. Implementar API endpoints
5. Añadir tests

### 2. No Asumir Funcionalidades por Nombre

**Ejemplo:**

- Ver "TICKET-013" en código → NO significa que existe entidad "Ticket"
- Ver "validation" → Verificar qué significa en el contexto (puede ser validación médica de contenido, no tickets)

### 3. Verificar Antes de Modificar

**Antes de modificar entidades:**

1. Buscar todas las referencias en el código
2. Verificar dependencias en otros módulos
3. Comprobar tests que puedan romperse
4. Documentar cambios en SPEC.md si son significativos

---

## 📚 Referencias

- **`SPEC.md`** - Especificación maestra (fuente de verdad)
- **`.cursorrules`** - Reglas de código y arquitectura
- **`README_ARCHITECTURE.md`** - Arquitectura detallada
- **`docs/QUE_FALTA.md`** - Tareas pendientes
- **`docs/CONTENIDO_FALTANTE.md`** - Contenido faltante

---

## ✅ Checklist Antes de Aceptar Cambios

Antes de aceptar cambios propuestos por un asistente:

- [ ] ¿Respeta `.cursorrules`?
- [ ] ¿No inventa funcionalidades no documentadas?
- [ ] ¿No usa `any` en TypeScript?
- [ ] ¿Valida inputs con Zod?
- [ ] ¿Sigue Clean Architecture (backend)?
- [ ] ¿Añade tests para código nuevo?
- [ ] ¿Documenta cambios significativos en SPEC.md?

---

**Última actualización:** 2025-02-02