erp-core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-PRE-DESARROLLO.md

# DIRECTIVA: Documentacion Pre-Desarrollo

**Proyecto:** ERP Core - Base Generica Reutilizable
**Version:** 1.0.0
**Fecha:** 2025-12-05
**Aplicable a:** ERP Core y todas las verticales
**Autoridad:** Tech Lead / Arquitecto de Solucion
**Estado:** OBLIGATORIO - Politica permanente

---

## PRINCIPIO FUNDAMENTAL

> **"Primero documentar, despues desarrollar"**

Ningun desarrollo puede iniciarse sin la documentacion completa definida y aprobada. La documentacion es el contrato que guia la implementacion.

---

## ALCANCE

Esta directiva aplica a:
- ERP Core (modulos genericos)
- Todas las verticales (construccion, vidrio-templado, mecanicas-diesel, clinicas, retail)
- Cualquier extension o personalizacion

---

## FASES DE DOCUMENTACION PRE-DESARROLLO

### FASE 1: Definicion de Requerimientos

**Entregables obligatorios:**
```
docs/01-requerimientos/
├── RF-{modulo}/                    # Requerimientos Funcionales
│   ├── RF-{modulo}-001.md         # Requerimiento individual
│   └── INDICE-RF-{modulo}.md      # Indice del modulo
├── RNF-{modulo}/                   # Requerimientos No Funcionales
└── MATRIZ-TRAZABILIDAD.md          # Trazabilidad RF -> Modulo -> Historia
```

**Contenido minimo RF-{modulo}-NNN.md:**
```markdown
# RF-{modulo}-NNN: [Titulo descriptivo]

## Identificacion
| Campo | Valor |
|-------|-------|
| ID | RF-{modulo}-NNN |
| Prioridad | P0/P1/P2/P3 |
| Complejidad | Alta/Media/Baja |
| Modulo | {nombre_modulo} |
| Dependencias | RF-xxx, RF-yyy |

## Descripcion
[Descripcion clara del requerimiento]

## Criterios de Aceptacion
- [ ] Criterio 1
- [ ] Criterio 2
- [ ] Criterio 3

## Reglas de Negocio
1. RN-001: [descripcion]
2. RN-002: [descripcion]

## Impacto en Capas
- **Database:** [tablas/schemas afectados]
- **Backend:** [modulos/services afectados]
- **Frontend:** [paginas/componentes afectados]

## Referencias
- Vertical aplicable: [core/construccion/vidrio/etc]
- Referencia Odoo: [si aplica]
```

---

### FASE 2: Modelado de Base de Datos

**Entregables obligatorios:**
```
docs/02-modelado/
├── database-design/
│   ├── ERD-{modulo}.md             # Diagrama ER en Mermaid
│   ├── DDL-SPEC-{schema}.md        # Especificacion detallada
│   └── DICCIONARIO-DATOS.md        # Diccionario de datos
├── domain-models/
│   ├── DM-{modulo}.md              # Modelo de dominio
│   └── AGREGADOS-{modulo}.md       # Agregados DDD
└── especificaciones-tecnicas/
    ├── ET-{modulo}-database.md     # Spec tecnica DB
    └── ET-{modulo}-api.md          # Spec tecnica API
```

