# FRONTEND INVENTORY - MiChangarrito
# Version: 2.3.0
# Ultima actualizacion: 2026-01-18
# Sistema: SIMCO v3.8.0 + CAPVED
# Actualizado: Sprint 6 - 14 paginas completas

metadata:
  proyecto: "michangarrito"
  componente: "frontend-web"
  framework: "React 19.2.0"
  bundler: "Vite 7.2.4"
  styling: "TailwindCSS 4.1.18"
  puerto: 3140
  estado: "43% paginas funcionales (6/14 conectadas a APIs)"
  actualizado: "2026-01-20"
  actualizado_por: "Agente Orquestador"

# ============================================================================
# NOTA IMPORTANTE (2026-01-20)
# ============================================================================
#
# Estado real del frontend:
# - 6 paginas FUNCIONALES (conectadas a APIs reales)
# - 8 paginas con MOCK DATA (requieren integracion)
#
# Paginas funcionales: Login, Register, Invoices, Marketplace, Tokens, CodiSpei, Referrals
# Paginas con mock: Dashboard, Products, Orders, Customers, Fiado, Inventory, Settings
#

# ============================================================================
# CONFIGURACION
# ============================================================================

configuracion:
  puerto: 3140
  proxy_api: "http://localhost:3141"
  api_prefix: "/api/v1"
  router: "React Router DOM 7.11.0"
  state_management: "Context API + TanStack React Query 5.90.16 + Zustand"
  http_client: "Axios 1.13.2"
  icons: "Lucide React 0.562.0"
  forms: "React Hook Form + Zod"

# ============================================================================
# RESUMEN
# ============================================================================

resumen:
  total_paginas: 14
  total_componentes: 50
  total_contexts: 3
  total_servicios_api: 17
  arquitectura: "SPA"
  paginas_nuevas:
    - Tokens (Tienda de Tokens - Sprint 6)
    - CodiSpei (CoDi QR + SPEI CLABE - Sprint 6)
    - Invoices (Facturacion CFDI 4.0)
    - Marketplace (Proveedores B2B)
    - Referrals (Sistema de referidos)

# ============================================================================
# ESTRUCTURA DE CARPETAS
# ============================================================================

estructura:
  root: "apps/frontend"
  src: "apps/frontend/src"
  componentes: "apps/frontend/src/components"
  paginas: "apps/frontend/src/pages"
  contexts: "apps/frontend/src/contexts"
  lib: "apps/frontend/src/lib"
  assets: "apps/frontend/src/assets"

# ============================================================================
# PAGINAS
# ============================================================================

