# BACKEND INVENTORY - MiChangarrito
# Version: 2.2.1
# Ultima actualizacion: 2026-01-10
# Sistema: SIMCO v3.8.0 + CAPVED
# Actualizado: Sincronizacion con desarrollo - 17 modulos completos

metadata:
  proyecto: "michangarrito"
  componente: "backend"
  framework: "NestJS 10.3.0"
  lenguaje: "TypeScript"
  puerto: 3141
  estado: "100% modulos completados"
  actualizado: "2026-01-10"
  actualizado_por: "Agente Orquestador"

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

configuracion:
  puerto: 3141
  base_path: "/api"
  version_api: "v1"
  swagger: true
  swagger_path: "/docs"
  cors_origin: "http://localhost:3140"
  orm: "TypeORM 0.3.19"
  auth: "JWT + Passport"

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

resumen:
  total_modulos: 19
  total_controllers: 22
  total_services: 26
  total_entities: 41
  total_dtos: 78
  total_guards: 3
  total_strategies: 1
  arquitectura: "modular"
  modulos_nuevos:
    - billing (CFDI 4.0)
    - marketplace (B2B Proveedores)
    - referrals (Sistema de referidos)
    - payments (CoDi/SPEI)
    - reports (Reportes y analítica)
    - templates (Templates de productos - MCH-007)
    - onboarding (Onboarding inteligente - MCH-006)

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

estructura:
  root: "apps/backend"
  src: "apps/backend/src"
  modules: "apps/backend/src/modules"
  shared: "apps/backend/src/shared"
  config: "apps/backend/src/config"

# ============================================================================
# MODULOS
# ============================================================================

