Announcements

Flow Summary

The current announcement flow is:

Step 1. Load the announcement feed
GET /api/v1/announcement

Step 2. Open one announcement
GET /api/v1/announcement/{uuid}

Treat these routes as protected in the current app setup.

Authorization: Bearer <access_token>

Language Behavior

• These handlers read Accept-Language
• Only exact zh returns the Chinese title and content
• Any other value falls back to English

1. List Announcements

GET /api/v1/announcement

Returns the mobile user's visible announcement feed.

Current visibility rules

The repository only returns:

• status = PUBLISHED
• announcements currently inside the publish window, where:
  • start_at <= now and end_at >= now, or
  • both start_at and end_at are null

Then it applies audience rules:

• ADMIN announcements with audience_type = ALL_USERS are visible to everyone
• If the current user has an agent_id, the feed also includes AGENT announcements for that agent where:
  • audience_type = ALL_USERS, or
  • audience_type = SPECIFIC_USERS and the user is linked in announcement_users

Important backend caveat

• The handler creates pagination metadata with page = 1 and limit = 10
• It then binds query params into a filter DTO that has no page or limit fields
• In practice, the list is currently hard-fixed to page 1 with 10 items
• Even though the route comment says paginated, client-provided pagination params are ignored right now

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": [
    {
      "id": 7,
      "uuid": "0d65f58d-47f6-43d7-84b2-4bdc8d44e391",
      "type": "ADMIN",
      "title": "System maintenance",
      "content": "Scheduled maintenance will start tonight.",
      "audience_type": "ALL_USERS",
      "status": "PUBLISHED",
      "small_image_url": "https://...",
      "photo_urls": "https://...",
      "large_image_url": "https://...",
      "published_at": "2026-02-28T10:00:00Z",
      "created_at": "2026-02-28T09:00:00Z",
      "agent_id": 0
    }
  ],
  "metadata": {
    "current_page": 1,
    "limit": 10,
    "total": 1
  }
}

2. Get Announcement By UUID

GET /api/v1/announcement/{uuid}

Returns one announcement by UUID.

Important backend caveat

• The detail query currently loads by UUID only
• It does not re-check:
  • status = PUBLISHED
  • publish window
  • agent visibility
  • specific-user audience membership
• That means the detail endpoint is currently broader than the list endpoint

Response fields

The detail payload returns the localized title and content, plus:

• type
• audience_type
• status
• small_image_url
• photo_urls
• large_image_url
• published_at
• created_at
• created_by_name
• agent_id

Integration Notes

1. Use the list endpoint for the app's announcement feed.
2. Treat the detail endpoint carefully, because its current access rules are looser than the feed query.