# 6-酒店管理系统 - 功能说明

# 项目概述

本系统是一套面向酒店业务的前后端分离管理系统，覆盖「酒店—客房类型—客房」资源管理、用户在线预订、预订审核与自动开单、入住与退房登记、酒店服务下单、入住评价、公告与轮播图内容运营等核心功能，并按**管理员（ADMIN）、酒店商家（HOTEL）、普通用户（USER）**三类角色划分后台管理界面与前台用户界面。系统后端采用 Django 3.2 + Django REST Framework 3.14 构建 RESTful 接口，业务按功能拆分为独立 App（user、admin、hotel、room_type、room、booking、check_in、hotel_service、hotel_service_order、review、notice、carousel 等），使用自研的 JWT Token 中间件完成认证与角色标识注入，数据存储于 MySQL（库名 d_6_hotel_system，字符集 utf8mb4）；前端采用 Vue 3.4 + Vite 5 + Element Plus 2.8 单页应用，通过 Axios 统一封装请求、Pinia 管理状态、ECharts 5 渲染后台首页统计图表，并内置图片上传组件 MyUpload。

# 项目概览

# ✨ 创新点

# 1. 多角色分表登录 + JWT 角色标识

要点：管理员、酒店商家、普通用户分别存放在 admin、hotel、user 三张独立数据表中，登录接口 /common/login 按前端传入的 type（ADMIN／HOTEL／USER）选择对应表与序列化器进行校验，一套登录入口支撑三种角色。
要点：type 不落库，只在登录成功后写入 JWT Token 的 payload（id、username、type），登录响应同时把 type 返回前端，前端据此决定跳转后台 /admin 还是前台 /。
要点：新增一个角色只需增加一张用户表，沿用同一套登录与用户中心逻辑。

# 2. 业务功能模块化的 Django App 架构

要点：每个业务域独立为一个 App，内部统一为 models.py + views.py + urls.py + XxxSerializer.py 四件套，模块之间互不侵入。
要点：INSTALLED_APPS 中已注册 12 个业务 App（admin、carousel、notice、review、hotel_service_order、hotel_service、check_in、booking、room、room_type、hotel、user），工具类（utils、middleware）与公共能力（apps/common）独立于业务模块。
要点：项目级 project/urls.py 以模块名称为前缀挂载各 App 路由（/hotel/、/room/、/booking/ …），模块增减不影响其余模块。

# 3. 统一的 CRUD 接口范式与统一响应体

要点：所有业务模块均提供 page（分页列表）、list（不分页全量）、add（新增）、update（更新）、delete（批量删除）、detail（详情）六个标准接口，前端管理页面按同一套模板组织（搜索表单 + 表格 + 分页 + 新增/编辑弹窗 + 批量删除）。
要点：后端统一通过 apps/common/ResponseMessage.py 返回 {"code": ..., "msg": ..., "data": ...}，前端 utils/http.js 按 code 分支统一提示与处理（200 成功、401 未授权跳登录、500 失败）。
要点：序列化器统一在列表数据中追加逻辑外键的中文名称（user_name、hotel_name、room_type_name、room_number 等），前端表格直接展示名称而非 ID。

# 4. 自研 JWT 认证中间件

要点：middleware/TokenInterceptorMiddleware.py 直接读取自定义请求头 token（而非标准 Authorization），用 utils/jwt_auth.py 以 settings.SECRET_KEY 为密钥做 HS256 解码，成功后将 request.id、request.username、request.type 注入视图。
要点：内置白名单——精确放行 /common/login、/common/register、/common/retrievePassword，前缀放行 /uploads/、/static/、/swagger/、/django-admin/，其余接口无有效 Token 一律返回 401 并提示「访问接口未授权，请重新登录」。
要点：Token 默认有效期 30 天（create_token 中 timeout=60*24*30 分钟），过期／非法／解码失败均有独立分支处理。

# 5. 状态驱动的业务流转与自动联动

