rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
0086695b4c
erp-core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-PRE-DESARROLLO.md

13 KiB
Raw Blame History

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:

# 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:

# 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