396 lines
13 KiB
Markdown
396 lines
13 KiB
Markdown
# 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
|