docs: Add ST3.2 reorganization analysis
Created detailed analysis document for ST3.2 Documentation Reorganization identifying redundant/obsolete files and reorganization plan. Part of ST3.2 Documentation Purge. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Adrian Flores Cortes
parent
a9224c661a
commit
3bccc36234
@ -0,0 +1,292 @@
|
||||
# ST3.2: Documentation Reorganization Analysis
|
||||
|
||||
**Fecha:** 2026-01-26
|
||||
**Tarea:** TASK-2026-01-29-DOCUMENTATION-PURGE
|
||||
**Subtarea:** ST3.2 (4h estimadas)
|
||||
**Agente:** Claude Opus 4.5
|
||||
|
||||
---
|
||||
|
||||
## Resumen Ejecutivo
|
||||
|
||||
Análisis de estructura docs/ para identificar archivos redundantes, obsoletos, o desorganizados que requieren reorganización post-integración de ST1-ST2.
|
||||
|
||||
---
|
||||
|
||||
## Hallazgos
|
||||
|
||||
### 1. Archivos Sueltos en docs/ (Potencialmente Redundantes)
|
||||
|
||||
| Archivo | Líneas | Fecha | Estado | Acción Recomendada |
|
||||
|---------|--------|-------|--------|-------------------|
|
||||
| **API.md** | 636 | 2026-01-04 | ⚠️ Posiblemente redundante | Comparar con swagger.yml (ST2.3), consolidar/archivar |
|
||||
| **ARCHITECTURE.md** | 576 | 2026-01-04 | ⚠️ Posiblemente redundante | Verificar vs docs/01-arquitectura/, consolidar |
|
||||
| **SECURITY.md** | 822 | 2026-01-04 | ✅ Legítimo | Mover a docs/90-transversal/security/ |
|
||||
| **_MAP.md** | 455 | 2026-01-07 | ⚠️ Desactualizado | Actualizar fecha y contenido |
|
||||
| **README.md** | 280 | 2026-01-04 | ✅ Legítimo | Mantener (punto de entrada) |
|
||||
|
||||
### 2. Carpetas Sueltas (Posiblemente Obsoletas)
|
||||
|
||||
#### docs/planning/ (Contenido obsoleto)
|
||||
```
|
||||
planning/
|
||||
├── Board.md # 2026-01-04 - Tablero Kanban obsoleto
|
||||
├── config.yml # 2026-01-04 - Config antigua
|
||||
└── REESTRUCTURACION-PROGRESS.md # 2026-01-04 - Proceso antiguo GAMILIT
|
||||
```
|
||||
|
||||
**Análisis:** Documenta "reestructuración GAMILIT" de enero 2026. Contenido obsoleto.
|
||||
|
||||
**Acción:** ❌ **ELIMINAR** (archivar en docs/99-analisis/obsoletos/ si hay valor histórico)
|
||||
|
||||
---
|
||||
|
||||
#### docs/architecture/ (Contenido desorganizado)
|
||||
```
|
||||
architecture/
|
||||
└── EA-BRIDGE-ARCHITECTURE.md # 14,401 líneas - MT4 Expert Advisor bridge
|
||||
```
|
||||
|
||||
**Análisis:** Arquitectura MT4 que debería estar en docs/01-arquitectura/
|
||||
|
||||
**Acción:** ➡️ **MOVER** a docs/01-arquitectura/ARQUITECTURA-EA-BRIDGE-MT4.md
|
||||
|
||||
---
|
||||
|
||||
#### docs/api-contracts/ (Contenido desorganizado)
|
||||
```
|
||||
api-contracts/
|
||||
└── SERVICE-INTEGRATION.md # 13,103 líneas - Integración servicios
|
||||
```
|
||||
|
||||
**Análisis:** Documenta integración entre servicios (MCP, ML, backend).
|
||||
|
||||
**Acción:** ➡️ **MOVER** a docs/90-transversal/integraciones/INT-SERVICES-INTEGRATION.md
|
||||
|
||||
---
|
||||
|
||||
### 3. Archivos Duplicados/Redundantes
|
||||
|
||||
#### API.md vs swagger.yml
|
||||
|
||||
| Aspecto | API.md (636 líneas) | swagger.yml (1,335 líneas) |
|
||||
|---------|---------------------|----------------------------|
|
||||
| Fecha | 2026-01-04 | 2026-01-26 (ST2.3) |
|
||||
| Formato | Markdown | OpenAPI 3.0.3 |
|
||||
| Contenido | Overview puertos, auth | Especificación completa 34 endpoints |
|
||||
| Estado | ⚠️ Posiblemente desactualizado | ✅ Actualizado y completo |
|
||||
|
||||
**Decisión:**
|
||||
- swagger.yml es la fuente oficial de especificación API
|
||||
- API.md tiene valor como overview legible (puertos, conceptos)
|
||||
- **Acción:** Actualizar API.md para referenciar swagger.yml, reducir duplicación
|
||||
|
||||
---
|
||||
|
||||
#### ARCHITECTURE.md vs docs/01-arquitectura/
|
||||
|
||||
| Aspecto | ARCHITECTURE.md (576 líneas) | docs/01-arquitectura/ (múltiples archivos) |
|
||||
|---------|------------------------------|-------------------------------------------|
|
||||
| Fecha | 2026-01-04 | 2026-01-24 (actualizado) |
|
||||
| Contenido | Overview general, tech stack | Arquitecturas específicas detalladas |
|
||||
| Nivel | Alto nivel (introducción) | Detallado (implementación) |
|
||||
|
||||
**Decisión:**
|
||||
- ARCHITECTURE.md tiene valor como overview de alto nivel
|
||||
- docs/01-arquitectura/ contiene documentos especializados
|
||||
- **Acción:** Mover secciones de ARCHITECTURE.md a docs/00-vision-general/ARQUITECTURA-GENERAL.md (consolida con doc existente)
|
||||
|
||||
---
|
||||
|
||||
## Plan de Reorganización
|
||||
|
||||
### Fase 1: Archivos Temporales Obsoletos (✅ ST3.1 - Completado)
|
||||
|
||||
```bash
|
||||
rm -f nul " -u" -u
|
||||
git add -A && git commit -m "chore: Remove temporary error files"
|
||||
```
|
||||
|
||||
**Resultado:** ✅ Commit f10c31db
|
||||
|
||||
---
|
||||
|
||||
### Fase 2: Reorganizar Carpetas Sueltas
|
||||
|
||||
#### 2.1: Mover architecture/EA-BRIDGE-ARCHITECTURE.md
|
||||
|
||||
```bash
|
||||
mv docs/architecture/EA-BRIDGE-ARCHITECTURE.md \
|
||||
docs/01-arquitectura/ARQUITECTURA-EA-BRIDGE-MT4.md
|
||||
|
||||
rmdir docs/architecture/
|
||||
|
||||
git add -A && git commit -m "docs: Move EA bridge architecture to 01-arquitectura/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2.2: Mover api-contracts/SERVICE-INTEGRATION.md
|
||||
|
||||
```bash
|
||||
mv docs/api-contracts/SERVICE-INTEGRATION.md \
|
||||
docs/90-transversal/integraciones/INT-SERVICES-INTEGRATION.md
|
||||
|
||||
rmdir docs/api-contracts/
|
||||
|
||||
git add -A && git commit -m "docs: Move service integration to 90-transversal/integraciones/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2.3: Eliminar docs/planning/ (obsoleto)
|
||||
|
||||
```bash
|
||||
# Opción 1: Archivar si hay valor histórico
|
||||
mkdir -p docs/99-analisis/obsoletos/planning-2026-01-04
|
||||
mv docs/planning/* docs/99-analisis/obsoletos/planning-2026-01-04/
|
||||
|
||||
# Opción 2: Eliminar directamente
|
||||
rm -rf docs/planning/
|
||||
|
||||
git add -A && git commit -m "docs: Remove obsolete planning/ directory"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fase 3: Consolidar Archivos Sueltos
|
||||
|
||||
#### 3.1: Consolidar ARCHITECTURE.md
|
||||
|
||||
**Acción:** Mover contenido único a docs/00-vision-general/ARQUITECTURA-GENERAL.md
|
||||
|
||||
```bash
|
||||
# Editar docs/00-vision-general/ARQUITECTURA-GENERAL.md para incorporar secciones únicas
|
||||
# Eliminar docs/ARCHITECTURE.md
|
||||
|
||||
rm docs/ARCHITECTURE.md
|
||||
git add -A && git commit -m "docs: Consolidate ARCHITECTURE.md into 00-vision-general/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3.2: Actualizar API.md para referenciar swagger.yml
|
||||
|
||||
**Acción:** Reducir API.md a overview con referencia a swagger.yml
|
||||
|
||||
**Ejemplo:**
|
||||
```markdown
|
||||
# API Documentation
|
||||
|
||||
**⚠️ For complete API specification, see: [swagger.yml](../apps/backend/swagger.yml)**
|
||||
|
||||
This document provides a high-level overview of the API.
|
||||
|
||||
## Base URL
|
||||
|
||||
Development: http://localhost:3080/api/v1
|
||||
|
||||
## Service Ports
|
||||
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| Backend API | 3080 | Main REST API |
|
||||
| Frontend | 3000 | React SPA |
|
||||
...
|
||||
|
||||
## Authentication
|
||||
|
||||
See [swagger.yml](../apps/backend/swagger.yml) for detailed authentication endpoints.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3.3: Mover SECURITY.md
|
||||
|
||||
```bash
|
||||
mkdir -p docs/90-transversal/security/
|
||||
mv docs/SECURITY.md docs/90-transversal/security/SECURITY.md
|
||||
|
||||
git add -A && git commit -m "docs: Move SECURITY.md to 90-transversal/security/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fase 4: Actualizar _MAP.md
|
||||
|
||||
**Cambios necesarios:**
|
||||
```yaml
|
||||
Metadata:
|
||||
updated_date: "2026-01-26" # Actualizar fecha
|
||||
version: "2.2.0" # Incrementar versión
|
||||
|
||||
Métricas:
|
||||
Documentación: 98% -> 100% # Después de ST1-ST3
|
||||
Implementación: 25% -> 30% # Reflejar OQI-006, OQI-007 completados
|
||||
|
||||
Secciones nuevas:
|
||||
- API Specification (swagger.yml)
|
||||
- Endpoint Routing (ENDPOINT-ROUTING.md)
|
||||
- Type Coherence (ST1 fixes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estructura Final Propuesta
|
||||
|
||||
```
|
||||
docs/
|
||||
├── _MAP.md # ✅ Actualizado (ST3.4)
|
||||
├── README.md # ✅ Mantener
|
||||
│
|
||||
├── 00-vision-general/
|
||||
│ ├── ARQUITECTURA-GENERAL.md # ✅ Consolidado ARCHITECTURE.md aquí
|
||||
│ └── ...
|
||||
│
|
||||
├── 01-arquitectura/
|
||||
│ ├── ARQUITECTURA-EA-BRIDGE-MT4.md # ➡️ Movido desde architecture/
|
||||
│ └── ...
|
||||
│
|
||||
├── 02-definicion-modulos/
|
||||
│ └── OQI-*/ # ✅ Sin cambios
|
||||
│
|
||||
├── 90-transversal/
|
||||
│ ├── integraciones/
|
||||
│ │ ├── INT-SERVICES-INTEGRATION.md # ➡️ Movido desde api-contracts/
|
||||
│ │ └── ...
|
||||
│ └── security/
|
||||
│ └── SECURITY.md # ➡️ Movido desde raíz
|
||||
│
|
||||
├── 99-analisis/
|
||||
│ └── obsoletos/ # ❌ Archivos obsoletos (planning/)
|
||||
│
|
||||
└── API.md # ⚠️ Reducido, referencia swagger.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validaciones Post-Reorganización
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] Todos los archivos movidos tienen rutas actualizadas en _MAP.md
|
||||
- [ ] No quedan carpetas vacías (architecture/, api-contracts/, planning/)
|
||||
- [ ] Referencias internas actualizadas (links relativos)
|
||||
- [ ] _MAP.md refleja estructura final
|
||||
- [ ] Git: 5-7 commits lógicos separados por tipo de cambio
|
||||
|
||||
---
|
||||
|
||||
## Esfuerzo Real vs Estimado
|
||||
|
||||
| Fase | Estimado | Real | Comentarios |
|
||||
|------|----------|------|-------------|
|
||||
| ST3.1: Eliminar temporales | 0.5h | 0.25h | ✅ Completado |
|
||||
| ST3.2: Reorganizar docs/ | 4h | TBD | En progreso |
|
||||
| ST3.3: Actualizar inventarios | 1.5h | Pendiente | |
|
||||
| ST3.4: Deployment guide | 2h | Pendiente | |
|
||||
|
||||
---
|
||||
|
||||
**Total ST3 estimado:** 8h
|
||||
**Progreso:** 12.5% (ST3.1 completado)
|
||||
Loading…
Reference in New Issue
Block a user