erp-suite/docs/ESTRUCTURA-DOCUMENTACION-ERP.md

# Estructura de Documentacion - ERP Suite

**Version:** 1.0.0
**Fecha:** 2025-12-05

---

## Vision General

Este documento define la estructura estandar de documentacion para todos los proyectos de la suite ERP:
- **ERP Core** (base generica)
- **Verticales** (construccion, vidrio-templado, mecanicas-diesel, clinicas, retail)

---

## Principio: Documentacion Pre-Desarrollo

> **Toda documentacion debe existir ANTES de iniciar el desarrollo**

Ver: `apps/erp-core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-PRE-DESARROLLO.md`

---

## Estructura de Directorios

### ERP Core (Base)

```
apps/erp-core/
├── docs/
│   ├── 00-vision-general/
│   │   ├── VISION-ERP-CORE.md
│   │   ├── ARQUITECTURA-GENERAL.md
│   │   └── ROADMAP.md
│   │
│   ├── 00-analisis-referencias/
│   │   ├── ANALISIS-ODOO.md
│   │   ├── PATRONES-REFERENCIA.md
│   │   └── BENCHMARKS.md
│   │
│   ├── 01-definicion-modulos/
│   │   ├── INDICE-MODULOS.md
│   │   ├── MGN-001-auth/
│   │   │   ├── DEFINICION.md
│   │   │   └── DEPENDENCIAS.md
│   │   ├── MGN-002-users/
│   │   └── ... (hasta MGN-015)
│   │
│   ├── 01-requerimientos/
│   │   ├── RF-auth/
│   │   │   ├── RF-AUTH-001.md
│   │   │   └── INDICE-RF-AUTH.md
│   │   ├── RF-users/
│   │   ├── RNF/
│   │   │   └── RNF-PERFORMANCE.md
│   │   └── MATRIZ-TRAZABILIDAD.md
│   │
│   ├── 02-modelado/
│   │   ├── database-design/
│   │   │   ├── ERD-COMPLETO.md
│   │   │   ├── DDL-SPEC-core_auth.md
│   │   │   ├── DDL-SPEC-core_users.md
│   │   │   ├── DDL-SPEC-core_partners.md
│   │   │   └── DICCIONARIO-DATOS.md
│   │   ├── domain-models/
│   │   │   ├── DM-auth.md
│   │   │   └── AGREGADOS.md
│   │   └── especificaciones-tecnicas/
│   │       ├── ET-auth-database.md
│   │       ├── ET-auth-backend.md
│   │       ├── ET-auth-frontend.md
│   │       └── ET-auth-integration.md
│   │
│   ├── 03-user-stories/
│   │   ├── MGN-001-auth/
│   │   │   ├── US-MGN001-001.md
│   │   │   ├── US-MGN001-002.md
│   │   │   └── BACKLOG-MGN001.md
│   │   ├── MGN-002-users/
│   │   └── BACKLOG-MAESTRO.md
│   │
│   ├── 04-test-plans/
│   │   ├── TP-auth.md
│   │   ├── TC-auth/
│   │   │   └── TC-AUTH-001.md
│   │   └── ESTRATEGIA-TESTING.md
│   │
│   ├── 90-transversal/
│   │   ├── SEGURIDAD.md
│   │   ├── MULTI-TENANCY.md
│   │   └── AUDITORIA.md
│   │
│   ├── 95-guias-desarrollo/
│   │   ├── GUIA-BACKEND.md
│   │   ├── GUIA-FRONTEND.md
│   │   ├── GUIA-DATABASE.md
│   │   └── CONVENCIONES.md
│   │
│   └── 97-adr/
│       ├── ADR-001-stack-tecnologico.md
│       ├── ADR-002-multi-tenancy.md
│       └── INDICE-ADR.md
│
└── orchestration/
    ├── 00-guidelines/
    │   ├── CONTEXTO-PROYECTO.md
    │   └── HERENCIA-DIRECTIVAS.md
    ├── directivas/
    │   ├── DIRECTIVA-MULTI-TENANT.md
    │   ├── DIRECTIVA-EXTENSION-VERTICALES.md
    │   ├── DIRECTIVA-DOCUMENTACION-PRE-DESARROLLO.md
    │   └── DIRECTIVA-PATRONES-ODOO.md
    └── ... (estructura NEXUS estandar)
```

