rckrdmrd/erp-suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-suite/docs/ANALISIS-ESTRUCTURA-DOCUMENTACION.md

13 KiB
Raw Permalink Blame History

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

# 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