rckrdmrd 4c4e27d9ba feat: Documentation and orchestration updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-07 05:35:20 -06:00

20 KiB

Raw Blame History

PLAN DE VALIDACIÓN Y DESARROLLO - ERP-CORE

Fecha: 2026-01-06 Versión: 1.0.0 Fase: CAPVED - Planeación (P) Orquestador: Claude Code - Opus 4.5

RESUMEN EJECUTIVO

Estado Actual del Proyecto

Capa	Implementado	Documentado	Gap
Backend	85% Foundation, 55% Core	95%	Tests 0%
Database	85% (100+ tablas, 8 schemas)	100%	HR Schema falta
Frontend	4 features (Users, Companies, Partners, Tenants)	55%	Módulos Core Business
Documentación	834 archivos, 16 MB	55% global	US 49%, Trazabilidad 7%

Métricas Clave Consolidadas

backend:
  entidades_typeorm: 46
  endpoints_implementados: 398
  lineas_codigo: ~10,500+
  modulos_foundation: 85%+ implementado
  modulos_core_business: 40-75% implementado
  tests_cobertura: 0% (CRÍTICO)

database:
  schemas: 8 (auth, core, analytics, financial, inventory, purchase, sales, projects)
  tablas: 100+
  funciones: 40+
  triggers: 30+
  rls_policies: 40+
  hr_schema: NO EXISTE (CRÍTICO)

frontend:
  features_completas: 4/15 (users, companies, partners, tenants)
  paginas: 21
  componentes_compartidos: 23
  stores_zustand: 4
  modulos_placeholder: 11 (catalogs, settings, audit, notifications, financial, inventory, sales, purchases, crm, projects, hr)

documentacion:
  total_archivos: 834
  epicas: 23/23 (100%)
  rf: 80+ (100%)
  et_backend: 86 (95%)
  et_frontend: 80 (85%)
  user_stories: 72/146 (49%)
  specs_transversales: 30 (100%)
  trazabilidad_yaml: 1/14 (7%)

FASE 2: PLAN DE ACCIÓN

1. GAPS CRÍTICOS IDENTIFICADOS

1.1 CRÍTICO - Bloquean Producción

ID	Gap	Capa	Impacto	Esfuerzo	Prioridad
GAP-001	Tests 0% cobertura	Backend	Muy Alto	Alto	P0
GAP-002	HR Schema no existe	Database	Alto	Medio	P0
GAP-003	RLS no validado	Database	Muy Alto	Medio	P0
GAP-004	Frontend módulos Core Business	Frontend	Alto	Alto	P0

1.2 ALTO - Afectan Funcionalidad

ID	Gap	Capa	Impacto	Esfuerzo	Prioridad
GAP-005	OAuth/2FA incompleto	Backend	Alto	Medio	P1
GAP-006	Email verification flow	Backend	Alto	Bajo	P1
GAP-007	Avatar upload	Backend	Medio	Bajo	P1
GAP-008	Permission cache	Backend	Alto	Medio	P1
GAP-009	Stock alerts	Backend	Medio	Bajo	P1
GAP-010	CFDI/PAC integration	Backend	Alto	Alto	P1

1.3 MEDIO - Mejoras

ID	Gap	Capa	Impacto	Esfuerzo	Prioridad
GAP-011	Audit module completo	Backend	Medio	Medio	P2
GAP-012	WebSocket notifications	Backend	Medio	Medio	P2
GAP-013	Reports generator	Backend	Medio	Alto	P2
GAP-014	Swagger/OpenAPI docs	Backend	Bajo	Bajo	P2

2. PLAN DE REMEDIACIÓN POR CAPA

2.1 DATABASE - Acciones Inmediatas

SPRINT_1_DATABASE:
  titulo: "Completar HR Schema y Validar RLS"
  duracion: "1 sprint (2 semanas)"
  story_points: 21

  tareas:
    - id: DB-001
      titulo: "Crear HR Schema completo"
      descripcion: |
        Crear schema hr con tablas:
        - employees (20+ columnas)
        - departments (8 columnas)
        - contracts (15 columnas)
        - timesheets (12 columnas)
        - leaves (10 columnas)
        - payslips (15 columnas)        
      archivos:
        - database/ddl/10-hr.sql
      sp: 8
      dependencias: [04-financial.sql]

    - id: DB-002
      titulo: "Validar RLS Policies existentes"
      descripcion: |
        Crear tests de penetración para:
        - Verificar aislamiento de tenants
        - Validar get_current_tenant_id()
        - Test cross-tenant access attempts        
      archivos:
        - database/tests/rls-validation.sql
        - database/tests/tenant-isolation.sql
      sp: 5
      dependencias: []

    - id: DB-003
      titulo: "Implementar system.track_field_changes()"
      descripcion: |
        Función para mail.thread pattern
        Triggers invocan esta función pero no existe        
      archivos:
        - database/ddl/09-system.sql (modificar)
      sp: 3
      dependencias: []

    - id: DB-004
      titulo: "Crear seed data para catálogos"
      descripcion: |
        Seeders idempotentes para:
        - countries (ISO 3166-1)
        - currencies (ISO 4217)
        - states (México, USA)
        - uom (unidades estándar)        
      archivos:
        - database/seeds/01-countries.sql
        - database/seeds/02-currencies.sql
        - database/seeds/03-states.sql
        - database/seeds/04-uom.sql
      sp: 5
      dependencias: []

