From ccec9a6206aa0b3786a67f566e453b2ca55acbb6 Mon Sep 17 00:00:00 2001 From: ck_yeun9 Date: Tue, 3 Feb 2026 05:44:12 +0000 Subject: [PATCH 1/5] update README.md. Signed-off-by: ck_yeun9 --- README.md | 256 +++++++++++++++++++++++++++--------------------------- 1 file changed, 129 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index 28dd55a..8da91a8 100644 --- a/README.md +++ b/README.md @@ -10,149 +10,143 @@

中文文档 | English Document

- - - - -### :pray: 感谢以下开源项目： - -1. ##### Autofac——An addictive .NET IoC container。[Autofac, MIT开源协议](https://github.com/autofac/Autofac) - -2. ##### SqlSugar——国内最受欢迎ORM框架。 [SQLSugar, MIT开源协议](https://gitee.com/dotnetchina/SqlSugar) - -3. ##### Mailkit——A cross-platform .NET library for IMAP, POP3, and SMTP。[Mailkit, MIT开源协议](https://github.com/jstedfast/MailKit) - -4. ##### NSwag——The OpenAPI/Swagger API toolchain for .NET and TypeScript。[NSwag, MIT开源协议](https://github.com/NSwag/NSwag) - -5. ##### Newtonsoft.Json——Json.NET is a popular high-performance JSON framework for .NET。[Newtonsoft.Json, MIT开源协议](https://github.com/JamesNK/Newtonsoft.Json) - -6. ##### quartznet——Open-source job scheduling system for .NET。[Quartz.NET, Apache2.0开源协议](https://github.com/quartznet/quartznet) - - -### :exclamation: 本项目介绍： - -本项目是基于.Net10构建的TS酒店管理系统后端API项目，欢迎Start&Fork - -1、一切开发请遵照MIT开源协议进行。 - -2、有bug欢迎提出issue！ - -3、本项目当前已支持多数据库以及一键建库建表，具体代码可以参考InitializeDatabase方法。 - -4、本项目已基于SQL Sugar框架支持多数据库(主流)，以下是目前已通过测试的数据库表格： - -| 数据库 | 版本 | 支持建库建表(Y/N) | 通过(Y/N) | -| ---------- | ---------------- | ----------------- | ---------------------------------------------------- | -| MariaDB | 10.11.10-MariaDB | Y | Y | -| PostgreSQL | 130020 | Y | Y | -| MySQL | 5.7+ | Y | Y | -| SQL Server | 2022 | Y | Y | -| Oracle | Unknown | N | 请参照SQLSugar文档([果糖网](https://www.donet5.com)) | -| SQLite | Unknown | N | N | - -### :thought_balloon: 开发目的： - -主要用于现有的C/S项目酒店管理系统升级2.0后实现前后端分离的WebAPI接口，本项目不包含任何UI界面。 - -### :mag_right: 系统开发环境： - -操作系统：Windows 11(x64) - -开发工具：Microsoft Visual Studio 2022(系统最新版本) - -数据库：MariaDB - -数据库管理工具：DbGate - -开发语言：C#语言、LINQ语言 - -开发平台：.Net - -开发框架：.Net 10 - -开发技术：.NET 10 WebAPI - -### :open_file_folder: 系统结构： - -``` +## 项目简介 + +本项目是基于 **.NET 10** 构建的 **TS酒店管理系统** 后端 Web API 项目。采用 **C#** 语言编写，使用 **SqlSugar** ORM 框架，支持 **MariaDB**, **MySQL**, **PostgreSQL**, **SQL Server** 等多种数据库。 + +主要用于现有的 C/S 项目酒店管理系统升级 2.0 后实现前后端分离，提供完善的业务接口支持。本项目不包含前端 UI 界面，仅提供 RESTful API 服务。 + +## 核心功能特性 + +### 1. 业务管理模块 +- **房间管理**：支持房间状态（空房、已住、维修、脏房、预约）管理，入住、退房、换房，房间配置（类型、价格）。 +- **客户管理**：客户档案管理，客户账号注册登录，会员类型管理。 +- **预订管理**：客房预订，预订过期自动检测（基于 Quartz），支持邮件通知提醒。 +- **消费管理**：商品销售管理（库存），客房消费（水电费、住宿费），结算状态跟踪。 +- **员工管理**：员工档案管理，考勤打卡（上下班签到），奖惩记录，履历管理，证件照片管理。 +- **资产管理**：酒店固定资产管理（资产编号、价值、来源、经办人）。 +- **新闻公告**：酒店内部新闻发布，系统公告管理。 + +### 2. 系统管理模块 (RBAC) +- **管理员管理**：支持超级管理员，普通管理员，管理员类型。 +- **角色与权限**：基于角色的访问控制 (RBAC)，细粒度的权限分配（菜单权限、按钮权限）。 +- **菜单管理**：动态菜单配置，支持按角色构建菜单树。 +- **数据字典**：支持民族、学历、部门、职位、证件类型等基础数据维护。 + +### 3. 数据统计与监控 +- **管理驾驶舱 (Dashboard)**：提供房间状态统计（空/住/修/脏/预）、营业统计（会员性别比例、消费趋势日月年）、物资库存预警、员工考勤统计（出勤/迟到/旷工）。 +- **操作日志**：详细的 HTTP 请求日志（耗时、参数、IP）和业务操作日志记录。 +- **监管统计**：支持酒店内部监管数据的录入与查询。 + +### 4. 基础设施与安全 +- **多数据库支持**：通过 SqlSugar 实现无缝切换主流关系型数据库，支持一键初始化建库建表。 +- **安全机制**： + - **JWT**：安全的 Token 认证机制。 + - **CSRF**：防止跨站请求伪造攻击。 + - **Data Protection**：敏感数据（如身份证号、联系方式）使用 ASP.NET Core Data Protection API 加密存储。 + - **请求日志**：全局请求中间件，记录接口调用详情。 +- **定时任务**：使用 Quartz .NET 处理预订过期提醒邮件发送。 +- **第三方集成**： + - **邮件服务**：MailKit 集成，支持发送提醒邮件（HTML 模板）。 + - **图床服务**：兰空图床 (Lsky) 集成，用于图片上传托管。 + +## 技术栈 + +- **.NET 10**: 基础框架。 +- **C# 12**: 开发语言。 +- **SqlSugar**: ORM 框架（多租户/多数据库支持，高性能）。 +- **Autofac**: IoC 容器（依赖注入）。 +- **Quartz .NET**: 定时任务调度（处理过期预订）。 +- **MailKit**: 邮件发送库。 +- **NSwag**: API 文档生成（Swagger UI）。 +- **Newtonsoft.Json**: JSON 序列化库。 + +## 项目结构 + +项目采用分层架构设计，结构清晰，便于维护和扩展： + +```text EOM.TSHotelManagement.Web -├─ .git -├─ .gitignore -├─ EOM.TSHotelManagement.Service -│ ├─ EOM.TSHotelManagement.Service.csproj -├─ EOM.TSHotelManagement.Contract -│ ├─ EOM.TSHotelManagement.Contract.csproj -├─ EOM.TSHotelManagement.Domain -│ ├─ EOM.TSHotelManagement.Domain.csproj -├─ EOM.TSHotelManagement.Data -│ ├─ EOM.TSHotelManagement.Data.csproj -├─ EOM.TSHotelManagement.Migration -│ ├─ EOM.TSHotelManagement.Migration.csproj -├─ EOM.TSHotelManagement.Web.sln -├─ EOM.TSHotelManagement.API -│ ├─ Controllers -│ ├─ EOM.TSHotelManagement.API.csproj -│ ├─ EOM.TSHotelManagement.API.csproj.user -│ ├─ EOM.TSHotelManagement.API.xml -│ ├─ Program.cs -│ ├─ appsettings.Development.json -│ ├─ appsettings.json -├─ LICENSE -├─ README.en.md -└─ README.md +├─ EOM.TSHotelManagement.API # API 入口层 (Controllers, Middleware, Config) +├─ EOM.TSHotelManagement.Contract # 契约层 (DTO, Request/Response Models, Service Interfaces) +├─ EOM.TSHotelManagement.Domain # 领域层 (Entities, Domain Logic) +├─ EOM.TSHotelManagement.Service # 服务层 (Business Logic Implementation) +├─ EOM.TSHotelManagement.Data # 数据层 (DbContext, Repositories, Database Init) +├─ EOM.TSHotelManagement.Infrastructure # 基础设施层 (Config Models, Helpers, JWT Config) +├─ EOM.TSHotelManagement.Common # 公共层 (Utils, Constants, Enums, Email Templates) +└─ EOM.TSHotelManagement.Migration # 数据库迁移工具 ``` -### :chart_with_upwards_trend: 系统数据库关系图(由PDMAN软件生成) :loudspeaker: +## 数据库支持 -[数据库关系图](https://oscode.top/project/tshotel/db_design.html) +本项目已通过 SqlSugar 框架支持多数据库一键建库建表： -### :exclamation: 项目作者： +| 数据库 | 版本 | 支持建库建表 | 状态 | +| ---------- | ---------------- | :----------: | :--: | +| MariaDB | 10.11.10+ | ✅ | ✅ | +| PostgreSQL | 13+ | ✅ | ✅ | +| MySQL | 5.7+ | ✅ | ✅ | +| SQL Server | 2022+ | ✅ | ✅ | +| Oracle | - | ❌ | ❌ | +| SQLite | - | ❌ | ❌ | -**Jackson(即本账号，项目组长,核心代码编写和后期项目整合)** +## 快速开始 -**Benjamin(开发，项目代码编写)** +### 环境要求 +- .NET 10 SDK +- Runtime 10.x +- Visual Studio 2026 (或 VS Code + C# Dev Kit) -**Bin(数据库，提供数据库管理支持)** +### 本地运行 -**易开元(后期维护和开发)** +1. **克隆项目**： + ```bash + git clone https://gitee.com/java-and-net/topsky-hotel-management-system-web-api.git + ``` -### :computer: 项目运行部署(执行下面步骤前需先安装.NET 10 SDK和Runtime)： +2. **配置数据库**： + 修改 `EOM.TSHotelManagement.API/appsettings.json`： + ```json + { + "DefaultDatabase": "MariaDB", // 可选值: MariaDB, MySql, PgSql, SqlServer + "ConnectionStrings": { + "MariaDB": "Server=localhost;Database=tshoteldb;User=root;Password=123456;" + // ... + }, + "InitializeDatabase": true // ⚠️ 首次运行请设为 true 以自动创建数据库和表结构 + } + ``` -**下载并安装Microsoft Visual Studio Professional 2026及以上版本，并通过下载Zip包解压，打开.sln后缀格式文件运行。** +3. **配置密钥**： + 在 `appsettings.json` 中设置 `Jwt__Key` (用于生成 Token) 和 `DataProtection` 相关的 Key (用于数据加解密)。 -### :inbox_tray: Docker运行部署(以Ubuntu为例，参数需按实际进行填写)： +4. **运行项目**： + 使用 Visual Studio 打开 `EOM.TSHotelManagement.Web.sln` 并启动 `EOM.TSHotelManagement.API` 项目。 -``` +### Docker 部署 + +项目提供了 Dockerfile(亦可通过build.ps1文件快速构建镜像，前提需确保本地启用WSL2.0以及Hyper-V和安装Docker Desktop)，支持 Docker 容器化部署。API 默认监听 8080 端口。 + +```bash +# 请根据实际情况修改环境变量参数 docker run -d \ --name tshotel-api \ -v /app/config:/app/config \ -v /app/keys:/app/keys \ + -p 63001:8080 \ -e ASPNETCORE_ENVIRONMENT=docker \ -e DefaultDatabase=MariaDB \ - -e MariaDBConnectStr=Server=yourdatabase;Database=tshoteldb;User=tshoteldb;Password=yourdatabasepassword; \ + -e MariaDBConnectStr="Server=your_db_host;Database=tshoteldb;User=tshoteldb;Password=your_password;" \ -e InitializeDatabase=true \ - -e Jwt__Key=your_key \ + -e Jwt__Key=your_super_secret_key \ -e Jwt__ExpiryMinutes=20 \ - -e Lsky__Enabled=true \ - -e Lsky__BaseAddress=https://yourdomain.com/api/v1 \ - -e Lsky__Email=domain@domain.com \ - -e Lsky__Password=your_password \ - -e Lsky__UploadApi=/upload \ - -e Lsky__GetTokenApi=/tokens \ -e Mail__Enabled=true \ - -e Mail__Host=smtp.domain.com \ - -e Mail__UserName=domain@domain.com \ - -e Mail__Password=your_password \ + -e Mail__Host=smtp.example.com \ + -e Mail__UserName=admin@example.com \ + -e Mail__Password=your_email_password \ -e Mail__Port=465 \ - -e Mail__EnableSsl=true \ - -e Mail__DisplayName=TSHotel-Administrator \ - -e ExpirationSettings__NotifyDaysBefore=3 \ - -e ExpirationSettings__CheckIntervalMinutes=5 \ - -e JobKeys__0=ReservationExpirationCheckJob \ -e AllowedOrigins__0=http://localhost:8080 \ -e AllowedOrigins__1=https://www.yourdomain.com \ - -e SoftwareVersion=2.2.8-202601101804 \ - -p 63001:8080 \ yjj6731/tshotel-management-system-api:latest ``` @@ -162,7 +156,7 @@ docker run -d \ |DefaultDatabase|默认数据库|Y|N/A|MariaDB/MySql/SqlServer/PgSql| |ASPNETCORE_ENVIRONMENT|系统环境(决定Dataprotection Key的生成位置以及环境判断)|Y|docker|docker| |{默认数据库(e.g:MariaDB/MySql/SqlServer/PgSql)}ConnectStr|对应数据库链接字符串|Y|N/A|N/A| -|Jwt__Key|JWT Key|Y|N/A|N/A| +|Jwt__Key|JWT Key|Y|无，必须设置|N/A| |Jwt__ExpiryMinutes|token有效时间/分钟|Y|20|N/A| |Lsky__Enabled|是否启用兰空图床集成|Y|false|true/false| |Lsky__BaseAddress|兰空图床基础地址|Y|N/A|N/A| @@ -171,7 +165,7 @@ docker run -d \ |Lsky__UploadApi|兰空图床上传图片接口|Y|N/A|N/A| |Lsky__GetTokenApi|兰空图床获取tokens接口|Y|N/A|N/A| |Mail__Enabled|是否启用邮件服务|Y|true|true/false| -|Mail__Host|邮箱smtp协议地址|Y|N/A|N/A| +|Mail__Host|邮箱smtp协议地址|Y|smtp.example.com|N/A| |Mail__UserName|邮箱smtp协议地址|Y|N/A|N/A| |Mail__Port|邮箱smtp端口|Y|465|N/A| |Mail__Password|邮箱密码|Y|N/A|N/A| @@ -184,18 +178,26 @@ docker run -d \ |AllowedOrigins__1|允许域站点,用于生产环境|Y|https://www.yourdomain.com|https://www.yourdomain.com| |SoftwareVersion|软件版本号,用于标记说明|N|N/A|N/A| +## 鸣谢 + +感谢以下优秀的开源项目： -### :inbox_tray: 数据库运行部署(本地)： +1. **Autofac** - An addictive .NET IoC container. ([MIT](https://github.com/autofac/Autofac)) +2. **SqlSugar** - 国内最受欢迎ORM框架. ([MIT](https://gitee.com/dotnetchina/SqlSugar)) +3. **Mailkit** - A cross-platform .NET library for IMAP, POP3, and SMTP. ([MIT](https://github.com/jstedfast/MailKit)) +4. **NSwag** - The OpenAPI/Swagger API toolchain for .NET and TypeScript. ([MIT](https://github.com/NSwag/NSwag)) +5. **Quartz .NET** - Open-source job scheduling system for .NET. ([Apache 2.0](https://github.com/quartznet/quartznet)) -**强烈推荐，以下第一种方式进行数据库部署** +## 项目作者 -1.自动建库建表 -在appsettings.json填写对应的DefaultDatabase参数和对应的数据库链接字符串，然后保存运行项目即可一键自动建表建库(前提本地安装了对应的数据库和开启服务) +- **Jackson** (项目组长, 核心代码编写和后期项目整合) +- **Benjamin** (开发，项目代码编写) +- **Bin** (数据库支持) +- **易开元** (后期维护和开发) -2.手动建库建表(注意：文件夹内的数据库脚本可能非最新版本，因此推荐以上第一种方式!!!) -通过可视化管理工具打开/数据库脚本/xxx版本，依次执行tshotel-backstage-dbscript-table.sql文件进行数据库与数据表建立。 -随后打开tshotel-backstage-dbscript-data.sql文件进行数据导入。 +## 许可证 +本项目基于 **MIT** 协议开源。免费开源，但请勿用于商业用途（具体请阅读 LICENSE 文件）。 ​ [![咖啡与网络/TopskyHotelManagementSystem-WebApi](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/java-and-net/topsky-hotel-manager-system-web-api) -- Gitee From 551feaa4bc4b0e19bae0c89ae886e7da5348be72 Mon Sep 17 00:00:00 2001 From: ck_yeun9 Date: Tue, 3 Feb 2026 05:51:45 +0000 Subject: [PATCH 2/5] update README.en.md. Signed-off-by: ck_yeun9 --- README.en.md | 301 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 187 insertions(+), 114 deletions(-) diff --git a/README.en.md b/README.en.md index 3391ec4..8189df7 100644 --- a/README.en.md +++ b/README.en.md @@ -1,4 +1,4 @@ -