paginas:
  - nombre: "Dashboard"
    ruta: "/dashboard"
    archivo: "pages/Dashboard.tsx"
    descripcion: "Panel principal con metricas y resumen del negocio"
    protegida: true
    estado: mock_data  # PENDIENTE: Conectar a dashboardApi
    api_requerida: "dashboardApi (getStats, getSalesChart, getTopProducts)"
    caracteristicas:
      - Tarjetas de estadisticas (ventas, pedidos, clientes, fiados)
      - Pedidos recientes
      - Alertas de stock bajo

  - nombre: "Products"
    ruta: "/products"
    archivo: "pages/Products.tsx"
    descripcion: "Catalogo de productos con busqueda y filtrado"
    protegida: true
    estado: mock_data  # PENDIENTE: Conectar a productsApi
    api_requerida: "productsApi (getAll, getById, create, update, delete)"
    caracteristicas:
      - Busqueda por nombre
      - Filtrado por categoria
      - Vista en grid
      - Acciones editar/eliminar

  - nombre: "Orders"
    ruta: "/orders"
    archivo: "pages/Orders.tsx"
    descripcion: "Gestion de pedidos con seguimiento de estado"
    protegida: true
    estado: mock_data  # PENDIENTE: Conectar a ordersApi
    api_requerida: "ordersApi (getAll, getById, create, updateStatus)"
    caracteristicas:
      - Filtrado por estado
      - Flujo de transicion de estados
      - Informacion de pedido y cliente

  - nombre: "Customers"
    ruta: "/customers"
    archivo: "pages/Customers.tsx"
    descripcion: "Directorio de clientes con historial de compras"
    protegida: true
    estado: mock_data  # PENDIENTE: Conectar a customersApi
    api_requerida: "customersApi (getAll, getById, create, update, getStats)"
    caracteristicas:
      - Busqueda por nombre/telefono
      - Informacion de compras
      - Balance de fiado

  - nombre: "Fiado"
    ruta: "/fiado"
    archivo: "pages/Fiado.tsx"
    descripcion: "Gestion de cuentas de credito y cobranza"
    protegida: true
    estado: mock_data  # PENDIENTE: Conectar a customersApi/fiados
    api_requerida: "customersApi (getFiado, createFiado, payFiado, cancelFiado)"
    caracteristicas:
      - Resumen de totales
      - Lista de fiados pendientes/vencidos
      - Registro de pagos
      - Envio de recordatorios

  - nombre: "Inventory"
    ruta: "/inventory"
    archivo: "pages/Inventory.tsx"
    descripcion: "Control de existencias y movimientos"
    protegida: true
    estado: mock_data  # PENDIENTE: Conectar a inventoryApi
    api_requerida: "inventoryApi (getMovements, createMovement, getLowStock, getAlerts)"
    caracteristicas:
      - Resumen de inventario
      - Tabla de productos con stock
      - Indicadores visuales
      - Movimientos recientes

  - nombre: "Settings"
    ruta: "/settings"
    archivo: "pages/Settings.tsx"
    descripcion: "Configuracion de la tienda y preferencias"
    protegida: true
    estado: mock_data  # PENDIENTE: Crear endpoints + conectar
    api_requerida: "settingsApi (PENDIENTE DE CREAR en backend)"
    caracteristicas:
      - Informacion del negocio
      - Configuracion de fiado
      - WhatsApp Business
      - Notificaciones
      - Plan de suscripcion

  - nombre: "Login"
    ruta: "/login"
    archivo: "pages/Login.tsx"
    descripcion: "Autenticacion de usuarios"
    protegida: false
    estado: funcional  # Conectado a authApi
    api_consumida: "authApi.login()"
    caracteristicas:
      - Campos telefono (10 digitos) y PIN (4-6 digitos)
      - Validacion HTML5
      - Redireccion a dashboard

  - nombre: "Register"
    ruta: "/register"
    archivo: "pages/Register.tsx"
    descripcion: "Registro de nuevos negocios"
    protegida: false
    estado: funcional  # Conectado a authApi
    api_consumida: "authApi.register()"
    caracteristicas:
      - Campos obligatorios (negocio, propietario, tipo, telefono, PIN)
      - Campos opcionales (email)
      - Tipos de negocio (tiendita, fonda, taqueria, etc)
      - Validacion de PIN coincidente

  - nombre: "Invoices"
    ruta: "/invoices"
    archivo: "pages/Invoices.tsx"
    descripcion: "Facturacion electronica CFDI 4.0"
    protegida: true
    estado: funcional  # Conectado a invoicesApi
    api_consumida: "invoicesApi (9 endpoints)"
    lineas: 24626
    caracteristicas:
      - Listado de facturas emitidas
      - Formulario de creacion de factura
      - Timbrado y envio automatico
      - Cancelacion de facturas
      - Configuracion fiscal por tenant

  - nombre: "Marketplace"
    ruta: "/marketplace"
    archivo: "pages/Marketplace.tsx"
    descripcion: "Marketplace B2B de proveedores"
    protegida: true
    estado: funcional  # Conectado a marketplaceApi
    api_consumida: "marketplaceApi (11 endpoints)"
    lineas: 26180
    caracteristicas:
      - Busqueda de proveedores por zona
      - Catalogo de productos por proveedor
      - Creacion de ordenes de compra
      - Seguimiento de pedidos
      - Sistema de reseñas y favoritos

  - nombre: "Referrals"
    ruta: "/referrals"
    archivo: "pages/Referrals.tsx"
    descripcion: "Sistema de referidos y recompensas"
    protegida: true
    estado: funcional  # Conectado a referralsApi
    api_consumida: "referralsApi (8 endpoints)"
    lineas: 10166
    caracteristicas:
      - Codigo de referido unico
      - Estadisticas de referidos
      - Lista de referidos activos
      - Recompensas disponibles
      - Canje de recompensas

  - nombre: "Tokens"
    ruta: "/tokens"
    archivo: "pages/Tokens.tsx"
    descripcion: "Tienda de tokens para servicios premium"
    protegida: true
    estado: funcional  # Conectado a billingApi
    api_consumida: "billingApi (10 endpoints)"
    sprint: "Sprint 6"
    caracteristicas:
      - Balance de tokens actual
      - Paquetes de tokens disponibles
      - Checkout con Stripe
      - Historial de uso de tokens
      - Costos por servicio (WhatsApp, LLM, OCR, Facturacion)

  - nombre: "CodiSpei"
    ruta: "/codi-spei"
    archivo: "pages/CodiSpei.tsx"
    descripcion: "Cobros via CoDi QR y SPEI CLABE virtual"
    protegida: true
    estado: funcional  # Conectado a codiSpeiApi
    api_consumida: "codiSpeiApi (8 endpoints)"
    sprint: "Sprint 6"
    caracteristicas:
      - Generacion de QR CoDi para cobros
      - CLABE virtual para transferencias SPEI
      - Historial de transacciones CoDi
      - Historial de transferencias SPEI
      - Instrucciones de uso

# ============================================================================
# COMPONENTES
# ============================================================================

