spleen1334/bookings-monolith

# Bookings（单体架构） Bookings 是一个个人学习项目：一个用于客房预订和后台预订管理的服务端渲染单体 Web 应用。它并非生产级软件。 部分后台静态资源似乎来自 BootstrapDash / RoyalUI 模板，应将其视为第三方课程/模板资料。 ## 学习目标 - 在单体架构中实践 Go Web 应用结构 - 学习路由、middleware、sessions、CSRF 和模板渲染 - 使用 PostgreSQL、SQL migrations 和 repository 风格的数据访问 - 探索认证流程、后台工作流和邮件通知 - 保持小型项目井然有序，以便未来的重构和学习 ## 技术栈 - Go `1.18` - Chi router - PostgreSQL - SCS sessions - Nosurf CSRF 保护 - pgx PostgreSQL 驱动 - bcrypt 密码哈希 - go-simple-mail (用于 SMTP) - `static/admin` 下基于可选 npm/gulp 的后台资源工具 ## 应用领域 - 客房可用性搜索与预订 - 为后台用户提供预订管理 - 在日历上锁定客房/日期 - 受登录保护的后台操作 ## 架构概述 - 单体架构：一个 Go 二进制文件处理路由、业务逻辑、HTML 渲染、session 状态、认证、后台工作流和数据库访问 - 没有独立的前端/后端可部署单元 - 入口点：`cmd/web/main.go` - 路由与 middleware：`cmd/web/routes.go` 中的 Chi router - 请求处理器：`internal/handlers` - 数据访问抽象：`internal/repository` 接口 - PostgreSQL 实现：`internal/repository/dbrepo/postgres.go` - 渲染层：`internal/render` - Session/认证助手：SCS sessions + 自定义 middleware - 模板：`templates/*.page.tmpl` + `*.layout.tmpl` - 静态资源：`static/` - Migrations：`migrations/`（Soda/Pop 风格） ## 项目结构 ``` bookings/ ├── cmd/web/ # main, routes, middleware, mail listener ├── internal/ │ ├── config/ # app config container │ ├── handlers/ # HTTP handlers and flow orchestration │ ├── repository/ # DB interface + implementations │ ├── render/ # template cache/rendering + default template data │ ├── forms/ # form validation helpers │ ├── helpers/ # auth + error helpers │ └── models/ # domain and template models ├── templates/ # public/admin page templates ├── static/ # CSS/JS/images/admin assets ├── email-templates/ # email HTML templates ├── migrations/ # SQL/Fizz migrations and seeds ├── database.yml.example # DB config template for migration tool └── run.sh # local build/run script ``` ## 主要请求流程 ### 1) 可用性搜索与预订 1. 用户打开 `/search-availability`。 2. 用户提交日期（`POST /search-availability` 或 JSON 变体）。 3. 应用通过 repository 方法查询客房可用性。 4. 可用客房将在 `/choose-room/{id}` 流程中渲染。 5. 提交并验证预订表单（`/make-reservation`）。 6. 预订及客房限制被持久化到数据库中。 7. 确认邮件和所有者通知邮件被加入队列并发送。 8. 用户被重定向至 `/reservation-summary`。 ### 2) 基于 session 的预订状态 - 进行中的预订数据存储在 session 中（`reservation` 键）。 - 诸如 `choose-room -> make-reservation -> summary` 的步骤依赖于 session 状态，并在数据缺失时进行安全重定向。 ### 3) 认证与后台访问 1. 用户通过 `/user/login` 登录。 2. 根据存储的 bcrypt 密码哈希验证凭据。 3. 成功后设置 session 键 `user_id`。 4. `/admin/*` 路由受 `Auth` middleware 保护。 5. 管理员可以查看、编辑、处理、删除预订以及管理锁定日历。 ### 4) 后台预订日历/锁定 - 日历视图（`/admin/reservations-calendar`）构建按客房划分的预订/锁定映射。 - POST 操作通过添加/删除 `room_restrictions` 记录来更新手动客房锁定。 ## 本地运行 1. 配置数据库/运行时标志。 2. 构建并运行： ``` go build -o build/bookings cmd/web/*.go ./build/bookings \ -db-name=bookings \ -db-user= \ -db-pass= \ -db-host=localhost \ -db-port=5432 \ -db-ssl=disable \ -cache=false \ -production=false ``` 服务器监听 `:8080`。 ## 测试 - 使用 `go test ./...` 运行 Go 测试 - 使用仓库中已有的包级别测试（如果存在） ## 配置 / 密钥 来自 `cmd/web/main.go`： - `-production` bool - `-cache` bool - `-db-name` string（必填） - `-db-host` string - `-db-user` string（必填） - `-db-pass` string - `-db-port` string - `-db-ssl` string 将本地密钥排除在版本控制之外。`database.yml.example` 是示例配置；`database.yml` 仅限本地使用。 ## 未来学习笔记 - 将此单体架构与拆分的服务架构进行比较 - 审查 middleware、sessions 和 CSRF 在 Go 中如何交互 - 研究模板组合和可重用的布局模式 - 评估后台资源 pipeline 是否仍然必要 - 随着项目的发展，重新审视 repository 边界和测试覆盖率 ## Git / 远程发布 - 此仓库用于个人学习和在 GitHub 上发布 - 使用普通的 GitHub 远程仓库，按原样推送学习项目 - 适当保留模板/课程资源的出处说明，并将其与原创作品明确区分 - 避免将此项目视为生产部署候选对象 ## 建议的 GitHub 主题 - go - golang - chi-router - postgresql - web-application - monolith - sessions - csrf - authentication - reservations - booking-system - learning-project - bootstrapdash - royalui ## 状态 - 活跃的学习项目 - 单体 Go 预订应用 - 尚未达到生产可用状态 ## 按区域划分的文档 - Web 入口点 + 路由：[`cmd/web/README.md`](./cmd/web/README.md) - 内部架构：[`internal/README.md`](./internal/README.md) - 后台资源/工具：[`static/admin/README.md`](./static/admin/README.md)

标签：Go语言, PostgreSQL, Syscall, Web开发, 单体架构, 学习项目, 客房预订系统, 测试用例, 程序破解