Organization logo.png

+

组织logo.png

TopskyHotelManagementSystem-WebApi

star @@ -10,120 +10,193 @@

中文文档 | English Document

- - -### :pray: Thanks to the following open source projects: - -1. ##### Autofac——An addictive .NET IoC container. [Autofac, MIT License](https://github.com/autofac/Autofac) - -2. ##### SqlSugar——.Net aot ORM Fastest ORM Simple Easy Sqlite orm Oracle ORM Mysql Orm postgresql ORm SqlServer oRm 达梦 ORM 人大金仓 ORM 神通ORM C# ORM , C# ORM .NET ORM NET5 ORM .NET6 ORM ClickHouse orm QuestDb ,TDengine ORM,OceanBase orm,GaussDB orm ,Tidb orm Object/Relational Mapping. [SQLSugar, MIT License](https://github.com/DotNetNext/SqlSugar) - -3. ##### Mailkit——A cross-platform .NET library for IMAP, POP3, and SMTP。[Mailkit,MIT License](https://github.com/jstedfast/MailKit) - -4. ##### Swashbuckle.AspNetCore——Swagger tools for documenting API's built on ASP.NET Core。[SwaggerUI,MIT License](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) - -5. ##### Newtonsoft.Json——Json.NET is a popular high-performance JSON framework for .NET。[Newtonsoft.Json,MIT License](https://github.com/JamesNK/Newtonsoft.Json) - -6. ##### quartznet——Open-source job scheduling system for .NET。[Quartz.NET,Apache2.0 License](https://github.com/quartznet/quartznet) - -### :exclamation: About this project: - -This project is a TS hotel management system backend API project built on .Net10, welcome to Star & Fork. - -1. All development should comply with the MIT open source license. -2. If you find bugs, feel free to raise an issue! -3. The project currently supports multiple databases and automated database/table creation. For implementation details, refer to the `InitializeDatabase` method. -4. This project has implemented multi-database support (mainstream) based on the SQL Sugar framework. Below is the list of currently tested and verified database compatibility tables: - - | Database | Version | Support Create Table(Y/N) | Pass(Y/N) | - | ---------- | ---------------- | -------------------------- | ------------------------------------------------------------ | - | MariaDB | 10.11.10-MariaDB | Y | Y | - | PostgreSQL | 130020 | Y | Y | - | MySQL | 5.7+ | Y | Y | - | SQL Server | 2022 | Y | Y | - | Oracle | Unknown | N | Reference SQLSugar Document([SQLSugar](https://www.donet5.com)) | - | SQLite | Unknown | N | N | - -### :thought_balloon: Development purpose: - -Mainly for upgrading the existing C/S project hotel management system to version 2.0 to achieve a WebAPI interface that separates the front end from the back end. This project does not include any UI interface. - -### :mag_right: System development environment: - -Operating System: Windows 11(x64) - -Development Tool: Microsoft Visual Studio 2022 (latest version of the system) - -Database: MariaDB - -Database Management Tool: DbGate - -Programming Language: C# language, LINQ language - -Development Platform: .Net - -Development Framework: .Net 10 - -Development Technology: .NET 10 WebAPI - -### :open_file_folder: System structure: - -``` +## Project Overview + +This project constitutes the backend Web API component for the **TS Hotel Management System**, developed using **.NET 10**. Written in **C#** and utilising the **SqlSugar** ORM framework, it supports multiple databases including **MariaDB**, **MySQL**, **PostgreSQL**, and **SQL Server**. + +Primarily designed to achieve front-end/back-end separation following the upgrade to version 2.0 of an existing client/server hotel management system, it provides comprehensive business interface support. This project excludes front-end UI components, delivering solely RESTful API services. + +## Core Functional Features + +### 1. Business Management Modules +- **Room Management**: Supports room status management (Vacant, Occupied, Under Maintenance, Dirty, Reserved), check-in/check-out, room transfers, and configuration (type, pricing). +- **Guest Management**: Guest profile management, account registration/login, membership tier administration. +- **Reservation Management**: Handles room bookings, automatic detection of expired reservations (Quartz-based), and email notification alerts. +- **Consumption Management**: Manages merchandise sales (including inventory), room charges (utilities, accommodation fees), and settlement status tracking. +- **Staff Management**: Oversees employee records, attendance tracking (clocking in/out), reward/disciplinary records, CV management, and ID photo storage. +- **Asset Management**: Hotel fixed asset management (asset ID, value, origin, handler). +- **News & Announcements**: Internal hotel news publishing, system announcement management. + +### 2. System Management Module (RBAC) +- **Administrator Management**: Supports super administrators, regular administrators, administrator types. +- **Roles and Permissions**: Role-Based Access Control (RBAC), granular permission allocation (menu permissions, button permissions). +- **Menu Management**: Dynamic menu configuration, supports role-based menu tree construction. +- **Data Dictionary**: Supports maintenance of foundational data such as ethnicity, educational background, department, position, ID type, etc. + +### 3. Data Statistics and Monitoring +- **Management Dashboard**: Provides room status statistics (Vacant/Occupied/Under Maintenance/Uncleaned/Reserved), operational metrics (member gender ratio, monthly/annual consumption trends), inventory alerts, and staff attendance records (attendance/late arrivals/absenteeism). +- **Operational Logs**: Detailed HTTP request logs (duration, parameters, IP) and business operation logs. +- **Supervisory Statistics**: Facilitates entry and querying of internal hotel oversight data. + +### 4. Infrastructure and Security +- **Multi-Database Support**: Enables seamless switching between mainstream relational databases via SqlSugar, with one-click database and table initialisation. +- **Security Mechanisms**: + - **JWT**: Secure token authentication mechanism. + - **CSRF**: Prevents cross-site request forgery attacks. + - **Data Protection**: Sensitive data (e.g., ID numbers, contact details) encrypted and stored using ASP.NET Core Data Protection API. + - **Request Logging**: Global request middleware records API call details. +- **Scheduled Tasks**: Utilises Quartz .NET to process scheduled expiry reminder email dispatches. +- **Third-Party Integrations**: + - **Email Service**: MailKit integration for sending reminder emails (HTML templates). + - **Image Hosting Service**: Lsky integration for image uploads and hosting. + +## Technology Stack + +- **.NET 10**: Foundational framework. +- **C# 12**: Development language. +- **SqlSugar**: ORM framework (multi-tenant/multi-database support, high performance). +- **Autofac**: IoC container (dependency injection). +- **Quartz .NET**: Scheduled task management (handling expired reservations). +- **MailKit**: Email sending library. +- **NSwag**: API documentation generation (Swagger UI). +- **Newtonsoft.Json**: JSON serialisation library. + +## Project Structure + +The project employs a layered architecture design, featuring a clear structure that facilitates maintenance and extensibility: + +```text EOM.TSHotelManagement.Web -├─ .git -├─ .gitignore -├─ EOM.TSHotelManagement.Service -│ ├─ EOM.TSHotelManagement.Service.csproj -├─ EOM.TSHotelManagement.Contract -│ ├─ EOM.TSHotelManagement.Contract.csproj -├─ EOM.TSHotelManagement.Domain -│ ├─ EOM.TSHotelManagement.Domain.csproj -├─ EOM.TSHotelManagement.Data -│ ├─ EOM.TSHotelManagement.Data.csproj -├─ EOM.TSHotelManagement.Migration -│ ├─ EOM.TSHotelManagement.Migration.csproj -├─ EOM.TSHotelManagement.Web.sln -├─ EOM.TSHotelManagement.API -│ ├─ Controllers -│ ├─ EOM.TSHotelManagement.API.csproj -│ ├─ EOM.TSHotelManagement.API.csproj.user -│ ├─ EOM.TSHotelManagement.API.xml -│ ├─ Program.cs -│ ├─ appsettings.Development.json -│ ├─ appsettings.json -├─ LICENSE -├─ README.en.md -└─ README.md +├─ EOM.TSHotelManagement.API # API entry layer (Controllers, Middleware, Config) +├─ EOM.TSHotelManagement.Contract # Contract layer (DTO, Request/Response Models, Service Interfaces) +├─ EOM.TSHotelManagement.Domain # Domain layer (Entities, Domain Logic) +├─ EOM.TSHotelManagement.Service # Service Layer (Business Logic Implementation) +├─ EOM.TSHotelManagement.Data # Data Layer (DbContext, Repositories, Database Init) +├─ EOM.TSHotelManagement.Infrastructure # Infrastructure Layer (Config Models, Helpers, JWT Config) +├─ EOM.TSHotelManagement.Common # Common Layer (Utils, Constants, Enums, Email Templates) +└─ EOM.TSHotelManagement.Migration # Database Migration Tool ``` -### :chart_with_upwards_trend: System database relationship diagram (generated by PDMAN software) :loudspeaker: - -[Database Relationship Diagram](https://oscode.top/project/tshotel/db_design.html) - -### :exclamation: Project authors: - -**Jackson (i.e., this account, project leader, core code writing, and later project integration)** - -**Benjamin (Developer, project code writing)** - -**Bin (Database, providing database management support)** - -**Easy-Open-Meta (late maintenance and development)** - -### :computer: Project deployment (before executing the steps below, you need to install .NET 10 SDK and Runtime): - -**Download and install Microsoft Visual Studio Professional 2026 or above version, unzip the Zip package, and run the file with .sln suffix to start.** - -### :inbox_tray: Database deployment (local): - -**Strongly Recommended: Use the First Method for Database Deployment** - -**1.Automated Database & Table Creation** -Fill in the `DefaultDatabase` parameter and corresponding connection string in `appsettings.json`, then run the project. This will automatically create the database and tables with one click. -*Prerequisite: The local database must be installed and running.* - -**2.Manual Database & Table Creation(Note: Database scripts in the folder may not be the latest version. We strongly recommend Method 1 above!!!)** -Use a visual management tool to open `/Database Scripts/xxxVersion/`, then execute the `tshotel-backstage-dbscript-table.sql` file to create the database and tables. -Next, open the `tshotel-backstage-dbscript-data.sql` file to import initial data. +## Database Support + +This project utilises the SqlSugar framework to support one-click database and table creation across multiple databases: + +| Database | Version | Supported Database/Table Creation | Status | +| ---------- | ---------------- | :----------: | :--: | +| MariaDB | 10.11.10+ | ✅ | ✅ | +| PostgreSQL | 13+ | ✅ | ✅ | +| MySQL | 5.7+ | ✅ | ✅ | +| SQL Server | 2022+ | ✅ | ✅ | +| Oracle | - | ❌ | ❌ | +| SQLite | - | ❌ | ❌ | + +## Quick Start + +### Environment Requirements +- .NET 10 SDK +- Runtime 10.x +- Visual Studio 2026 (or VS Code + C# Dev Kit) + +### Running Locally + +1. **Clone the project**: + ```bash + git clone https://gitee.com/java-and-net/topsky-hotel-management-system-web-api.git + ``` + +2. **Configure the database**: + Modify `EOM.TSHotelManagement.API/appsettings.json`: + ```json + { + ‘DefaultDatabase’: ‘MariaDB’, // Optional values: MariaDB, MySql, PgSql, SqlServer + ‘ConnectionStrings’: { + ‘MariaDB’: ‘Server=localhost;Database=tshoteldb;User=root;Password=123456;’ + // ... + }, + ‘InitialiseDatabase’: true // ⚠️ Set to true on first run to automatically create database and table structure + } + ``` + +3. **Configure Keys**: + Set `Jwt__Key` (for token generation) and `DataProtection`-related keys (for data encryption/decryption) in `appsettings.json`. + +4. **Running the Project**: + Open `EOM.TSHotelManagement.Web.sln` in Visual Studio and start the `EOM.TSHotelManagement.API` project. + +### Docker Deployment + +The project provides a Dockerfile (alternatively, images can be rapidly built via the `build.ps1` script, provided WSL 2.0 and Hyper-V are enabled locally and Docker Desktop is installed), supporting Docker containerised deployment. The API listens on port 8080 by default. + +```bash +# Please modify environment variable parameters according to your actual setup +docker run -d \ + --name tshotel-api \ + -v /app/config:/app/config \ + -v /app/keys:/app/keys \ + -p 63001:8080 \ + -e ASPNETCORE_ENVIRONMENT=docker \ + -e DefaultDatabase=MariaDB \ + -e MariaDBConnectStr="Server=your_db_host;Database=tshoteldb;User=tshoteldb;Password=your_password;" \ + -e InitializeDatabase=true \ + -e Jwt__Key=your_super_secret_key \ + -e Jwt__ExpiryMinutes=20 \ + -e Mail__Enabled=true \ + -e Mail__Host=smtp.example.com \ + -e Mail__UserName=admin@example.com \ + -e Mail__Password=your_email_password \ + -e Mail__Port=465 \ + -e AllowedOrigins__0=http://localhost:8080 \ + -e AllowedOrigins__1=https://www.yourdomain.com \ + yjj6731/tshotel-management-system-api:latest +``` - [![咖啡与网络/TopskyHotelManagementSystem-WebApi](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/java-and-net/topsky-hotel-manager-system-web-api) +| Parameter Name | Parameter Description | Required (Y/N) | Default Value | Available Values | +|------|------|---------|-----|-----| +|name|Container Name|Y|N/A|N/A| +|DefaultDatabase|Default Database|Y|N/A|MariaDB/MySQL/SQL Server/PostgreSQL| +|ASPNETCORE_ENVIRONMENT|System Environment (determines Dataprotection Key generation location and environment detection)|Y|docker|docker| +|{Default Database (e.g.: MariaDB/MySQL/SQL Server/PostgreSQL)}ConnectStr|Corresponding Database Connection String|Y|N/A|N/A| +|Jwt__Key|JWT Key|Y|None, must be set|N/A| +|Jwt__ExpiryMinutes|Token Validity Period (Minutes)|Y|20|N/A| +|Lsky__Enabled|Enable Lsky image hosting integration|Y|false|true/false| +|Lsky__BaseAddress|Lsky image hosting base address|Y|N/A|N/A| +|Lsky__Email|Lsky account email|Y|N/A|N/A| +|Lsky__Password|Lsky account password|Y|N/A|N/A| +|Lsky__UploadApi|Lsky Image Hosting Upload Interface|Y|N/A|N/A| +|Lsky__GetTokenApi|Lsky Image Hosting Token Retrieval Interface|Y|N/A|N/A| +|Mail__Enabled|Enable email service|Y|true|true/false| +|Mail__Host|Email SMTP protocol address|Y|smtp.example.com|N/A| +|Mail__UserName|Email SMTP protocol address|Y|N/A|N/A| +|Mail__Port|Email SMTP port|Y|465|N/A| +|Mail__Password|Email password|Y|N/A|N/A| +|Mail__EnableSsl|Enable SSL|Y|true|true/false| +|Mail__DisplayName|Sender display name|Y|N/A|N/A| +|InitializeDatabase|Initialise database|N|true|true/false| +|ExpirationSettings__NotifyDaysBefore|Days Before Expiration Notification|Y|3|a few days| +|ExpirationSettings__CheckIntervalMinutes|Notification Check Interval|Y|5|a few minutes| +|AllowedOrigins__0|Allowed Domain Sites (for Development Environments)|Y|http://localhost:8080|http://localhost:8080| +|AllowedOrigins__1|Allowed domain sites for production environment|Y|https://www.yourdomain.com|https://www.yourdomain.com| +|SoftwareVersion|Software version number for documentation purposes|N|N/A|N/A| + +## Acknowledgements + +We extend our gratitude to the following outstanding open-source projects: + +1. **Autofac** - An addictive .NET IoC container. ([MIT](https://github.com/autofac/Autofac)) +2. **SqlSugar** - China's most popular ORM framework. ([MIT](https://gitee.com/dotnetchina/SqlSugar)) +3. **Mailkit** - A cross-platform .NET library for IMAP, POP3, and SMTP. ([MIT](https://github.com/jstedfast/MailKit)) +4. **NSwag** - The OpenAPI/Swagger API toolchain for .NET and TypeScript. ([MIT](https://github.com/NSwag/NSwag)) +5. **Quartz .NET** - Open-source job scheduling system for .NET. ([Apache 2.0](https://github.com/quartznet/quartznet)) + +## Project Contributors + +- **Jackson** (Project Lead, core code author and later project integration) +- **Benjamin** (Development, project code authoring) +- **Bin** (Database Support) +- **Yi Kaiyuan** (Later Maintenance and Development) + +## Licence + +This project is open-sourced under the **MIT** licence. It is free and open-source, but please refrain from using it for commercial purposes (please read the LICENCE file for specifics). + +​ [![咖啡与网络/TopskyHotelManagementSystem-WebApi](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/java-and-net/topsky-hotel-manager-system-web-api) -- Gitee From c899fd77ee5d7303655a91214160467adc5ea80a Mon Sep 17 00:00:00 2001 From: ck_yeun9 Date: Tue, 3 Feb 2026 06:04:50 +0000 Subject: [PATCH 3/5] update README.en.md. Signed-off-by: ck_yeun9 --- README.en.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.en.md b/README.en.md index 8189df7..5183e92 100644 --- a/README.en.md +++ b/README.en.md @@ -131,6 +131,10 @@ The project provides a Dockerfile (alternatively, images can be rapidly built vi # Please modify environment variable parameters according to your actual setup docker run -d \ --name tshotel-api \ + --health-cmd="curl -f http://localhost:8080/health || exit 1" \ + --health-interval=30s \ + --health-timeout=10s \ + --health-retries=3 \ -v /app/config:/app/config \ -v /app/keys:/app/keys \ -p 63001:8080 \ @@ -178,6 +182,8 @@ docker run -d \ |AllowedOrigins__1|Allowed domain sites for production environment|Y|https://www.yourdomain.com|https://www.yourdomain.com| |SoftwareVersion|Software version number for documentation purposes|N|N/A|N/A| +> ⚠️ **Security Advisory**: In production environments, do not directly pass password-like parameters in plaintext via the `-e` flag. It is recommended to utilise Docker Secrets or environment variable injection tools (such as HashiCorp Vault) for protection. + ## Acknowledgements We extend our gratitude to the following outstanding open-source projects: -- Gitee From 9c41dc2aeaa7ce864a33a30100a0e497f5b243de Mon Sep 17 00:00:00 2001 From: ck_yeun9 Date: Tue, 3 Feb 2026 06:04:56 +0000 Subject: [PATCH 4/5] update README.md. Signed-off-by: ck_yeun9 --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 8da91a8..b18aed9 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,10 @@ EOM.TSHotelManagement.Web # 请根据实际情况修改环境变量参数 docker run -d \ --name tshotel-api \ + --health-cmd="curl -f http://localhost:8080/health || exit 1" \ + --health-interval=30s \ + --health-timeout=10s \ + --health-retries=3 \ -v /app/config:/app/config \ -v /app/keys:/app/keys \ -p 63001:8080 \ @@ -178,6 +182,8 @@ docker run -d \ |AllowedOrigins__1|允许域站点,用于生产环境|Y|https://www.yourdomain.com|https://www.yourdomain.com| |SoftwareVersion|软件版本号,用于标记说明|N|N/A|N/A| +> ⚠️ **安全提醒**：生产环境中请勿直接通过 `-e` 明文传入密码类参数，推荐使用 Docker Secrets 或环境变量注入工具（如 HashiCorp Vault）进行保护。 + ## 鸣谢 感谢以下优秀的开源项目： -- Gitee From 11dfae49c5c9a3f7b753005bdad8cf7bc60eff11 Mon Sep 17 00:00:00 2001 From: ck_yeun9 Date: Tue, 3 Feb 2026 06:15:37 +0000 Subject: [PATCH 5/5] update README.en.md. Signed-off-by: ck_yeun9 --- README.en.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.en.md b/README.en.md index 5183e92..0c69549 100644 --- a/README.en.md +++ b/README.en.md @@ -1,4 +1,4 @@ -

