# Navegacion Rapida de API - MiInventario
# Alias: @PROJ_QUICK_API
# Version: 1.0.0
# Fecha: 2026-01-16

version: "1.0.0"
proyecto: "miinventario"

# ============================================================================
# ENDPOINTS POR MODULO
# ============================================================================
por_modulo:
  auth:
    base: "/auth"
    endpoints:
      - { method: "POST", path: "/register", descripcion: "Iniciar registro con OTP" }
      - { method: "POST", path: "/verify-otp", descripcion: "Verificar OTP y crear cuenta" }
      - { method: "POST", path: "/login", descripcion: "Iniciar sesion" }
      - { method: "POST", path: "/refresh", descripcion: "Renovar tokens" }
      - { method: "POST", path: "/logout", descripcion: "Cerrar sesion" }

  users:
    base: "/users"
    endpoints:
      - { method: "GET", path: "/me", descripcion: "Obtener perfil actual" }
      - { method: "PATCH", path: "/me", descripcion: "Actualizar perfil" }
      - { method: "PATCH", path: "/me/fcm-token", descripcion: "Actualizar FCM token" }

  stores:
    base: "/stores"
    endpoints:
      - { method: "POST", path: "/", descripcion: "Crear tienda" }
      - { method: "GET", path: "/", descripcion: "Listar tiendas" }
      - { method: "GET", path: "/:id", descripcion: "Obtener tienda" }
      - { method: "PATCH", path: "/:id", descripcion: "Actualizar tienda" }
      - { method: "DELETE", path: "/:id", descripcion: "Eliminar tienda" }

  inventory:
    base: "/stores/:storeId/inventory"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar inventario" }
      - { method: "GET", path: "/statistics", descripcion: "Estadisticas" }
      - { method: "GET", path: "/low-stock", descripcion: "Items con stock bajo" }
      - { method: "GET", path: "/categories", descripcion: "Categorias disponibles" }
      - { method: "GET", path: "/:itemId", descripcion: "Obtener item" }
      - { method: "PATCH", path: "/:itemId", descripcion: "Actualizar item" }
      - { method: "DELETE", path: "/:itemId", descripcion: "Eliminar item" }

  credits:
    base: "/credits"
    endpoints:
      - { method: "GET", path: "/balance", descripcion: "Obtener balance" }
      - { method: "GET", path: "/transactions", descripcion: "Historial transacciones" }
      - { method: "GET", path: "/packages", descripcion: "Paquetes disponibles" }

  payments:
    base: "/payments"
    endpoints:
      - { method: "POST", path: "/", descripcion: "Crear pago" }
      - { method: "GET", path: "/", descripcion: "Historial pagos" }
      - { method: "GET", path: "/:paymentId", descripcion: "Detalle pago" }
      - { method: "POST", path: "/webhook/stripe", descripcion: "Webhook Stripe", auth: false }

  referrals:
    base: "/referrals"
    endpoints:
      - { method: "GET", path: "/my-code", descripcion: "Codigo personal" }
      - { method: "GET", path: "/stats", descripcion: "Estadisticas referidos" }
      - { method: "GET", path: "/", descripcion: "Listar referidos" }
      - { method: "GET", path: "/validate", descripcion: "Validar codigo", auth: false }
      - { method: "POST", path: "/apply", descripcion: "Aplicar codigo" }

  notifications:
    base: "/notifications"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar notificaciones" }
      - { method: "GET", path: "/unread-count", descripcion: "Contar no leidas" }
      - { method: "PATCH", path: "/:id/read", descripcion: "Marcar leida" }
      - { method: "POST", path: "/mark-all-read", descripcion: "Marcar todas leidas" }
      - { method: "POST", path: "/register-token", descripcion: "Registrar FCM token" }

  feedback:
    base: "/feedback"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar feedback" }
      - { method: "POST", path: "/", descripcion: "Enviar feedback" }
      - { method: "GET", path: "/:id", descripcion: "Obtener feedback" }
      - { method: "POST", path: "/corrections", descripcion: "Enviar correccion" }
      - { method: "POST", path: "/ground-truth", descripcion: "Enviar ground truth" }
      - { method: "POST", path: "/product-submission", descripcion: "Enviar producto" }

  validations:
    base: "/validations"
    endpoints:
      - { method: "POST", path: "/", descripcion: "Crear validacion" }
      - { method: "GET", path: "/:id", descripcion: "Obtener validacion" }
      - { method: "GET", path: "/:id/response", descripcion: "Obtener respuesta" }

  admin:
    base: "/admin"
    endpoints:
      - { method: "GET", path: "/dashboard", descripcion: "Dashboard principal" }
      - { method: "GET", path: "/dashboard/stats", descripcion: "Estadisticas" }
      - { method: "GET", path: "/moderation", descripcion: "Lista moderacion" }
      - { method: "PATCH", path: "/moderation/:id", descripcion: "Actualizar moderacion" }
      - { method: "GET", path: "/packages", descripcion: "Listar paquetes" }
      - { method: "POST", path: "/packages", descripcion: "Crear paquete" }
      - { method: "PATCH", path: "/packages/:id", descripcion: "Actualizar paquete" }
      - { method: "DELETE", path: "/packages/:id", descripcion: "Eliminar paquete" }
      - { method: "GET", path: "/promotions", descripcion: "Listar promociones" }
      - { method: "POST", path: "/promotions", descripcion: "Crear promocion" }
      - { method: "PATCH", path: "/promotions/:id", descripcion: "Actualizar promocion" }
      - { method: "DELETE", path: "/promotions/:id", descripcion: "Eliminar promocion" }
      - { method: "GET", path: "/providers", descripcion: "Listar proveedores IA" }
      - { method: "PATCH", path: "/providers/:id", descripcion: "Actualizar proveedor" }
      - { method: "GET", path: "/audit-log", descripcion: "Ver audit log" }
      - { method: "GET", path: "/audit-log/:id", descripcion: "Detalle audit log" }
      - { method: "GET", path: "/users", descripcion: "Listar usuarios" }

  health:
    base: "/health"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Health check", auth: false }
      - { method: "GET", path: "/ready", descripcion: "Readiness check", auth: false }