要点：预订（booking.status）、入住记录（check_in.status）、服务订单（hotel_service_order.status）、客房（room.status）均以中文字符串状态字段驱动列表按钮与流转（如仅「待确认」的预订显示「审核」按钮）。
要点：预订状态由「待确认」变更为「已确认」时，BookingUpdateAPIView 自动按 hotel_id + room_type_id 匹配客房并创建入住记录，实现「审核即开单」的联动。
要点：服务订单新增时后端自动补默认状态「待处理」，审核时分别流转为「处理中」（接受订单）与「已取消」（拒绝订单）。

# ✨ 项目亮点

# 一、业务功能亮点

酒店—客房类型—客房三级资源管理：hotel（酒店，含酒店账号、名称、地址、描述、图片）、room_type（客房类型，含价格、床型、面积、最大入住人数、图片）、room（客房，含房间号、楼层、状态、描述）通过 hotel_id、room_type_id 逻辑关联，形成完整的房态与房型基础数据。
预订—入住—退房—评价全链路闭环：用户提交预订（booking）→ 审核通过自动生成入住记录（check_in）→ 登记退房时间与实际费用 → 状态为「已退房」后用户可对本次入住打分并评价（review，通过 check_in_id 关联），评价与订单一一对应。
酒店服务与服务订单：酒店维度维护服务项目（早餐、洗衣、接送机、叫醒等，hotel_service），用户按「服务单价 × 数量」下单生成服务订单（hotel_service_order），商家侧提供接受／拒绝审核流转。
内容运营能力：carousel 轮播图与 notice 公告均由管理员维护，前台首页轮播图取 /carousel/list，公告列表取 /notice/page 并支持详情弹窗。

# 二、技术实现亮点

现代化前端技术栈：采用 Vue 3.4.29（Composition API + <script setup>）、Element Plus 2.8.4（含 @element-plus/icons-vue 2.3.1 图标库）、Vite 5.3.1、Vue Router 4.4.3、Pinia 2.2.2、Axios 1.7.5、ECharts 5.5.1、Day.js 1.11.13、Swiper 11.1.14，并使用 unplugin-element-plus 0.8.0 与 sass-embedded 1.83.4 做按需引入与样式编译。
稳定可靠的后端架构：Django ~=3.2（settings.py 由 Django 3.2.20 生成）+ djangorestframework ~=3.14.0 + PyJWT ~=2.7.0 + drf-yasg 1.21.7 + django-cors-headers 4.2.0 + mysqlclient 2.1.1 + PyMySQL 1.1.0；视图统一使用 DRF 的 APIView／GenericAPIView，REST_FRAMEWORK 中配置了 DATETIME_FORMAT 与 DATE_FORMAT 统一输出格式，分页大小由 settings.PAGE_SIZE = 10 统一控制。
完善的数据库设计：12 张核心表，全部采用逻辑外键（user_id、hotel_id、room_type_id、room_id、booking_id、check_in_id、hotel_service_id），不建物理主外键关联，SET FOREIGN_KEY_CHECKS = 0；状态类字段统一用 varchar 存储中文描述（如「待确认」「已入住」「待处理」），金额字段使用 decimal(10,2)，主键统一为 bigint 自增，表与字段均带中文 COMMENT。
丰富的第三方集成：drf-yasg 提供 Swagger 接口文档（/swagger/）、django-cors-headers 解决跨域且允许自定义请求头 token、ECharts 负责后台首页可视化、Element Plus 承担全部 UI 组件、@wangeditor/editor 5.1.14 与 @kangc/v-md-editor 2.3.18 作为富文本／Markdown 编辑能力依赖，另有 highlight.js 11.8.0、lunar-javascript 1.6.12、crypto-js 4.1.1、sm-crypto 0.3.13、lodash 4.17.21 等工具库。
安全性设计：JWT 采用 HS256 签名，密钥复用 settings.SECRET_KEY；Token 通过自定义头 token 传递并结合中间件白名单拦截未授权访问；CORS_ALLOW_HEADERS 仅开放 token 与 content-type；序列化器统一设置 read_only_fields = ['id', 'create_time', 'update_time'] 防止前端提交只读字段；修改个人信息与密码接口均校验 user_id == request.id，禁止越权修改他人数据；重置密码接口校验 request.type == "ADMIN"。