**Contenido minimo DDL-SPEC-{schema}.md:**
```markdown
# Especificacion DDL: Schema {nombre}

## Resumen
| Metrica | Valor |
|---------|-------|
| Tablas | N |
| Funciones | N |
| Triggers | N |
| Vistas | N |

## Diagrama ER

```mermaid
erDiagram
    TABLA_A ||--o{ TABLA_B : tiene
    TABLA_A {
        uuid id PK
        varchar nombre
        timestamp created_at
    }
```

## Tablas

### {nombre_tabla}

| Columna | Tipo | Nullable | Default | Descripcion |
|---------|------|----------|---------|-------------|
| id | UUID | NOT NULL | gen_random_uuid() | PK |
| tenant_id | UUID | NOT NULL | - | FK a tenants |
| ... | ... | ... | ... | ... |

**Indices:**
- `idx_{tabla}_tenant` ON (tenant_id)
- `idx_{tabla}_{columna}` ON (columna)

**Constraints:**
- `pk_{tabla}` PRIMARY KEY (id)
- `fk_{tabla}_tenant` FOREIGN KEY (tenant_id) REFERENCES tenants(id)
- `uq_{tabla}_{columna}` UNIQUE (tenant_id, columna)

**Triggers:**
- `trg_{tabla}_updated_at` - Actualiza updated_at en UPDATE
- `trg_{tabla}_audit` - Registra en audit_log

**RLS Policies:**
- `tenant_isolation_{tabla}` - Filtro por tenant_id
```

---

### FASE 3: Historias de Usuario

**Entregables obligatorios:**
```
docs/03-user-stories/
├── {MGN-NNN}/                      # Modulo generico
│   ├── US-{MGN-NNN}-001.md        # Historia de usuario
│   ├── US-{MGN-NNN}-002.md
│   └── BACKLOG-{MGN-NNN}.md       # Backlog del modulo
├── {MAI-NNN}/                      # Modulo vertical (ej: construccion)
│   ├── US-{MAI-NNN}-001.md
│   └── BACKLOG-{MAI-NNN}.md
└── BACKLOG-MAESTRO.md              # Backlog consolidado
```

**Contenido minimo US-{modulo}-NNN.md:**
```markdown
# US-{modulo}-NNN: [Titulo]

## Identificacion
| Campo | Valor |
|-------|-------|
| ID | US-{modulo}-NNN |
| Modulo | {nombre_modulo} |
| Prioridad | P0/P1/P2/P3 |
| Story Points | N |
| Sprint | Sprint N |

## Historia
**Como** [rol de usuario]
**Quiero** [accion/funcionalidad]
**Para** [beneficio/valor]

## Criterios de Aceptacion (Gherkin)

### Escenario 1: [nombre]
```gherkin
Given [contexto inicial]
When [accion del usuario]
Then [resultado esperado]
And [resultado adicional]
```

## Mockups/Wireframes
[Referencia a figma/imagen o descripcion de UI]

## Notas Tecnicas
- API Endpoints requeridos
- Validaciones especiales
- Integraciones

## Dependencias
- US-xxx (bloqueante)
- US-yyy (relacionada)

## Trazabilidad
- RF: RF-{modulo}-NNN
- Tabla: {schema}.{tabla}
- API: [endpoint]
```

---

### FASE 4: Especificaciones Tecnicas

**Entregables obligatorios:**
```
docs/02-modelado/especificaciones-tecnicas/
├── ET-{modulo}-database.md         # Backend especificacion
├── ET-{modulo}-backend.md          # Backend especificacion
├── ET-{modulo}-frontend.md         # Frontend especificacion
└── ET-{modulo}-integration.md      # Integracion entre capas
```

**Contenido minimo ET-{modulo}-backend.md:**
```markdown
# Especificacion Tecnica Backend: {modulo}

## Resumen de Implementacion

### Estructura de Modulo
```
modules/{modulo}/
├── {modulo}.module.ts
├── {modulo}.controller.ts
├── {modulo}.service.ts
├── entities/
│   └── {entidad}.entity.ts
├── dto/
│   ├── create-{entidad}.dto.ts
│   ├── update-{entidad}.dto.ts
│   └── query-{entidad}.dto.ts
└── __tests__/
    └── {modulo}.service.spec.ts
```

## API Endpoints

### GET /api/{modulo}
- **Descripcion:** Lista paginada de {entidad}
- **Query params:** page, limit, sort, filter[campo]
- **Response:** `{ data: [], meta: { total, page, limit } }`
- **Permisos:** `{modulo}:read`

### POST /api/{modulo}
- **Descripcion:** Crear {entidad}
- **Body:** CreateDto
- **Response:** `{ data: {entidad} }`
- **Permisos:** `{modulo}:create`

[... mas endpoints]

## DTOs

### Create{Entidad}Dto
```typescript
{
  nombre: string;        // required, 3-100 chars
  codigo?: string;       // optional, unique per tenant
  descripcion?: string;  // optional, max 500 chars
}
```

## Validaciones
| Campo | Regla | Mensaje Error |
|-------|-------|---------------|
| nombre | required, 3-100 | "Nombre es requerido (3-100 caracteres)" |
| codigo | unique per tenant | "Codigo ya existe" |

## Manejo de Errores
| Codigo | Situacion | Response |
|--------|-----------|----------|
| 400 | Validacion fallida | `{ error: "VALIDATION_ERROR", details: [...] }` |
| 404 | No encontrado | `{ error: "NOT_FOUND", message: "..." }` |
| 409 | Conflicto | `{ error: "CONFLICT", message: "..." }` |
```

---

### FASE 5: Plan de Pruebas

**Entregables obligatorios:**
```
docs/04-test-plans/
├── TP-{modulo}.md                  # Plan de pruebas del modulo
├── TC-{modulo}/                    # Casos de prueba
│   ├── TC-{modulo}-001.md
│   └── TC-{modulo}-002.md
└── ESTRATEGIA-TESTING.md           # Estrategia global
```

**Contenido minimo TP-{modulo}.md:**
```markdown
# Plan de Pruebas: {modulo}

## Alcance
- Pruebas unitarias: Services, DTOs
- Pruebas integracion: Controllers, Database
- Pruebas E2E: Flujos criticos

## Cobertura Minima
| Capa | Cobertura |
|------|-----------|
| Services | 80% |
| Controllers | 70% |
| Frontend | 60% |

## Casos de Prueba Criticos

### TC-001: CRUD basico
- Crear entidad valida
- Leer entidad existente
- Actualizar campos
- Eliminar (soft delete)

### TC-002: Validaciones
- Campos requeridos vacios
- Formatos invalidos
- Unicidad violada

### TC-003: Permisos
- Sin autenticacion (401)
- Sin permiso (403)
- Tenant incorrecto (404)
```

---

## CHECKLIST PRE-DESARROLLO

Antes de iniciar cualquier desarrollo, verificar:

### Requerimientos
- [ ] RF documentado con criterios de aceptacion
- [ ] Reglas de negocio definidas
- [ ] Dependencias identificadas
- [ ] Prioridad asignada

### Base de Datos
- [ ] Diagrama ER actualizado
- [ ] DDL-SPEC con todas las tablas
- [ ] Diccionario de datos completo
- [ ] Indices y constraints definidos
- [ ] RLS policies especificadas

### Backend
- [ ] Especificacion tecnica completa
- [ ] Endpoints definidos con request/response
- [ ] DTOs especificados con validaciones
- [ ] Permisos definidos

### Frontend
- [ ] Wireframes/mockups aprobados
- [ ] Componentes identificados
- [ ] Flujos de navegacion
- [ ] Estados de UI (loading, error, empty)

### Testing
- [ ] Plan de pruebas creado
- [ ] Casos de prueba criticos definidos
- [ ] Cobertura minima establecida

---

## PROCESO DE APROBACION

```
┌─────────────────────────────────────────────────────────────┐
│ 1. CREAR DOCUMENTACION                                       │
│    Desarrollador/Analista crea docs segun templates          │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. REVISION TECNICA                                          │
│    Tech Lead revisa consistencia y completitud               │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. VALIDACION NEGOCIO                                        │
│    PO valida que refleja requerimientos correctamente        │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. APROBACION FINAL                                          │
│    ✅ Marcar docs como "APROBADO"                            │
│    ✅ Crear tarea en backlog con referencia a docs           │
└─────────────┬───────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. INICIAR DESARROLLO                                        │
│    Solo con documentacion APROBADA                           │
└─────────────────────────────────────────────────────────────┘
```

---

## ESTRUCTURA DOCS POR VERTICAL

Cada vertical debe mantener su propia documentacion que EXTIENDE la del core:

```
apps/verticales/{vertical}/docs/
├── 00-vision-general/
│   └── VISION-{VERTICAL}.md
├── 01-requerimientos/
│   └── RF-{MAI-NNN}/              # Modulos especificos de vertical
├── 02-modelado/
│   ├── database-design/
│   │   └── DDL-SPEC-{schema}.md   # Schemas propios de vertical
│   └── especificaciones-tecnicas/
├── 03-user-stories/
│   └── {MAI-NNN}/
├── 04-test-plans/
└── 90-transversal/
    └── MAPEO-CORE-VERTICAL.md     # Mapeo de modulos core usados
```

---

## REFERENCIAS

### Directivas Relacionadas
- `core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md`
- `core/orchestration/directivas/DIRECTIVA-FLUJO-5-FASES.md`
- `core/orchestration/directivas/DIRECTIVA-VALIDACION-DOCUMENTACION.md`

### Templates
- `core/orchestration/templates/TEMPLATE-ANALISIS.md`
- `core/orchestration/templates/TEMPLATE-PLAN.md`

### Patrones de Referencia
- Odoo Enterprise modules structure
- `knowledge-base/patterns/` (patrones de Odoo)

---

## CONSECUENCIAS DE NO DOCUMENTAR

1. **Desarrollo rechazado:** No se puede iniciar sin docs aprobados
2. **Regresion:** Si se descubre falta de docs, se pausa desarrollo
3. **Deuda tecnica:** Docs incompletos generan deuda tecnica critica
4. **Impacto en verticales:** Afecta a todas las verticales que heredan

---

**Version:** 1.0.0
**Ultima actualizacion:** 2025-12-05
**Estado:** ACTIVA Y OBLIGATORIA