rckrdmrd/workspace-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
workspace-v1/orchestration/referencias/ESTANDAR-ESTRUCTURA-DOCS.md
rckrdmrd 66161b1566 feat: Workspace-v1 complete migration with NEXUS v3.4 
Sistema NEXUS v3.4 migrado con:

Estructura principal:
- core/orchestration: Sistema SIMCO + CAPVED (27 directivas, 28 perfiles)
- core/catalog: Catalogo de funcionalidades reutilizables
- shared/knowledge-base: Base de conocimiento compartida
- devtools/scripts: Herramientas de desarrollo
- control-plane/registries: Control de servicios y CI/CD
- orchestration/: Configuracion de orquestacion de agentes

Proyectos incluidos (11):
- gamilit (submodule -> GitHub)
- trading-platform (OrbiquanTIA)
- erp-suite con 5 verticales:
  - erp-core, construccion, vidrio-templado
  - mecanicas-diesel, retail, clinicas
- betting-analytics
- inmobiliaria-analytics
- platform_marketing_content
- pos-micro, erp-basico

Configuracion:
- .gitignore completo para Node.js/Python/Docker
- gamilit como submodule (git@github.com:rckrdmrd/gamilit-workspace.git)
- Sistema de puertos estandarizado (3005-3199)

Generated with NEXUS v3.4 Migration System
EPIC-010: Configuracion Git y Repositorios
2026-01-04 03:37:42 -06:00

352 lines
10 KiB
Markdown
Raw Permalink Blame History