modulos:
  - nombre: auth
    ruta: "modules/auth"
    descripcion: "Autenticacion JWT, registro y sesiones"
    estado: completado
    entities:
      - Tenant (tenant.entity.ts)
      - User (user.entity.ts)
    controllers:
      - AuthController (auth.controller.ts)
    services:
      - AuthService (auth.service.ts)
    guards:
      - JwtAuthGuard (guards/jwt-auth.guard.ts)
    strategies:
      - JwtStrategy (strategies/jwt.strategy.ts)
    dtos:
      - RegisterDto
      - LoginDto
      - RefreshTokenDto
    endpoints:
      - POST /v1/auth/register
      - POST /v1/auth/login
      - POST /v1/auth/refresh
      - POST /v1/auth/change-pin

  - nombre: products
    ruta: "modules/products"
    descripcion: "Catalogo de productos"
    estado: completado
    entities:
      - Product (entities/product.entity.ts)
    controllers:
      - ProductsController (products.controller.ts)
    services:
      - ProductsService (products.service.ts)
    dtos:
      - CreateProductDto
      - UpdateProductDto
      - ProductFilterDto
    endpoints:
      - GET /v1/products
      - GET /v1/products/favorites
      - GET /v1/products/low-stock
      - GET /v1/products/barcode/:barcode
      - GET /v1/products/:id
      - POST /v1/products
      - PUT /v1/products/:id
      - PATCH /v1/products/:id/toggle-active
      - PATCH /v1/products/:id/toggle-favorite
      - PATCH /v1/products/:id/adjust-stock
      - DELETE /v1/products/:id

  - nombre: categories
    ruta: "modules/categories"
    descripcion: "Categorias de productos"
    estado: completado
    entities:
      - Category (entities/category.entity.ts)
    controllers:
      - CategoriesController (categories.controller.ts)
    services:
      - CategoriesService (categories.service.ts)
    dtos:
      - CreateCategoryDto
      - UpdateCategoryDto
    endpoints:
      - GET /v1/categories
      - GET /v1/categories/:id
      - POST /v1/categories
      - PUT /v1/categories/:id
      - PATCH /v1/categories/:id/toggle-active
      - DELETE /v1/categories/:id

  - nombre: sales
    ruta: "modules/sales"
    descripcion: "Punto de venta y ventas"
    estado: completado
    entities:
      - Sale (entities/sale.entity.ts)
      - SaleItem (entities/sale-item.entity.ts)
    controllers:
      - SalesController (sales.controller.ts)
    services:
      - SalesService (sales.service.ts)
    dtos:
      - CreateSaleDto
      - SaleItemDto
      - CancelSaleDto
      - SalesFilterDto
    endpoints:
      - GET /v1/sales
      - GET /v1/sales/today
      - GET /v1/sales/recent
      - GET /v1/sales/ticket/:ticketNumber
      - GET /v1/sales/:id
      - POST /v1/sales
      - POST /v1/sales/:id/cancel

  - nombre: customers
    ruta: "modules/customers"
    descripcion: "Clientes y sistema de fiados"
    estado: completado
    entities:
      - Customer (entities/customer.entity.ts)
      - Fiado (entities/fiado.entity.ts)
      - FiadoPayment (entities/fiado-payment.entity.ts)
    controllers:
      - CustomersController (customers.controller.ts)
    services:
      - CustomersService (customers.service.ts)
    dtos:
      - CreateCustomerDto
      - UpdateCustomerDto
      - CreateFiadoDto
      - PayFiadoDto
    endpoints:
      - GET /v1/customers
      - GET /v1/customers/with-fiados
      - GET /v1/customers/phone/:phone
      - GET /v1/customers/:id
      - GET /v1/customers/:id/stats
      - POST /v1/customers
      - PUT /v1/customers/:id
      - PATCH /v1/customers/:id/toggle-active
      - GET /v1/customers/fiados/all
      - GET /v1/customers/fiados/pending
      - POST /v1/customers/fiados
      - POST /v1/customers/fiados/:id/pay
      - PATCH /v1/customers/fiados/:id/cancel

  - nombre: orders
    ruta: "modules/orders"
    descripcion: "Gestion de pedidos"
    estado: completado
    entities:
      - Order (entities/order.entity.ts)
      - OrderItem (entities/order-item.entity.ts)
    controllers:
      - OrdersController (orders.controller.ts)
    services:
      - OrdersService (orders.service.ts)
    dtos:
      - CreateOrderDto
      - OrderItemDto
      - UpdateOrderStatusDto
    endpoints:
      - GET /v1/orders
      - GET /v1/orders/active
      - GET /v1/orders/today
      - GET /v1/orders/stats
      - GET /v1/orders/number/:orderNumber
      - GET /v1/orders/:id
      - POST /v1/orders
      - PATCH /v1/orders/:id/status
      - PATCH /v1/orders/:id/confirm
      - PATCH /v1/orders/:id/prepare
      - PATCH /v1/orders/:id/ready
      - PATCH /v1/orders/:id/complete
      - PATCH /v1/orders/:id/cancel

  - nombre: inventory
    ruta: "modules/inventory"
    descripcion: "Control de inventario y alertas"
    estado: completado
    entities:
      - InventoryMovement (entities/inventory-movement.entity.ts)
      - StockAlert (entities/stock-alert.entity.ts)
    controllers:
      - InventoryController (inventory.controller.ts)
    services:
      - InventoryService (inventory.service.ts)
    dtos:
      - CreateMovementDto
      - AdjustStockDto
    endpoints:
      - GET /v1/inventory/movements
      - GET /v1/inventory/movements/product/:productId
      - POST /v1/inventory/movements
      - POST /v1/inventory/adjust
      - GET /v1/inventory/alerts
      - PATCH /v1/inventory/alerts/:id/dismiss
      - GET /v1/inventory/low-stock
      - GET /v1/inventory/out-of-stock
      - GET /v1/inventory/stats

  - nombre: payments
    ruta: "modules/payments"
    descripcion: "Metodos de pago"
    estado: completado
    entities:
      - PaymentMethod (entities/payment-method.entity.ts)
    controllers:
      - PaymentsController (payments.controller.ts)
    services:
      - PaymentsService (payments.service.ts)
    endpoints:
      - GET /v1/payment-methods
      - GET /v1/payment-methods/default
      - GET /v1/payment-methods/:id
      - POST /v1/payment-methods/initialize
      - PATCH /v1/payment-methods/:id/toggle-active
      - PATCH /v1/payment-methods/:id/set-default

  - nombre: subscriptions
    ruta: "modules/subscriptions"
    descripcion: "Planes, suscripciones y tokens"
    estado: completado
    entities:
      - Plan (entities/plan.entity.ts)
      - Subscription (entities/subscription.entity.ts)
      - TokenBalance (entities/token-balance.entity.ts)
      - TokenUsage (entities/token-usage.entity.ts)
    controllers:
      - SubscriptionsController (subscriptions.controller.ts)
    services:
      - SubscriptionsService (subscriptions.service.ts)
    endpoints:
      - GET /v1/subscriptions/plans
      - GET /v1/subscriptions/plans/:code
      - GET /v1/subscriptions/current
      - GET /v1/subscriptions/stats
      - POST /v1/subscriptions/cancel
      - GET /v1/subscriptions/tokens/balance
      - GET /v1/subscriptions/tokens/usage

  - nombre: messaging
    ruta: "modules/messaging"
    descripcion: "Conversaciones WhatsApp y notificaciones"
    estado: completado
    entities:
      - Conversation (entities/conversation.entity.ts)
      - Message (entities/message.entity.ts)
      - Notification (entities/notification.entity.ts)
    controllers:
      - MessagingController (messaging.controller.ts)
    services:
      - MessagingService (messaging.service.ts)
    endpoints:
      - GET /v1/messaging/conversations
      - GET /v1/messaging/conversations/:id
      - GET /v1/messaging/conversations/:id/messages
      - PATCH /v1/messaging/conversations/:id/read
      - GET /v1/messaging/notifications
      - GET /v1/messaging/notifications/count
      - PATCH /v1/messaging/notifications/:id/read

  - nombre: billing
    ruta: "modules/billing"
    descripcion: "Facturacion y Stripe"
    estado: completado
    controllers:
      - BillingController (billing.controller.ts)
    services:
      - BillingService (billing.service.ts)
      - StripeService (stripe.service.ts)
    endpoints:
      - GET /billing/plans
      - GET /billing/token-packages
      - GET /billing/summary
      - GET /billing/token-balance
      - GET /billing/token-usage
      - POST /billing/checkout/subscription
      - POST /billing/checkout/tokens
      - POST /billing/portal

  - nombre: integrations
    ruta: "modules/integrations"
    descripcion: "Integraciones multi-tenant (WhatsApp, LLM)"
    estado: completado
    entities:
      - TenantIntegrationCredential (entities/tenant-integration-credential.entity.ts)
      - TenantWhatsAppNumber (entities/tenant-whatsapp-number.entity.ts)
    controllers:
      - IntegrationsController (controllers/integrations.controller.ts)
      - InternalIntegrationsController (controllers/internal-integrations.controller.ts)
    services:
      - TenantIntegrationsService (services/tenant-integrations.service.ts)
    dtos:
      - UpsertWhatsAppCredentialsDto
      - UpsertLLMCredentialsDto
      - CreateIntegrationCredentialDto
      - IntegrationCredentialResponseDto
    endpoints:
      - GET /integrations/status
      - GET /integrations/whatsapp
      - PUT /integrations/whatsapp
      - DELETE /integrations/whatsapp
      - GET /integrations/llm
      - PUT /integrations/llm
      - DELETE /integrations/llm/:provider
      - GET /integrations/credentials
      - POST /integrations/credentials
      - PUT /integrations/credentials/:type/:provider/toggle
      # Endpoints internos (X-Internal-Key)
      - GET /internal/integrations/:tenantId/whatsapp
      - GET /internal/integrations/:tenantId/llm
      - GET /internal/integrations/resolve-tenant/:phoneNumberId

  - nombre: codi-spei
    ruta: "modules/codi-spei"
    descripcion: "Pagos CoDi y transferencias SPEI"
    estado: completado
    controllers:
      - CodiSpeiController (codi-spei.controller.ts)
    services:
      - CodiSpeiService (codi-spei.service.ts)
    endpoints:
      - GET /v1/codi-spei/config
      - POST /v1/codi-spei/generate-qr
      - POST /v1/codi-spei/verify
      - GET /v1/codi-spei/transactions
      - POST /v1/codi-spei/webhook

  - nombre: invoices
    ruta: "modules/invoices"
    descripcion: "Facturacion electronica CFDI 4.0"
    estado: completado
    entities:
      - Invoice (entities/invoice.entity.ts)
      - InvoiceItem (entities/invoice-item.entity.ts)
      - TaxConfig (entities/tax-config.entity.ts)
    controllers:
      - InvoicesController (invoices.controller.ts)
    services:
      - InvoicesService (invoices.service.ts)
      - CfdiService (cfdi.service.ts)
    dtos:
      - CreateInvoiceDto
      - CancelInvoiceDto
    endpoints:
      - GET /v1/invoices
      - GET /v1/invoices/:id
      - POST /v1/invoices
      - POST /v1/invoices/:id/stamp
      - POST /v1/invoices/:id/send
      - POST /v1/invoices/:id/cancel
      - GET /v1/invoices/tax-config

  - nombre: marketplace
    ruta: "modules/marketplace"
    descripcion: "Marketplace B2B de proveedores"
    estado: completado
    entities:
      - Supplier (entities/supplier.entity.ts)
      - SupplierProduct (entities/supplier-product.entity.ts)
      - SupplierOrder (entities/supplier-order.entity.ts)
      - SupplierOrderItem (entities/supplier-order-item.entity.ts)
      - SupplierReview (entities/supplier-review.entity.ts)
      - SupplierFavorites (entities/supplier-favorites.entity.ts)
    controllers:
      - MarketplaceController (marketplace.controller.ts)
    services:
      - MarketplaceService (marketplace.service.ts)
    dtos:
      - CreateSupplierOrderDto
      - SupplierFilterDto
    endpoints:
      - GET /v1/marketplace/suppliers
      - GET /v1/marketplace/suppliers/:id
      - GET /v1/marketplace/suppliers/:id/products
      - GET /v1/marketplace/orders
      - POST /v1/marketplace/orders
      - PATCH /v1/marketplace/orders/:id/status
      - POST /v1/marketplace/suppliers/:id/favorite
      - POST /v1/marketplace/suppliers/:id/review

  - nombre: referrals
    ruta: "modules/referrals"
    descripcion: "Sistema de referidos y recompensas"
    estado: completado
    entities:
      - ReferralCode (entities/referral-code.entity.ts)
      - Referral (entities/referral.entity.ts)
      - ReferralReward (entities/referral-reward.entity.ts)
    controllers:
      - ReferralsController (referrals.controller.ts)
    services:
      - ReferralsService (referrals.service.ts)
    dtos:
      - CreateReferralDto
      - RedeemRewardDto
    endpoints:
      - GET /v1/referrals/code
      - GET /v1/referrals/stats
      - GET /v1/referrals/list
      - POST /v1/referrals/apply
      - GET /v1/referrals/rewards
      - POST /v1/referrals/rewards/:id/redeem

  - nombre: widgets
    ruta: "modules/widgets"
    descripcion: "Widgets y atajos rapidos"
    estado: completado
    controllers:
      - WidgetsController (widgets.controller.ts)
    services:
      - WidgetsService (widgets.service.ts)
    endpoints:
      - GET /v1/widgets
      - GET /v1/widgets/quick-actions
      - POST /v1/widgets/configure

  - nombre: templates
    ruta: "modules/templates"
    descripcion: "Templates de productos por proveedor y giro (MCH-007)"
    estado: completado
    epica: MCH-007
    entities:
      - ProductTemplate (entities/product-template.entity.ts)
      - TemplateImport (entities/template-import.entity.ts)
    controllers:
      - TemplatesController (templates.controller.ts)
    services:
      - TemplatesService (templates.service.ts)
    dtos:
      - TemplateFilterDto
      - ImportTemplateDto
      - SearchTemplateDto
      - TemplateResponseDto
      - ImportResultDto
    endpoints:
      - GET /templates/giros
      - GET /templates/giros/:giro
      - GET /templates/providers
      - GET /templates/providers/:provider
      - GET /templates/search
      - POST /templates/import
      - GET /templates/imports
      - GET /templates/:id
      - GET /templates/stats/summary

