Expose /api/v1/flash-sale/status/{productId} — real-time stock endpoint

[piush365]

Background

Clients currently have no way to check remaining stock without placing an order. A status endpoint lets frontend UIs show a live countdown (e.g. "47 units left") and lets monitoring dashboards poll without touching the order path.

Proposed Change

GET /api/v1/flash-sale/status/{productId}

Response (200 OK):

{
  "productId": "IPHONE15",
  "stockRemaining": 47,
  "status": "AVAILABLE",   // AVAILABLE | LOW_STOCK | SOLD_OUT
  "timestamp": "2024-11-15T10:30:00Z"
}

• Status LOW_STOCK when stockRemaining <= 10 (configurable threshold).
• Status SOLD_OUT when stockRemaining <= 0.
• Reads directly from Redis — no database hit.
• Should be publicly accessible (no API key required) since it's read-only.

Rate Limiting Consideration

This endpoint must not bypass or share quota with the /buy endpoint. Use a separate, more permissive rate limiter key (status_rate_limiter:{ip}).

Acceptance Criteria

• New controller method getStatus with OpenAPI annotations
• InventoryStore gets a getStock(String key): long method
• Endpoint is permitted without authentication in SecurityConfig
• Unit test covers AVAILABLE, LOW_STOCK, and SOLD_OUT states
• Swagger UI shows the endpoint