# 三、用户体验亮点

双界面设计：后台管理界面 AdminLayout.vue（左侧深色折叠菜单 + 顶部用户下拉）服务于管理员与酒店商家；前台用户界面 FrontLayout.vue（顶部横向导航 + 用户下拉）服务于普通用户。登录后按 type 自动分流，且两侧布局互相排斥——USER 访问后台会被重定向到 /，ADMIN／HOTEL 访问前台会被重定向到 /admin。
响应式布局：列表页使用 el-col :xs/:sm/:md 栅格（如前台首页房型卡片 :xs="24" :sm="12" :md="8"），前台布局中写有 @media (max-width: 768px) 媒体查询，小屏下隐藏用户名文字与菜单文字、搜索框宽度自适应。
交互优化：
- 友好的加载提示和错误提示：表格使用 v-loading、提交按钮使用 :loading，ElMessage 统一弹出「操作成功／修改成功／预订成功／订购成功」等反馈。
- 重要操作的确认弹窗：批量删除、取消预订、删除评价、取消服务订单均先经 ElMessageBox.confirm 确认。
- 及时的全局消息提示：Axios 响应拦截器按 code 与 HTTP 状态码集中提示，401 自动清除 Token 并跳转登录页。
- 严谨的前后端表单验证：前端 el-form 配置 rules（必填、格式）并调用 validate()；后端 DRF 序列化器 is_valid() 校验，失败时返回具体错误信息（如「数据验证失败: {...}」）。
文件上传体验：封装 components/MyUpload.vue，支持 imageCard（图片卡片）／image／video／audio／file 多种类型模式，上传时自动携带 token 请求头；limit=1 时按钮变为「点击替换」并自动替换旧文件，超过限制时给出提示；图片／视频／音频支持弹窗预览，附件类型点击直接下载。

# 管理员（ADMIN）

# 数据看板

后台首页：展示酒店总数、客房总数、预订总数、用户总数四张统计卡片，以及预订趋势、客房类型分布、月度收入统计、服务订单统计四张 ECharts 图表（数据来自 GET /common/statistics）。

个人信息维护：下拉菜单中可进入「个人信息」修改昵称、邮箱、电话、头像（POST /common/updateCurrentUser），可进入「修改密码」校验原密码后改密（POST /common/updatePassword，成功后清空登录态并跳回登录页）。

# 系统管理

管理员管理：管理员账号的增删改查，支持新增（用户名、密码、昵称、头像、联系方式、邮箱）、编辑、单个／批量删除、详情查看，头像使用 MyUpload 组件上传。

用户管理：普通用户账号的增删改查，字段含用户名、密码、昵称、头像、联系方式、邮箱、身份证号、余额。

酒店管理：酒店账号及酒店信息维护（用户名、密码、昵称、头像、联系方式、邮箱、酒店名称、地址、酒店描述、酒店图片），支持按酒店名称搜索、批量删除。

# 酒店与客房管理

客房类型管理：维护房型基础数据（所属酒店、类型名称、类型描述、价格、床型、面积、最多入住人数、图片），支持按类型名称搜索，图片使用 MyUpload 上传。

客房管理：维护具体房间（所属酒店、房间号、客房类型、楼层、状态、描述），支持按房间号搜索；状态通过 el-radio-group 在「可用／已预订／维护中」间切换。

# 订单与入住管理

预订管理：查看全部预订记录（用户、酒店、房型、入住日期、退房日期、入住天数、总价、状态、联系人、联系电话、备注），对「待确认」的预订执行审核——通过置为「已确认」，拒绝置为「已取消」并可填写拒绝原因（追加到备注），还可编辑与删除。

