wangxuming/XQKqueue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: establish integrated project memory

Browse Source
This commit is contained in:
brother7
2026-08-12 19:33:12 +08:00
parent 50ac5bddc4
commit 1eb36645e4
31 changed files with 872 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
.project-docs/20-architecture/data-flow.md Normal file
View File

@@ -0,0 +1,33 @@
# Data Flow
## Primary Flows
| Flow | Source | Destination | Notes |
|---|---|---|---|
| Take ticket | Staff/visitor client | Go service -> PostgreSQL | Validates project/session and party size, enforces idempotency/rate limits as applicable, checks same-phone WAITING duplicates, encrypts personal data, increments session revision |
| Call next | Staff client | Go service transaction -> PostgreSQL | Locks project/session, selects a contiguous FIFO prefix by ticket or people target, writes one call batch, updates tickets/revision, emits audit/event state |
| Browser display | Browser route | `GET /api/display/overview` or `GET /api/display/{identifier}/snapshot` | Read-only privacy-safe projections; identifier accepts project code or compatible display token |
| Android overview | `MainActivity` | `GET /api/display/overview` every 5 seconds | Renders project cards; no announcement coordinator exists |
| Android project display | `MainActivity` | `GET /api/display/{identifier}/snapshot` every 3 seconds | One response updates UI and announcement detector; first snapshot establishes a silent baseline |
| Android announcement | New current call batch | `AnnouncementCoordinator` -> embedded WAV composer -> `AudioTrack` | Number/range only, FIFO, three repetitions, canceled on pause or screen change |
## State Ownership
- PostgreSQL owns durable queue state; the queue-session revision is the recovery/version signal.
- The Go service owns all mutations and public projection allowlists.
- Web and Android clients own only presentation caches, polling lifecycle, and transient UI state. The service exposes authenticated staff SSE, but the current web client does not consume it.
- Android `AnnouncementCoordinator` tracks only the current project-screen baseline/deduplication state and resets when the screen stops.
## External Interfaces
- Public display: `GET /api/display/overview`, `GET /api/display/{identifier}/snapshot`.
- Public visitor: project listing, ticket creation, and private token status. The public phone lookup endpoint is a development/operational-test path and returns 404 in `APP_ENV=production` until replaced by OTP or an external identity provider.
- Internal lookup: the same active-ticket phone lookup is restricted to private-network requests.
- Staff/admin: separate authenticated route groups and cookies; staff queue reads/ticket creation/call-next, admin project/user/history APIs, and an authenticated staff SSE endpoint.
- Implemented-but-unregistered: ticket transition and missed-ticket reissue handlers exist in source but have no `Server.Handler()` routes or current web integration; they are not part of the active external interface.
- Android deep links: `https://queue.nianxx.cn/admin/display` and `https://queue.nianxx.cn/display/{identifier}`.
- Android audio assets: `android/app/src/main/res/raw/voice_*.wav`.
## Last Updated
2026-08-12