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

37
.project-docs/20-architecture/module-map.md Normal file
View File

@@ -0,0 +1,37 @@
# Module Map
## Source Layout
| Path | Responsibility | Owner Notes |
|---|---|---|
| `server/cmd/api` | API process entry point | Keep startup configuration and lifecycle thin |
| `server/internal/httpapi` | HTTP routes, authentication boundaries, queue transactions, public projections, history, events, and currently unregistered ticket-transition/reissue handlers | High-risk concurrency and privacy boundary; do not assume a handler is exposed without checking `Server.Handler()` |
| `server/internal/domain` | Pure queue selection and display-number rules | Prefer deterministic unit tests |
| `server/internal/model` | Persistent domain structures and constants | Coordinate changes with migrations |
| `server/internal/database` | Database connection and maintenance/purge operations | Personal-data lifecycle is sensitive |
| `server/internal/security` | Encryption, digests, password/session helpers | Never log or expose secrets/PII |
| `server/migrations` | Ordered PostgreSQL schema changes | Production migrations precede API rollout |
| `web/src/pages`, `components`, `hooks`, `lib` | Browser routes, presentation, state hooks, and API client | One application serves multiple role-specific surfaces |
| `android/app/src/main/java/cn/nianxx/queue/display` | Native navigation, API client/parser, polling, Views, formatting, announcement state, WAV composition/playback | Overview must remain audio-free |
| `android/app/src/main/res/raw` | The exact embedded Mandarin announcement fragments | Format and file set are regression-tested |
| `deliverables/android` | Installable debug APK, checksum, and handoff notes | Must match the verified build output |
| `scripts` | Database setup, seed, smoke, and integration-test orchestration | Do not run demo seed in production |
## Dependency Direction
- Clients depend on public/service contracts; they do not own queue transitions.
- HTTP handlers may use domain, model, database, and security modules; pure domain code should not depend on transport/UI concerns.
- Android Views consume parsed display models; announcement playback consumes validated call text and embedded assets.
## Risky Or Sensitive Areas
- `server/internal/httpapi/staff.go`: transactional queue writes, duplicate handling, FIFO selection, revisions, and audit.
- `server/internal/httpapi/public.go`: privacy-safe public projections and public ticket protections.
- `server/internal/httpapi/reissue.go` and ticket-transition logic: implemented business paths are currently not registered in `Server.Handler()` or wired in the web client; treat them as inactive until routes and integration tests are added.
- `android/.../MainActivity.java`: screen-state, poller, and announcement lifecycle boundary.
- `android/.../QueueAnnouncementPlayer.java` and `EmbeddedWavComposer.java`: cross-thread native audio lifecycle and asset validation.
- `android/.../SingleLineFitTextView.java`: business-critical full range-number visibility across device fonts/densities.
## Last Updated
2026-08-12

32
.project-docs/20-architecture/system-overview.md Normal file
View File

@@ -0,0 +1,32 @@
# System Overview
## Current Architecture
XQKqueue is a modular monolith. A Go HTTP service owns business rules and writes to PostgreSQL. One React/Vite application supplies staff, visitor, administrator, and browser-display routes. A separate native Android application consumes only privacy-safe public display endpoints for dedicated large screens.
## Main Components
| Component | Responsibility | Notes |
|---|---|---|
| Go service | Authentication, queue commands, public/read models, audit, maintenance, and HTTP transport | Standard-library router plus GORM; sole write authority |
| PostgreSQL | Projects, sessions, tickets, call batches, users, idempotency, revisions, and audit history | Versioned SQL migrations |
| React web application | Staff H5, visitor ticket/status pages, administrator UI, and browser display surfaces | REST writes and interval polling; the server SSE endpoint is not currently consumed by the web client |
| Native Android display | Overview and project-specific public display UI, polling, offline state, and project-detail announcements | Android Views; no WebView or system TTS |
| Delivery/scripts | Migrations, seed data, smoke tests, container/local startup, and APK handoff | Production must migrate before API start and must not run demo seed |
## Important Boundaries
- Queue selection, duplicate enforcement, ticket numbering, and revisions belong to the service transaction boundary, never a client.
- Public DTOs are allowlisted projections and must never include encrypted or hashed personal fields.
- Android overview and project screens are distinct states; only a valid project screen may create the announcement coordinator.
- A project snapshot is the Android project screen's single source for both rendering and new-call detection.
- Browser and Android displays may share API semantics, but neither should import or emulate privileged staff/admin behavior.
## Related Decisions
- [ADR-001: Native Android large-screen application](../10-decisions/adr-001-native-android-display.md)
- [ADR-002: Embedded audio announcements](../10-decisions/adr-002-embedded-audio-announcements.md)
## Last Updated
2026-08-12