入住记录管理：维护入住记录（预订、酒店、客房、用户、入住时间、退房时间、实际入住天数、实际费用、状态），支持按用户名搜索；对 status='待确认' 的记录提供「确认」按钮置为「已确认」，编辑表单中可登记退房时间、实际天数、实际费用并将状态改为「已退房」。

服务订单管理：查看全部服务订单（用户、酒店、服务项目、入住记录、数量、总价、状态、备注），支持按用户名搜索；对「待处理」订单执行审核——接受订单置为「处理中」，拒绝订单置为「已取消」。

评价管理：查看与维护入住评价（用户、酒店、入住记录、评分、评价内容），支持按用户名搜索，可编辑、删除、查看详情。

# 内容管理

公告管理：公告标题与内容的增删改查，支持按标题搜索，公告内容通过后台表单维护并支持在前台以 HTML 形式展示。

轮播图管理：前台首页轮播图的标题与图片维护，支持按标题搜索，图片使用 MyUpload 上传。

# 酒店商家（HOTEL）

# 数据看板

后台首页：与管理员一致，展示统计卡片与四张 ECharts 图表。

个人信息维护：可修改本酒店账号的昵称、邮箱、电话、头像与密码。

# 酒店与客房管理

客房类型管理：维护房型数据（类型名称、描述、价格、床型、面积、最多入住人数、图片）。

客房管理：维护客房数据（酒店、房间号、客房类型、楼层、状态、描述）。

# 订单与入住管理

预订管理：查看并处理预订，对待确认预订执行审核（通过／拒绝），可编辑与删除。

入住记录管理：查看入住记录，确认待确认记录，登记退房时间与实际费用完成退房。

服务订单管理：查看服务订单并执行接受／拒绝审核。

评价管理：查看与维护本酒店的评价记录。

说明：上述模块在本角色下与管理员共用同一套页面与接口；后端分页接口中另写有「HOTEL 角色按 hotel_id = 当前用户 id 过滤数据」的分支（utils/current_user.py），详见「功能权限对照表」下的说明。

# 普通用户（USER）

# 前台浏览

首页：轮播图展示（GET /carousel/list）与客房类型卡片展示（GET /room_type/list），卡片内含房型图片、名称、描述、床型／面积／容纳人数标签与每晚价格，可「立即预订」或点击进入详情。

客房列表：以卡片形式展示全部房型，支持按名称搜索与重置，可查看详情或直接预订。

客房详情：展示房型完整信息（图片、名称、描述、价格、床型、面积、最多入住人数、设施标签），底部提供「立即预订」入口。

酒店服务：展示全部服务项目（名称、描述、价格、图片），可填写数量下单，前端按「服务单价 × 数量」实时计算总价。

系统公告：分页展示公告标题列表，支持分页翻页，点击可弹窗查看公告详情（HTML 内容渲染）。

# 预订与入住

在线预订：选择客房类型、入住日期、退房日期（日期选择器禁用过去日期，退房日期必须晚于入住日期），前端自动计算入住天数与总价，填写联系人、联系电话与备注后提交，生成状态为「待确认」的预订。

我的预订：查看自己的预订列表（房型、酒店、入住/退房日期、天数、总价、状态、联系人），支持分页、详情弹窗；状态为「待确认」时可取消（二次确认后置为「已取消」），状态为「已退房」时可发起评价。

入住记录：查看自己的入住记录（预订信息、酒店、房间号、入住时间、退房时间、实际入住天数、实际费用、状态），支持分页与详情弹窗；状态为「已退房」且尚未评价时提供「评价」按钮。

# 服务与评价

服务订单：查看自己的服务订单（服务项目、酒店、数量、总价、状态、备注），支持分页与详情弹窗；状态为「待处理」时可取消订单（二次确认后删除该订单）。

我的评价：查看自己提交的评价列表（酒店、评分、评价内容），支持分页、详情弹窗与删除。

# 个人中心

个人信息：以只读表单展示当前账号的用户名、昵称、邮箱、联系方式，并提供跳转「编辑信息」与「修改密码」的按钮。

