miinventario-v2/orchestration/analisis/PLAN-REFINADO-DOCUMENTACION-2026-01-13.md

# Plan Refinado de Corrección de Documentación - MiInventario

---
id: PLAN-REF-DOC-20260113
type: Plan
status: Approved
version: "1.0.0"
created_date: 2026-01-13
updated_date: 2026-01-13
simco_version: "4.0.0"
analyst: "Claude Opus 4.5 (Arquitecto de Documentación)"
refines: "PLAN-CORRECCION-DOCUMENTACION-2026-01-13.md"
incorporates:
  - "ANALISIS-VALIDACION-DOCUMENTACION-2026-01-13.md"
  - "VALIDACION-PLAN-DOCUMENTACION-2026-01-13.md"
  - "ANALISIS-DEPENDENCIAS-DOCUMENTACION-2026-01-13.md"
---

## 1. Resumen de Refinamientos

Este plan refinado incorpora:
- Análisis de 63 archivos con dependencias mapeadas
- Orden de actualización basado en impacto (archivos con más referencias primero)
- Correcciones de nomenclatura detectadas (INT-002, INT-006)
- Archivos huérfanos identificados

---

## 2. Decisiones Confirmadas

| # | Decisión | Valor Final | Justificación |
|---|----------|-------------|---------------|
| D-001 | Estado real del proyecto | **100% completado** | PROJECT-STATUS.md + trazas completas |
| D-002 | Puerto backend definitivo | **3142** | Usado en PROJECT-STATUS.md |
| D-003 | Archivos 02-especificaciones/ | **Eliminar referencias** | Info está en inventarios YAML |
| D-004 | Archivos 90-transversal/ | **Crear GUIA-DESPLIEGUE y SEGURIDAD** | Críticos para operaciones |
| D-005 | Nomenclatura INT-002 | **Mantener INT-002-oxxo.md** | Actualizar referencias |
| D-006 | Nomenclatura INT-006 | **Mantener INT-006-ia-provider.md** | Actualizar referencias |

---

## 3. Plan de Ejecución Refinado

### FASE 1: INVENTARIOS BASE (Máxima Prioridad)

**Orden basado en dependencias:**

#### 1.1 CONTEXT-MAP.yml (30+ referencias)
**Archivo:** `orchestration/CONTEXT-MAP.yml`

**Cambios:**
```yaml
# Línea 1-5
version: "1.2.0"        # Era "0.1.0"
estado: completado      # Era "planificacion"

# Sección epicas (líneas 104-239):
# Cambiar TODOS los "estado: pendiente" → "estado: completado"

# Sección integraciones (líneas 250-302):
# Corregir: INT-002-oxxo-voucher.md → INT-002-oxxo.md
# Corregir: INT-006-ai-provider.md → INT-006-ia-provider.md

# Puertos (si aplica):
BACKEND_PORT: 3142      # Era 3150
```

**Impacto:** Actualización se propaga a 15+ archivos

#### 1.2 MASTER_INVENTORY.yml (20+ referencias)
**Archivo:** `orchestration/inventarios/MASTER_INVENTORY.yml`

**Cambios:**
```yaml
# Metadata
version: "3.0.0"        # Era "2.0.0"
updated_date: 2026-01-13

# Estado general
estado_general: "100% - Completado"  # Era "80%"

# Fases
fase_1:
  estado: completado    # OK
  sp_completados: 97    # OK

fase_2:
  estado: completado    # Era "pendiente"
  sp_completados: 21    # Era 0

fase_3:
  estado: completado    # OK
  sp_completados: 50    # OK

fase_4:
  estado: completado    # Era "parcial"
  sp_completados: 34    # Era 20

# Contadores
modulos_backend: 14     # Era 11 (agregar admin, feedback, validations)
endpoints: 61           # Era 45 (agregar 16 nuevos)
screens_mobile: 22      # Era 20 (agregar validation screens)
tablas: 21              # Era 13 (agregar 8 nuevas)
stores: 9               # Era 7
services: 12            # Era 10
```

#### 1.3 DATABASE_INVENTORY.yml (22+ referencias)
**Archivo:** `orchestration/inventarios/DATABASE_INVENTORY.yml`

**Agregar entidades:**
```yaml
# Nuevas tablas (8)
- audit_logs
- promotions
- ia_providers
- corrections
- ground_truth
- product_submissions
- validation_requests
- validation_responses

# Nuevas migraciones (2)
- 1736502000000-CreateFeedbackTables.ts
- 1736600000000-CreateAdminTables.ts

# Nuevos ENUMs (4)
- corrections_type_enum: [QUANTITY, SKU, CONFIRMATION]
- ground_truth_status_enum: [PENDING, APPROVED, REJECTED]
- product_submissions_status_enum: [PENDING, APPROVED, REJECTED]
- promotions_type_enum: [PERCENTAGE, FIXED_CREDITS, MULTIPLIER]

# Actualizar users_role_enum
- users_role_enum: [USER, VIEWER, MODERATOR, ADMIN, SUPER_ADMIN]

# Agregar campos en referrals
- fraudHold: boolean
- fraudReason: varchar(255)
- reviewedBy: uuid (FK users.id)
- reviewedAt: timestamp
```