# ============================================================================
# SHARED
# ============================================================================

shared:
  guards:
    - nombre: "JwtAuthGuard"
      archivo: "modules/auth/guards/jwt-auth.guard.ts"
      descripcion: "Valida JWT en header Authorization"

    - nombre: "RolesGuard"
      archivo: "modules/auth/guards/roles.guard.ts"
      descripcion: "Valida roles de usuario (pendiente)"

  strategies:
    - nombre: "JwtStrategy"
      archivo: "modules/auth/strategies/jwt.strategy.ts"
      descripcion: "Extrae y valida JWT del header Bearer"

  decorators: []

  interceptors: []

  filters: []

  pipes: []

  middleware: []

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

config:
  database:
    tipo: "TypeORM"
    host: "${DB_HOST}"
    port: 5432
    database: "michangarrito_dev"
    schema: "public"
    synchronize: false
    ssl: "${DB_SSL}"

  jwt:
    secret: "${JWT_SECRET}"
    access_expires: "24h"
    refresh_expires: "7d"

  stripe:
    secret_key: "${STRIPE_SECRET_KEY}"
    webhook_secret: "${STRIPE_WEBHOOK_SECRET}"

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

dependencias:
  "@nestjs/common": "^10.3.0"
  "@nestjs/config": "^3.1.1"
  "@nestjs/core": "^10.3.0"
  "@nestjs/jwt": "^10.2.0"
  "@nestjs/passport": "^10.0.3"
  "@nestjs/platform-express": "^10.3.0"
  "@nestjs/swagger": "^7.2.0"
  "@nestjs/typeorm": "^10.0.1"
  "bcrypt": "^5.1.1"
  "class-transformer": "^0.5.1"
  "class-validator": "^0.14.1"
  "helmet": "^7.1.0"
  "passport": "^0.7.0"
  "passport-jwt": "^4.0.1"
  "pg": "^8.11.3"
  "stripe": "^20.1.1"
  "typeorm": "^0.3.19"

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

comandos:
  build: "npm run build"
  start_dev: "npm run start:dev"
  start_prod: "npm run start:prod"
  lint: "npm run lint"
  test: "npm run test"

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

notas:
  - "Todos los endpoints requieren JWT excepto /v1/auth/login y /v1/auth/register"
  - "Multi-tenant via JWT claim tenantId"
  - "Endpoints de billing sin prefijo v1/"
  - "Endpoints de integrations sin prefijo v1/"
  - "Swagger disponible en /docs"
  - "Validacion global con ValidationPipe (whitelist, transform)"
  - "Helmet para seguridad de headers HTTP"
  - "CORS configurable via CORS_ORIGIN"