编辑信息：修改头像（MyUpload 上传）、昵称、邮箱、电话，提交后重新拉取当前用户信息并刷新本地缓存。

修改密码：填写原密码与新密码，后端校验原密码正确后更新，前端清空登录态并跳回登录页重新登录。

注册与找回密码：未登录时可注册普通用户账号（用户名、昵称、头像、密码，固定注册为 USER 类型）；忘记密码时可通过手机号 + 验证码 + 新密码重置（后端按手机号匹配 user 表并更新密码，源码中标注验证码校验为 TODO 简化处理）。

# 功能权限对照表

功能模块	管理员（ADMIN）	酒店商家（HOTEL）	普通用户（USER）
后台首页（统计卡片 + 图表）	✓	✓	-
前台首页（轮播图 + 房型展示）	-	-	✓
管理员管理	✓	-	-
用户管理	✓	-	-
酒店管理	✓	-	-
客房类型管理	✓	✓	-（可浏览房型列表/详情）
客房管理	✓	✓	-
预订管理	✓	✓	-（仅自己的预订，前台下单/取消）
入住记录管理	✓	✓	-（仅自己的入住记录，前台查看）
服务项目管理	✓	✓	-（仅浏览服务列表）
服务订单管理	✓	✓	-（仅自己的服务订单，前台下单/取消）
评价管理	✓	✓	-（仅自己的评价，前台提交/删除）
公告管理	✓	-	-（仅前台浏览公告）
轮播图管理	✓	-	-
个人信息 / 修改密码	✓	✓	✓
注册	-	-	✓
找回密码	✓	-	✓

说明：上表「✓／-」以后台 AdminLayout.vue 菜单的 v-if="currentUser.type === 'ADMIN'" 渲染条件、前台 FrontLayout.vue 菜单与 router/index.js 的路由归属为准；登录页需显式选择 ADMIN／HOTEL／USER，USER 访问 /admin 会被重定向到前台、ADMIN／HOTEL 访问前台会被重定向到 /admin。后端另有两类强校验并实际生效：/common/resetPassword 仅允许 request.type == "ADMIN" 调用，/common/updateCurrentUser、/common/updatePassword 校验目标 id 必须等于当前登录用户 id。各分页接口中还写有按角色过滤数据的分支（USER 按 user_id、HOTEL 按 hotel_id），该分支读取 utils/current_user.py 的线程本地变量，而 middleware/CurrentUserMiddleware.py 未注册进 settings.MIDDLEWARE，因此该数据隔离分支在运行时不会命中。

# 业务状态说明

# 预订状态（`booking` 表的 `status` 字段，默认值「待确认」）

状态	含义
待确认	用户刚提交预订的初始状态，后台此时显示「审核」按钮
已确认	审核通过；后端在「待确认 → 已确认」时自动创建入住记录
已入住	客人已办理入住
已退房	客人已离店（预订单在前台「已退房」状态下可发起评价）
已取消	审核拒绝或用户自行取消

# 入住记录状态（`check_in` 表的 `status` 字段，默认值「已入住」）

状态	含义
已入住	入住中（后端自动生成的入住记录即为此状态）
已退房	已完成退房，用户可对本次入住进行评价
待确认 / 已确认	列表对 `status='待确认'` 的记录显示「确认」按钮，点击后置为「已确认」

# 服务订单状态（`hotel_service_order` 表的 `status` 字段，默认值「待处理」）

状态	含义
待处理	用户下单后的初始状态（后端新增时自动补默认值），后台此时显示「审核」按钮
处理中	商家「接受订单」后的状态
已完成	服务已完成
已取消	商家「拒绝订单」后的状态；用户侧对「待处理」订单执行「取消订单」会直接删除该记录

# 客房状态（`room` 表的 `status` 字段）

状态	含义
可用	客房可正常售卖（后台表单选项）
已预订	客房已被预订（后台表单选项）
维护中	客房维护中不可售卖（后台表单选项）
空闲	SQL 初始化数据中 5 间客房使用的取值