# Estandar de Estructura de Documentacion
**Version:** 1.0.0
**Sistema:** NEXUS v3.4 + SIMCO
**Fecha:** 2026-01-03
**EPIC:** EPIC-002 - Documentacion en Todos los Niveles
---
## 1. Vision General
Este documento define el estandar oficial de estructura de directorios `docs/` para todos los proyectos del workspace NEXUS. El objetivo es garantizar:
- **Navegabilidad:** Cualquier desarrollador puede encontrar informacion rapidamente
- **Consistencia:** Misma estructura en todos los proyectos
- **Escalabilidad:** Estructura que crece con el proyecto
- **Trazabilidad:** Historial de decisiones y cambios documentado
---
## 2. Estructura de Directorios
### 2.1 Estructura Completa
```
{proyecto}/docs/
├── README.md # OBLIGATORIO - Punto de entrada
├── _MAP.md # OBLIGATORIO - Indice navegable
│
├── 00-vision-general/ # Vision, stack, arquitectura general
│ ├── _MAP.md
│ ├── VISION-PRODUCTO.md
│ ├── ARQUITECTURA-GENERAL.md
│ └── STACK-TECNOLOGICO.md
│
├── 01-arquitectura/ # Diagramas, decisiones tecnicas
│ ├── _MAP.md
│ ├── DIAGRAMA-COMPONENTES.md
│ ├── DIAGRAMA-BASE-DATOS.md
│ └── diagramas/
│
├── 02-definicion-modulos/ # Modulos funcionales del proyecto
│ ├── _MAP.md
│ └── {PREFIJO}-{NNN}-{nombre}/
│ ├── _MAP.md
│ ├── README.md
│ └── especificaciones/
│
├── 03-backlog/ # Backlog de features pendientes
│ └── _MAP.md
│
├── 04-roadmap/ # Roadmap y planificacion
│ └── _MAP.md
│
├── 10-herencia-verticales/ # Solo para suite-cores
│ └── _MAP.md
│
├── 90-transversal/ # Inventarios, integraciones
│ ├── _MAP.md
│ ├── inventarios/
│ └── integraciones/
│
├── 95-guias-desarrollo/ # Guias para desarrolladores
│ ├── _MAP.md
│ └── GUIA-CONTRIBUCION.md
│
├── 96-quick-reference/ # Cheatsheets y refs rapidas
│ ├── _MAP.md
│ └── CHEATSHEET-*.md
│
├── 97-adr/ # Architecture Decision Records
│ ├── _MAP.md
│ └── ADR-{NNN}-{titulo}.md
│
├── 98-analisis/ # Documentos de analisis
│ ├── _MAP.md
│ └── ANALISIS-*.md
│
└── 99-finiquito/ # Documentacion de entrega
├── _MAP.md
└── ENTREGA-*.md
```
### 2.2 Directorios por Tipo de Proyecto
| Directorio | Standalone | Suite-Core | Vertical | Descripcion |
|------------|:----------:|:----------:|:--------:|-------------|
| 00-vision-general | REQUERIDO | REQUERIDO | REQUERIDO | Vision y arquitectura |
| 01-arquitectura | REQUERIDO | REQUERIDO | OPCIONAL | Diagramas y decisiones |
| 02-definicion-modulos | REQUERIDO | REQUERIDO | REQUERIDO | Modulos del proyecto |
| 03-backlog | OPCIONAL | OPCIONAL | OPCIONAL | Features pendientes |
| 10-herencia-verticales | N/A | REQUERIDO | N/A | Guia para verticales |
| 90-transversal | REQUERIDO | REQUERIDO | OPCIONAL | Inventarios |
| 95-guias-desarrollo | OPCIONAL | REQUERIDO | OPCIONAL | Guias de desarrollo |
| 96-quick-reference | OPCIONAL | OPCIONAL | OPCIONAL | Cheatsheets |
| 97-adr | RECOMENDADO | REQUERIDO | OPCIONAL | ADRs |
| 98-analisis | OPCIONAL | OPCIONAL | OPCIONAL | Analisis |
| 99-finiquito | OPCIONAL | OPCIONAL | OPCIONAL | Entrega |
---
## 3. Archivos Obligatorios
### 3.1 README.md (Raiz de docs/)
El `README.md` es el **punto de entrada principal**. Debe contener:
1. **Titulo del proyecto**
2. **Descripcion breve** (1-2 parrafos)
3. **Enlaces rapidos** a secciones principales
4. **Estado actual** del proyecto
5. **Como contribuir** (enlace a guias)
**Template:**
```markdown
# Documentacion de {Nombre del Proyecto}
> {Descripcion breve del proyecto en 1-2 lineas}
## Enlaces Rapidos
- [Vision General](00-vision-general/)
- [Arquitectura](01-arquitectura/)
- [Modulos](02-definicion-modulos/)
- [Guias de Desarrollo](95-guias-desarrollo/)
## Estado del Proyecto
| Aspecto | Estado |
|---------|--------|
| Backend | En Desarrollo |
| Frontend | En Desarrollo |
| Database | Estable |
## Navegacion
Ver [_MAP.md](_MAP.md) para indice completo.
---
*Actualizado: YYYY-MM-DD*
```
### 3.2 _MAP.md (Indice de Navegacion)
Cada directorio con contenido debe tener un `_MAP.md`. Ver [TEMPLATE-MAP.md](../templates/TEMPLATE-MAP.md) para el template estandar.
**Contenido minimo:**
- Tabla con archivos/directorios
- Descripcion de cada item
- Estado (Activo, En Desarrollo, Planificado)
- Enlaces de navegacion (Padre, Relacionados)
- Fecha de actualizacion
---
## 4. Reglas de Nomenclatura
### 4.1 Directorios
| Tipo | Formato | Ejemplo |
|------|---------|---------|
| Directorio estandar | `{NN}-{nombre-kebab}` | `00-vision-general` |
| Modulo de proyecto | `{PREFIJO}-{NNN}-{nombre}` | `AUTH-001-autenticacion` |
| Subdirectorio | `{nombre-kebab}` | `especificaciones` |
**Prefijos numericos:**
- `00-09`: Vision, arquitectura, fundamentos
- `10-19`: Herencia y extensiones (suite-cores)
- `20-89`: Reservado para expansion
- `90-94`: Transversal, inventarios
- `95-96`: Guias y referencias
- `97`: ADRs
- `98`: Analisis
- `99`: Finiquito
### 4.2 Archivos
| Tipo | Formato | Ejemplo |
|------|---------|---------|
| Documento principal | `{NOMBRE-MAYUSCULAS}.md` | `ARQUITECTURA-GENERAL.md` |
| Especificacion tecnica | `ET-{MODULO}-{NNN}-{nombre}.md` | `ET-AUTH-001-login.md` |
| ADR | `ADR-{NNN}-{titulo}.md` | `ADR-001-uso-de-jwt.md` |
| Cheatsheet | `CHEATSHEET-{tema}.md` | `CHEATSHEET-GIT.md` |
| Analisis | `ANALISIS-{tema}.md` | `ANALISIS-PERFORMANCE.md` |
| Indice | `_MAP.md` | `_MAP.md` |
### 4.3 Prefijos de Modulos
Cada proyecto define sus propios prefijos. Ejemplos:
| Proyecto | Prefijos | Descripcion |
|----------|----------|-------------|
| trading-platform | OQI, CORE, ML | Orbiquantia modules |
| gamilit | GAME, EDU, REWARD | Gamificacion, educacion, recompensas |
| erp-suite | AUTH, INV, FIN | Autenticacion, inventario, finanzas |
---
## 5. Estados Validos
| Estado | Descripcion | Uso |
|--------|-------------|-----|
| **Activo** | Contenido vigente y mantenido | Documento en uso |
| **En Desarrollo** | Contenido en construccion | Trabajo en progreso |
| **Planificado** | Pendiente de crear | Placeholder |
| **Obsoleto** | Ya no se mantiene | Marcar para revision |
| **Draft** | Borrador sin aprobar | Requiere revision |
---
## 6. Convenciones de Contenido
### 6.1 Encabezados
- **H1 (#):** Solo uno por archivo, igual al titulo
- **H2 (##):** Secciones principales
- **H3 (###):** Subsecciones
- **H4+ (####):** Usar con moderacion
### 6.2 Tablas
Usar tablas para:
- Listados estructurados
- Comparaciones
- Estados y configuraciones
### 6.3 Enlaces
- **Siempre relativos:** `[texto](../ruta/archivo.md)`
- **Evitar absolutos:** No usar `/home/usuario/...`
- **Validar periodicamente:** Con script de validacion
### 6.4 Diagramas
- Preferir **Mermaid** para diagramas inline
- Guardar diagramas complejos en `diagramas/`
- Incluir fuente editable junto con imagen
---
## 7. Validacion
Usar el script `validate-docs-structure.sh` para verificar cumplimiento:
```bash
./validate-docs-structure.sh /path/to/project
```
El script valida:
1. Existencia de `README.md` y `_MAP.md`
2. Estructura de directorios recomendada
3. Existencia de `_MAP.md` en subdirectorios con contenido
4. Archivos huerfanos (no-markdown)
5. Directorios vacios
---
## 8. Ejemplos por Tipo de Proyecto
### 8.1 Proyecto Standalone (trading-platform)
```
docs/
├── README.md
├── _MAP.md
├── 00-vision-general/
│ ├── _MAP.md
│ └── VISION-ORBIQUANTIA.md
├── 01-arquitectura/
│ └── _MAP.md
├── 02-definicion-modulos/
│ ├── _MAP.md
│ ├── OQI-001-fundamentos-auth/
│ ├── OQI-002-education/
│ └── OQI-003-trading/
├── 90-transversal/
│ └── _MAP.md
└── 97-adr/
└── _MAP.md
```
### 8.2 Suite-Core (erp-core)
```
docs/
├── README.md
├── _MAP.md
├── 00-vision-general/
├── 01-arquitectura/
├── 02-definicion-modulos/
├── 10-herencia-verticales/ # ESPECIAL: Guia para verticales
│ ├── _MAP.md
│ ├── GUIA-HERENCIA.md
│ └── ESTRUCTURA-VERTICAL.md
├── 90-transversal/
├── 95-guias-desarrollo/
└── 97-adr/
```
### 8.3 Vertical (erp-construccion)
```
docs/
├── README.md # Referencia a erp-core
├── _MAP.md
├── 00-vision-general/
│ └── VISION-CONSTRUCCION.md # Solo contenido especifico
├── 02-definicion-modulos/
│ ├── _MAP.md
│ └── CONST-001-proyectos/ # Modulos especificos
└── 90-transversal/
```
---
## 9. Migracion de Estructuras Existentes
### 9.1 Checklist de Migracion
1. [ ] Crear `docs/README.md` si no existe
2. [ ] Crear `docs/_MAP.md` si no existe
3. [ ] Renombrar directorios al formato `NN-nombre`
4. [ ] Mover contenido a directorios correctos
5. [ ] Crear `_MAP.md` en cada subdirectorio
6. [ ] Validar enlaces internos
7. [ ] Ejecutar `validate-docs-structure.sh`
8. [ ] Resolver warnings y errores
### 9.2 Mapeo de Directorios Comunes
| Estructura Antigua | Estructura Nueva |
|-------------------|------------------|
| `docs/architecture/` | `docs/01-arquitectura/` |
| `docs/modules/` | `docs/02-definicion-modulos/` |
| `docs/guides/` | `docs/95-guias-desarrollo/` |
| `docs/decisions/` | `docs/97-adr/` |
| `docs/specs/` | `docs/02-definicion-modulos/{mod}/especificaciones/` |
---
## 10. Referencias
- [TEMPLATE-MAP.md](../templates/TEMPLATE-MAP.md) - Template para indices
- [validate-docs-structure.sh](../scripts/validation/validate-docs-structure.sh) - Script de validacion
- [SIMCO-DOCUMENTAR.md](../directivas/simco/SIMCO-DOCUMENTAR.md) - Directiva de documentacion
---
**Documento creado:** 2026-01-03
**Sistema:** NEXUS v3.4 + SIMCO
**EPIC:** EPIC-002 - Documentacion en Todos los Niveles
Reference in New Issue View Git Blame Copy Permalink