组织logo.png

+

Organization Logo.png

TopskyHotelManagementSystem-WebApi

star @@ -108,12 +108,12 @@ This project utilises the SqlSugar framework to support one-click database and t Modify `EOM.TSHotelManagement.API/appsettings.json`: ```json { - ‘DefaultDatabase’: ‘MariaDB’, // Optional values: MariaDB, MySql, PgSql, SqlServer - ‘ConnectionStrings’: { - ‘MariaDB’: ‘Server=localhost;Database=tshoteldb;User=root;Password=123456;’ + "DefaultDatabase": "MariaDB", // Optional values: MariaDB, MySql, PgSql, SqlServer + "ConnectionStrings": { + "MariaDB": "Server=localhost;Database=tshoteldb;User=root;Password=123456;" // ... }, - ‘InitialiseDatabase’: true // ⚠️ Set to true on first run to automatically create database and table structure + "InitializeDatabase": true // ⚠️ Set to true on first run to automatically create database and table structure } ``` @@ -199,10 +199,10 @@ We extend our gratitude to the following outstanding open-source projects: - **Jackson** (Project Lead, core code author and later project integration) - **Benjamin** (Development, project code authoring) - **Bin** (Database Support) -- **Yi Kaiyuan** (Later Maintenance and Development) +- **Easy Open Meta** (Later Maintenance and Development) ## Licence This project is open-sourced under the **MIT** licence. It is free and open-source, but please refrain from using it for commercial purposes (please read the LICENCE file for specifics). -​ [![咖啡与网络/TopskyHotelManagementSystem-WebApi](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/java-and-net/topsky-hotel-manager-system-web-api) +​ [![java-and-net/TopskyHotelManagementSystem-WebApi](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/widgets/widget_card.svg?colors=4183c4,ffffff,ffffff,e3e9ed,666666,9b9b9b)](https://gitee.com/java-and-net/topsky-hotel-manager-system-web-api) -- Gitee