36 lines
1.8 KiB
Markdown
36 lines
1.8 KiB
Markdown
# 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.
|