2.2 BACKEND - Acciones Inmediatas

SPRINT_1_BACKEND:
  titulo: "Tests Foundation + Permission Cache"
  duracion: "1 sprint (2 semanas)"
  story_points: 34

  tareas:
    - id: BE-001
      titulo: "Setup Jest + Supertest"
      descripcion: |
        Configurar framework de testing:
        - Jest config
        - Supertest para integration tests
        - Test database setup
        - Fixtures y factories        
      archivos:
        - backend/jest.config.js
        - backend/tests/setup.ts
        - backend/tests/factories/
      sp: 5
      dependencias: []

    - id: BE-002
      titulo: "Tests Auth Module (MGN-001)"
      descripcion: |
        24+ test cases:
        - Login (happy path, invalid email, wrong password, rate limit)
        - Register (success, duplicate email, weak password)
        - Refresh token (valid, expired, revoked)
        - Logout (single, all sessions)
        - Change password        
      archivos:
        - backend/src/modules/auth/__tests__/auth.service.spec.ts
        - backend/src/modules/auth/__tests__/auth.controller.spec.ts
        - backend/src/modules/auth/__tests__/auth.integration.spec.ts
      sp: 8
      dependencias: [BE-001]

    - id: BE-003
      titulo: "Tests Users Module (MGN-002)"
      descripcion: |
        18+ test cases:
        - CRUD operations
        - Search and filters
        - Role assignment
        - Activate/deactivate        
      archivos:
        - backend/src/modules/users/__tests__/
      sp: 5
      dependencias: [BE-001]

    - id: BE-004
      titulo: "Tests Roles Module (MGN-003)"
      descripcion: |
        15+ test cases:
        - Permission assignment
        - System role protection
        - Permission validation        
      archivos:
        - backend/src/modules/roles/__tests__/
      sp: 5
      dependencias: [BE-001]

    - id: BE-005
      titulo: "Tests Tenants Module (MGN-004)"
      descripcion: |
        12+ test cases:
        - Tenant isolation
        - Feature flags
        - Plan limits        
      archivos:
        - backend/src/modules/tenants/__tests__/
      sp: 5
      dependencias: [BE-001]

    - id: BE-006
      titulo: "Implementar Permission Cache (Redis)"
      descripcion: |
        Cache de permisos por usuario:
        - Redis como backend
        - TTL 1 hora
        - Invalidación en cambio de rol
        Target: < 5ms lookup        
      archivos:
        - backend/src/modules/auth/services/permission-cache.service.ts
        - backend/src/config/redis.config.ts
      sp: 6
      dependencias: []

SPRINT_2_BACKEND:
  titulo: "Tests Core Business + OAuth/2FA"
  duracion: "1 sprint (2 semanas)"
  story_points: 34

  tareas:
    - id: BE-007
      titulo: "Tests Financial Module (MGN-010)"
      descripcion: |
        20+ test cases:
        - Journal entries balance validation
        - Invoice workflow
        - Payment reconciliation        
      archivos:
        - backend/src/modules/financial/__tests__/
      sp: 8
      dependencias: [BE-001]

    - id: BE-008
      titulo: "Tests Inventory Module (MGN-011)"
      descripcion: |
        15+ test cases:
        - Stock moves
        - Valuation (FIFO, LIFO, Average)
        - Adjustments        
      archivos:
        - backend/src/modules/inventory/__tests__/
      sp: 6
      dependencias: [BE-001]

    - id: BE-009
      titulo: "OAuth2 Integration (Google, Microsoft)"
      descripcion: |
        Implementar flujo OAuth2:
        - Google OAuth provider
        - Microsoft OAuth provider
        - Link/unlink accounts        
      archivos:
        - backend/src/modules/auth/providers/google.provider.ts
        - backend/src/modules/auth/providers/microsoft.provider.ts
        - backend/src/modules/auth/auth.controller.ts (endpoints OAuth)
      sp: 8
      dependencias: []

    - id: BE-010
      titulo: "2FA/MFA Implementation"
      descripcion: |
        Implementar 2FA:
        - TOTP setup (Google Authenticator)
        - Backup codes
        - SMS verification (opcional)        
      archivos:
        - backend/src/modules/auth/services/mfa.service.ts
        - backend/src/modules/auth/auth.controller.ts (endpoints MFA)
      sp: 8
      dependencias: []

    - id: BE-011
      titulo: "Email Verification Flow"
      descripcion: |
        Flujo completo:
        - Send verification email
        - Verify token
        - Resend verification        
      archivos:
        - backend/src/modules/auth/services/email-verification.service.ts
        - backend/src/shared/services/email.service.ts
      sp: 4
      dependencias: []

