290 lines
8 KiB
Markdown
290 lines
8 KiB
Markdown
# 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
|