#### 1.4 BACKEND_INVENTORY.yml (22+ referencias)
**Archivo:** `orchestration/inventarios/BACKEND_INVENTORY.yml`

**ELIMINAR módulo videos (fantasma)**

**AGREGAR módulos:**
```yaml
# Módulo admin (17 endpoints)
- nombre: admin
  ruta: src/modules/admin/
  servicios:
    - admin-dashboard.service.ts
    - admin-moderation.service.ts
    - admin-packages.service.ts
    - admin-promotions.service.ts
    - admin-providers.service.ts
    - audit-log.service.ts
  endpoints:
    - GET /admin/dashboard
    - GET /admin/dashboard/revenue-series
    - GET /admin/providers
    - PATCH /admin/providers/:id
    - GET /admin/packages
    - POST /admin/packages
    - PATCH /admin/packages/:id
    - GET /admin/promotions
    - POST /admin/promotions
    - PATCH /admin/promotions/:id
    - POST /admin/promotions/validate
    - GET /admin/products/pending
    - POST /admin/products/:id/approve
    - POST /admin/products/:id/reject
    - GET /admin/referrals/fraud-holds
    - POST /admin/referrals/:id/approve
    - POST /admin/referrals/:id/reject
  entidades:
    - AuditLog
    - Promotion
    - IaProvider

# Módulo feedback (6 endpoints)
- nombre: feedback
  ruta: src/modules/feedback/
  servicios:
    - feedback.service.ts
  endpoints:
    - PATCH /stores/:storeId/inventory/:itemId/correct-quantity
    - PATCH /stores/:storeId/inventory/:itemId/correct-sku
    - POST /stores/:storeId/inventory/:itemId/confirm
    - GET /stores/:storeId/inventory/:itemId/history
    - POST /products/submit
    - GET /products/search
  entidades:
    - Correction
    - GroundTruth
    - ProductSubmission

# Módulo validations (4 endpoints)
- nombre: validations
  ruta: src/modules/validations/
  servicios:
    - validations.service.ts
    - validation-engine.service.ts
  endpoints:
    - GET /validations/check/:videoId
    - GET /validations/:requestId/items
    - POST /validations/:requestId/submit
    - POST /validations/:requestId/skip
  entidades:
    - ValidationRequest
    - ValidationResponse
```

**AGREGAR Guards y Decorators:**
```yaml
guards:
  - nombre: RolesGuard
    ruta: src/common/guards/roles.guard.ts
    estado: implementado

decorators:
  - nombre: Roles
    ruta: src/common/decorators/roles.decorator.ts
    estado: implementado
```

#### 1.5 FRONTEND_INVENTORY.yml (28+ referencias)
**Archivo:** `orchestration/inventarios/FRONTEND_INVENTORY.yml`

**Agregar:**
```yaml
# Screens (3 nuevas)
screens:
  - nombre: validation/items
    ruta: app/validation/items.tsx
    estado: implementado
  - nombre: validation/complete
    ruta: app/validation/complete.tsx
    estado: implementado

layouts:
  - nombre: _layout (validation)
    ruta: app/validation/_layout.tsx
    estado: implementado

# Stores (2 nuevos)
stores:
  - nombre: validations.store.ts
    ruta: stores/validations.store.ts
    estado: implementado
  - nombre: feedback.store.ts
    ruta: stores/feedback.store.ts
    estado: implementado

# Services (2 nuevos)
services:
  - nombre: validations.service.ts
    ruta: services/api/validations.service.ts
    estado: implementado
  - nombre: feedback.service.ts
    ruta: services/api/feedback.service.ts
    estado: implementado

# Componentes (7 nuevos)
componentes_validation:
  - ValidationPromptModal.tsx
  - ValidationItemCard.tsx
  - ValidationProgressBar.tsx

componentes_feedback:
  - ConfirmItemButton.tsx
  - CorrectionHistoryCard.tsx
  - CorrectSkuModal.tsx
  - CorrectQuantityModal.tsx
```

---

### FASE 2: ÉPICAS CRÍTICAS (Mayor Impacto)

**Orden por número de referencias entrantes:**

#### 2.1 Épicas con 35+ referencias (Actualizar primero)

