workspace-v1/projects/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: core/catalog/ (componentes reutilizables)
• Estándares: core/standards/ (estándares de documentación)

---

Version: 1.0.0 Ultima actualizacion: 2025-12-05