# HotinGo

**Repository Path**: Lyong9102/hotingo

## Basic Information

- **Project Name**: HotinGo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div id="top"></div>

<!-- Language Links -->
<div align="center">
  <strong>
    <a href="README.md">English</a> | <a href="README-ZH.md">中文</a>
  </strong>
</div>

<br />

<!-- PROJECT SHIELDS -->

[![贡献者][contributors-shield]][contributors-url]
[![最后提交][last-commit-shield]][last-commit-url]
[![Fork数][forks-shield]][forks-url]
[![Stars][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]

<!-- PROJECT Intro -->
<br />
<div align="center">
  <a href="https://gitee.com/Lyong9102/hotingo/stargazers">
    <img src="assets/Readme-assets/banner.png" alt="项目横幅" width="100%">
  </a>

  <p align="center">
    HotinGo - 酒店管理系统
    <br />
    <a href="https://gitee.com/Lyong9102/hotingo"><strong>浏览文档 »</strong></a>
    <br />
    <br />
    <a href="https://www.figma.com/file/MVq5Q3fhVJB2r70r7I3nJ3/HotinGo?node-id=102%3A2">Figma设计文件</a>
    ·
    <a href="https://gitee.com/Lyong9102/hotingo/issues">报告Bug</a>
    ·
    <a href="https://gitee.com/Lyong9102/hotingo/issues">请求功能</a>
  </p>
</div>


<!-- TABLE OF CONTENTS -->
<details>
  <summary>目录</summary>
  <ol>
    <li>
      <a href="#关于项目">关于项目</a>
      <ul>
        <li><a href="#核心功能">核心功能</a></li>
        <li><a href="#为什么选择-hotingo">为什么选择 HotinGo</a></li>
        <li><a href="#界面截图">界面截图</a></li>
        <li><a href="#项目动机">项目动机</a></li>
        <li><a href="#技术栈">技术栈</a></li>
      </ul>
    </li>
    <li>
      <a href="#快速开始">快速开始</a>
      <ul>
        <li><a href="#前置要求">前置要求</a></li>
        <li><a href="#安装步骤">安装步骤</a></li>
        <li><a href="#故障排除">故障排除</a></li>
        <li><a href="#附加功能">附加功能</a></li>
        <ul>
            <li><a href="#数据库备份">数据库备份</a></li>
            <li><a href="#添加新用户">添加新用户</a></li>
        </ul>
      </ul>
    </li>
    <li><a href="#安全性说明">安全性说明</a></li>
    <li><a href="#路线图">路线图</a></li>
    <li><a href="#贡献">贡献</a></li>
    <li><a href="#许可证">许可证</a></li>
    <li><a href="#联系方式">联系方式</a></li>
    <li><a href="#致谢">致谢</a></li>
  </ol>
</details>

<!-- ABOUT THE PROJECT -->

# 关于项目

<a href="https://projects.mohityadav.codes/#HotinGo">
    <img src="assets/Readme-assets/logo-full.png" alt="项目横幅" width="300">
</a>

HotinGo 是一个开源、注重设计的现代化 Python 酒店管理系统。基于 Python 3（2026）、Tkinter 和 SQLite3 构建，展示了经典框架如何创建具有精美用户界面的应用程序。

## 核心功能

### 完整的增删改查操作
-   **客人管理**：添加、更新、查看和删除客人记录及联系信息
-   **房间管理**：管理房间库存、价格、类型（日间/夜间）和可用状态
-   **预订管理**：创建和跟踪预订，包括入住/退房日期、餐食计划和房间分配

### 安全性与数据完整性
-   **参数化查询**：所有数据库操作使用预处理语句防止 SQL 注入攻击
-   **外键约束**：维护客人、房间和预订之间的引用完整性
-   **安全认证**：基于 SQLite3 的登录系统，具有数据库级访问控制

### 零配置数据库
-   **无需外部服务器**：嵌入式 SQLite3 数据库本地运行
-   **自动初始化**：首次运行时自动创建数据库和架构
-   **简单备份**：只需复制 `hms.db` 文件 - 无需复杂的导出过程
-   **可移植**：通过复制单个文件即可移动整个数据库

### 现代开发实践
-   **环境变量**：通过 `.env` 文件配置设置
-   **虚拟环境支持**：隔离的依赖管理
-   **启动验证**：自动检查依赖项和数据库完整性
-   **跨平台**：支持 Windows、macOS 和 Linux

<p align="right">(<a href="#top">返回顶部</a>)</p>

## 为什么选择 HotinGo？

### 零配置
无需安装或配置复杂的数据库服务器。SQLite3 内嵌在 Python 中，克隆仓库后即可立即使用。数据库会在首次运行时自动初始化。

### 现代技术栈（2026）
使用最新稳定版本构建：
- **Python 3.12+**：现代语言特性和性能改进
- **SQLite3**：零配置、无服务器、自包含的数据库引擎
- **Matplotlib 3.9+**：高级数据可视化功能
- **NumPy 2.0+**：高性能数值计算

### 生产级代码质量
- **类型提示**：完整的类型注解，提供更好的 IDE 支持和代码可靠性
- **安全优先**：参数化查询防止 SQL 注入
- **错误处理**：全面的异常处理和信息丰富的错误消息
- **自动化测试**：包含数据库操作和 GUI 组件的测试套件

### 开发者友好的文档
- **完整设置指南**：包含故障排除的分步安装说明
- **代码注释**：函数带有详细的文档字符串
- **安全指导**：清晰解释安全措施和限制
- **架构文档**：快速理解项目结构

<p align="right">(<a href="#top">返回顶部</a>)</p>

## 界面截图

应用程序界面预览：

<table>
    <tr>
        <td>
            <img src="assets/Readme-assets/screenshots/login.png" alt="登录界面" />
            <br />
            <p align="center">登录</p></td>
        <td>
            <img src="assets/Readme-assets/screenshots/dashboard.png" alt="仪表板" />
            <br />
            <p align="center">仪表板</p></td>
    </tr>
    <tr>
        <td>
            <img src="assets/Readme-assets/screenshots/add-reservations.png" alt="添加预订页面" />
            <br />
            <p align="center">添加预订页面</p></td>
        <td>
            <img src="assets/Readme-assets/screenshots/update-reservations.png" alt="更新预订界面" />
            <br />
            <p align="center">更新预订</p></td>
    </tr>
    <tr>
        <td>
            <img src="assets/Readme-assets/screenshots/view-reservations.png" alt="查看预订界面" />
            <br />
            <p align="center">查看预订</p></td>
        <td>
            <img src="assets/Readme-assets/screenshots/logout.png" alt="确认登出" />
            <br />
            <p align="center">确认登出</p></td>
    </tr>
    <tr>
        <td colspan="2">
            <img src="assets/Readme-assets/screenshots/about.png" alt="关于页面" />
            <br />
            <p align="center">关于页面</p></td>
    </tr>
</table>

想要创建自己的版本？[在 Figma 上查看设计](https://www.figma.com/file/MVq5Q3fhVJB2r70r7I3nJ3/HotinGo?node-id=102%3A2)，然后使用 [Tkinter Designer](https://github.com/ParthJadhav/Tkinter-Designer) 导出为 Python 代码。

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- Motivation -->

## 项目动机

该项目最初是作为 12 年级计算机科学项目创建的。为了让它在其他项目中脱颖而出，付出了额外的努力，由于它从未打算在实际生活中使用，因此实用性并不是最关心的问题。

<details>
    <summary>更多信息...</summary>
    <p>根据印度中央教育委员会（CBSE）的规定，选修信息实践课程的学生需要通过创建一个应用程序来展示他们对 Python 和 MySQL 的知识，该应用程序将在年底由来自其他学校的考官/教师进行评估，从而确定高中的最终成绩。因此，该应用程序是我们团队努力、耐力和奉献精神的结晶。您可以通过提交历史记录看到我们从哪里开始，项目如何停滞，然后我们如何将项目发展到今天的样子。</p>
</details>

<p align="right">(<a href="#top">返回顶部</a>)</p>

## 技术栈

项目使用的技术栈：

-   [Python 3](https://python.org/) 🐍 - 现代编程语言（2026 最新稳定版：3.12+）
-   [Tkinter](https://docs.python.org/3/library/tk.html/) & [TTk](https://docs.python.org/3/library/tkinter.ttk.html) - Python 内置的 GUI 框架，用于创建用户界面
-   [SQLite3](https://www.sqlite.org/) 📦 - 零配置嵌入式数据库引擎（无需服务器）
-   [Tkinter Designer](https://github.com/ParthJadhav/Tkinter-Designer) ☄️ - 将 Figma 用户界面导出为 Python 代码
-   [Numpy](https://numpy.org/) 🧮 - 高性能数值计算库（v2.0+）
-   [Matplotlib](https://matplotlib.org/) 📈 - 高级数据可视化和图表创建（v3.9+）
-   [Python Dotenv](https://github.com/theskumar/python-dotenv) 🤫 - 从 [`.env` 文件](https://zetcode.com/javascript/dotenv/)管理环境变量

### 为什么选择 SQLite3？

SQLite3 是此应用程序的完美选择，因为：
- **零配置**：无需安装或配置数据库服务器
- **自包含**：整个数据库在一个文件中
- **跨平台**：在 Windows、macOS 和 Linux 上工作方式相同
- **嵌入式**：内置在 Python 标准库中
- **ACID 兼容**：完整的事务支持和回滚功能
- **快速**：针对本地操作进行优化
- **可移植**：复制 `.db` 文件即可备份或传输整个数据库

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- GETTING STARTED -->

# 快速开始

按照以下说明设置您自己的 HotinGo 实例。设置过程简单明了，只需几分钟。

## 前置要求

开始之前，请确保已安装以下内容：

-   **Python 3.8+**（推荐：Python 3.12+）- [下载说明](https://www.python.org/downloads/)
-   **Pip 3**（通常随 Python 自动安装）

验证安装，运行：
```sh
python --version
pip --version
```

如果两个命令都返回版本号，则可以继续。

## 安装步骤

### 步骤 1：克隆仓库

将仓库克隆到本地：

```sh
git clone https://gitee.com/Lyong9102/hotingo.git
cd hotingo
```

**预期输出**：您应该看到 Git 克隆仓库并创建一个新的 `hotingo` 目录。

### 步骤 2：创建虚拟环境（推荐）

创建虚拟环境以隔离项目依赖项：

**Windows：**
```sh
python -m venv venv
venv\Scripts\activate
```

**macOS/Linux：**
```sh
python3 -m venv venv
source venv/bin/activate
```

**预期输出**：终端提示符应在开头显示 `(venv)`。

### 步骤 3：安装依赖项

安装所有必需的包：

```sh
pip install -r requirements.txt
```

**预期输出**：
```
Successfully installed matplotlib-3.9.1 numpy-2.0.1 python-dotenv-1.0.1
```

这将安装：
- `matplotlib` - 数据可视化和图表
- `numpy` - 数值运算（matplotlib 需要）
- `python-dotenv` - 环境变量管理

### 步骤 4：安装字体（可选但推荐）

为获得最佳视觉体验，请安装 Montserrat 字体系列：

1. 导航到 `assets` 文件夹
2. 双击每个 `.ttf` 字体文件
3. 在字体预览窗口中点击"安装"

**注意**：在某些系统上，您可能需要管理员权限来安装字体。

### 步骤 5：配置环境变量（可选）

应用程序使用合理的默认值，可以立即工作。要自定义：

1. 复制示例环境文件：
   ```sh
   cp .env.example .env
   ```

2. 编辑 `.env` 以自定义设置（可选）：
   ```
   DB_PATH=./hms.db
   ```

**注意**：默认情况下，数据库路径相对于项目根目录。

### 步骤 6：运行应用程序

启动 HotinGo：

```sh
python main.py
```

**预期输出**：
```
============================================================
HotinGo - Hotel Management System
============================================================
Python Version: 3.12.0
Checking dependencies...
All dependencies are installed.

Database Path: C:\Users\...\HotinGo\hms.db
Database found. Connecting to existing database.

============================================================
Startup checks complete. Launching application...
============================================================
```

登录窗口将自动出现。

**默认凭据**：
- 用户名：`username`
- 密码：`password`

<p align="right">(<a href="#top">返回顶部</a>)</p>

## 故障排除

### 缺少依赖项错误

如果看到"缺少必需的依赖项"，请确保已激活虚拟环境并运行：
```sh
pip install -r requirements.txt
```

如果特定包失败，请单独安装：
```sh
pip install matplotlib
pip install numpy
pip install python-dotenv
```

### 数据库初始化失败

1. 验证项目目录中存在 `sql/hms_sqlite.sql`
2. 检查您是否对项目文件夹有写权限
3. 如果 `hms.db` 存在但已损坏，请删除它并重新启动应用程序：
   ```sh
   rm hms.db  # Windows: del hms.db
   python main.py
   ```

### 字体渲染问题

如果界面看起来不正确：
1. 从 `assets` 文件夹安装 Montserrat 字体
2. 安装字体后重新启动应用程序
3. 在某些系统上，您可能需要重新启动计算机

### 应用程序无法启动

1. 验证 Python 版本（必须是 3.8 或更高版本）：
   ```sh
   python --version
   ```

2. 确保您在正确的目录中：
   ```sh
   ls main.py  # Windows: dir main.py
   ```
   您应该看到文件列出。

3. 检查控制台输出以获取特定错误消息并参考错误详细信息。

### 仍然有问题？

1. 查看 [Gitee 上的现有问题](https://gitee.com/Lyong9102/hotingo/issues)
2. 创建新问题，包含：
   - 准确的错误消息
   - 您的 Python 版本（`python --version`）
   - 您的操作系统
   - 您已尝试的步骤

<p align="right">(<a href="#top">返回顶部</a>)</p>

## 附加功能

以下是您可以尝试的一些功能

### 数据库备份

由于应用程序使用 SQLite3，备份数据非常简单：
- 只需将 `hms.db` 文件复制到安全位置
- 要还原，用备份副本替换 `hms.db` 文件

### 添加新用户

要添加新的登录凭据，您需要直接将记录插入数据库的 `login` 表。您可以使用任何 SQLite 浏览器（如 [DB Browser for SQLite](https://sqlitebrowser.org/)）或运行 SQL 命令：

```sql
INSERT INTO login (username, password) VALUES ("your-username", "your-password");
```

**安全注意事项**：此版本以明文形式存储密码（请参阅[安全性说明](#安全性说明)）。对于生产使用，应对密码进行哈希处理。

**为什么没有注册页面？** 这是一个面向管理员的应用程序。添加公共注册页面会通过允许未经授权的访问来损害安全性。以前的版本包含注册/重置功能，但已删除以维护仅限管理员访问模式。

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- SECURITY -->

# 安全性说明

HotinGo 实施了多种安全措施来保护您的酒店数据。但是，作为教育项目，需要注意一些重要的安全考虑因素：

## 已实施的安全措施

### SQL 注入防护
所有数据库查询使用**参数化语句**（预处理语句）来防止 SQL 注入攻击。用户输入永远不会直接连接到 SQL 查询中。

```python
# 安全：使用参数化查询
cursor.execute("SELECT * FROM guests WHERE name = ?", (user_input,))

# 不安全：直接字符串连接（本项目中未使用）
# cursor.execute(f"SELECT * FROM guests WHERE name = '{user_input}'")
```

### 数据库文件权限
在基于 Unix 的系统（Linux、macOS）上，应用程序自动为数据库文件设置限制性权限：
- 文件权限：`0600`（仅所有者可读/写）
- 这可以防止系统上的其他用户访问数据库

**Windows 用户**：使用 NTFS 文件权限将 `hms.db` 文件的访问权限限制为仅授权用户。

### 环境变量保护
敏感配置存储在 `.env` 文件中，该文件：
- 通过 `.gitignore` 从版本控制中排除
- 永远不应提交到 Git 仓库
- 应具有受限的读取权限（Unix：`chmod 600 .env`）

## 已知的安全限制

### 密码存储
**⚠️ 重要安全说明**：此版本在数据库中以**明文**形式存储密码。这是一个已知的限制，仅适用于教育目的。

**对于生产使用**，应使用 bcrypt 或类似方法对密码进行哈希处理：
```python
# 未来改进（参见问题 #2）
import bcrypt
hashed = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt())
```

请参阅[问题 #2](https://gitee.com/Lyong9102/hotingo/issues/2)了解计划的改进。

### 访问控制
- 该应用程序专为单用户管理员访问而设计
- 未实施基于角色的访问控制（RBAC）
- 所有经过身份验证的用户都具有完整的系统访问权限

## 安全最佳实践

### 保护您的 .env 文件
1. 永远不要将 `.env` 提交到版本控制
2. 设置限制性权限：
   ```bash
   # Unix/Linux/macOS
   chmod 600 .env
   ```
3. 为任何机密使用强大、唯一的值
4. 创建一个 `.env.example` 文件（不包含实际机密）以供文档使用

### 数据库备份安全
备份数据库时：
- 将备份存储在具有受限访问权限的安全位置
- 如果在异地或云存储中存储，请加密备份
- 请记住，备份包含明文密码
- 定期测试备份还原过程

### 部署建议
如果部署此应用程序：
- 仅在受信任、受控的环境中使用
- 实施额外的身份验证层（VPN、防火墙规则）
- 监控数据库访问日志
- 考虑实施 bcrypt 密码哈希（请参阅路线图）
- 保持 Python 和所有依赖项最新

### 报告安全问题
如果您发现安全漏洞，请负责任地报告：
- **不要**公开问题
- 直接联系维护者（请参阅[联系方式](#联系方式)部分）
- 提供有关漏洞的详细信息
- 在公开披露之前留出时间进行修复

请参阅 [SECURITY.md](SECURITY.md) 了解更多详细信息。

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- ROADMAP -->

# 路线图

-   [x] ~~添加注册和忘记密码功能~~ ([问题 #3](https://gitee.com/Lyong9102/hotingo/issues/3))
-   [ ] 为密码添加 bcrypt 哈希 ([问题 #2](https://gitee.com/Lyong9102/hotingo/issues/2))

请参阅[开放问题](https://gitee.com/Lyong9102/hotingo/issues)获取完整的建议功能列表（和已知问题）。

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- CONTRIBUTING -->

# 贡献

贡献使开源社区成为学习、启发和创造的绝佳场所。非常感谢您所做的任何贡献。

如果您有建议可以改进此项目，请 fork 仓库并创建拉取请求。您也可以简单地使用"增强"标签打开一个问题。
不要忘记给项目加星！再次感谢！

1. Fork 项目
2. 创建您的功能分支（`git checkout -b feature/AmazingFeature`）
3. 提交您的更改（`git commit -m '添加一些 AmazingFeature'`）
4. 推送到分支（`git push origin feature/AmazingFeature`）
5. 打开一个拉取请求

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- LICENSE -->

# 许可证

根据 MIT 许可证分发。有关更多信息，请参阅 [`LICENSE.txt`](/LICENSE.txt)。

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- CONTACT -->

# 联系方式

该项目由 Lyong9102 维护。如有问题、建议或贡献：

项目链接：[https://gitee.com/Lyong9102/hotingo](https://gitee.com/Lyong9102/hotingo)

原作者：Mohit Yadav - [@just_moh_it](https://twitter.com/just_moh_it) - mohit@mohit.yayy.me

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- ACKNOWLEDGMENTS -->

# 致谢

-   **Parth Jadhav 和团队**开发的出色的 [Tkinter Designer](https://github.com/ParthJadhav/Tkinter-Designer)。没有它，这个项目不会是现在的样子。强烈推荐查看。
-   [Nikuu 3d Illustration Pack by Paperpillar](https://www.figma.com/community/file/1000311109311441524) - 仪表板和登录页面上使用的插图
-   [Montserrat Font](https://fonts.google.com/specimen/Montserrat) 创作者

<p align="right">(<a href="#top">返回顶部</a>)</p>

<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

[contributors-shield]: https://img.shields.io/badge/contributors-2-blue.svg?style=for-the-badge
[last-commit-shield]: https://img.shields.io/badge/last%20commit-2026--06-green.svg?style=for-the-badge
[last-commit-url]: https://gitee.com/Lyong9102/hotingo/commits/main
[contributors-url]: https://gitee.com/Lyong9102/hotingo/contributors
[forks-shield]: https://gitee.com/Lyong9102/hotingo/badge/fork.svg?theme=dark&style=for-the-badge
[forks-url]: https://gitee.com/Lyong9102/hotingo/members
[stars-shield]: https://gitee.com/Lyong9102/hotingo/badge/star.svg?theme=dark&style=for-the-badge
[stars-url]: https://gitee.com/Lyong9102/hotingo/stargazers
[issues-shield]: https://img.shields.io/badge/issues-0%20open-brightgreen.svg?style=for-the-badge
[issues-url]: https://gitee.com/Lyong9102/hotingo/issues
[license-shield]: https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge
[license-url]: https://gitee.com/Lyong9102/hotingo/blob/main/LICENSE.txt
[logo]: assets/Readme-assets/logo-full.png