2.3 FRONTEND - Acciones Inmediatas

SPRINT_1_FRONTEND:
  titulo: "Implementar Catalogs Module (MGN-005)"
  duracion: "1 sprint (2 semanas)"
  story_points: 34

  tareas:
    - id: FE-001
      titulo: "Feature Catalogs - Structure"
      descripcion: |
        Crear estructura del feature:
        - api/catalogs.api.ts
        - hooks/ (useCountries, useCurrencies, useUom, useCategories)
        - types/catalog.types.ts
        - components/ (forms, lists, selects)        
      archivos:
        - frontend/src/features/catalogs/
      sp: 5
      dependencias: []

    - id: FE-002
      titulo: "Countries & States Pages"
      descripcion: |
        CRUD completo:
        - CountriesListPage
        - StatesByCountryPage
        - CountrySelect, StateSelect components        
      archivos:
        - frontend/src/pages/catalogs/countries/
        - frontend/src/features/catalogs/components/CountrySelect.tsx
      sp: 5
      dependencias: [FE-001]

    - id: FE-003
      titulo: "Currencies Pages"
      descripcion: |
        CRUD + Exchange rates:
        - CurrenciesListPage
        - ExchangeRatesPage
        - CurrencySelect, CurrencyRateForm        
      archivos:
        - frontend/src/pages/catalogs/currencies/
      sp: 5
      dependencias: [FE-001]

    - id: FE-004
      titulo: "Units of Measure Pages"
      descripcion: |
        CRUD:
        - UomCategoriesListPage
        - UomListPage
        - UomSelect, UomForm        
      archivos:
        - frontend/src/pages/catalogs/uom/
      sp: 5
      dependencias: [FE-001]

    - id: FE-005
      titulo: "Product Categories Pages"
      descripcion: |
        CRUD con jerarquía:
        - CategoriesTreePage
        - CategoryForm
        - CategoryTree component (expandable)        
      archivos:
        - frontend/src/pages/catalogs/categories/
      sp: 8
      dependencias: [FE-001]

    - id: FE-006
      titulo: "Rutas y navegación Catalogs"
      descripcion: |
        Actualizar router:
        - /catalogs/countries
        - /catalogs/currencies
        - /catalogs/uom
        - /catalogs/categories        
      archivos:
        - frontend/src/app/router/routes.tsx
      sp: 3
      dependencias: [FE-002, FE-003, FE-004, FE-005]

    - id: FE-007
      titulo: "Stores Catalogs (Zustand)"
      descripcion: |
        Crear stores:
        - useCurrencyStore (current currency)
        - useCatalogCacheStore (cached lists)        
      archivos:
        - frontend/src/shared/stores/useCurrencyStore.ts
        - frontend/src/shared/stores/useCatalogCacheStore.ts
      sp: 3
      dependencias: []