| Orden | Archivo | Referencias | Cambios |
|-------|---------|-------------|---------|
| 1 | MII-005-procesamiento-ia.md | 45+ | status: Completado, tareas: Completado |
| 2 | MII-009-wallet-creditos.md | 42+ | status: Completado, tareas: Completado |
| 3 | MII-001-infraestructura-base.md | 38+ | status: Completado, tareas: Completado |
| 4 | MII-006-reportes-inventario.md | 35+ | status: Completado, tareas: Completado |
| 5 | MII-004-captura-video.md | 35+ | status: Completado, tareas: Completado |
| 6 | MII-002-autenticacion.md | 35+ | status: Completado, tareas: Completado |

**Cambio estándar por épica:**
```yaml
# Frontmatter
status: Completado      # Era "Pendiente"
updated_date: 2026-01-13

# Tareas técnicas (en cada archivo)
| T-001 | ... | Completado |   # Era "Pendiente"
| T-002 | ... | Completado |
# ... todas las tareas
```

#### 2.2 Épicas con 25-34 referencias

| Orden | Archivo | Referencias |
|-------|---------|-------------|
| 7 | MII-003-gestion-tiendas.md | 30+ |
| 8 | MII-010-paquetes-recarga.md | 28+ |
| 9 | MII-011-pagos-tarjeta.md | 28+ |
| 10 | MII-012-pagos-oxxo.md | 28+ |
| 11 | MII-014-referidos.md | 28+ |
| 12 | MII-007-retroalimentacion.md | 25+ |
| 13 | MII-008-validacion-aleatoria.md | 22+ |
| 14 | MII-013-pagos-7eleven.md | 25+ |
| 15 | MII-015-admin-saas.md | 25+ |

---

### FASE 3: DOCUMENTOS DE VISIÓN

#### 3.1 ARQUITECTURA-TECNICA.md (26+ referencias)
**Archivo:** `docs/00-vision-general/ARQUITECTURA-TECNICA.md`

**Cambios:**
- Actualizar contadores si difieren del código real
- Verificar referencias a inventarios YAML siguen siendo válidas

#### 3.2 REQUERIMIENTOS-FUNCIONALES.md (32+ referencias)
**Archivo:** `docs/00-vision-general/REQUERIMIENTOS-FUNCIONALES.md`

**Cambios:**
- Actualizar estados de RFs a "Implementado"
- Eliminar referencia a REQUERIMIENTOS-ORIGINALES.md

---

### FASE 4: MAPAS E ÍNDICES

#### 4.1 docs/01-epicas/_MAP.md
**Archivo:** `docs/01-epicas/_MAP.md`

**Verificar:** Estados ya deberían mostrar "Completada" (si no, actualizar)

#### 4.2 docs/_MAP.md (Índice principal)
**Archivo:** `docs/_MAP.md`

**Cambios:**
- Corregir: `INT-002-oxxo-voucher.md` → `INT-002-oxxo.md`
- Corregir: `INT-006-ai-provider.md` → `INT-006-ia-provider.md`

#### 4.3 docs/02-especificaciones/_MAP.md

**Cambios:**
- Cambiar estados de "Pendiente" a "No Planificado" para archivos que no se crearán
- O eliminar referencias a archivos inexistentes

---

### FASE 5: DOCUMENTOS TRANSVERSALES

#### 5.1 Crear GUIA-DESPLIEGUE.md
**Archivo:** `docs/90-transversal/GUIA-DESPLIEGUE.md`

**Contenido mínimo (basado en PRODUCTION-CONFIG.md de orchestration):**
```markdown
# Guía de Despliegue - MiInventario

## 1. Requisitos Previos
- Docker y Docker Compose
- Node.js 18+
- Variables de entorno configuradas

## 2. Servicios Docker
- PostgreSQL 15 (puerto 5433)
- Redis 7 (puerto 6380)
- MinIO S3 (puertos 9002, 9003)

## 3. Comandos de Despliegue
npm run db:up          # Iniciar servicios Docker
npm run db:down        # Detener servicios
npm run dev            # Desarrollo (backend + mobile)
npm run build          # Build de producción

## 4. Variables de Entorno
Ver .env.example para lista completa

## 5. Verificación
GET http://localhost:3142/health
```

#### 5.2 Crear SEGURIDAD.md
**Archivo:** `docs/90-transversal/SEGURIDAD.md`

**Contenido mínimo:**
```markdown
# Seguridad - MiInventario

## 1. Autenticación
- JWT con refresh tokens
- OTP por SMS para verificación
- Tokens en HttpOnly cookies

## 2. Autorización
- RBAC: USER, VIEWER, MODERATOR, ADMIN, SUPER_ADMIN
- Row-Level Security (RLS) en PostgreSQL
- Guards en NestJS

## 3. Protección de Datos
- Passwords hasheados con bcrypt
- Secretos en variables de entorno
- HTTPS obligatorio en producción

## 4. Validación
- class-validator en DTOs
- Sanitización de inputs
- Rate limiting por IP
```

