diff --git a/README.md b/README.md index 28dd55ab70bab18db3cc23f6d0f8172225a8b133..dec36879e52c4f96a9c8db4f8a92c83967e3380e 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) +# TopskyHotelManagementSystem-WebApi +
-### :exclamation: 本项目介绍： +![Star](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/badge/star.svg?theme=white) +![Fork](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/badge/fork.svg?theme=white) +![License](https://img.shields.io/badge/license-MIT-000000.svg) +![Language](https://img.shields.io/badge/language-CSharp-red.svg) -本项目是基于.Net10构建的TS酒店管理系统后端API项目，欢迎Start&Fork +**TS酒店管理系统后端 API** -1、一切开发请遵照MIT开源协议进行。 +基于 .NET 10 构建的酒店管理系统后端接口。 -2、有bug欢迎提出issue！ +[English Document](./README.en.md) -3、本项目当前已支持多数据库以及一键建库建表，具体代码可以参考InitializeDatabase方法。 +
-4、本项目已基于SQL Sugar框架支持多数据库(主流)，以下是目前已通过测试的数据库表格： +## 1. 项目简介 (Introduction) -| 数据库 | 版本 | 支持建库建表(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 | +本项目是基于 **.NET 10** 构建的 **TS酒店管理系统 (Topsky Hotel Management System)** 的后端 Web API 部分。项目旨在实现现有 C/S 酒店管理系统的 2.0 升级，采用前后端分离架构，不包含前端 UI 界面。 -### :thought_balloon: 开发目的： +主要特性包括： +* **前后端分离**：提供标准 RESTful API。 +* **多数据库支持**：通过 SqlSugar ORM 支持主流数据库（MariaDB, MySQL, PostgreSQL, SQL Server 等）。 +* **自动化**：集成自动建库建表功能。 +* **定时任务**：使用 Quartz.NET 处理预约过期检查等任务。 +* **安全机制**：集成 JWT 认证、CSRF 防护及细粒度权限管理。 -主要用于现有的C/S项目酒店管理系统升级2.0后实现前后端分离的WebAPI接口，本项目不包含任何UI界面。 +## 2. 技术栈 (Tech Stack) -### :mag_right: 系统开发环境： +* **.NET 10**: 开发平台 +* **C# / LINQ**: 开发语言 +* **Autofac**: 依赖注入容器 (IoC) +* **SqlSugar**: ORM 框架 (多数据库支持) +* **MailKit**: 邮件发送库 +* **NSwag**: API 文档生成工具 (Swagger/OpenAPI) +* **Quartz.NET**: 定时任务调度 +* **Newtonsoft.Json**: JSON 序列化 -操作系统：Windows 11(x64) +感谢以上优秀的开源项目。 -开发工具：Microsoft Visual Studio 2022(系统最新版本) +## 3. 项目结构 (Project Structure) -数据库：MariaDB +项目采用标准的分层架构（Clean Architecture）： -数据库管理工具：DbGate +* `EOM.TSHotelManagement.API`：**表现层**。包含 Controllers、Filters、Middleware、配置入口。 +* `EOM.TSHotelManagement.Service`：**应用服务层**。处理业务逻辑。 +* `EOM.TSHotelManagement.Contract`：**契约层**。定义数据传输对象 (DTOs)，包括输入输出模型。 +* `EOM.TSHotelManagement.Domain`：**领域层**。定义实体 (Entities) 和业务模型。 +* `EOM.TSHotelManagement.Data`：**数据层**。实现仓储 (Repository) 模式，数据库初始化逻辑。 +* `EOM.TSHotelManagement.Infrastructure`：**基础设施层**。提供配置类、工具类等支持。 -开发语言：C#语言、LINQ语言 +## 4. 主要功能 (Features) -开发平台：.Net +### 4.1 核心业务 (Business) +* **房间管理 (Room)**：房间状态管理（空闲、已住、维修、脏房、预约）、房型配置、入住/退房/换房操作。 +* **预订管理 (Reservation)**：预订信息录入、预订过期自动检查（通过 Quartz 任务）、入住登记。 +* **客户管理 (Customer)**：客户档案、证件类型管理、会员类型与规则、消费记录、账户登录（支持 JWT）。 +* **消费管理 (Spend)**：客房商品销售、消费流水、结算状态管理。 +* **资产管理 (Asset)**：酒店固定资产录入与统计。 -开发框架：.Net 10 +### 4.2 人力资源 (Human Resources) +* **员工管理 (Employee)**：员工档案、考勤打卡（Check）、奖惩记录、履历历史、员工照片。 +* **考勤统计**：日统计、月度汇总。 -开发技术：.NET 10 WebAPI +### 4.3 系统管理 (System Management) +* **管理员 (Admin)**：管理员账号、角色类型管理。 +* **权限控制 (RBAC)**： + * **角色 (Role)**：角色定义与权限授予。 + * **菜单 (Menu)**：动态菜单构建。 + * **权限 (Permission)**：基于特性的细粒度权限控制（代码如 `RequirePermission`）。 +* **基础数据**：部门、职位、民族、学历、公告类型等字典维护。 -### :open_file_folder: 系统结构： +### 4.4 辅助功能 (Utilities) +* **仪表盘 (Dashboard)**：房间统计（状态/房型）、营业统计、人力资源统计、物流库存统计。 +* **新闻公告 (News/Notice)**：新闻动态发布、任命公告管理。 +* **日志监控**：请求日志记录（RequestLog）、操作日志记录（OperationLog）。 +* **工具**：身份证地区码解析、邮件发送、图床上传集成（Lsky）。 -``` -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 -``` +## 5. 数据库支持 (Database Support) -### :chart_with_upwards_trend: 系统数据库关系图(由PDMAN软件生成) :loudspeaker: +本项目已基于 **SqlSugar** 框架支持多数据库连接。以下是各数据库的测试状态： -[数据库关系图](https://oscode.top/project/tshotel/db_design.html) +| 数据库 | 版本 | 支持建库建表 | 测试状态 | +| ---------- | ---------------- | ------------ | -------- | +| **MariaDB**| 10.11.10 | ✅ | ✅ 通过 | +| **PostgreSQL**| 130020 | ✅ | ✅ 通过 | +| **MySQL** | 5.7+ | ✅ | ✅ 通过 | +| **SQL Server**| 2022 | ✅ | ✅ 通过 | +| Oracle | Unknown | ❌ | 待测试 | +| SQLite | Unknown | ❌ | 待测试 | -### :exclamation: 项目作者： +> **注意**：建库建表功能可在应用启动时通过配置自动完成（见下文部署说明）。 -**Jackson(即本账号，项目组长,核心代码编写和后期项目整合)** +## 6. 配置与部署 (Configuration & Deployment) -**Benjamin(开发，项目代码编写)** +### 6.1 环境要求 +* .NET 10 SDK & Runtime +* 对应数据库服务（任选上述支持的数据库） -**Bin(数据库，提供数据库管理支持)** +### 6.2 配置文件 (appsettings.json) -**易开元(后期维护和开发)** +主要配置项位于 `EOM.TSHotelManagement.API/appsettings.json` 或环境变量： -### :computer: 项目运行部署(执行下面步骤前需先安装.NET 10 SDK和Runtime)： +* **DefaultDatabase**: 指定默认数据库类型 (如 `MariaDB`, `MySql`, `PgSql`, `SqlServer`)。 +* **{Database}ConnectStr**: 对应的数据库连接字符串。 +* **Jwt**: JWT 密钥 (`Key`) 和过期时间 (`ExpiryMinutes`)。 +* **Mail**: SMTP 邮件服务器配置。 +* **Lsky**: 兰空图床配置（用于图片上传）。 -**下载并安装Microsoft Visual Studio Professional 2026及以上版本，并通过下载Zip包解压，打开.sln后缀格式文件运行。** +### 6.3 Docker 部署 (推荐) -### :inbox_tray: Docker运行部署(以Ubuntu为例，参数需按实际进行填写)： +项目提供了 Docker 支持，适合快速部署。 -``` +```bash docker run -d \ --name tshotel-api \ -v /app/config:/app/config \ -v /app/keys:/app/keys \ -e ASPNETCORE_ENVIRONMENT=docker \ -e DefaultDatabase=MariaDB \ - -e MariaDBConnectStr=Server=yourdatabase;Database=tshoteldb;User=tshoteldb;Password=yourdatabasepassword; \ + -e MariaDBConnectStr="Server=yourdb;Database=tshoteldb;User=xxx;Password=xxx;" \ -e InitializeDatabase=true \ - -e Jwt__Key=your_key \ + -e Jwt__Key="your_jwt_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_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 \ + -e AllowedOrigins__0="http://localhost:8080" \ + -e AllowedOrigins__1="https://yourdomain.com" \ -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) +#### 关键环境变量说明： + +| 参数 | 说明 | 必填 | +|------|------|------| +| `DefaultDatabase` | 数据库类型 | Y | +| `{Type}ConnectStr` | 数据库连接串 | Y | +| `InitializeDatabase` | 启动时自动建库建表 (true/false) | N (默认 true) | +| `Jwt__Key` | JWT 签名密钥 | Y | +| `AllowedOrigins` | 允许的跨域来源 | N | + +### 6.4 本地运行 (Local Development) + +1. 安装 **Visual Studio 2022** 或 **VS Code**。 +2. 安装 **.NET 10 SDK**。 +3. 确保本地数据库服务运行。 +4. 修改 `appsettings.json` 中的数据库连接字符串。 +5. 打开 `EOM.TSHotelManagement.API/EOM.TSHotelManagement.API.sln` 运行。 + +## 7. 数据库关系图 + +系统数据库 E-R 图已发布在外部站点： +[查看数据库设计图](https://oscode.top/project/tshotel/db_design.html) + +## 8. 许可证 (License) + +本项目采用 **MIT** 开源协议。 + +--- + +**项目贡献者 (Authors)**: + +* **Jackson** (项目组长, 核心架构) +* **Benjamin** (主要开发) +* **Bin** (数据库支持) +* **易开元** (后期维护) \ No newline at end of file