# Estándar de Estructura de Documentación

## Objetivo

Definir la estructura estándar para la documentación de proyectos dentro del workspace, basada en las mejores prácticas del proyecto Gamilit.

---

## Estructura de Carpetas `docs/`

### Principio de Numeración

La numeración sigue un esquema jerárquico:
- **00-09**: Visión general y contexto
- **01-0N**: Fases del proyecto (secuenciales)
- **90-99**: Documentación transversal y referencia

```
docs/
├── 00-vision-general/           # Visión, arquitectura, contexto
├── 01-fase-{nombre}/            # Primera fase del proyecto
├── 02-fase-{nombre}/            # Segunda fase del proyecto
├── ...                          # Fases adicionales según necesidad
├── 0N-fase-{nombre}/            # N-ésima fase
│
├── 90-transversal/              # Documentación que cruza todas las fases
├── 95-guias-desarrollo/         # Guías técnicas de desarrollo
├── 96-quick-reference/          # Referencias rápidas (cheatsheets)
├── 97-adr/                      # Architecture Decision Records
├── 98-standards/                # Estándares del proyecto
├── 99-finiquito/                # Documentación de cierre/entrega
│
├── {feature-especifica}/        # Carpetas de features sin numeración
└── README.md                    # Índice maestro de documentación
```

---

## Reglas de Numeración

### Fases del Proyecto (01-0N)

Las fases representan etapas cronológicas o lógicas del proyecto:

| Prefijo | Uso | Ejemplo |
|---------|-----|---------|
| `01-fase-` | Primera fase | `01-fase-alcance-inicial/` |
| `02-fase-` | Segunda fase | `02-fase-robustecimiento/` |
| `03-fase-` | Tercera fase | `03-fase-extensiones/` |
| `04-fase-` | Fase de backlog | `04-fase-backlog/` |

**Nomenclatura:** `{NN}-fase-{nombre-descriptivo}/`

### Documentación Transversal (90-99)

Reservada para documentación que no pertenece a una fase específica:

| Prefijo | Propósito |
|---------|-----------|
| `90-transversal/` | Cruza todas las fases (APIs, BD, componentes) |
| `95-guias-desarrollo/` | Guías técnicas para desarrolladores |
| `96-quick-reference/` | Cheatsheets, referencias rápidas |
| `97-adr/` | Architecture Decision Records |
| `98-standards/` | Estándares y convenciones del proyecto |
| `99-finiquito/` | Manuales de usuario, entrega final |

### Carpetas sin Numeración

Para features o módulos específicos que no son fases:

```
├── sistema-recompensas/         # Feature específica
├── student-portal/              # Portal específico
├── database/                    # Documentación de BD
└── frontend/                    # Documentación de frontend
```

---

## Estructura Interna de Fases

Cada fase debe contener:

```
01-fase-{nombre}/
├── README.md                    # Índice de la fase
├── _MAP.md                      # Mapa de archivos (opcional)
├── {EPICA-001}/                 # Épica o feature principal
│   ├── README.md
│   ├── requerimientos/
│   │   └── US-{XXX}-{nombre}.md
│   ├── especificaciones/
│   │   └── SPEC-{nombre}.md
│   └── implementacion/
│       └── IMPL-{nombre}.md
└── {EPICA-002}/
    └── ...
```

---

## Archivo README.md Principal

El README.md de docs/ debe incluir:

1. **Encabezado del Proyecto**
   - Nombre, versión, período, estado

2. **Alcance** (MVP vs Backlog)
   - Tabla clara de qué está incluido vs pendiente

3. **Mapa de Navegación**
   - Árbol de estructura con descripción de cada carpeta

4. **Resumen por Fase**
   - Objetivo, épicas, resultados, métricas

5. **Navegación por Dominio**
   - Acceso rápido por área funcional

6. **Métricas y Estado**
   - Completitud, coverage, KPIs

---

## Ejemplos por Tipo de Proyecto

### Proyecto con Fases Cronológicas (Gamilit)

```
docs/
├── 00-vision-general/
├── 01-fase-alcance-inicial/     # Mes 1
├── 02-fase-robustecimiento/     # Mes 2
├── 03-fase-extensiones/         # Mes 3-4
├── 04-fase-backlog/             # Futuro
├── 90-transversal/
├── 95-guias-desarrollo/
├── 96-quick-reference/
├── 97-adr/
├── 98-standards/
└── 99-finiquito/
```

### Proyecto con Módulos (ERP)

```
docs/
├── 00-vision-general/
├── 01-modulo-contabilidad/
├── 02-modulo-inventarios/
├── 03-modulo-ventas/
├── 04-modulo-compras/
├── 90-transversal/
├── 95-guias-desarrollo/
├── 97-adr/
└── 98-standards/
```

### Proyecto Nuevo (Minimal)

```
docs/
├── 00-vision-general/
│   └── README.md                # Visión inicial
├── 01-fase-mvp/
│   └── README.md                # Pendiente de definir
├── 95-guias-desarrollo/
│   └── README.md
└── README.md
```

---

## Anti-patrones

### NO hacer:

1. **Duplicar numeración**
   ```
   # INCORRECTO
   ├── 01-requerimientos/
   ├── 01-fase-inicial/          # Conflicto de numeración
   ```

2. **Mezclar niveles**
   ```
   # INCORRECTO
   ├── 01-fase-inicial/
   ├── componentes/              # Sin numeración junto con numerados
   ├── 02-fase-desarrollo/
   ```

3. **Numeración no secuencial**
   ```
   # INCORRECTO
   ├── 01-fase-inicial/
   ├── 05-fase-final/            # Salto de numeración
   ```

### SÍ hacer:

1. **Numeración consistente**
   ```
   # CORRECTO
   ├── 01-fase-mvp/
   ├── 02-fase-consolidacion/
   ├── 03-fase-expansion/
   ```

2. **Features sin numerar van al final**
   ```
   # CORRECTO
   ├── 01-fase-mvp/
   ├── 02-fase-consolidacion/
   ├── 90-transversal/
   ├── sistema-pagos/            # Feature específica
   └── integraciones/            # Feature específica
   ```

---

## Migración de Proyectos Existentes

Cuando se migra documentación existente:

1. **Identificar estructura actual**
2. **Mapear a la estructura estándar**
3. **Eliminar duplicados de numeración**
4. **Preservar contenido original**
5. **Actualizar referencias internas**

---

## Validación

El script `validate-structure.sh` verifica:
- Existencia de `docs/README.md`
- Carpeta `docs/` presente
- Sin carpetas con numeración duplicada

---

*Estándar basado en el proyecto Gamilit - Sistema NEXUS*
*Última actualización: 2025-12-05*