酒店 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帮我升级功能
最新发布
本文探讨了一个Node.js应用程序中app.js文件启动时为何会自动执行特定路由代码的问题。该路由用于验证邮箱是否已被注册，并介绍了相关的数据库查询逻辑。
扫一扫
1214
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