SPRINT_2_FRONTEND:
  titulo: "Implementar Settings Module (MGN-006)"
  duracion: "1 sprint (2 semanas)"
  story_points: 29

  tareas:
    - id: FE-008
      titulo: "Feature Settings - Structure"
      descripcion: |
        Crear estructura:
        - api/settings.api.ts
        - hooks/ (useSystemSettings, useTenantSettings, useUserPreferences)
        - types/settings.types.ts        
      archivos:
        - frontend/src/features/settings/
      sp: 3
      dependencias: []

    - id: FE-009
      titulo: "System Settings Page (Admin)"
      descripcion: |
        Configuración global del sistema:
        - General settings
        - Email configuration
        - Security settings        
      archivos:
        - frontend/src/pages/settings/SystemSettingsPage.tsx
      sp: 5
      dependencias: [FE-008]

    - id: FE-010
      titulo: "Tenant Settings Page"
      descripcion: |
        Configuración del tenant:
        - Branding (logo, colors)
        - Localization (language, timezone, dateFormat)
        - Features enabled        
      archivos:
        - frontend/src/pages/settings/TenantSettingsPage.tsx
      sp: 5
      dependencias: [FE-008]

    - id: FE-011
      titulo: "User Preferences Page"
      descripcion: |
        Preferencias del usuario:
        - Theme (light/dark/system)
        - Language preference
        - Notification settings        
      archivos:
        - frontend/src/pages/settings/UserPreferencesPage.tsx
      sp: 5
      dependencias: [FE-008]

    - id: FE-012
      titulo: "Feature Flags Management"
      descripcion: |
        Gestión de feature flags:
        - FeatureFlagsListPage
        - FeatureFlagToggle component
        - Por tenant        
      archivos:
        - frontend/src/pages/settings/FeatureFlagsPage.tsx
      sp: 5
      dependencias: [FE-008]

    - id: FE-013
      titulo: "Settings Stores (Zustand)"
      descripcion: |
        Crear stores:
        - useSettingsStore
        - useFeatureFlagsStore        
      archivos:
        - frontend/src/shared/stores/useSettingsStore.ts
        - frontend/src/shared/stores/useFeatureFlagsStore.ts
      sp: 3
      dependencias: []

    - id: FE-014
      titulo: "Theme Selector Component"
      descripcion: |
        Componente para cambiar tema:
        - Light/Dark/System
        - Persistent en localStorage
        - Aplica clases Tailwind        
      archivos:
        - frontend/src/shared/components/organisms/ThemeSelector.tsx
      sp: 3
      dependencias: []

3. CRONOGRAMA DE SPRINTS

SPRINT_0: # Actual
  fechas: "2026-01-06 a 2026-01-19"
  objetivo: "Validación y Planeación"
  tareas:
    - Análisis exhaustivo (COMPLETADO)
    - Planeación detallada (EN PROGRESO)
    - Validación del plan
    - Análisis de dependencias
  entregables:
    - PLAN-VALIDACION-DESARROLLO-2026-01-06.md
    - ANALISIS-DEPENDENCIAS.md
    - Refinamiento del plan

SPRINT_1:
  fechas: "2026-01-20 a 2026-02-02"
  objetivo: "Foundation - Tests + Database Completion"
  capas:
    database:
      - DB-001: HR Schema (8 SP)
      - DB-002: RLS Validation (5 SP)
      - DB-003: track_field_changes() (3 SP)
      - DB-004: Seed data (5 SP)
    backend:
      - BE-001: Jest Setup (5 SP)
      - BE-002: Auth Tests (8 SP)
    frontend:
      - FE-001: Catalogs Structure (5 SP)
      - FE-002: Countries Pages (5 SP)
  total_sp: 44

SPRINT_2:
  fechas: "2026-02-03 a 2026-02-16"
  objetivo: "Tests Core + OAuth + Catalogs Frontend"
  capas:
    backend:
      - BE-003: Users Tests (5 SP)
      - BE-004: Roles Tests (5 SP)
      - BE-005: Tenants Tests (5 SP)
      - BE-006: Permission Cache (6 SP)
    frontend:
      - FE-003: Currencies Pages (5 SP)
      - FE-004: UoM Pages (5 SP)
      - FE-005: Categories Pages (8 SP)
  total_sp: 39

SPRINT_3:
  fechas: "2026-02-17 a 2026-03-02"
  objetivo: "OAuth/2FA + Settings Frontend"
  capas:
    backend:
      - BE-007: Financial Tests (8 SP)
      - BE-008: Inventory Tests (6 SP)
      - BE-009: OAuth Integration (8 SP)
    frontend:
      - FE-006: Catalogs Routes (3 SP)
      - FE-007: Catalogs Stores (3 SP)
      - FE-008: Settings Structure (3 SP)
      - FE-009: System Settings (5 SP)
  total_sp: 36

SPRINT_4:
  fechas: "2026-03-03 a 2026-03-16"
  objetivo: "2FA + Settings Completion + Financial Frontend"
  capas:
    backend:
      - BE-010: 2FA Implementation (8 SP)
      - BE-011: Email Verification (4 SP)
    frontend:
      - FE-010: Tenant Settings (5 SP)
      - FE-011: User Preferences (5 SP)
      - FE-012: Feature Flags (5 SP)
      - FE-013: Settings Stores (3 SP)
      - FE-014: Theme Selector (3 SP)
  total_sp: 33

4. DEPENDENCIAS ENTRE TAREAS

