51 lines
2.0 KiB
Markdown
51 lines
2.0 KiB
Markdown
# Queue API
|
|
|
|
Go 1.26 modular-monolith API for the scenic queue system. It uses the standard
|
|
library HTTP router, GORM, PostgreSQL, versioned embedded SQL migrations and
|
|
database-backed sessions.
|
|
|
|
## Local run
|
|
|
|
1. Start PostgreSQL and create the database in `DATABASE_URL`.
|
|
2. Copy `.env.example` to `.env`, replace both cryptographic keys, and export
|
|
the variables. Keys must decode to exactly 32 random bytes.
|
|
3. Run `go run ./cmd/api`. With `MIGRATE_ON_START=true`, embedded migrations run
|
|
under a PostgreSQL advisory lock.
|
|
4. Seed the local demo users, projects, queues, batches, devices and audit data with:
|
|
|
|
```sh
|
|
ADMIN_PASSWORD='replace-me' go run ./cmd/seed
|
|
```
|
|
|
|
The command is repeatable and prints the demo display and visitor paths. It
|
|
resets only the `DEMO`, `RAFT` and `CABLE` projects. Default users are the
|
|
protected `xqkwljtadmin` account and `staff`; override the staff credential
|
|
and primary-project values with
|
|
`ADMIN_USERNAME`, `STAFF_USERNAME`, `ADMIN_PASSWORD`, `PROJECT_CODE` and
|
|
`PROJECT_NAME`.
|
|
|
|
For a production release, run `go run ./cmd/migrate` as a separate release Job
|
|
with `MIGRATE_ON_START=false`, then rotate the protected administrator password
|
|
with `SUPER_ADMIN_PASSWORD='...' go run ./cmd/bootstrap-admin`. Do not run the
|
|
seed command against production.
|
|
|
|
`POST /api/staff/projects/{id}/tickets` and
|
|
`POST /api/staff/projects/{id}/call-next` require an `Idempotency-Key` header.
|
|
If a phone already has active tickets, ticket creation returns
|
|
`DUPLICATE_PHONE`; repeat with the same request body except
|
|
`allow_duplicate: true` and a new idempotency key after the employee confirms.
|
|
|
|
## Tests
|
|
|
|
```sh
|
|
go test ./...
|
|
go vet ./...
|
|
```
|
|
|
|
From the repository root, `make test-db` creates a disposable PostgreSQL
|
|
database and runs migration/maintenance integration tests.
|
|
|
|
Unit tests cover ETA, phone normalization, authenticated encryption, token
|
|
hashing and password hashing. PostgreSQL integration tests run through
|
|
`make test-db` against a disposable database.
|