diff --git a/README.md b/README.md index 28dd55ab70bab18db3cc23f6d0f8172225a8b133..4e1cb5dd24dc9b55f6ffde1973e93d7a915701ec 100644 --- a/README.md +++ b/README.md @@ -1,201 +1,173 @@ -

组织logo.png

-

TopskyHotelManagementSystem-WebApi

-

- star - fork - - -

-
-

中文文档 | 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界面。 +# TopskyHotelManagementSystem-WebApi -### :mag_right: 系统开发环境： - -操作系统：Windows 11(x64) - -开发工具：Microsoft Visual Studio 2022(系统最新版本) - -数据库：MariaDB - -数据库管理工具：DbGate - -开发语言：C#语言、LINQ语言 - -开发平台：.Net - -开发框架：.Net 10 +
-开发技术：.NET 10 WebAPI +[![star](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/badge/star.svg?theme=white)](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/stargazers) +[![fork](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/badge/fork.svg?theme=white)](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/fork) +[![license](https://img.shields.io/badge/license-MIT-000000.svg)](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/blob/master/LICENSE) +[![language](https://img.shields.io/badge/language-CSharp-red.svg)](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api) -### :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 2022 (或 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，支持 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 ``` -| 参数名称 | 参数说明 | 必填(Y/N) | 默认值 | 可选值 | -|------|------|---------|-----|-----| -|name|容器名称|Y|N/A|N/A| -|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__ExpiryMinutes|token有效时间/分钟|Y|20|N/A| -|Lsky__Enabled|是否启用兰空图床集成|Y|false|true/false| -|Lsky__BaseAddress|兰空图床基础地址|Y|N/A|N/A| -|Lsky__Email|兰空图床账户邮箱|Y|N/A|N/A| -|Lsky__Password|兰空图床账户密码|Y|N/A|N/A| -|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__UserName|邮箱smtp协议地址|Y|N/A|N/A| -|Mail__Port|邮箱smtp端口|Y|465|N/A| -|Mail__Password|邮箱密码|Y|N/A|N/A| -|Mail__EnableSsl|是否启用SSL|Y|true|true/false| -|Mail__DisplayName|发送邮件人显示名称|Y|N/A|N/A| -|InitializeDatabase|初始化数据库|N|true|true/false| -|ExpirationSettings__NotifyDaysBefore|提前通知天数|Y|3|a few days| -|ExpirationSettings__CheckIntervalMinutes|通知检查间隔|Y|5|a few minutes| -|AllowedOrigins__0|允许域站点,用于开发环境|Y|http://localhost:8080|http://localhost:8080| -|AllowedOrigins__1|允许域站点,用于生产环境|Y|https://www.yourdomain.com|https://www.yourdomain.com| -|SoftwareVersion|软件版本号,用于标记说明|N|N/A|N/A| - - -### :inbox_tray: 数据库运行部署(本地)： - -**强烈推荐，以下第一种方式进行数据库部署** - -1.自动建库建表 -在appsettings.json填写对应的DefaultDatabase参数和对应的数据库链接字符串，然后保存运行项目即可一键自动建表建库(前提本地安装了对应的数据库和开启服务) - -2.手动建库建表(注意：文件夹内的数据库脚本可能非最新版本，因此推荐以上第一种方式!!!) -通过可视化管理工具打开/数据库脚本/xxx版本，依次执行tshotel-backstage-dbscript-table.sql文件进行数据库与数据表建立。 -随后打开tshotel-backstage-dbscript-data.sql文件进行数据导入。 - - - -​ [![咖啡与网络/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) +## 鸣谢 + +感谢以下优秀的开源项目： + +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)) + +## 项目作者 + +- **Jackson** (项目组长, 核心代码编写和后期项目整合) +- **Benjamin** (开发，项目代码编写) +- **Bin** (数据库支持) +- **易开元** (后期维护和开发) + +## 许可证 + +本项目基于 **MIT** 协议开源。免费开源，但请勿用于商业用途（具体请阅读 LICENSE 文件）。 \ No newline at end of file