说明：room.status 的前端表单选项为「可用／已预订／维护中」，而 sql/d_6_hotel_system.sql 初始化数据中的取值为「空闲」，二者未统一。

# 默认账号

以下账号取自 project/sql/d_6_hotel_system.sql 的初始化数据（密码为明文存储于 password 字段，长度为 varchar(25)）。

# 管理员

用户名: admin
密码: 123456
昵称: 系统管理员
联系方式: 13800000000

1
2
3
4

# 酒店商家

用户名: hotel
密码: 123456
昵称: 如家酒店
联系方式: 13900000000

1
2
3
4

# 测试用户

用户名: user
密码: 123456
昵称: 普通用户
联系方式: 13800000000

1
2
3
4

说明：项目另提供管理命令 python manage.py generate_test_data（apps/common/management/commands/generate_test_data.py）批量生成测试数据，其脚本中插入的账号为 admin/123456、user1[2/3]/123456、hotel1[2/3]/123456。

# 核心业务流程

# 客房预订流程

1. 用户登录后进入前台首页（/index）或客房列表（/roomList），浏览客房类型 GET /room_type/list
2. 点击「立即预订」跳转 /booking?roomTypeId=x，选择入住日期与退房日期
   （退房日期选择器禁用早于入住日期的日期）
3. 前端按（退房日期 - 入住日期）计算入住天数，再按「房型单价 × 天数」计算总价
4. 填写联系人、联系电话、备注后提交 POST /booking/add，状态置为「待确认」
5. 在「我的预订」（/myBooking）查看记录 GET /booking/page；状态为「待确认」时可取消
   PUT /booking/update（id + status="已取消"）

1
2
3
4
5
6
7

# 预订审核与自动开单流程

1. 管理员/酒店商家在后台「预订管理」查看预订列表 GET /booking/page
2. 对 status="待确认" 的记录点击「审核」，选择「通过（已确认）」或「拒绝（已取消）」
3. PUT /booking/update 提交；拒绝时可填写拒绝原因，前端将其追加写入 remark 字段
4. 后端 BookingUpdateAPIView 检测到「待确认 → 已确认」时自动联动：
   按 instance.hotel_id + instance.room_type_id 查询第一间客房，
   创建 check_in 入住记录（check_in_time=当前时间、actual_days=预订天数、
   actual_price=预订总价、status="已入住"）

1
2
3
4
5
6
7

# 入住—退房—评价流程

1. 管理员/酒店商家在「入住记录管理」查看记录 GET /check_in/page（支持按用户名搜索）
2. 对 status="待确认" 的记录点击「确认」置为「已确认」（PUT /check_in/update）
3. 编辑入住记录，登记退房时间、实际入住天数、实际费用，状态改为「已退房」
4. 用户在「入住记录」（/myCheckIn）查看自己的记录 GET /check_in/page，
   状态为「已退房」且未评价时出现「评价」按钮
5. 用户打分（评分 1-5 星）并填写评价内容后提交 POST /review/add，
   写入 review 表（user_id、hotel_id、check_in_id、rating、content）

1
2
3
4
5
6
7

# 酒店服务下单流程

1. 用户在前台「酒店服务」（/serviceList）浏览服务项目 GET /hotel_service/list
2. 选择数量下单，前端按「服务单价 × 数量」计算总价，POST /hotel_service_order/add
   （后端在未传 status 时自动补默认值「待处理」）
3. 管理员/酒店商家在「服务订单管理」审核：
   「接受订单」→ 置为「处理中」，「拒绝订单」→ 置为「已取消」
   （PUT /hotel_service_order/update）
4. 用户在「服务订单」（/myServiceOrder）查看状态流转；状态为「待处理」时可取消
   DELETE /hotel_service_order/delete（请求体传数组 [id]）

1
2
3
4
5
6
7
8

# 技术说明

# 系统架构

