# DIRECTIVA: ESTRUCTURA DE DOCUMENTACIÓN DE PROYECTOS

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Aplicable a:** Todos los proyectos en `/workspace/projects/`
**Estado:** OBLIGATORIO

---

## OBJETIVO

Definir la estructura estándar de carpetas para la documentación técnica de proyectos, garantizando:
- Numeración única sin duplicados
- Organización lógica por ciclo de vida del proyecto
- Consistencia entre proyectos
- Facilidad de navegación y mantenimiento

---

## ESTRUCTURA ESTÁNDAR

```
{proyecto}/docs/
├── 00-vision-general/           # Visión, objetivos y alcance del proyecto
├── 01-analisis-referencias/     # Análisis de sistemas de referencia
├── 02-definicion-modulos/       # Lista, índice y dependencias de módulos
├── 03-requerimientos/           # Requerimientos funcionales organizados por módulo
│   └── RF-{modulo}/             # Subcarpeta por módulo (RF-auth, RF-users, etc.)
├── 04-modelado/                 # Diseño técnico
│   ├── database-design/         # DDL specs, schemas, diagramas ER
│   ├── domain-models/           # Modelos de dominio
│   └── especificaciones-tecnicas/  # ET backend/frontend por módulo
├── 05-user-stories/             # Historias de usuario por módulo
│   └── US-{modulo}/             # Subcarpeta por módulo
├── 06-test-plans/               # Planes y casos de prueba
├── 07-devops/                   # CI/CD, infraestructura, deployment
├── 90-transversal/              # Documentos que aplican a todo el proyecto
├── 95-guias-desarrollo/         # Guías para desarrolladores
└── 97-adr/                      # Architecture Decision Records
```

---

## REGLAS DE NUMERACIÓN

### Prefijos Reservados

| Rango | Propósito | Ejemplo |
|-------|-----------|---------|
| 00-09 | Visión y análisis inicial | 00-vision-general, 01-analisis-referencias |
| 10-19 | Definición y requerimientos | 02-definicion-modulos, 03-requerimientos |
| 20-49 | Diseño y modelado | 04-modelado |
| 50-69 | Implementación | 05-user-stories, 06-test-plans |
| 70-79 | Operaciones | 07-devops |
| 90-99 | Transversales y referencias | 90-transversal, 95-guias, 97-adr |

### Reglas

1. **PROHIBIDO** usar el mismo prefijo numérico para carpetas diferentes
2. Los prefijos deben ser de 2 dígitos (00-99)
3. Usar guiones (`-`) como separador, NO underscores
4. Nombres en kebab-case después del prefijo
5. Dejar gaps en numeración para futuras adiciones

---

## MAPEO DE CARPETAS EXISTENTES

### Carpetas DEPRECADAS (eliminar si están vacías)

Las siguientes carpetas fueron usadas en versiones anteriores y deben eliminarse:

- `01-fase-mvp` → Contenido migrar a `00-vision-general` o eliminar
- `02-fase-core` → Contenido migrar a `02-definicion-modulos` o eliminar
- `03-fase-complementaria` → Eliminar (concepto obsoleto)
- `adr` → Migrar contenido a `97-adr`

### Renumeración Requerida

Si un proyecto tiene estructura antigua:

| Antes | Después | Acción |
|-------|---------|--------|
| 00-analisis-referencias | 01-analisis-referencias | Renumerar |
| 00-vision-general | 00-vision-general | Mantener |
| 01-definicion-modulos | 02-definicion-modulos | Renumerar |
| 01-requerimientos | 03-requerimientos | Renumerar |
| 02-modelado | 04-modelado | Renumerar |
| 03-user-stories | 05-user-stories | Renumerar |
| 04-test-plans | 06-test-plans | Renumerar |
| 05-devops | 07-devops | Renumerar |

---

## CONTENIDO POR CARPETA

### 00-vision-general/

```
00-vision-general/
├── VISION-{PROYECTO}.md         # Documento de visión del proyecto
├── ALCANCE.md                   # Alcance y límites
├── STAKEHOLDERS.md              # Partes interesadas
└── ROADMAP.md                   # Roadmap de alto nivel
```

### 01-analisis-referencias/

```
01-analisis-referencias/
├── {sistema}/                   # Subcarpeta por sistema analizado
│   ├── README.md                # Resumen del análisis
│   ├── {modulo}-analysis.md     # Análisis por módulo
│   └── ADOPTAR-ADAPTAR-EVITAR.md
├── MAPA-COMPONENTES.md          # Mapeo de componentes genéricos
└── RESUMEN-FASE-0.md            # Resumen del análisis inicial
```

### 02-definicion-modulos/

```
02-definicion-modulos/
├── LISTA-MODULOS.md             # Lista completa de módulos
├── INDICE-MODULOS.md            # Índice con estados y progreso
├── DEPENDENCIAS-MODULOS.md      # Matriz de dependencias
├── ALCANCE-POR-MODULO.md        # Alcance de cada módulo
└── gaps/                        # Gap analysis por módulo
    └── GAP-ANALYSIS-MGN-{NNN}.md
```

### 03-requerimientos/

