2025-2026-3 暑期学期《计算机系统综合实验》课程项目：酒店在线预定平台。
本项目以真实酒店预定流程为背景，完成需求分析、系统设计、编码、测试、部署和答辩展示的全流程工作流。最终目的是交付一个模块清晰、接口明确、可测试、可演示、符合软件工程规范的应用系统。
- 注册、登录并维护个人账号。
- 在未来一周内按入住、离店、房间数和入住人数查询可用房型。
- 查看房型名称、图片、价格、介绍、每间入住容量和剩余数量。
- 在确认页获取后端实时报价，再按“天”提交预定，系统重新校验容量和库存后生成订单。
- 查看个人订单列表、完整详情及其状态。
- 至少提前一天取消预定，取消成功后释放库存。
- 查看个人信用状态；连续违规取消三次后，一周内禁止再次预定。
- 使用 AI 智能体描述日期、人数、预算和偏好，获得基于实时房态的房型推荐。
- 每个商家管理账号只运营其唯一绑定的一家酒店。
- 对本酒店房型名称、价格、库存、图片等信息进行增删改查。
- 查看本酒店预定订单、库存变化和必要的用户信用摘要。
- 使用 AI 智能体查询房态和订单，并在确认后执行库存或预定管理操作。
- 不绑定具体酒店，管理全平台账号、酒店和商家归属。
- 创建商家账号、酒店及其一对一绑定，并执行受控数据维护。
- 数据结构变更只通过 Alembic 完成，不向网页或 AI 开放任意 SQL。
- 普通用户、商家管理员和平台管理员采用同一身份体系、不同角色授权，后端必须校验角色、资源所有权和酒店归属。
- 可预定日期限制为未来一周内；入住日期必须早于离店日期。
- 房量按日期管理，不能只维护一个全局剩余库存。
- 入住人数不得超过“房型每间容量 × 房间数”，查询与创建订单均由后端校验。
- 创建订单与扣减库存必须在同一数据库事务中完成，避免超卖。
- 取消订单与释放库存必须在同一数据库事务中完成，且同一订单只能成功取消一次。
- 用户必须至少提前一天取消；具体截止时间统一按服务端配置和时区计算。
- “连续三次取消”以连续三个已结束订单均为用户主动取消为准；触发后禁订七天。成功入住完成后连续取消计数清零。
- 金额使用定点小数保存，报价和订单总价只由后端计算，禁止使用浮点数计算价格。
| 层级 | 技术 | 选择理由 |
|---|---|---|
| 前端 | React 18、TypeScript、Vite | 组件化成熟、类型安全、开发反馈快，标杆项目已有可复用经验 |
| UI | Ant Design、CSS Modules | 快速构建一致的桌面端界面，同时保留响应式定制能力 |
| 路由与请求 | React Router、TanStack Query、Axios | 明确页面边界，统一服务端状态、缓存、加载和错误处理 |
| 后端 | Python 3.11+、FastAPI、Pydantic 2 | 接口契约清晰、开发效率高、自动生成 OpenAPI 文档 |
| AI 智能体 | LLM Provider Adapter、受控工具调用 | 模型负责理解与表达，工具复用业务服务并执行权限、确认和审计 |
| ORM 与迁移 | SQLAlchemy 2、Alembic | 显式事务、成熟关系模型、数据库结构可追踪 |
| 数据库 | MySQL 8 | 适合用户、房型、每日库存和订单等强关系、强事务业务 |
| 身份认证 | JWT 短时访问令牌 + BCrypt/Argon2 密码哈希 | 前后端分离场景易落地；不存储明文密码 |
| 测试 | Vitest、Testing Library、Pytest | 覆盖前端组件、后端服务与关键接口 |
| 工程工具 | pnpm、uv、ESLint、Prettier、Ruff、mypy | 固定依赖、统一格式、尽早发现类型和质量问题 |
Hotel-Reservation/
├─ frontend/ # React 前端
│ ├─ src/
│ │ ├─ api/ # HTTP 客户端与接口函数
│ │ ├─ components/ # 可复用展示组件
│ │ ├─ features/ # auth、rooms、reservations、admin
│ │ ├─ hooks/ # 通用 Hooks
│ │ ├─ layouts/ # 页面布局
│ │ ├─ pages/ # 路由页面
│ │ ├─ routes/ # 路由与权限守卫
│ │ ├─ types/ # 前端类型
│ │ └─ utils/ # 无副作用工具函数
│ └─ tests/
├─ backend/ # FastAPI 后端
│ ├─ app/
│ │ ├─ api/v1/ # 路由层
│ │ ├─ core/ # 配置、安全、异常、日志
│ │ ├─ models/ # ORM 模型
│ │ ├─ repositories/ # 数据访问
│ │ ├─ schemas/ # 请求与响应模型
│ │ └─ services/ # 业务规则与事务编排
│ ├─ migrations/ # Alembic 迁移
│ └─ tests/
├─ doc/ # 需求、设计、UML、测试和答辩资料
├─ .env.example # 可公开的配置模板
├─ README.md
└─ agents.md # 开发与代理执行规范
- 所有业务接口使用
/api/v1前缀，交换格式统一为 JSON。 - 资源路径使用复数名词，例如
/room-types、/reservations。 - 使用标准 HTTP 方法和状态码，不以
200包装所有错误。 - 错误响应统一包含稳定的
code、面向用户的message和可选details。 - 时间通过 ISO 8601 传输，服务端统一使用
Asia/Shanghai解释业务截止时间。 - 分页、排序和筛选参数采用统一命名；接口变更必须同步 OpenAPI 和前端类型。
- 图片第一阶段使用受控 URL 或本地上传目录，数据库仅保存元数据和地址。
users：账户、密码摘要、角色、状态和禁订截止时间。hotels：独立酒店主体、状态和平台创建者。merchant_hotel_bindings：商家账号与酒店的严格一对一绑定。auth_sessions：JWT 对应的可撤销短时登录会话。room_types：房型名称、说明、价格、基础库存、每间入住容量和展示信息。room_type_images：房型图片及排序。daily_inventories：房型、日期、总量、已预定量；房型与日期联合唯一。reservations：订单号、用户、房型、入住/离店日期、房间数、入住人数、金额、状态和时间戳。credit_events：取消、完成、禁订等信用事件审计记录。
数据库迁移是结构变更的唯一入口。禁止只修改本地数据库、不提交迁移脚本。
本节覆盖从拉取代码、启动数据库、执行迁移，到注入三类 M1 测试账号并启动前后端的完整流程。团队成员按顺序执行即可得到一致的本地验收环境。
- Node.js 20+
- pnpm 9+
- Python 3.11+
- uv
- MySQL 8+
复制根目录 .env.example 为 .env，按说明填写数据库地址。前后端开发命令统一读取这份根配置；只有 VITE_ 前缀的变量会暴露给浏览器。真实密码、密钥、个人配置和生产数据不得提交到 Git。
项目提供独立的 MySQL 8 开发容器。默认映射到本机 3308 端口，避免与其他项目常用的 3306 端口冲突。
docker compose up -d
docker compose ps确认容器状态为 healthy 后，再执行后端迁移。
cd backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8000如需创建个人平台管理员，执行以下命令。终端会安全提示输入密码，不会把密码写入命令历史或迁移文件。
uv run python -m app.commands.create_platform_admin --username admin --display-name "平台管理员"团队成员拉取代码、启动 MySQL 并执行迁移后，运行一次以下命令即可获得相同的测试账号、演示酒店、商家绑定和三个在售房型：
cd backend
uv sync
uv run alembic upgrade head
uv run python -m app.commands.seed_m1_demo_accounts| 角色 | 账号 | 密码 | 数据范围 |
|---|---|---|---|
| 平台管理员 | demo_admin |
Admin12345 |
全平台 |
| 商家管理员 | demo_merchant |
Merchant12345 |
DEMO-001 成都太古里亚朵S酒店 |
| 开发测试用户 | demo_customer |
Customer12345 |
普通会员数据 |
该命令具备以下行为：
- 只允许在
development或test环境运行，生产环境会直接拒绝。 - 可以重复执行，不会产生重复账号、酒店或绑定。
- 会创建或重置
雅致大床房、城景双床房和行政套房，便于查看用户端房型浏览与商家端管理页面。 - 重复执行会恢复上表中的演示密码和启用状态，并撤销这些账号的旧登录会话。
- 如果同名账号已被其他角色占用，或演示酒店已绑定其他商家，命令会拒绝覆盖并回滚。
- 这些是公开的本地测试凭据，不得用于部署环境或真实业务数据。
接口文档默认位于 http://localhost:8000/docs。
/api/v1/health 用于检查后端进程是否存活，/api/v1/health/ready 还会检查数据库是否可用。
cd frontend
pnpm install
pnpm dev前端默认使用 http://localhost:5173，通过环境变量配置 API 基地址。
上述命令对应当前脚手架；执行数据库迁移前，需要先创建空数据库并确保 .env 中的 MySQL 连接可用。
- 从 issue 处领取本次开发任务。例如：修复某 bug、重构前端界面、增加某功能。
- 如果对于开发任务不清楚的，务必与组长或对应负责人沟通清楚，避免返工。
- 从最新
main创建短生命周期功能分支，命名为feat/*、fix/*、docs/*或refactor/*。 - 进行开发。与 AI 协作开发，我们的同学争取不写一句代码，全部 vibe coding。
- commit 你的代码，一次 commit 尽量只做一个功能点。也就是提交代码要少量多次。使用 Conventional Commits，例如
feat(reservation): prevent overselling。 - 拉 PR（Pull Request），组长或对应负责人会审查代码。如果可以的话核查者会直接合并到
main分支。这意味着你的代码被采用了！
课程评价侧重以下三部分：
- 系统分析与设计（30%）：需求分析、概要设计、详细设计、UML 模型和测试报告。
- 系统实现（55%）：工作量、模块质量与复杂度，以及稳定性、易用性和容错性。
- 演示答辩（15%）：主要功能与界面演示、项目汇报 PPT、团队分工及问答。
项目按需求分析、概要设计、详细设计、程序编码、测试、集成验收的阶段推进。团队人数不超过 6 人，每位成员对自己承担的模块、提交和答辩内容负责。
doc/相关要求.pdf：课程目标、项目功能、考核方式和交付要求。doc/开发规范.md：工作的时候强制遵守的规范。- 详细的强制开发规则见
agents.md，Agent 每次工作的时候都会看一遍这个文件作为上下文。 - 阶段任务与验收见
MILESTONES.md。 - 功能优先级与实现思路见
FUNCTION_MATRIX.md。