前端：Vue 3.4.29 + Element Plus 2.8.4 + Vite 5.3.1
后端：Django 3.2.x + Django REST Framework 3.14.x
数据库：MySQL 8.0（库名 d_6_hotel_system，字符集 utf8mb4）
认证：自定义 JWT Token（HS256，请求头 token，有效期 30 天）
其他依赖：PyJWT 2.7.x、drf-yasg 1.21.7、django-cors-headers 4.2.0、mysqlclient 2.1.1、PyMySQL 1.1.0；前端 Vue Router 4.4.3、Pinia 2.2.2、Axios 1.7.5、ECharts 5.5.1、Swiper 11.1.14、Day.js 1.11.13

# 访问地址

后端API：http://127.0.0.1:8000
前端页面：http://localhost:5173（开发环境，Vite 默认端口，vite.config.js 未显式配置 server.port）
Swagger 接口文档：http://127.0.0.1:8000/swagger/
Django 自带管理后台：http://127.0.0.1:8000/django-admin/
前端接口基地址：.env.development 中 VITE_APP_API_URL='http://127.0.0.1:8000'（生产环境为 /api）

# 数据库

数据库名：d_6_hotel_system
字符集：utf8mb4（排序规则 utf8mb4_unicode_ci，存储引擎 InnoDB）
总表数：12 张表（user、admin、hotel、room_type、room、booking、check_in、hotel_service、hotel_service_order、review、notice、carousel）

表名	中文说明	主要字段
user	用户表	username、password、nickname、avatar、contact、email、id_card、balance
admin	管理员表	username、password、nickname、avatar、contact、email
hotel	酒店表	username、password、nickname、avatar、contact、email、name、address、description、image
room_type	客房类型表	hotel_id、name、description、price、bed_type、area、max_people、image
room	客房表	hotel_id、room_number、room_type_id、floor、status、description
booking	预订表	user_id、hotel_id、room_type_id、check_in_date、check_out_date、days、total_price、status、contact_name、contact_phone、remark
check_in	入住记录表	booking_id、hotel_id、room_id、user_id、check_in_time、check_out_time、actual_days、actual_price、status
hotel_service	服务项目表	hotel_id、name、description、price、image
hotel_service_order	服务订单表	user_id、hotel_id、hotel_service_id、check_in_id、quantity、total_price、status、remark
review	评价表	user_id、hotel_id、check_in_id、rating、content
notice	公告表	title、content
carousel	轮播图表	title、image

说明：源码中另有 apps/pet（Pet 模型，db_table = 'pet'）及其前端页面 views/admin/Pet.vue、views/admin/PetCategory.vue，但该 App 未注册进 INSTALLED_APPS、未在 project/urls.py 挂载路由、前端 router/index.js 也未配置对应路由，SQL 中无 pet 建表语句，故不计入本系统功能与表清单。

# API接口规范

RESTful风格（以模块名为前缀，各业务模块接口结构一致）：
GET    /module/page          # 分页查询（参数 pageNum，每页 PAGE_SIZE=10 条）
GET    /module/list          # 查询全部（不分页）
POST   /module/add           # 新增
PUT    /module/update        # 更新（请求体含 id，partial 更新）
DELETE /module/delete        # 批量删除（请求体传 id 数组）
GET    /module/detail?id=1   # 查询详情

公共接口：
POST   /common/login             # 登录（username、password、type）
PUT    /common/register          # 注册（固定 USER 类型）
POST   /common/retrievePassword  # 找回密码（tel、code、password）
GET    /common/currentUser       # 获取当前登录用户
POST   /common/updateCurrentUser # 更新当前用户信息
POST   /common/updatePassword    # 修改密码（oldPassword、newPassword）
POST   /common/resetPassword     # 重置密码（仅 ADMIN，重置为 123456）
GET    /common/statistics        # 首页统计数据
POST   /file/upload              # 文件上传（表单字段名 file）

响应格式（apps/common/ResponseMessage.py）：
{
    "code": 200,
    "msg": "操作成功",
    "data": {...}
}

