XQKqueue/.project-docs/50-evidence/topics/20260811-native-display-f2456ea9__public-display-api.md

Evidence: Public display API contract

• Date: 2026-08-11
• Status: Verified
• Scope: Native Android overview and project-detail implementation
• Confidence: High
• Sources: server/internal/httpapi/public.go, related Go tests, and live HTTPS responses from queue.nianxx.cn
• Last verified: 2026-08-11
• Stale trigger: public display routes or DTOs change, or production is deployed from a server revision that differs from this repository

Confirmed endpoints

• GET /api/display/overview returns { projects: [...], server_time } without authentication.
• GET /api/display/{identifier}/snapshot accepts a normalized project code or a 40-128 character display token.
• Invalid or unknown identifiers return DISPLAY_NOT_FOUND with HTTP 404.

Confirmed overview project fields

• id, code, name, status
• waiting_count, waiting_ticket_count, waiting_people_count
• issued_ticket_count, nullable latest_ticket_number, experienced_people
• nullable current_batch, estimated_wait, last_updated_at

Confirmed snapshot fields

• Project: project_name, status, nested project
• Queue: revision, the three waiting counts, issued/latest/experienced metrics
• Calls: nullable current_batch, recent_batches
• Timing: estimated_wait, server_time, last_updated_at

Each call batch exposes batch_number, sequence, status, call_mode, requested/ticket/people counts, called_at, and tickets. Each ticket exposes public display number fields, status, and party size; no personal visitor fields are present.

Implementation consequence

The native detail screen can render and decide announcements from one snapshot request every three seconds. A second announcement-only request is unnecessary. The first successful snapshot after entering or resuming a project must establish a baseline and must not replay the current batch.