酒店 PMS 系统
一、系统架构图(可视化核心):画一张架构图,标注各模块及数据流向
用户 → 前端页面(Vue/Flask模板) ↓↑(API调用,带JWT Token) 后端服务(Flask + SQLAlchemy) ↓↑(ORM映射) 数据库(MySQL)
二、数据模型文档(理解 “数据地基”)
ER 图与核心实体
表结构详情(表格形式)
核心业务规则清单
三、后端开发文档
技术栈与项目结构
API 接口手册
核心逻辑实现说明
四、前端开发文档
技术栈与页面结构
技术栈:Vue(或 Flask 模板)+ axios(API 请求)+ JWT(Token 存储);
核心页面及功能:
登录页(/login):输入账号密码,调用/login获取 Token,存储到 localStorage;
房态看板(/rooms):展示所有房间状态,定时轮询/rooms刷新(每 30 秒一次);
订单管理(/orders):创建订单表单(调用POST /orders)、订单列表(调用GET /orders);
系统设置(/settings):仅管理员可见,配置夜审时间等。
2. 与后端交互规则
Token 处理:登录后获取 Token,所有请求在 Header 中携带(Authorization: Bearer {token});Token 过期时自动跳转登录页;
权限控制:登录后根据role字段隐藏 / 显示功能:
管理员(admin):可见所有页面(房态、订单、系统设置);
保洁(cleaner):仅可见房态看板;
财务(finance):仅可见订单管理;
状态联动:操作后实时更新界面(如创建订单后,房态看板立即刷新房间状态为 booked)。
五、开发与维护规范(指导后续操作)
明确 “新增功能 / 修改功能” 的标准流程,避免混乱。
1. 新增功能流程
按 “数据库→后端→联调→前端” 顺序,举例 “新增‘房间维修状态’”:
步骤 1:改数据库
给 rooms 表加is_repair字段(tinyint,0 = 正常,1 = 维修);
更新 ER 图和表结构文档;
步骤 2:改后端
在 Room 模型类加is_repair属性;
新增 APIPUT /rooms/{id}/repair(修改维修状态);
订单创建逻辑中增加判断(is_repair=1时不可预订);
步骤 3:联调
用 Postman 测试PUT /rooms/1/repair→检查数据库字段更新;
测试订单创建(维修中的房间应返回错误);
步骤 4:改前端
房态看板中用红色标记维修房间;
新增 “标记维修” 按钮(仅管理员可见),调用PUT /rooms/{id}/repair。
2. 修改现有功能注意事项
改数据库字段:需同步修改后端模型类、API 返回值,以及前端数据展示逻辑;
改 API 参数:需同步更新前端调用代码(如参数名从checkin_date改为start_date);
改权限规则:需同时修改后端 API 权限控制和前端页面可见性(如开放保洁修改房态,需后端放开权限 + 前端加按钮)。
六、快速上手指南(新开发者必备)
用 “步骤化” 说明如何搭建环境、运行系统,降低入门成本:
1.环境搭建
数据库:导入init_db.sql(含表结构和测试数据);
后端:安装依赖(pip install -r requirements.txt),修改config.py中数据库连接地址,启动python app.py;
前端:安装依赖(npm install),启动npm run dev,访问localhost:8080;
2.测试账号
管理员:admin/123(角色 admin);
保洁:cleaner/123(角色 cleaner);
3.核心功能测试路径
登录→房态看板→选择房间创建订单→办理入住→办理退房。
工具建议
文档管理:用 Markdown 编写,放在项目根目录的docs/文件夹,与代码一起用 Git 版本控制(确保文档与代码同步更新);
图表工具:ER 图用 draw.io,架构图用 processon,流程图用 mermaid(支持 Markdown 嵌入);
API 文档:用 Swagger(Flask 可集成 Flask-RESTX)自动生成 API 文档,方便前端调用时参考。
四、前端开发文档
技术栈与页面结构
技术栈
核心框架:Vue 3
路由:Vue Router 4
状态管理:Pinia
HTTP 客户端:Axios
UI 组件:可选用 Element Plus 或 Vuetify
认证:JWT 存储在 localStorage
页面结构
hotel-pms-frontend/
├── public/ # 静态资源
├── src/
│ ├── api/ # API请求
│ │ ├── index.js # 请求拦截器配置
│ │ ├── auth.js # 认证相关API
│ │ ├── rooms.js # 房间相关API
│ │ └── orders.js # 订单相关API
│ ├── assets/ # 资源文件
│ ├── components/ # 组件
│ │ ├── common/ # 通用组件
│ │ │ ├── Navbar.vue # 导航栏
│ │ │ ├── Sidebar.vue # 侧边栏
│ │ │ └── Footer.vue # 页脚
│ │ ├── rooms/ # 房间相关组件
│ │ └── orders/ # 订单相关组件
│ ├── views/ # 页面
│ │ ├── Login.vue # 登录页
│ │ ├── Dashboard.vue # 仪表盘
│ │ ├── rooms/ # 房间相关页面
│ │ │ ├── RoomList.vue # 房间列表
│ │ │ └── RoomDetail.vue # 房间详情
│ │ ├── orders/ # 订单相关页面
│ │ │ ├── OrderList.vue # 订单列表
│ │ │ ├── OrderCreate.vue # 创建订单
│ │ │ └── OrderDetail.vue # 订单详情
│ │ └── settings/ # 系统设置页面
│ ├── router/ # 路由配置
│ │ └── index.js # 路由定义
│ ├── store/ # 状态管理
│ │ ├── index.js # store入口
│ │ ├── auth.js # 认证状态
│ │ └── rooms.js # 房间状态
│ ├── utils/ # 工具函数
│ │ ├── auth.js # 认证工具
│ │ └── format.js # 格式化工具
│ ├── App.vue # 根组件
│ └── main.js # 入口文件
├── package.json # 依赖管理
└── vue.config.js # Vue配置
核心页面及功能
1.登录页(/login)
功能:用户登录,获取 Token 并存储
主要元素:用户名输入框、密码输入框、登录按钮
交互:表单验证、登录请求、错误提示、登录成功后跳转
2.仪表盘(/dashboard)
功能:系统概览,显示关键统计信息
主要元素:房间状态统计、今日订单统计、收入统计图表
交互:数据定时刷新、快捷操作入口
3.房态看板(/rooms)
功能:展示所有房间状态,提供房间管理功能
主要元素:房间卡片(按状态区分颜色)、筛选器、搜索框、添加 / 编辑按钮
交互:房间状态更新、维修标记、定时刷新(30 秒一次)
4.订单管理(/orders)
功能:订单列表展示,订单创建、编辑、取消等操作
主要元素:订单表格、筛选器、搜索框、创建订单按钮
交互:办理入住 / 退房、订单详情查看、订单筛选
5.订单创建(/orders/create)
功能:创建新订单
主要元素:房间选择、客户信息表单、日期选择器、价格计算展示
交互:房间可用性验证、价格自动计算、表单提交
6.系统设置(/settings)
功能:系统参数配置,仅管理员可见
主要元素:夜审时间设置、用户管理、权限配置
交互:参数保存、用户添加 / 编辑 / 删除
与后端交互规则
Token 处理
登录成功后获取 Token,存储在 localStorage 中
所有请求通过 Axios 拦截器自动在 Header 中携带 Token
响应拦截器处理 401 错误(Token 过期或无效),自动跳转至登录页
// src/api/index.js
import axios from 'axios';
import { getToken, removeToken } from '../utils/auth';
import router from '../router';
const service = axios.create({
baseURL: process.env.VUE_APP_API_BASE_URL || '/api',
timeout: 5000});
// 请求拦截器
service.interceptors.request.use(
config => {
// 自动添加Token
const token = getToken();
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
},
error => {
return Promise.reject(error);
});
// 响应拦截器
service.interceptors.response.use(
response => {
return response.data;
},
error => {
// 处理401错误
if (error.response && error.response.status === 401) {
removeToken();
router.push('/login');
}
return Promise.reject(error);
});
export default service;
权限控制
登录后根据用户 role 字段控制页面访问权限
使用路由守卫控制页面访问权限
根据用户角色动态生成导航菜单
// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router';
import { getToken, getUserRole } from '../utils/auth';
const routes = [
{
path: '/login',
name: 'Login',
component: () => import('../views/Login.vue'),
meta: { requiresAuth: false }
},
{
path: '/',
name: 'Dashboard',
component: () => import('../views/Dashboard.vue'),
meta: { requiresAuth: true }
},
{
path: '/rooms',
name: 'Rooms',
component: () => import('../views/rooms/RoomList.vue'),
meta: { requiresAuth: true }
},
{
path: '/orders',
name: 'Orders',
component: () => import('../views/orders/OrderList.vue'),
meta: {
requiresAuth: true,
roles: ['admin', 'finance'] // 仅管理员和财务可访问
}
},
{
path: '/settings',
name: 'Settings',
component: () => import('../views/settings/Index.vue'),
meta: {
requiresAuth: true,
roles: ['admin'] // 仅管理员可访问
}
}];
const router = createRouter({
history: createWebHistory(),
routes});
// 路由守卫
router.beforeEach((to, from, next) => {
// 不需要认证的页面直接放行
if (!to.meta.requiresAuth) {
next();
return;
}
// 检查是否已登录
if (!getToken()) {
next('/login');
return;
}
// 检查角色权限
if (to.meta.roles && !to.meta.roles.includes(getUserRole())) {
next('/'); // 无权限跳转到首页
return;
}
next();});
export default router;
状态联动
操作成功后实时更新界面数据
重要操作(如办理入住 / 退房)后自动刷新相关数据
使用定时任务定期刷新房态等关键数据。后端开发文档
技术栈
核心框架:Node.js + Express
数据库:MySQL
ORM:Sequelize
认证:JWT (jsonwebtoken)
接口文档:Swagger UI Express
其他:cors, dotenv, body-parser
项目结构
hotel-pms-backend/
├── config/ # 配置文件
│ ├── db.js # 数据库配置
│ └── config.js # 系统配置
├── controllers/ # 控制器
│ ├── authController.js # 认证相关
│ ├── roomController.js # 房间相关
│ ├── orderController.js # 订单相关
│ └── userController.js # 用户相关
├── middleware/ # 中间件
│ ├── auth.js # 认证中间件
│ ├── errorHandler.js # 错误处理中间件
│ └── roleCheck.js # 角色检查中间件
├── models/ # 数据模型
│ ├── index.js # 模型入口
│ ├── user.js # 用户模型
│ ├── room.js # 房间模型
│ ├── order.js # 订单模型
│ └── customer.js # 客户模型
├── routes/ # 路由
│ ├── index.js # 路由入口
│ ├── authRoutes.js # 认证路由
│ ├── roomRoutes.js # 房间路由
│ ├── orderRoutes.js # 订单路由
│ └── userRoutes.js # 用户路由
├── services/ # 业务逻辑
│ ├── authService.js # 认证服务
│ ├── roomService.js # 房间服务
│ └── orderService.js # 订单服务
├── utils/ # 工具函数
│ ├── jwt.js # JWT工具
│ ├── logger.js # 日志工具
│ └── validator.js # 数据验证工具
├── app.js # 应用入口
├── server.js # 服务器启动
├── package.json # 依赖管理
└── .env # 环境变量
API 接口手册
基础信息
基础 URL:http://localhost:3000/api
所有请求除登录外均需在 Header 中携带认证信息:Authorization: Bearer {token}
数据格式:JSON
认证接口
接口 方法 描述 请求参数 响应
/auth/login POST 用户登录 {username, password} {success, token, user: {id, username, role}}
/auth/logout POST 用户登出 - {success, message}
/auth/me GET 获取当前用户信息 - {id, username, role, name}
房间接口
接口 方法 描述 请求参数 响应
/rooms GET 获取所有房间 - [{id, room_number, type, price, status, is_repair}]
/rooms/:id GET 获取单个房间 - {id, room_number, type, price, status, is_repair, description}
/rooms POST 添加房间 {room_number, type, price, status, description} {success, data: {id, ...}}
/rooms/:id PUT 更新房间信息 {room_number, type, price, status, description} {success, message}
/rooms/:id DELETE 删除房间 - {success, message}
/rooms/:id/status PATCH 更新房间状态 {status} {success, message}
/rooms/:id/repair PATCH 更新维修状态 {is_repair} {success, message}
订单接口
接口 方法 描述 请求参数 响应
/orders GET 获取所有订单 - [{id, order_number, room_id, customer_id, checkin_date, checkout_date, total_price, status}]
/orders/:id GET 获取单个订单 - {id, order_number, room, customer, checkin_date, checkout_date, total_price, status, payment_status}
/orders POST 创建订单 {room_id, customer_id, checkin_date, checkout_date} {success, data: {id, ...}}
/orders/:id PUT 更新订单 {checkin_date, checkout_date, status, payment_status} {success, message}
/orders/:id DELETE 取消订单 - {success, message}
/orders/:id/checkin PATCH 办理入住 - {success, message}
/orders/:id/checkout PATCH 办理退房 - {success, message}
核心逻辑实现说明
1. 认证逻辑
// controllers/authController.js
const login = async (req, res) => {
try {
const { username, password } = req.body;
// 查找用户
const user = await User.findOne({ where: { username } });
if (!user) {
return res.status(401).json({ success: false, message: '用户名或密码错误' });
}
// 验证密码(实际项目中应使用bcrypt等工具加密验证)
if (user.password !== password) {
return res.status(401).json({ success: false, message: '用户名或密码错误' });
}
// 生成JWT Token
const token = generateToken(user);
// 返回结果
res.json({
success: true,
token,
user: {
id: user.id,
username: user.username,
role: user.role
}
});
} catch (error) {
res.status(500).json({ success: false, message: '服务器错误' });
}};
2. 房间状态管理逻辑
// controllers/roomController.js
const updateStatus = async (req, res) => {
try {
const { id } = req.params;
const { status } = req.body;
// 查找房间
const room = await Room.findByPk(id);
if (!room) {
return res.status(404).json({ success: false, message: '房间不存在' });
}
// 检查房间是否在维修中
if (room.is_repair && status !== '维修中') {
return res.status(400).json({
success: false,
message: '维修中的房间不能更改状态'
});
}
// 更新状态
await room.update({ status });
res.json({ success: true, message: '房间状态更新成功' });
} catch (error) {
res.status(500).json({ success: false, message: '服务器错误' });
}};
3. 订单创建逻辑
// controllers/orderController.js
const createOrder = async (req, res) => {
try {
const { room_id, customer_id, checkin_date, checkout_date } = req.body;
const user_id = req.user.id; // 从JWT中获取当前用户ID
// 验证房间是否存在且可用
const room = await Room.findByPk(room_id);
if (!room) {
return res.status(404).json({ success: false, message: '房间不存在' });
}
if (room.status !== '空闲' || room.is_repair) {
return res.status(400).json({ success: false, message: '房间不可用' });
}
// 验证客户是否存在
const customer = await Customer.findByPk(customer_id);
if (!customer) {
return res.status(404).json({ success: false, message: '客户不存在' });
}
// 计算总金额
const checkin = new Date(checkin_date);
const checkout = new Date(checkout_date);
const days = Math.ceil((checkout - checkin) / (1000 * 60 * 60 * 24));
const total_price = days * room.price;
// 生成订单编号
const order_number = `ORD${Date.now()}`;
// 创建订单
const order = await Order.create({
order_number,
room_id,
customer_id,
user_id,
checkin_date,
checkout_date,
total_price,
status: '预订中',
payment_status: '未支付'
});
// 更新房间状态
await room.update({ status: '已预订' });
res.status(201).json({
success: true,
data: order
});
} catch (error) {
res.status(500).json({ success: false, message: '服务器错误' });
}};
。给我完整的前后端代码,功能齐全完善,特备是,自主在设置里添加各种数据等,附上markdown文件和readme文件,让后续人好维护,小白级教学,还要方便我交给chatgpt帮我升级功能
最新发布