异常与未授权响应：
{
    "code": 401,
    "msg": "访问接口未授权，请重新登录",
    "data": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

请求头约定：除白名单接口外，所有请求需携带 token 请求头（前端在 Axios 请求拦截器中自动从 localStorage 取出 token 注入）。

# 系统特色

# 数据可视化

组件：ECharts 5.5.1
图表：
- 预订趋势（折线图，取最近 6 个月按 check_in_date 分组的预订数量）
- 客房类型分布（饼图，按 room_type.name 分组统计数量）
- 月度收入统计（柱状图，按月份汇总 booking.total_price）
- 服务订单统计（柱状图）
位置：管理后台首页（/admin/home），同时在顶部展示酒店总数、客房总数、预订总数、用户总数四张统计卡片；图表数据统一由 GET /common/statistics 提供，并监听 resize 自适应窗口宽度

# 文件上传

上传接口：POST /file/upload（apps/common/views.py 的 FileUploadAPIView），表单字段名为 file，请求需携带 token
前端组件：components/MyUpload.vue，已应用于 Admin.vue、User.vue、Hotel.vue、Carousel.vue、HotelService.vue、RoomType.vue、Register.vue、EditCurrentUser.vue
支持格式：由组件的 accept 按类型约束——imageCard／image 模式为 image/*，video 模式为 video/*，audio 模式为 audio/*，file 模式不限；后端不校验扩展名，按原始文件扩展名保存
存储方式：读取 settings.UPLOAD_PATH（值为相对项目根目录的 uploads\），文件名为 uuid4() + 原扩展名，上传目录不存在时自动创建；MEDIA_ROOT = BASE_DIR/uploads，DEBUG = True 时由 static(MEDIA_URL, MEDIA_ROOT) 提供访问
访问格式：http://127.0.0.1:8000/uploads/<uuid>.<ext>（由 settings.HTTP_PICTURE = "http://127.0.0.1:8000/uploads/" 拼接文件名生成）
交互细节：limit=1 且已有文件时按钮显示「点击替换」并自动替换；超出数量限制时提示或自动替换；图片／视频／音频点击可弹窗预览，附件点击直接下载

# 6-酒店管理系统 - 功能说明

# 项目概述

# 项目概览

# ✨ 创新点

# 1. 多角色分表登录 + JWT 角色标识

# 2. 业务功能模块化的 Django App 架构

# 3. 统一的 CRUD 接口范式与统一响应体

# 4. 自研 JWT 认证中间件

# 5. 状态驱动的业务流转与自动联动

# ✨ 项目亮点

# 一、 业务功能亮点

# 二、 技术实现亮点

# 三、 用户体验亮点

# 管理员（ADMIN）

# 数据看板

# 系统管理

# 酒店与客房管理

# 订单与入住管理

# 内容管理

# 酒店商家（HOTEL）

# 数据看板

# 酒店与客房管理

# 订单与入住管理

# 普通用户（USER）

# 前台浏览

# 预订与入住

# 服务与评价

# 个人中心

# 功能权限对照表

# 业务状态说明

# 预订状态（booking 表的 status 字段，默认值「待确认」）

# 入住记录状态（check_in 表的 status 字段，默认值「已入住」）

# 服务订单状态（hotel_service_order 表的 status 字段，默认值「待处理」）

# 客房状态（room 表的 status 字段）

# 默认账号

# 管理员

# 酒店商家

# 测试用户

# 核心业务流程

# 客房预订流程

# 预订审核与自动开单流程

# 入住—退房—评价流程

# 酒店服务下单流程

# 技术说明

# 系统架构

# 访问地址

# 数据库

# API接口规范

# 系统特色

# 数据可视化

# 文件上传

# 一、业务功能亮点

# 二、技术实现亮点

# 三、用户体验亮点

# 预订状态（`booking` 表的 `status` 字段，默认值「待确认」）

# 入住记录状态（`check_in` 表的 `status` 字段，默认值「已入住」）

# 服务订单状态（`hotel_service_order` 表的 `status` 字段，默认值「待处理」）

# 客房状态（`room` 表的 `status` 字段）