# ANALISIS DE ESTRUCTURA DE DOCUMENTACION - ERP Suite

**Fecha:** 2025-12-05
**Agente:** Requirements-Analyst
**Referencia:** Filosofia GAMILIT

---

## 1. PROBLEMA IDENTIFICADO

La documentacion de ERP Suite **NO cumple** con la filosofia de documentacion establecida en GAMILIT. La estructura actual esta orientada a **tipos de documento** en lugar de **modulos funcionales**, lo que dificulta:

1. **Trazabilidad:** No hay conexion clara RF -> ET -> US -> Codigo
2. **Inventarios:** No existen inventarios consolidados de objetos
3. **Dependencias:** No hay grafo de dependencias documentado
4. **Localizacion:** Dificil encontrar toda la informacion de un modulo
5. **Conflictos:** Riesgo de duplicar objetos sin detectarlo

---

## 2. COMPARATIVA GAMILIT vs ERP Suite

### 2.1 Estructura GAMILIT (CORRECTA)

```
docs/
├── 01-fase-alcance-inicial/
│   └── EAI-001-fundamentos/          <- MODULO AUTOCONTENIDO
│       ├── _MAP.md                   <- Indice con metricas
│       ├── README.md                 <- Descripcion epica
│       ├── requerimientos/           <- RF del modulo
│       │   ├── RF-AUTH-001.md
│       │   └── RF-AUTH-002.md
│       ├── especificaciones/         <- ET del modulo
│       │   ├── ET-AUTH-001.md
│       │   └── ET-AUTH-002.md
│       ├── historias-usuario/        <- US del modulo
│       │   ├── US-FUND-001.md
│       │   └── US-FUND-002.md
│       └── implementacion/
│           └── TRACEABILITY.yml      <- TRAZABILIDAD COMPLETA
│
├── 90-transversal/
│   └── inventarios/                  <- INVENTARIOS GLOBALES
│       ├── DATABASE_INVENTORY.yml
│       ├── BACKEND_INVENTORY.yml
│       ├── FRONTEND_INVENTORY.yml
│       ├── TRACEABILITY_MATRIX.yml
│       └── DEPENDENCY_GRAPH.yml
│
└── orchestration/
    └── inventarios/                  <- INVENTARIOS OPERACIONALES
        ├── MASTER_INVENTORY.yml
        ├── SEEDS_INVENTORY.yml
        └── TEST_COVERAGE.yml
```

**Filosofia:** Todo lo de un modulo esta JUNTO. Inventarios GLOBALES para evitar duplicados.

### 2.2 Estructura ERP Suite Actual (INCORRECTA)

```
apps/erp-core/docs/
├── 02-definicion-modulos/            <- Solo READMEs genericos
│   ├── INDICE-MODULOS.md
│   └── MGN-001-auth/
│       └── README.md                 <- Solo descripcion
│
├── 03-requerimientos/                <- RF separados por tipo
│   └── RF-auth/
│       └── RF-AUTH-001.md
│
├── 04-modelado/
│   ├── especificaciones-tecnicas/    <- ET separados
│   │   ├── backend/
│   │   └── frontend/
│   └── database-design/              <- DDL separados
│
├── 05-user-stories/                  <- US separadas
│   └── mgn-001/
│       └── US-MGN-001-001.md
│
└── 08-epicas/                        <- Epicas separadas
    └── EPIC-MGN-001-auth.md

# NO EXISTEN:
# - _MAP.md por modulo
# - TRACEABILITY.yml por modulo
# - Inventarios globales (DATABASE_INVENTORY, BACKEND_INVENTORY)
# - DEPENDENCY_GRAPH.yml
# - MASTER_INVENTORY.yml
```

**Problema:** Informacion DISPERSA. Sin trazabilidad. Sin inventarios.

---

## 3. GAPS CRITICOS IDENTIFICADOS

### 3.1 Estructura

| Elemento | GAMILIT | ERP Suite | Gap |
|----------|---------|-----------|-----|
| Modulos autocontenidos | Si | No | CRITICO |
| _MAP.md por modulo | Si | No | CRITICO |
| TRACEABILITY.yml por epica | Si | No | CRITICO |
| Inventarios globales | 4 archivos | 0 | CRITICO |
| DEPENDENCY_GRAPH.yml | Si | No | ALTO |
| MASTER_INVENTORY.yml | Si | No | ALTO |
| Trazabilidad RF->Codigo | 100% | 0% | CRITICO |

### 3.2 Contenido

| Elemento | GAMILIT | ERP Suite | Gap |
|----------|---------|-----------|-----|
| RF con paths a implementacion | Si | No | ALTO |
| ET con endpoints especificos | Si | Parcial | MEDIO |
| US con criterios Gherkin | 100% | 30% | ALTO |
| Metricas por modulo | Si | No | ALTO |
| Bug fixes documentados | Si | No | MEDIO |
| Changelog por modulo | Si | No | MEDIO |

