miinventario-v2/orchestration/_archive/analisis/PLAN-REFINADO-DOCUMENTACION-2026-01-13.md
Adrian Flores Cortes e101c7b94c
Some checks are pending
Build / Build Backend (push) Waiting to run
Build / Build Docker Image (push) Blocked by required conditions
Build / Build Mobile (TypeScript Check) (push) Waiting to run
Lint / Lint Backend (push) Waiting to run
Lint / Lint Mobile (push) Waiting to run
Test / Backend E2E Tests (push) Waiting to run
Test / Mobile Unit Tests (push) Waiting to run
[ESTANDAR-ORCHESTRATION] refactor: Consolidate to standard structure
- Move 5 non-standard folders to _archive/
- Archive 2 extra root files
- Update _MAP.md with standardized structure

Standard: SIMCO-ESTANDAR-ORCHESTRATION v1.0.0
Level: CONSUMER (L2)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-24 14:38:05 -06:00

563 lines
18 KiB
Markdown

# 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