38 lines
3.0 KiB
Markdown
38 lines
3.0 KiB
Markdown
# 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
|