### 3.3 Operacional

| Elemento | GAMILIT | ERP Suite |
|----------|---------|-----------|
| Ubicacion canonica de inventarios | orchestration/inventarios/ | No existe |
| Tests coverage tracking | TEST_COVERAGE.yml | No existe |
| Seeds inventory | SEEDS_INVENTORY.yml | No existe |

---

## 4. CONSECUENCIAS DE LA ESTRUCTURA ACTUAL

1. **Duplicacion de objetos:** Sin inventario global, se pueden crear tablas/endpoints duplicados
2. **Conflictos de nombres:** Sin DEPENDENCY_GRAPH, no se detectan colisiones
3. **Implementacion sin traza:** Codigo sin referencia a RF/US
4. **Perdida de contexto:** Desarrollador debe buscar en 5+ carpetas para entender un modulo
5. **Metricas perdidas:** No hay forma de medir avance real vs planificado
6. **Deuda tecnica oculta:** Sin tracking de bugs/fixes

---

## 5. PLAN DE REESTRUCTURACION PROPUESTO

### Fase 1: Crear Estructura Base (Prioridad Critica)

1. **Crear carpeta orchestration/inventarios/**
   - MASTER_INVENTORY.yml
   - DATABASE_INVENTORY.yml
   - BACKEND_INVENTORY.yml
   - FRONTEND_INVENTORY.yml
   - DEPENDENCY_GRAPH.yml
   - TRACEABILITY_MATRIX.yml

2. **Reestructurar docs/ por modulos:**
   ```
   apps/erp-core/docs/
   ├── 01-fase-foundation/
   │   ├── MGN-001-auth/              <- TODO junto
   │   │   ├── _MAP.md
   │   │   ├── README.md
   │   │   ├── requerimientos/
   │   │   ├── especificaciones/
   │   │   ├── historias-usuario/
   │   │   └── implementacion/
   │   │       └── TRACEABILITY.yml
   │   ├── MGN-002-users/
   │   ├── MGN-003-roles/
   │   └── MGN-004-tenants/
   │
   ├── 02-fase-core-business/
   │   ├── MGN-005-catalogs/
   │   ├── MGN-010-financial/
   │   └── ...
   │
   └── 90-transversal/
       └── inventarios/               <- Inventarios de docs
   ```

### Fase 2: Migrar Documentacion Existente

1. Mover RF de `03-requerimientos/` a `MGN-XXX/requerimientos/`
2. Mover ET de `04-modelado/` a `MGN-XXX/especificaciones/`
3. Mover US de `05-user-stories/` a `MGN-XXX/historias-usuario/`
4. Eliminar estructura dispersa

### Fase 3: Crear Trazabilidad

1. Crear TRACEABILITY.yml por cada modulo MGN-XXX
2. Crear _MAP.md por cada modulo
3. Poblar inventarios globales

### Fase 4: Aplicar a Verticales

1. Replicar estructura en verticales/construccion/
2. Replicar en otras verticales

---

## 6. ESTRUCTURA OBJETIVO FINAL

```
erp-suite/
├── apps/
│   ├── erp-core/
│   │   ├── docs/
│   │   │   ├── 01-fase-foundation/
│   │   │   │   ├── _MAP.md                    <- Indice de fase
│   │   │   │   ├── README.md
│   │   │   │   ├── MGN-001-auth/
│   │   │   │   │   ├── _MAP.md               <- Indice modulo (metricas)
│   │   │   │   │   ├── README.md             <- Descripcion
│   │   │   │   │   ├── requerimientos/
│   │   │   │   │   │   ├── RF-AUTH-001.md
│   │   │   │   │   │   └── RF-AUTH-002.md
│   │   │   │   │   ├── especificaciones/
│   │   │   │   │   │   ├── ET-AUTH-001-backend.md
│   │   │   │   │   │   ├── ET-AUTH-002-frontend.md
│   │   │   │   │   │   └── ET-AUTH-003-database.md
│   │   │   │   │   ├── historias-usuario/
│   │   │   │   │   │   ├── US-AUTH-001.md
│   │   │   │   │   │   └── US-AUTH-002.md
│   │   │   │   │   └── implementacion/
│   │   │   │   │       └── TRACEABILITY.yml   <- RF->ET->US->Codigo
│   │   │   │   ├── MGN-002-users/
│   │   │   │   ├── MGN-003-roles/
│   │   │   │   └── MGN-004-tenants/
│   │   │   │
│   │   │   ├── 02-fase-core-business/
│   │   │   │   └── [misma estructura]
│   │   │   │
│   │   │   ├── 03-fase-extended/
│   │   │   │   └── [misma estructura]
│   │   │   │
│   │   │   ├── 04-fase-saas/
│   │   │   │   └── [misma estructura]
│   │   │   │
│   │   │   └── 90-transversal/
│   │   │       ├── inventarios/
│   │   │       │   └── README.md              <- Referencia a orchestration
│   │   │       └── templates/
│   │   │
│   │   └── orchestration/
│   │       └── inventarios/                   <- INVENTARIOS CANONICOS
│   │           ├── MASTER_INVENTORY.yml
│   │           ├── DATABASE_INVENTORY.yml
│   │           ├── BACKEND_INVENTORY.yml
│   │           ├── FRONTEND_INVENTORY.yml
│   │           ├── DEPENDENCY_GRAPH.yml
│   │           ├── TRACEABILITY_MATRIX.yml
│   │           ├── SEEDS_INVENTORY.yml
│   │           └── TEST_COVERAGE.yml
│   │
│   └── verticales/
│       └── construccion/
│           ├── docs/
│           │   └── [misma estructura]
│           └── orchestration/
│               └── inventarios/
```

---

## 7. EJEMPLO DE TRACEABILITY.yml PARA ERP

```yaml
# TRACEABILITY.yml - MGN-001: Autenticacion
# Matriz de trazabilidad: Documentacion -> Codigo

epic_code: MGN-001
epic_name: Autenticacion
phase: 1
phase_name: Foundation
story_points: 34
status: ready

# DOCUMENTACION
documentation:
  requirements:
    - id: RF-AUTH-001
      file: requerimientos/RF-AUTH-001-login.md
      title: Login con Email/Password
      status: documented

    - id: RF-AUTH-002
      file: requerimientos/RF-AUTH-002-tokens.md
      title: Manejo de Tokens JWT
      status: documented

  specifications:
    - id: ET-AUTH-001
      file: especificaciones/ET-AUTH-001-backend.md
      rf: RF-AUTH-001
      title: Backend Implementation
      status: documented

  user_stories:
    - id: US-MGN001-001
      file: historias-usuario/US-MGN001-001-login.md
      title: Login con Email/Password
      rf: [RF-AUTH-001]
      story_points: 8
      status: ready

# IMPLEMENTACION
implementation:
  database:
    schemas:
      - name: core_auth
        path: apps/database/ddl/schemas/core_auth/
        tables:
          - name: users_auth
            file: apps/database/ddl/schemas/core_auth/tables/users_auth.sql
            rf: RF-AUTH-001
          - name: sessions
            file: apps/database/ddl/schemas/core_auth/tables/sessions.sql
            rf: RF-AUTH-002
        functions:
          - name: validate_password
            file: apps/database/ddl/schemas/core_auth/functions/validate_password.sql
            rf: RF-AUTH-001

  backend:
    module: auth
    path: apps/backend/src/modules/auth/
    services:
      - name: auth.service.ts
        methods: [login, logout, refresh]
        rf: [RF-AUTH-001, RF-AUTH-002]
    controllers:
      - name: auth.controller.ts
        endpoints:
          - POST /api/v1/auth/login
          - POST /api/v1/auth/logout
          - POST /api/v1/auth/refresh
        rf: [RF-AUTH-001, RF-AUTH-002]
    guards:
      - name: jwt-auth.guard.ts
        rf: RF-AUTH-002

  frontend:
    feature: auth
    path: apps/frontend/src/features/auth/
    components:
      - LoginForm.tsx
      - LogoutButton.tsx
    stores:
      - authStore.ts

# DEPENDENCIAS
dependencies:
  depends_on: []  # Primera epica
  required_by: [MGN-002, MGN-003, MGN-004, ALL]

# METRICAS
metrics:
  story_points:
    estimated: 34
    actual: null
    variance: null
  coverage:
    unit_tests: 0%
    integration_tests: 0%
    e2e_tests: 0%
```

---

## 8. PROXIMOS PASOS INMEDIATOS

1. [ ] Crear orchestration/inventarios/ en erp-core
2. [ ] Crear MASTER_INVENTORY.yml inicial
3. [ ] Crear DATABASE_INVENTORY.yml con objetos existentes
4. [ ] Reestructurar MGN-001 como ejemplo completo
5. [ ] Crear _MAP.md para MGN-001
6. [ ] Crear TRACEABILITY.yml para MGN-001
7. [ ] Documentar proceso en guia de desarrollo

---

## 9. BENEFICIOS ESPERADOS

1. **Trazabilidad completa:** Cualquier linea de codigo tiene traza a RF
2. **Prevencion de duplicados:** Inventarios detectan colisiones
3. **Localizacion rapida:** Todo de un modulo en una carpeta
4. **Metricas precisas:** Story points, coverage, bugs por modulo
5. **Onboarding facil:** Nuevo desarrollador entiende modulo rapido
6. **Mantenimiento eficiente:** Cambio en RF actualiza traza automatica

---

**Generado por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Accion requerida:** Aprobar plan de reestructuracion