# ============================================================================
# ENDPOINTS POR METODO
# ============================================================================
por_metodo:
  GET:
    - "/users/me"
    - "/stores"
    - "/stores/:id"
    - "/stores/:storeId/inventory"
    - "/stores/:storeId/inventory/statistics"
    - "/stores/:storeId/inventory/low-stock"
    - "/stores/:storeId/inventory/categories"
    - "/stores/:storeId/inventory/:itemId"
    - "/credits/balance"
    - "/credits/transactions"
    - "/credits/packages"
    - "/payments"
    - "/payments/:paymentId"
    - "/referrals/my-code"
    - "/referrals/stats"
    - "/referrals"
    - "/referrals/validate"
    - "/notifications"
    - "/notifications/unread-count"
    - "/feedback"
    - "/feedback/:id"
    - "/validations/:id"
    - "/validations/:id/response"
    - "/admin/dashboard"
    - "/admin/dashboard/stats"
    - "/admin/moderation"
    - "/admin/packages"
    - "/admin/promotions"
    - "/admin/providers"
    - "/admin/audit-log"
    - "/admin/audit-log/:id"
    - "/admin/users"
    - "/health"
    - "/health/ready"

  POST:
    - "/auth/register"
    - "/auth/verify-otp"
    - "/auth/login"
    - "/auth/refresh"
    - "/auth/logout"
    - "/stores"
    - "/payments"
    - "/payments/webhook/stripe"
    - "/referrals/apply"
    - "/notifications/mark-all-read"
    - "/notifications/register-token"
    - "/feedback"
    - "/feedback/corrections"
    - "/feedback/ground-truth"
    - "/feedback/product-submission"
    - "/validations"
    - "/admin/packages"
    - "/admin/promotions"

  PATCH:
    - "/users/me"
    - "/users/me/fcm-token"
    - "/stores/:id"
    - "/stores/:storeId/inventory/:itemId"
    - "/notifications/:id/read"
    - "/admin/moderation/:id"
    - "/admin/packages/:id"
    - "/admin/promotions/:id"
    - "/admin/providers/:id"

  DELETE:
    - "/stores/:id"
    - "/stores/:storeId/inventory/:itemId"
    - "/admin/packages/:id"
    - "/admin/promotions/:id"

# ============================================================================
# AUTENTICACION
# ============================================================================
autenticacion:
  tipo: "JWT Bearer"
  header: "Authorization"
  formato: "Bearer {token}"
  endpoints_publicos:
    - "/auth/register"
    - "/auth/verify-otp"
    - "/auth/login"
    - "/auth/refresh"
    - "/referrals/validate"
    - "/payments/webhook/stripe"
    - "/health"
    - "/health/ready"

# ============================================================================
# ERRORES COMUNES
# ============================================================================
errores:
  400: "Bad Request - Datos invalidos"
  401: "Unauthorized - Token invalido o expirado"
  403: "Forbidden - Sin permisos"
  404: "Not Found - Recurso no encontrado"
  422: "Unprocessable Entity - Validacion fallida"
  500: "Internal Server Error"

# ============================================================================
# REFERENCIAS
# ============================================================================
referencias:
  swagger: "/api/docs"
  services: "@PROJ_DEF_SERVICES"
  backend_inventory: "orchestration/inventarios/BACKEND_INVENTORY.yml"