graph TD
    subgraph Database
        DB001[HR Schema] --> DB002[RLS Validation]
        DB003[track_field_changes] --> DB004[Seed Data]
    end

    subgraph Backend
        BE001[Jest Setup] --> BE002[Auth Tests]
        BE001 --> BE003[Users Tests]
        BE001 --> BE004[Roles Tests]
        BE001 --> BE005[Tenants Tests]
        BE002 --> BE006[Permission Cache]
        BE002 --> BE007[Financial Tests]
        BE002 --> BE008[Inventory Tests]
        BE006 --> BE009[OAuth]
        BE009 --> BE010[2FA]
        BE010 --> BE011[Email Verification]
    end

    subgraph Frontend
        FE001[Catalogs Structure] --> FE002[Countries]
        FE001 --> FE003[Currencies]
        FE001 --> FE004[UoM]
        FE001 --> FE005[Categories]
        FE002 --> FE006[Routes]
        FE003 --> FE006
        FE004 --> FE006
        FE005 --> FE006
        FE001 --> FE007[Stores]
        FE008[Settings Structure] --> FE009[System]
        FE008 --> FE010[Tenant]
        FE008 --> FE011[User Prefs]
        FE008 --> FE012[Feature Flags]
        FE008 --> FE013[Settings Stores]
    end

    DB001 -.-> BE007
    DB002 -.-> BE005
    BE002 -.-> FE001

5. MÉTRICAS DE ÉXITO

sprint_1_success:
  database:
    - HR schema creado con 6+ tablas
    - RLS tests passing 100%
    - Seed data ejecutable
  backend:
    - Jest configurado y funcionando
    - Auth tests: >80% coverage
  frontend:
    - Catalogs feature structure creada
    - Countries CRUD funcional

sprint_2_success:
  backend:
    - Foundation tests: >80% coverage (Auth, Users, Roles, Tenants)
    - Permission cache: <5ms lookup
  frontend:
    - Catalogs module 100% funcional
    - 4 nuevas páginas CRUD

sprint_3_success:
  backend:
    - OAuth Google/Microsoft funcional
    - Core Business tests: >60% coverage
  frontend:
    - Settings structure completa
    - System settings funcional

sprint_4_success:
  backend:
    - 2FA TOTP funcional
    - Email verification funcional
    - Tests coverage global: >70%
  frontend:
    - Settings module 100% funcional
    - Theme selector funcionando

global_success:
  tests_coverage: ">70% (desde 0%)"
  frontend_features: "6 (desde 4)"
  database_schemas: "9 (desde 8)"
  rls_validated: "true"
  oauth_enabled: "true"
  2fa_enabled: "true"

6. RIESGOS Y MITIGACIONES

Riesgo	Probabilidad	Impacto	Mitigación
Tests setup complejo	Media	Alto	Dedicar tiempo extra en BE-001, usar ejemplos existentes
OAuth providers cambios API	Baja	Medio	Usar SDKs oficiales, documentar bien
RLS performance issues	Media	Alto	Crear índices apropiados, test early
Frontend scope creep	Alta	Medio	Ceñirse estrictamente a specs documentadas
Dependencias entre capas	Media	Alto	Comunicación constante entre subagentes

7. ASIGNACIÓN DE PERFILES

perfiles_requeridos:
  orquestador:
    perfil: PERFIL-ORQUESTADOR.md
    responsabilidades:
      - Coordinación general
      - Validación de entregas
      - Resolución de conflictos

  database_agent:
    perfil: PERFIL-DATABASE.md
    tareas: [DB-001, DB-002, DB-003, DB-004]
    sprint: 1

  backend_agent:
    perfil: PERFIL-BACKEND-EXPRESS.md
    tareas: [BE-001 a BE-011]
    sprints: [1, 2, 3, 4]

  frontend_agent:
    perfil: PERFIL-FRONTEND.md
    tareas: [FE-001 a FE-014]
    sprints: [1, 2, 3, 4]

  testing_agent:
    perfil: PERFIL-TESTING.md
    tareas: [Validación de tests, QA]
    sprints: [2, 3, 4]

SIGUIENTE PASO: FASE 3 - VALIDACIÓN

Una vez aprobado este plan, proceder con:

Validar cobertura completa de gaps identificados
Verificar dependencias entre archivos a modificar
Confirmar estimaciones de story points
Aprobar cronograma de sprints
Asignar recursos (perfiles de agentes)

Documento generado por: ORQUESTADOR (Claude Code Opus 4.5) Sistema: SIMCO + CAPVED Fase actual: P (Planeación) Próxima fase: V (Validación)

20 KiB Raw Blame History