# HuojiHotel **Repository Path**: JamesMaium/HuojiHotel ## Basic Information - **Project Name**: HuojiHotel - **Description**: 欢迎关注抖音 @火鸡程序员 火鸡酒店客房管理系统免费开源，需要的兄弟随时clone，记得点个Star! 关键词： 酒店管理系统、宾馆管理系统、客房管理系统 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-08-19 - **Last Updated**: 2026-08-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🏨 酒店客房管理系统 > 基于 Python + PyQt5 + SQLite 的 Windows 桌面客户端酒店管理系统，轻量、高效、开箱即用。 > > **既可作为计算机专业毕业设计，也可直接用于中小型酒店的日常运营管理。** --- ## 📋 目录 - [项目简介](#项目简介) - [功能特性](#功能特性) - [技术栈](#技术栈) - [系统要求](#系统要求) - [快速开始](#快速开始) - [打包部署](#打包部署) - [项目结构](#项目结构) - [数据库设计](#数据库设计) - [打印功能](#打印功能) - [数据安全](#数据安全) - [毕设使用指南](#毕设使用指南) - [商业使用指南](#商业使用指南) - [默认账号](#默认账号) - [开发者信息](#开发者信息) - [更新日志](#更新日志) - [常见问题](#常见问题) --- ## 项目简介 本系统是一款功能完善的酒店客房管理系统，采用 **Python 3 + PyQt5 + SQLite** 技术栈开发，为 Windows 平台桌面应用。系统采用嵌入式 SQLite 数据库，无需额外安装数据库服务，单文件存储，真正做到「下载即用」。 系统覆盖酒店前台运营的全流程：房态管理、预订管理、入住登记、退房结算、账务管理、客户管理、协议客户、统计报表、系统管理等十大核心模块，满足中小型酒店、宾馆、民宿的日常管理需求。 同时，系统架构清晰、代码规范、文档齐全，非常适合作为计算机相关专业的**毕业设计项目**使用。 --- ## 功能特性 ### 🏠 房态看板（首页） - 可视化房间状态面板，颜色区分（空闲/已预订/已入住/清洁中/维修中） - 按楼层分组展示，实时统计入住率 - 点击房间卡片直接办理入住/退房，无需切换页面 - 房间详情弹窗，支持快捷操作 ### 🛏️ 客房管理 - **楼层管理**：楼层增删改查，支持编辑 - **房型管理**：单人间/标准间/大床房/豪华间/套房等，自定义价格 - **房间管理**：房间编号、楼层、房型、价格、状态、备注 - 房间状态批量更新 ### 📅 预订管理 - 新建预订（客人信息、房型偏好、入住离店日期、押金） - 预订查询（按姓名/电话/预订号模糊搜索） - 预订确认、修改、取消、转入住 - 预订状态管理（待确认/已确认/已入住/已取消/已过期） - 两栏式表单布局，信息录入更高效 ### ✅ 入住管理 - 散客直接入住 / 预订转入住两种方式 - 自动推荐可用房间，支持手动分配 - 客人身份信息登记（姓名、证件号、证件类型、联系方式） - 押金收取（现金/微信/支付宝/银行卡/挂账） - 换房操作、续住操作 - 入住登记单 58mm 小票打印 ### 🚪 退房管理 - 自动核算费用（房费×天数 + 额外消费 - 折扣 - 押金） - 押金抵扣，实时显示应收/应退/找零金额 - 多种支付方式结算 - 退房结算单 58mm 小票打印 - 事务机制保障数据一致性 ### 💰 账务与消费管理 - 在住账单实时查看，支持录入额外消费 - 消费项目管理（minibar/洗衣/餐饮/接送等） - 账单明细查看与打印 - 历史账单查询与打印 - 挂账管理（协议客户挂账额度控制、还款记录） ### 👤 客户管理 - 客户档案自动积累，入住即建档 - 会员等级管理（普通/银卡/金卡/钻石，不同折扣率） - 客户标签（VIP/常客/黑名单等） - 客户信息模糊查询 - 敏感数据脱敏显示（手机号、证件号） - 两栏式布局：基本信息+证件信息 / 会员信息+备注 ### 📊 统计报表 - 日报/月报/自定义区间统计 - 收入趋势柱状图 - 入住率分析 - 客源分析 - 支持导出 Excel 和 PDF ### 🤝 协议客户管理 - 协议单位信息管理 - 协议价格设置（按房型） - 挂账额度控制，超额预警 - 对账单生成 - 还款记录管理 - 两栏式布局 ### ⚙️ 系统管理 - **用户管理**：用户增删改查、角色分配、重置密码 - **角色权限**：超级管理员/前台接待/客房服务员/财务人员 - **操作日志**：登录/退房/修改等关键操作全程记录 - **系统设置**：酒店名称、地址、联系方式、营业时间、入住退房时间 - **数据备份**：一键备份与恢复，WAL 模式 checkpoint 保障数据完整 - 顶部栏「关于」「赞赏」快捷入口 --- ## 技术栈 | 类别 | 技术 | 说明 | |------|------|------| | 开发语言 | Python 3.x | 主开发语言 | | GUI 框架 | PyQt5 | 桌面界面 | | 数据库 | SQLite 3 | 嵌入式单文件数据库，WAL 模式 | | 密码加密 | bcrypt | 用户密码安全存储 | | 打印支持 | ESC/POS + win32print + pyserial | 58mm 热敏小票打印 | | 报表导出 | openpyxl + reportlab | Excel/PDF 导出 | | 打包工具 | PyInstaller | 打包为单文件 EXE | | 系统交互 | pywin32 | Windows API 调用（打印、USB设备） | --- ## 系统要求 - **操作系统**：Windows 10 / Windows 11（64位） - **Python 版本**：3.8 及以上（开发环境） - **内存**：最低 2GB，推荐 4GB 以上 - **磁盘空间**：最低 100MB（含数据库） - **分辨率**：最低 1280×800，推荐 1920×1080 --- ## 快速开始 ### 方式一：直接运行 EXE（推荐） 1. 下载 `dist/酒店客房管理系统.exe` 2. 双击运行，无需安装 Python 和任何依赖 3. 首次启动自动创建数据库和初始数据 ### 方式二：开发环境运行 ```bash # 1. 克隆或下载项目 cd 酒店客房管理系统 # 2. 安装依赖 pip install -r requirements.txt # 3. 启动程序 python main.py # 或双击 run.bat ``` ### 首次启动 - 自动创建 `data/` 目录及数据库文件 - 自动初始化 16 张数据表 - 自动插入初始数据（角色、用户、房型、楼层、房间、测试数据等） - 使用默认账号登录 --- ## 打包部署 ### 打包为单文件 EXE ```bash # 双击 build.bat # 或手动执行 pyinstaller --onefile --windowed ^ --icon "logo.ico" ^ --name "酒店客房管理系统" ^ --add-data "resources;resources" ^ --hidden-import PyQt5.QtPrintSupport ^ --hidden-import win32print ^ --hidden-import win32api ^ --hidden-import win32con ^ --hidden-import win32file ^ --hidden-import pywintypes ^ --hidden-import pythoncom ^ --hidden-import serial ^ --hidden-import serial.tools ^ --hidden-import serial.tools.list_ports ^ main.py ``` 打包完成后，EXE 文件位于 `dist/酒店客房管理系统.exe`，约 270MB。 ### 部署说明 - EXE 为单文件绿色版，无需安装，拷贝即可使用 - 数据库文件自动创建在 EXE 同目录的 `data/` 文件夹下 - 建议将 EXE 放在非系统盘目录（如 `D:\酒店管理\`），避免权限问题 - 升级时直接替换 EXE 文件，`data/` 目录中的数据不会丢失 --- ## 项目结构 ``` 酒店客房管理系统/ ├── main.py # 程序入口（启动画面+登录→主窗口） ├── config.py # 全局配置（路径、常量、状态、颜色） ├── requirements.txt # 依赖清单 ├── run.bat # 开发环境启动脚本 ├── build.bat # EXE 打包脚本 ├── logo.ico # 程序图标 ├── money.png # 赞赏二维码 ├── README.md # 项目说明文档 ├── database/ │ ├── db_manager.py # 数据库管理器（单例+事务+唯一索引） │ └── init_db.py # 建表SQL + 初始数据 ├── gui/ │ ├── login_window.py # 登录窗口（深色渐变） │ └── main_window.py # 主窗口（左侧导航+右侧堆叠+顶部栏） ├── modules/ │ ├── room_management/ │ │ ├── room_board.py # 房态看板（快捷入住/退房） │ │ └── room_manage.py # 客房管理（楼层/房型/房间） │ ├── reservation/ │ │ └── reservation_page.py # 预订管理 │ ├── check_in/ │ │ └── check_in_page.py # 入住管理 │ ├── check_out/ │ │ └── check_out_page.py # 退房管理 │ ├── billing/ │ │ └── billing_page.py # 账务管理（在住/历史/挂账） │ ├── customer/ │ │ └── customer_page.py # 客户管理 │ ├── reports/ │ │ └── reports_page.py # 统计报表（图表） │ ├── agreement/ │ │ └── agreement_page.py # 协议客户管理 │ └── system_management/ │ ├── system_page.py # 系统管理（用户/日志/设置/备份） │ ├── donation_dialog.py # 赞赏二维码弹窗 │ └── about_dialog.py # 关于信息弹窗 ├── utils/ │ ├── helpers.py # 工具函数（密码/脱敏/金额格式化） │ ├── logger.py # 日志模块 │ ├── export.py # Excel/PDF 导出 │ └── printer.py # 打印模块（USB/串口/Windows RAW） ├── resources/ # 资源文件（图标、图片） └── data/ # 运行时数据（自动创建） ├── hotel_management.db # SQLite 数据库 ├── logs/ # 日志文件 └── backup/ # 数据库备份 ``` --- ## 数据库设计 ### 数据表（共 16 张） | 表名 | 说明 | |------|------| | users | 系统用户 | | roles | 角色 | | floors | 楼层 | | room_types | 房型 | | rooms | 房间 | | guests | 客户档案 | | reservations | 预订记录 | | check_ins | 入住记录 | | bills | 账单 | | bill_items | 账单明细 | | agreement_companies | 协议单位 | | credit_payments | 挂账还款记录 | | operation_logs | 操作日志 | | settings | 系统设置 | | member_levels | 会员等级 | | customer_tags | 客户标签 | ### 数据安全机制 - **事务支持**：入住/退房/消费/还款等关键操作使用数据库事务，失败自动回滚 - **唯一索引**：同房间仅一条 active 入住记录、账单号/入住单号/预订单号唯一，防止重复数据 - **WAL 模式**：SQLite WAL 日志模式，读写并发性能更好 - **密码加密**：用户密码使用 bcrypt 加密存储，不可逆 - **数据备份**：一键备份，备份前执行 checkpoint 确保数据完整 - **操作日志**：关键操作全程记录，可追溯 --- ## 打印功能 系统支持 **58mm 热敏小票打印机**，兼容多种连接方式： ### 支持的打印机类型 | 类型 | 说明 | |------|------| | USB 直连 | 未安装驱动的 usbprint 设备（如 VID_09C5&PID_58DE，美团同款） | | Windows 打印机 | 已安装驱动的 USB/网络打印机（RAW 模式） | | COM 串口 | 串口/蓝牙串口热敏打印机，波特率自动适配 | | PDF 虚拟打印 | 保存为 58mm 宽度 PDF 小票 | ### 打印内容 - **入住小票**：酒店名称、入住凭证、单号、客人、房间、入住离店时间、房价、押金 - **退房小票**：酒店名称、退房结算、房费、消费、优惠、押金、应收、实付、找零、支付方式 - **历史账单**：支持从账务管理历史账单中打印结算凭证 ### 打印特性 - 中文 GBK 编码，国产热敏打印机通用 - 标题和金额双倍宽高大字显示 - 行间距优化，阅读舒适 - 首次打印自动选择并保存打印机，后续无需重复选择 - 打印失败自动清除保存配置，重新选择 --- ## 数据安全 ### 事务机制 所有涉及金额和状态变更的操作均在数据库事务中执行： - 办理入住（插入入住记录+创建账单+更新房间状态） - 办理退房（更新入住状态+结算账单+更新房间状态） - 录入消费（插入明细+更新账单金额） - 还款操作（更新挂账余额+插入还款记录） 任何一步失败，整个事务回滚，数据保持一致。 ### 防重复机制 - 唯一索引防止同一房间同时存在多条 active 入住 - 账单号、入住单号、预订单号全局唯一 - UI 层按钮防抖，防止重复点击提交 ### 备份恢复 - 一键备份：WAL checkpoint 后复制数据库文件，确保数据完整 - 从备份恢复：选择备份文件即可恢复，恢复后需重启程序 --- ## 毕设使用指南 本系统非常适合作为计算机科学与技术、软件工程、信息管理与信息系统等专业的**毕业设计项目**。 ### 为什么适合做毕设 - ✅ **技术栈主流**：Python + PyQt5 + SQLite，易于理解和答辩 - ✅ **功能完整**：十大模块覆盖酒店运营全流程，工作量饱满 - ✅ **架构清晰**：MVC 分层，代码规范，便于讲解设计思路 - ✅ **亮点突出**：事务机制、数据安全、打印兼容、UI 统一设计 - ✅ **可演示性强**：界面美观，交互流畅，答辩演示效果好 - ✅ **文档齐全**：README、代码注释、数据库设计完整 ### 毕设答辩要点建议 1. **需求分析**：酒店行业痛点、系统目标、用户角色 2. **系统设计**：架构图、功能模块图、数据库 ER 图 3. **关键技术**： - PyQt5 信号槽机制、自定义对话框 - SQLite 事务与并发控制 - ESC/POS 热敏打印指令 - bcrypt 密码加密 4. **系统演示**：入住→消费→退房全流程演示，打印小票 5. **创新点**：房态看板快捷操作、多类型打印机兼容、数据安全机制 ### 论文章节参考 - 第1章 绪论（研究背景、意义、国内外现状） - 第2章 相关技术介绍（Python、PyQt5、SQLite） - 第3章 系统需求分析（功能性需求、非功能性需求） - 第4章 系统设计（总体架构、功能模块、数据库设计） - 第5章 系统实现（各模块核心代码与界面） - 第6章 系统测试（测试用例、测试结果） - 第7章 总结与展望 --- ## 商业使用指南 本系统可直接用于中小型酒店、宾馆、民宿的日常运营管理。 ### 部署步骤 1. 将 EXE 拷贝到前台电脑（建议非系统盘目录） 2. 双击运行，系统自动初始化 3. 使用 admin 账号登录，进入「系统管理 → 系统设置」 4. 修改酒店名称、地址、联系方式等基础信息 5. 进入「客房管理」，设置楼层、房型、房间信息 6. 进入「系统管理 → 用户管理」，创建前台、财务等操作员账号 7. 连接 58mm 热敏打印机，办理入住时测试打印 ### 日常操作流程 1. **客人到店**：房态看板点击空闲房间 → 办理入住 → 收押金 → 打印小票 2. **客人消费**：账务管理 → 在住账单 → 录入消费（minibar/餐饮等） 3. **客人退房**：房态看板点击已入住房间 → 办理退房 → 核算费用 → 收款找零 → 打印小票 4. **交接班**：统计报表查看当日营收，账务管理核对账单 ### 数据维护 - 定期使用「系统管理 → 数据备份」功能备份数据库 - 建议每日备份一次，备份文件拷贝到 U 盘或云端 - 系统崩溃时，使用「从备份文件恢复」功能还原数据 --- ## 默认账号 | 用户名 | 密码 | 角色 | 说明 | |--------|------|------|------| | `admin` | `admin123` | 超级管理员 | 全部权限，首次登录后请修改密码 | --- ## 开发者信息 - **创作者**：抖音博主 **@火鸡程序员** - **共同开发**：@火鸡程序员 & 豆包 AI - **技术支持**：抖音搜索「火鸡程序员」关注获取更新 - **项目版本**：v1.0.0 - **发布日期**：2026年 > 如果这个系统对您有帮助，欢迎扫码赞赏支持作者 ❤️ --- ## 更新日志 ### v1.0.0（2026-08） - 🎉 首个正式版本发布 - 十大核心功能模块完整实现 - SQLite 嵌入式数据库，事务机制保障数据安全 - 58mm 热敏小票打印，支持 USB/串口/Windows RAW 多种方式 - 统一表单 UI 设计，两栏式布局，必填红星标注 - 房态看板快捷入住/退房 - 历史账单打印支持 - 数据库一键备份与恢复 - 酒店名称全局显示（窗口标题+左上角Logo+小票抬头） - 程序图标自定义 - 关于与赞赏弹窗 --- ## 常见问题 ### Q: 启动时提示数据库文件不存在？ A: 首次启动会自动创建数据库，如遇权限问题，请将 EXE 放到非系统盘目录（如 D 盘）运行。 ### Q: 打印机检测不到？ A: 请检查： 1. 打印机是否开机并连接电脑 2. 设备管理器中是否显示「USB 打印支持」或 COM 端口 3. USB 打印机无需安装驱动，系统会自动识别为 usbprint 设备 4. 首次打印会自动列出所有可用设备，选择对应打印机即可 ### Q: 打印出来是乱码？ A: 请确认使用的是 58mm 热敏打印机，系统使用 GBK 编码和 ESC/POS 指令，国产热敏打印机（佳博、芯烨、商米等）均兼容。 ### Q: 忘记管理员密码怎么办？ A: 可使用数据库工具（如 DB Browser for SQLite）打开 `data/hotel_management.db`，将 users 表中 admin 的 password 字段重置为 bcrypt 加密后的新密码。 ### Q: 如何升级到新版本？ A: 直接替换 EXE 文件即可，`data/` 目录中的数据库和配置不会丢失。升级前建议先备份数据库。 ### Q: 支持多台电脑联网使用吗？ A: 当前版本为单机版，数据库存储在本地。如需多机联网，可将数据库文件放到共享文件夹，或后续升级为 C/S 架构。 --- ## 许可证 本项目仅供学习和商业使用，请勿用于非法用途。 © 2026 火鸡程序员. 保留所有权利。