01.products

Landing Page Products

Mô tả Tổng quan

Endpoint Landing Page Products cung cấp danh sách sản phẩm công khai cho trang tiếp thị. Không yêu cầu xác thực, tối ưu tốc độ và độ tin cậy, và chỉ trả về tập trường an toàn cho hiển thị công khai. Dùng để hiển thị sản phẩm nổi bật, mới nhất hoặc phổ biến.

Endpoint hỗ trợ lọc cơ bản và phân trang để trang đích hiển thị lưới sản phẩm nhanh và ổn định.

Swagger Link

API: Landing Products API

Sơ đồ Hoạt động

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    Visitor[Visitor]
    Controller[LandingPageController]
    Service(ProductService)
    Cache[(Cache)]
    Database[(Database)]

    Visitor --- Step1[
      <div style='text-align: center'>
        <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; border-radius: 50%; font-weight: bold'>1</span>
        <p style='margin-top: 8px'>GET /api/v1/landing-page/products</p>
      </div>
    ]
    Step1 --> Controller

    Controller --- Step2[
      <div style='text-align: center'>
        <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
        <p style='margin-top: 8px'>Xác thực tham số</p>
      </div>
    ]
    Step2 --> Service

    Service --- Step3[
      <div style='text-align: center'>
        <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
        <p style='margin-top: 8px'>Đọc từ Cache</p>
      </div>
    ]
    Step3 --> Cache

    Cache --- Step4[
      <div style='text-align: center'>
        <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
        <p style='margin-top: 8px'>Cache miss → Query DB</p>
      </div>
    ]
    Step4 --> Database
    Database --> Service
    Service --> Controller

    Controller --- Step5[
      <div style='text-align: center'>
        <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
        <p style='margin-top: 8px'>Trả về JSON</p>
      </div>
    ]
    Step5 --> Visitor

Tài liệu Tình huống

Trường hợp 1: Thành công (Có dữ liệu)

Sơ đồ Trình tự

sequenceDiagram
    participant Visitor
    participant API as LandingPageController
    participant Service as ProductService
    participant Cache
    participant DB as Database

    Note over Visitor,API: Bước 1: GET /api/v1/landing-page/products
    Visitor->>API: GET /api/v1/landing-page/products?page=1&per_page=12&sort_by=created_at&sort_order=desc

    Note over API,Service: Bước 2: Xác thực & Lấy dữ liệu
    API->>Service: listPublicProducts(params)
    Service->>Cache: get(cacheKey)
    alt Cache hit
        Cache-->>Service: product_list
    else Cache miss
        Service->>DB: SELECT public fields with pagination/sort
        DB-->>Service: rows
        Service->>Cache: put(cacheKey, rows, ttl)
    end

    Note over API,Visitor: Bước 3: Phản hồi
    API-->>Visitor: 200 OK (products + pagination)

Các bước

Bước 1: Yêu cầu

  • Method: GET
  • Path: /api/v1/landing-page/products
  • Query params (tất cả tùy chọn):
    • page: số nguyên, mặc định 1
    • per_page: số nguyên, mặc định 12
    • q: từ khóa tìm kiếm (khớp tiêu đề đơn giản)
    • sort_by: created_at | popularity | price
    • sort_order: asc | desc

Bước 2: Xác thực & Xử lý

  • Kiểm tra giới hạn page/per_page
  • Whitelist sort_by và sort_order
  • Ưu tiên cache; fallback database

Bước 3: Phản hồi

  • Thành công: 200 OK
  • Ví dụ:
{
  "success": true,
  "data": {
    "products": [
      {
        "id": "dogparadise:4589602260099",
        "name": "Sample Product",
        "image_url": "https://cdn.example.com/p/4589602260099.jpg",
        "price": 1299,
        "currency": "JPY",
        "rating": 4.6,
        "review_count": 152
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 12,
      "total": 145,
      "last_page": 13
    }
  }
}

Trường hợp 2: Thành công (Rỗng)

Ví dụ

{
  "success": true,
  "data": { "products": [], "pagination": { "current_page": 1, "per_page": 12, "total": 0, "last_page": 0 } }
}

Trường hợp 3: Tham số không hợp lệ

  • Ví dụ: per_page quá lớn, sort_by không hỗ trợ
  • Phản hồi: 400 Bad Request

Ví dụ

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Invalid sort_by. Allowed: created_at, popularity, price"
  }
}

Xử lý Lỗi

  • 400 Bad Request: tham số truy vấn không hợp lệ
  • 429 Too Many Requests: giới hạn tần suất cho endpoint công khai
  • 500 Internal Server Error: lỗi bất ngờ (được ghi log)

Ghi chú Bổ sung

  • Endpoint công khai: không yêu cầu xác thực
  • Chỉ trả về các trường an toàn, công khai
  • Có thể cache ngắn hạn để cải thiện hiệu năng
  • Giữ per_page nhỏ để tải nhanh trang đích