Initial commit

README.md

@@ -0,0 +1,92 @@
+# 景区排队叫号系统
+
+这是一个面向景区多项目运营的轻量排队叫号系统。当前实现目标是首个可运行纵向切片：员工独立 H5 的取号和批量叫号，游客私密状态页，管理端的运营概览、项目设置与大屏中心，实体公示大屏，设备模拟器和审计基础。
+
+产品与交互基线见：
+
+- [产品与技术规划](docs/scenic-queue-system-plan.md)
+- [UI/UX 设计范式](docs/scenic-queue-design-paradigm.md)
+- [登录持久化设计](docs/login-persistence-design.md)
+
+## 技术架构
+
+- 前端：React、TypeScript、Vite；员工、游客、公示屏和管理端使用同一前端工程的独立路由。
+- 后端：Go、标准库 HTTP 路由、GORM。
+- 数据库：PostgreSQL 17，版本化 SQL 迁移。
+- 实时更新：REST 写入、SSE 推送，客户端轮询降级。
+- 部署：模块化单体；中心服务是唯一写入权威。
+
+## 本地开发
+
+已验证的工具版本：Go 1.26、Node.js 22、pnpm 10、PostgreSQL 17。
+
+```bash
+make install
+make db-init
+cp server/.env.example server/.env
+```
+
+`server/.env.example` 只包含本地示例密钥。正式环境必须替换两把 32 字节密钥；本地长期使用也建议运行两次 `openssl rand -base64 32` 后替换。
+
+启动 API、初始化演示数据和启动前端：
+
+```bash
+make api
+make seed
+make web
+```
+
+- API：`http://localhost:8080`
+- 前端：`http://localhost:5173`
+- 本地超级管理员账号：`xqkwljtadmin`（密码由 `SUPER_ADMIN_PASSWORD` 设置）
+- 本地演示员工：`staff` / `ChangeMe123!`
+
+`make seed` 会注入一套可直接演示的基础数据：
+
+- `DEMO` 云栖观光车：运行中，含已完成批次、当前叫号、已到场、过号、取消和等待队列。
+- `RAFT` 峡谷漂流：暂停中，含候场队列，用于验证暂停态。
+- `CABLE` 云顶索道：未开放，用于验证空队列和未开放态。
+
+命令会在终端输出公示屏与游客页的本地路径。它可重复执行：每次只重置上述演示项目，不会删除其他项目。本地演示员工账号和固定演示令牌禁止用于生产。
+
+设置本地超级管理员密码：
+
+```bash
+SUPER_ADMIN_PASSWORD='至少 12 位的本地密码' make bootstrap-admin
+```
+
+没有 Homebrew PostgreSQL 时，也可以使用：
+
+```bash
+docker compose up -d postgres
+```
+
+## 核心页面
+
+- `/staff/login`：员工 H5 独立登录，只接受员工账号。
+- `/admin/login`：管理端独立登录，只接受管理员账号。
+- 两端使用独立会话 Cookie，可在同一浏览器同时登录，不会互相覆盖。
+- `/staff`：员工 H5 叫号页，聚焦当前批次与叫下一批。
+- `/staff/tickets`：员工 H5 取号页与等待队列核对。
+- 员工端每次“叫下一批”会自动结束上一批，再按 FIFO 叫出固定数量的连续号码。
+- `/visitor/:token`：游客私密状态页。
+- `/display/:token`：单项目只读公示屏。
+- `/admin`：管理端运营概览。
+- `/admin/projects`：管理端项目规则与预计等待时间设置。
+- `/admin/display`：管理端大屏中心，可全屏展示多项目的公开运行状态。
+
+## 质量检查
+
+```bash
+make test
+make test-db
+make check
+make build
+make smoke-real
+```
+
+`make smoke-real` 会创建一个临时 PostgreSQL 数据库，启动独立 Go API，写入受控测试手机号并完成员工全号、游客尾四位、管理端全号、公屏零手机号的真实接口验收；结束后自动关闭测试 API 并删除临时数据库。它不使用前端 mock，也不会改动日常开发数据库。
+
+核心叫号写操作必须由服务端事务、行锁、幂等键和队列修订号共同保护；前端按钮禁用不能替代这些约束。
+
+生产交接说明见 [后端与数据库上线交接](docs/backend-production-handoff.md)。生产环境先运行独立迁移命令，再启动 API；不得运行 `make seed`。