componentes:
  layout:
    - nombre: "Layout"
      archivo: "components/Layout.tsx"
      lineas: 168
      descripcion: "Layout principal con sidebar y navegacion"
      caracteristicas:
        - Sidebar fijo (desktop) / colapsable (mobile)
        - 7 items de navegacion
        - Header mobile con menu
        - Bloque de usuario
        - Boton de logout
        - Outlet para paginas

# ============================================================================
# CONTEXTS
# ============================================================================

contexts:
  - nombre: "AuthContext"
    archivo: "contexts/AuthContext.tsx"
    lineas: 119
    descripcion: "Gestion de autenticacion"
    provee:
      - user (User | null)
      - tenant (Tenant | null)
      - isAuthenticated (boolean)
      - isLoading (boolean)
      - login(phone, pin)
      - register(data)
      - logout()
    persistencia: localStorage (accessToken, refreshToken, user, tenant)

# ============================================================================
# SERVICIOS API
# ============================================================================

lib:
  - nombre: "api"
    archivo: "lib/api.ts"
    lineas: 132
    descripcion: "Cliente HTTP Axios con endpoints API"
    grupos:
      - authApi:
          - register(data)
          - login(phone, pin)
          - refresh(refreshToken)
          - changePin(...)
      - productsApi:
          - getAll(params)
          - getById(id)
          - create(data)
          - update(id, data)
          - delete(id)
      - ordersApi:
          - getAll(params)
          - getById(id)
          - create(data)
          - updateStatus(id, status)
      - customersApi:
          - getAll(params)
          - getById(id)
          - create(data)
          - update(id, data)
          - getFiado(id)
      - inventoryApi:
          - getMovements(params)
          - createMovement(data)
          - getLowStock()
          - getAlerts()
      - dashboardApi:
          - getStats()
          - getSalesChart(period)
          - getTopProducts()
    interceptores:
      - request: "Agrega Bearer token"
      - response: "Maneja 401, intenta refresh, limpia localStorage"

# ============================================================================
# RUTAS
# ============================================================================

rutas:
  publicas:
    - path: "/login"
      componente: "Login"
    - path: "/register"
      componente: "Register"

  protegidas:
    - path: "/"
      componente: "Layout"
      redirect: "/dashboard"
    - path: "/dashboard"
      componente: "Dashboard"
    - path: "/products"
      componente: "Products"
    - path: "/orders"
      componente: "Orders"
    - path: "/customers"
      componente: "Customers"
    - path: "/fiado"
      componente: "Fiado"
    - path: "/inventory"
      componente: "Inventory"
    - path: "/codi-spei"
      componente: "CodiSpei"
    - path: "/invoices"
      componente: "Invoices"
    - path: "/marketplace"
      componente: "Marketplace"
    - path: "/tokens"
      componente: "Tokens"
    - path: "/referrals"
      componente: "Referrals"
    - path: "/settings"
      componente: "Settings"

  wrappers:
    - ProtectedRoute: "Verifica isAuthenticated, redirige a /login"
    - PublicRoute: "Redirige a /dashboard si autenticado"

# ============================================================================
# ESTILOS
# ============================================================================

estilos:
  framework: "TailwindCSS 4.1.18"
  plugins:
    - "@tailwindcss/forms"
  colores_custom:
    primary: "Orange (50-900)"
    secondary: "Green (50-900)"
  componentes_css:
    - ".btn-primary"
    - ".btn-secondary"
    - ".btn-outline"
    - ".card"
    - ".input"

# ============================================================================
# DEPENDENCIAS PRINCIPALES
# ============================================================================

dependencias:
  "react": "19.2.0"
  "react-dom": "19.2.0"
  "react-router-dom": "7.11.0"
  "@tanstack/react-query": "5.90.16"
  "axios": "1.13.2"
  "tailwindcss": "4.1.18"
  "lucide-react": "0.562.0"
  "clsx": "2.1.1"

devDependencias:
  "typescript": "5.9.3"
  "vite": "7.2.4"
  "@vitejs/plugin-react": "*"
  "eslint": "*"
  "postcss": "*"
  "autoprefixer": "*"

# ============================================================================
# COMANDOS
# ============================================================================

comandos:
  dev: "npm run dev"
  build: "npm run build"
  preview: "npm run preview"
  lint: "npm run lint"

# ============================================================================
# CONFIGURACION VITE
# ============================================================================

vite:
  puerto: 3140
  proxy:
    "/api":
      target: "http://localhost:3141"
      changeOrigin: true
      secure: false

# ============================================================================
# NOTAS
# ============================================================================

notas:
  - "Responsive design para tablet y desktop"
  - "Dark mode pendiente"
  - "PWA pendiente"
  - "Offline mode pendiente"
  - "Paginas usan datos mock, pendiente integracion completa con API"
  - "React Query configurado con staleTime 5min, retry 1"
  - "Hooks personalizados pendientes (src/hooks/)"