miinventario-v2/orchestration/_archive/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:

# 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:

# 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:

# 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:

# 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:

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:

# 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:

# 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):

# 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:

# 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:

# 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

# 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