```
03-requerimientos/
├── RF-{modulo}/                 # Requerimientos por módulo
│   ├── INDICE-RF-{MODULO}.md    # Índice de RFs del módulo
│   └── RF-{MODULO}-{NNN}.md     # Requerimiento individual
└── RNF/                         # Requerimientos no funcionales
    └── RNF-{NNN}.md
```

### 04-modelado/

```
04-modelado/
├── database-design/
│   ├── README.md                # Índice de schemas
│   ├── DDL-SPEC-{schema}.md     # Especificación DDL por schema
│   ├── database-roadmap.md      # Roadmap de DB
│   └── schemas/                 # Estadísticas y diagramas
├── domain-models/
│   └── {dominio}-domain.md      # Modelo de dominio
└── especificaciones-tecnicas/
    ├── backend/
    │   └── mgn-{nnn}/
    │       └── ET-BACKEND-MGN-{NNN}-{NNN}-{nombre}.md
    └── frontend/
        └── mgn-{nnn}/
            └── ET-FRONTEND-MGN-{NNN}-{NNN}-{nombre}.md
```

### 05-user-stories/

```
05-user-stories/
└── US-{modulo}/
    ├── INDICE-US-{MODULO}.md    # Índice de historias
    └── US-{MODULO}-{NNN}.md     # Historia de usuario
```

### 06-test-plans/

```
06-test-plans/
├── ESTRATEGIA-TESTING.md        # Estrategia general de testing
├── unit/                        # Tests unitarios
├── integration/                 # Tests de integración
└── e2e/                         # Tests end-to-end
```

### 07-devops/

```
07-devops/
├── ARQUITECTURA-INFRA.md        # Arquitectura de infraestructura
├── CI-CD.md                     # Pipelines de CI/CD
├── DEPLOYMENT.md                # Guía de deployment
└── MONITORING.md                # Monitoreo y alertas
```

### 90-transversal/

```
90-transversal/
├── GLOSARIO.md                  # Glosario de términos
├── CONVENCIONES.md              # Convenciones del proyecto
└── FAQ.md                       # Preguntas frecuentes
```

### 95-guias-desarrollo/

```
95-guias-desarrollo/
├── SETUP-LOCAL.md               # Configuración local
├── CONTRIBUTING.md              # Guía de contribución
└── CODE-STYLE.md                # Estilo de código
```

### 97-adr/

```
97-adr/
└── ADR-{NNN}-{nombre}.md        # Decisiones arquitectónicas
```

---

## PROCESO DE MIGRACIÓN

### Para proyectos existentes con estructura antigua:

1. **Identificar** carpetas con numeración duplicada
2. **Verificar** si las carpetas están vacías
3. **Eliminar** carpetas vacías deprecadas
4. **Migrar** contenido de carpetas con contenido a la nueva ubicación
5. **Renumerar** según la tabla de mapeo
6. **Actualizar** referencias internas en documentos

### Comandos de migración (ejemplo para erp-core):

```bash
# 1. Eliminar carpetas vacías
rmdir docs/01-fase-mvp docs/02-fase-core docs/03-fase-complementaria docs/97-adr 2>/dev/null

# 2. Mover contenido de adr a 97-adr
mv docs/adr/* docs/97-adr/ && rmdir docs/adr

# 3. Renumerar carpetas (ajustar según necesidad)
# NOTA: Usar git mv para mantener historial
git mv docs/00-analisis-referencias docs/01-analisis-referencias
git mv docs/01-definicion-modulos docs/02-definicion-modulos
git mv docs/01-requerimientos docs/03-requerimientos
git mv docs/02-modelado docs/04-modelado
git mv docs/03-user-stories docs/05-user-stories
git mv docs/04-test-plans docs/06-test-plans
git mv docs/05-devops docs/07-devops
```

---

## VALIDACIÓN

### Checklist de validación de estructura:

- [ ] No hay prefijos numéricos duplicados
- [ ] Todas las carpetas siguen el formato `NN-nombre-kebab-case`
- [ ] No hay carpetas vacías sin propósito
- [ ] Los documentos dentro siguen nomenclatura UPPERCASE.md
- [ ] Existe README.md o índice en cada carpeta principal
- [ ] Las referencias entre documentos son válidas

### Script de validación:

```bash
#!/bin/bash
# Validar estructura de docs
cd docs/

# Verificar duplicados
ls -d */ | cut -d'-' -f1 | sort | uniq -d

# Verificar formato de nombres
ls -d */ | grep -vE '^[0-9]{2}-[a-z-]+/$'

# Verificar carpetas vacías
find . -type d -empty
```

---

## EXCEPCIONES

Las siguientes excepciones están permitidas:

1. **Carpeta `adr/`** puede coexistir con `97-adr/` temporalmente durante migración
2. **Subcarpetas de módulos** no requieren prefijo numérico (ej: `RF-auth/`)
3. **Carpetas de assets** (images, diagrams) pueden usar nombres simples

---

## REFERENCIAS

- [ESTANDARES-NOMENCLATURA-BASE.md](./ESTANDARES-NOMENCLATURA-BASE.md)
- [DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md](./DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md)
- [PRINCIPIOS-SOLID-DOCS.md](./PRINCIPIOS-SOLID-DOCS.md)

---

**Versión:** 1.0.0
**Creada por:** Architecture-Analyst
**Aprobada por:** Tech Lead
**Última actualización:** 2025-12-05