### Verticales (Extension)

Cada vertical EXTIENDE la documentacion del core, no la duplica.

```
apps/verticales/{vertical}/
├── docs/
│   ├── 00-vision-general/
│   │   ├── VISION-{VERTICAL}.md           # Vision especifica
│   │   └── MAPEO-CORE.md                  # Que modulos del core usa
│   │
│   ├── 01-requerimientos/
│   │   ├── RF-{MAI-NNN}/                  # Solo reqs NUEVOS de vertical
│   │   │   ├── RF-{MAI-NNN}-001.md
│   │   │   └── INDICE-RF.md
│   │   └── EXTENSIONES-CORE.md            # Extensiones a RF del core
│   │
│   ├── 02-modelado/
│   │   ├── database-design/
│   │   │   ├── ERD-{VERTICAL}.md          # Solo schemas de vertical
│   │   │   └── DDL-SPEC-vertical_{x}.md
│   │   └── especificaciones-tecnicas/
│   │       └── ET-{modulo}-extension.md   # Extensiones al core
│   │
│   ├── 03-user-stories/
│   │   ├── {MAI-NNN}/                     # Modulos especificos
│   │   │   ├── US-{MAI-NNN}-001.md
│   │   │   └── BACKLOG.md
│   │   └── BACKLOG-{VERTICAL}.md
│   │
│   ├── 04-test-plans/
│   │   └── TP-{modulo}.md
│   │
│   └── 90-transversal/
│       └── INTEGRACIONES-{VERTICAL}.md
│
└── orchestration/
    ├── 00-guidelines/
    │   ├── CONTEXTO-PROYECTO.md           # Contexto de la vertical
    │   └── HERENCIA-DIRECTIVAS.md         # Hereda core + erp-core
    ├── directivas/
    │   └── DIRECTIVA-{VERTICAL}.md        # Directivas propias
    └── ... (estructura NEXUS estandar)
```

---

## Nomenclatura de Modulos

### Core (MGN - Modulo Generico)

| Codigo | Modulo | Descripcion |
|--------|--------|-------------|
| MGN-001 | auth | Autenticacion y sesiones |
| MGN-002 | users | Gestion de usuarios |
| MGN-003 | roles | Roles y permisos (RBAC) |
| MGN-004 | tenants | Multi-tenancy |
| MGN-005 | catalogs | Catalogos maestros |
| MGN-006 | settings | Configuracion sistema |
| MGN-007 | audit | Auditoria y logs |
| MGN-008 | notifications | Notificaciones |
| MGN-009 | reports | Reportes genericos |
| MGN-010 | financial | Contabilidad basica |
| MGN-011 | inventory | Inventario basico |
| MGN-012 | purchasing | Compras basicas |
| MGN-013 | sales | Ventas basicas |
| MGN-014 | crm | CRM basico |
| MGN-015 | projects | Proyectos genericos |

### Construccion (MAI - Modulo Arquitectura Inmobiliaria)

| Codigo | Modulo | Descripcion |
|--------|--------|-------------|
| MAI-001 | fundamentos | Base de construccion |
| MAI-002 | proyectos-obra | Proyectos de construccion |
| MAI-003 | presupuestos | Presupuestos de obra |
| MAI-004 | compras-inventarios | Compras especializadas |
| MAI-005 | control-obra | Control de avances |
| MAI-006 | subcontratistas | Gestion subcontratistas |
| MAI-007 | infonavit | Integracion INFONAVIT |

### Vidrio Templado (MVT - Modulo Vidrio Templado)

| Codigo | Modulo | Descripcion |
|--------|--------|-------------|
| MVT-001 | produccion | Ordenes de produccion |
| MVT-002 | corte-optimizacion | Optimizacion de corte |
| MVT-003 | templado | Proceso de templado |
| MVT-004 | instalacion | Instalacion en sitio |

### Mecanicas Diesel (MMD - Modulo Mecanica Diesel)

| Codigo | Modulo | Descripcion |
|--------|--------|-------------|
| MMD-001 | ordenes-servicio | Ordenes de trabajo |
| MMD-002 | diagnostico | Diagnostico diesel |
| MMD-003 | refacciones | Refacciones especializadas |

---

## Flujo de Documentacion

