阶段1: 需求分析与系统设计

目标

完成 Hotel Reservation（酒店预订系统）的完整需求分析文档，包括技术选型、数据模型设计和 API 设计。本阶段不写一行代码，全部产出为设计文档。

---

涉及理论

模块	核心知识点	在本阶段的作用
Module 0	5层分析框架	从用户故事到数据流程的完整拆解
Module 1	规模估算 / API 设计	计算 QPS、存储量；设计 RESTful 端点
Module 2	数据模型	表结构、关系、索引规划
Module 18	技术栈选型	用 ADR 记录选型理由

---

实操步骤

步骤1: 用5层框架完成需求分析

用5层框架逐层分析酒店预订系统，产出一份完整的需求分析文档。

你是一名资深系统架构师。请用以下5层分析框架，对"酒店预订系统（Hotel Reservation）"进行完整的需求分析。

## 5层分析框架

### 第1层：用户层
列出所有角色（游客、注册用户、酒店管理员、平台管理员），描述每个角色的核心诉求。

### 第2层：用户故事层
为每个角色写出3-5条用户故事，格式：
"作为[角色]，我想要[功能]，以便[价值]"

重点覆盖：
- 游客：搜索酒店、查看详情、按条件筛选
- 注册用户：预订房间、查看订单、取消订单
- 酒店管理员：管理房型、管理库存、查看订单
- 平台管理员：查看统计、管理酒店

### 第3层：功能层
将用户故事转化为功能模块，按模块分组：
- 搜索模块（搜索、筛选、排序、分页）
- 预订模块（选房、下单、支付、取消）
- 用户模块（注册、登录、个人中心）
- 酒店管理模块（房型管理、库存管理、订单管理）
- 平台管理模块（数据统计、酒店审核）

### 第4层：数据层
列出核心实体及其关键属性（暂不需要完整字段），画出实体关系（1对多、多对多）。

### 第5层：流程层
画出以下核心流程（用文字描述每一步）：
1. 搜索→预订→支付 的完整流程
2. 取消订单→退款 的流程
3. 酒店管理员上架新房型的流程

输出为 Markdown 格式，每层一个二级标题。

步骤2: 规模估算

基于业务假设，计算系统需要承受的 QPS 和存储量。

你是一名系统架构师，正在为酒店预订系统做规模估算。

## 业务假设
- 平台有 10 万家酒店
- 每家酒店平均 5 种房型
- 日均搜索量 100 万次
- 日均预订量 5 万单
- 系统保留 2 年历史数据

## 请计算以下指标

### 1. QPS 估算
- 搜索 QPS = 日搜索量 / 86400，再乘以峰值系数（假设峰值是均值的3倍）
- 预订 QPS = 日预订量 / 86400，峰值系数3倍
- 读写比是多少？

### 2. 存储量估算
- 酒店表：10万条，每条约 1KB → 总量？
- 房型表：50万条，每条约 0.5KB → 总量？
- 库存表：50万房型 × 365天 → 总条数？每条约 100B → 总量？
- 订单表：5万/天 × 730天 → 总条数？每条约 2KB → 总量？
- 总存储量？

### 3. 带宽估算
- 搜索结果页（约 5KB JSON）× QPS
- 详情页（约 10KB JSON）× QPS的20%

### 4. 结论
给出推荐的数据库类型、是否需要缓存、是否需要分库分表的初步判断。

请写出完整的计算过程，保留中间步骤。输出 Markdown 格式。

步骤3: 技术选型 (ADR)

用 Architecture Decision Record 格式记录技术选型。

你是一名架构师，请为酒店预订系统撰写技术选型 ADR（Architecture Decision Record）。

## 系统约束
- 团队规模：1-2人
- 开发周期：4周MVP
- 日均搜索 100万，预订 5万
- 需要防超卖（并发安全）

## 需要决策的技术点

### 1. 后端语言和框架
候选：Go+Gin / Node+Express / Java+Spring Boot
请选择 Go+Gin，并从以下维度说明理由：
- 性能（并发模型）
- 开发效率
- 部署简易度
- 团队学习成本

### 2. 数据库
候选：PostgreSQL / MySQL / MongoDB
请选择 PostgreSQL，说明理由（重点：事务支持、JSON字段、全文搜索）

### 3. 缓存
候选：Redis / Memcached / 不用缓存
请选择 Redis，说明理由（重点：数据结构丰富、过期策略、原子操作）

### 4. 前端
候选：React+Vite / Next.js / Vue
请选择 React+Vite+Tailwind CSS，说明理由

### 5. 部署
候选：Docker Compose / Kubernetes / 裸机
请选择 Docker Compose（开发阶段），说明理由

## 输出格式
每个决策用以下格式：
### 决策：[技术选择]
- **状态**：已采纳
- **背景**：[为什么需要做这个决策]
- **候选方案**：[列出候选]
- **决定**：[选了什么]
- **理由**：[为什么选它]
- **后果**：[选了它之后的正面和负面影响]