---

### FASE 6: CORRECCIÓN DE PUERTO BACKEND

**Archivos a modificar:**
1. `orchestration/CONTEXT-MAP.yml` - línea con BACKEND_PORT
2. `orchestration/environment/ENVIRONMENT-INVENTORY.yml` - línea con BACKEND_PORT

**Cambio:** `3150` → `3142`

---

### FASE 7: FRONTMATTER (Si hay tiempo)

**20 archivos en docs/00-vision-general/ y docs/01-epicas/**

Mover bloque frontmatter de después del título a antes:

```markdown
# ANTES:
# Título del Documento

---
id: XXX
...
---

# DESPUÉS:
---
id: XXX
...
---

# Título del Documento
```

---

## 4. Orden de Ejecución Final

```
┌────────────────────────────────────────────────────────────────────┐
│                    ORDEN DE EJECUCIÓN REFINADO                      │
├────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ FASE 1: INVENTARIOS BASE (1-2h)                             │   │
│  │ 1. CONTEXT-MAP.yml (30+ refs)                               │   │
│  │ 2. MASTER_INVENTORY.yml (20+ refs)                          │   │
│  │ 3. DATABASE_INVENTORY.yml (22+ refs)                        │   │
│  │ 4. BACKEND_INVENTORY.yml (22+ refs)                         │   │
│  │ 5. FRONTEND_INVENTORY.yml (28+ refs)                        │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ FASE 2: ÉPICAS CRÍTICAS (1.5h)                              │   │
│  │ 1. MII-005 (45+ refs) - Procesamiento IA                    │   │
│  │ 2. MII-009 (42+ refs) - Wallet Créditos                     │   │
│  │ 3. MII-001 (38+ refs) - Infraestructura                     │   │
│  │ 4-6. MII-006, MII-004, MII-002 (35+ refs cada una)          │   │
│  │ 7-15. Resto de épicas                                       │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ FASE 3-4: VISIÓN + MAPAS (1h)                               │   │
│  │ - ARQUITECTURA-TECNICA.md                                   │   │
│  │ - REQUERIMIENTOS-FUNCIONALES.md                             │   │
│  │ - Índices (_MAP.md)                                         │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ FASE 5: TRANSVERSALES (1h)                                  │   │
│  │ - Crear GUIA-DESPLIEGUE.md                                  │   │
│  │ - Crear SEGURIDAD.md                                        │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ FASE 6-7: PUERTO + FRONTMATTER (1-2h opcional)              │   │
│  │ - Corregir puerto en 2 archivos                             │   │
│  │ - Mover frontmatter en 20 archivos                          │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  TIEMPO TOTAL ESTIMADO: 5.5-8.5 horas                              │
└────────────────────────────────────────────────────────────────────┘
```

---

## 5. Checklist de Validación Post-Ejecución

```markdown
# Validaciones Fase 1
[ ] grep "status: Pendiente" orchestration/*.yml → vacío
[ ] grep "estado: pendiente" orchestration/CONTEXT-MAP.yml → vacío
[ ] grep "3150" orchestration/ → vacío
[ ] grep "videos" orchestration/inventarios/BACKEND_INVENTORY.yml → vacío
[ ] Contar módulos en BACKEND = 14
[ ] Contar entidades en DATABASE = 21

# Validaciones Fase 2
[ ] grep "status: Pendiente" docs/01-epicas/*.md → vacío
[ ] Cada épica tiene todas las tareas "Completado"

# Validaciones Fase 3-4
[ ] grep "REQUERIMIENTOS-ORIGINALES" docs/ → vacío
[ ] grep "oxxo-voucher" docs/_MAP.md → vacío
[ ] grep "ai-provider" docs/_MAP.md → vacío

# Validaciones Fase 5
[ ] Archivo docs/90-transversal/GUIA-DESPLIEGUE.md existe
[ ] Archivo docs/90-transversal/SEGURIDAD.md existe

# Validaciones Fase 6-7
[ ] grep "3150" . → vacío (en todo el proyecto)
[ ] Primeras líneas de cada .md en 00-vision-general comienzan con "---"
```

---

## 6. Resumen Ejecutivo

| Métrica | Valor |
|---------|-------|
| **Archivos a modificar** | ~45 |
| **Archivos a crear** | 2 |
| **Referencias a actualizar** | 400+ |
| **Tiempo estimado** | 5.5-8.5 horas |
| **Prioridad máxima** | CONTEXT-MAP.yml, MASTER_INVENTORY.yml |
| **Mayor riesgo** | MII-005 (45+ refs), MII-009 (42+ refs) |

---

**Plan refinado por:** Claude Opus 4.5
**Fecha:** 2026-01-13
**Estado:** ✅ APROBADO PARA EJECUCIÓN