```
┌─────────────────────────────────────────────────────────────────┐
│ PASO 1: REQUERIMIENTOS                                          │
│ ─────────────────────                                           │
│ • Crear RF-{modulo}-NNN.md con criterios de aceptacion          │
│ • Definir reglas de negocio                                     │
│ • Identificar dependencias con otros modulos                    │
│ • Actualizar MATRIZ-TRAZABILIDAD.md                             │
│                                                                 │
│ Entregable: docs/01-requerimientos/RF-{modulo}/                 │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│ PASO 2: MODELADO DATABASE                                       │
│ ────────────────────────                                        │
│ • Disenar diagrama ER (Mermaid)                                 │
│ • Crear DDL-SPEC-{schema}.md con todas las tablas               │
│ • Definir indices, constraints, triggers                        │
│ • Especificar RLS policies                                      │
│ • Actualizar DICCIONARIO-DATOS.md                               │
│                                                                 │
│ Entregable: docs/02-modelado/database-design/                   │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│ PASO 3: ESPECIFICACIONES TECNICAS                               │
│ ───────────────────────────────                                 │
│ • ET-{modulo}-database.md (DDL final)                           │
│ • ET-{modulo}-backend.md (endpoints, DTOs, validaciones)        │
│ • ET-{modulo}-frontend.md (componentes, paginas, estados)       │
│ • ET-{modulo}-integration.md (flujos entre capas)               │
│                                                                 │
│ Entregable: docs/02-modelado/especificaciones-tecnicas/         │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│ PASO 4: USER STORIES                                            │
│ ──────────────────                                              │
│ • Crear US-{modulo}-NNN.md con Gherkin                          │
│ • Asignar story points y prioridad                              │
│ • Vincular a requerimientos (trazabilidad)                      │
│ • Actualizar BACKLOG-{modulo}.md                                │
│                                                                 │
│ Entregable: docs/03-user-stories/{modulo}/                      │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│ PASO 5: PLAN DE PRUEBAS                                         │
│ ─────────────────────                                           │
│ • Crear TP-{modulo}.md con estrategia                           │
│ • Definir casos de prueba criticos                              │
│ • Establecer cobertura minima                                   │
│                                                                 │
│ Entregable: docs/04-test-plans/                                 │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│ PASO 6: APROBACION                                              │
│ ────────────────                                                │
│ • Tech Lead revisa completitud                                  │
│ • PO valida contra requerimientos                               │
│ • Marcar docs como APROBADO                                     │
│                                                                 │
│ Estado: LISTO PARA DESARROLLO                                   │
└─────────────────────────────────────────────────────────────────┘
```

---

## Checklist por Tipo de Documento

### Requerimiento Funcional (RF)
- [ ] Identificacion completa (ID, prioridad, modulo)
- [ ] Descripcion clara
- [ ] Criterios de aceptacion (minimo 3)
- [ ] Reglas de negocio definidas
- [ ] Impacto en capas identificado
- [ ] Dependencias listadas

### DDL Specification
- [ ] Diagrama ER actualizado
- [ ] Todas las tablas documentadas
- [ ] Columnas con tipo, nullable, default
- [ ] Indices definidos con proposito
- [ ] Constraints (PK, FK, UQ, CHK)
- [ ] Triggers especificados
- [ ] RLS policies definidas

### Especificacion Tecnica Backend
- [ ] Estructura de modulo definida
- [ ] Todos los endpoints documentados
- [ ] DTOs con validaciones
- [ ] Manejo de errores
- [ ] Permisos requeridos

### Historia de Usuario
- [ ] Formato "Como/Quiero/Para"
- [ ] Escenarios Gherkin
- [ ] Story points asignados
- [ ] Trazabilidad a RF
- [ ] Mockups/wireframes (si aplica)

### Plan de Pruebas
- [ ] Alcance definido
- [ ] Cobertura minima establecida
- [ ] Casos criticos identificados
- [ ] Datos de prueba especificados

---

## Referencias

### Directivas Relacionadas
- `core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md`
- `erp-core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-PRE-DESARROLLO.md`
- `erp-core/orchestration/directivas/DIRECTIVA-PATRONES-ODOO.md`

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

### Recursos de Referencia
- **Catálogo central:** `shared/catalog/` *(componentes reutilizables)*
- **Estándares:** `core/standards/` *(estándares de documentación)*

---

**Version:** 1.0.0
**Ultima actualizacion:** 2025-12-05