步骤4: 数据模型设计

设计完整的数据库表结构。

你是一名后端工程师，使用 Go + GORM + PostgreSQL。请为酒店预订系统设计完整的数据模型。

## 核心实体

### 1. User（用户）
字段：ID, Email, PasswordHash, Name, Phone, Role(guest/hotel_admin/admin), CreatedAt, UpdatedAt

### 2. Hotel（酒店）
字段：ID, Name, Address, City, Province, Country, Latitude, Longitude, Description, Rating, ImageURL, OwnerID(FK→User), Status(active/inactive), CreatedAt, UpdatedAt

### 3. RoomType（房型）
字段：ID, HotelID(FK→Hotel), Name, Description, MaxGuests, BedType, Area, Price(基础价/分), Amenities(JSON), ImageURL, CreatedAt, UpdatedAt

### 4. Inventory（库存）
字段：ID, RoomTypeID(FK→RoomType), Date, TotalCount, AvailableCount, Price(当日价/分)
唯一约束：(RoomTypeID, Date)

### 5. Order（订单）
字段：ID, UserID(FK→User), HotelID(FK→Hotel), RoomTypeID(FK→RoomType), CheckInDate, CheckOutDate, GuestName, GuestPhone, TotalPrice(分), Status(pending/confirmed/cancelled/completed), PaymentID, CancelledAt, CreatedAt, UpdatedAt

## 要求
1. 用 Go struct + GORM tag 写出完整的模型定义
2. 价格用 int64 存储（单位：分），避免浮点精度问题
3. 标注所有索引（搜索常用字段）
4. 标注外键关系
5. 为每个模型写出简短注释说明设计意图
6. 写出 GORM AutoMigrate 的调用代码

输出完整的 Go 代码，可以直接复制使用。

步骤5: API 设计

设计完整的 RESTful API。

你是一名后端工程师，请为酒店预订系统设计完整的 RESTful API。

## 要求
- 基础路径：/api/v1
- 认证方式：JWT Bearer Token
- 分页格式：?page=1&page_size=20
- 错误格式：{"error": "message"}
- 成功格式：{"data": {...}} 或 {"data": [...], "pagination": {...}}

## API 列表

### 认证模块
- POST /api/v1/auth/register — 注册
- POST /api/v1/auth/login — 登录
- POST /api/v1/auth/refresh — 刷新token

### 搜索模块（公开）
- GET /api/v1/hotels/search?city=&check_in=&check_out=&guests=&min_price=&max_price=&page=&page_size= — 搜索酒店
- GET /api/v1/hotels/:id — 酒店详情（含房型列表+指定日期库存）

### 预订模块（需登录）
- POST /api/v1/bookings — 创建订单
- GET /api/v1/bookings — 我的订单列表
- GET /api/v1/bookings/:id — 订单详情
- POST /api/v1/bookings/:id/cancel — 取消订单

### 酒店管理（需 hotel_admin 角色）
- GET /api/v1/admin/hotels/:id/room-types — 房型列表
- POST /api/v1/admin/hotels/:id/room-types — 创建房型
- PUT /api/v1/admin/room-types/:id — 更新房型
- PUT /api/v1/admin/room-types/:id/inventory — 批量更新库存

### 平台管理（需 admin 角色）
- GET /api/v1/platform/hotels — 所有酒店列表
- PUT /api/v1/platform/hotels/:id/status — 更新酒店状态

## 对每个 API 请写出：
1. 方法 + 路径
2. 请求头（是否需要 Authorization）
3. 请求参数或请求体（JSON 示例）
4. 成功响应（JSON 示例，含具体字段）
5. 错误响应（列出可能的错误码和消息）
6. 备注（业务规则）

输出 Markdown 格式，每个 API 一个三级标题。

---

检查清单

• 5层分析框架的每一层都有实质内容，不是泛泛而谈
• 规模估算有完整的计算过程，不只是结论
• 技术选型 ADR 每个决策都有理由和后果
• 数据模型包含所有5个核心实体，字段完整
• 价格字段使用整数（分）而非浮点
• API 设计覆盖搜索、预订、取消、管理四大模块
• 每个 API 都有请求和响应的 JSON 示例

---

常见踩坑

1. 价格用 float64 存储 — 浮点精度问题会导致金额计算错误。永远用 int64 存储分（cents），前端展示时除以 100。例如 ¥199.00 存为 19900。

2. 库存表没有唯一约束 — 如果 (room_type_id, date) 没有唯一约束，并发写入可能产生重复记录。必须在数据库层面加 UNIQUE INDEX，不能只靠应用层校验。

3. 需求分析跳过流程层直接画表 — 不画核心流程就设计数据模型，容易遗漏关键字段（比如取消时间 cancelled_at、支付ID payment_id）。务必先想清楚”一个订单从创建到完成经历哪些状态”，再定义字段。