# 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