Python Vue宾馆客房管理系统全栈开发实战指南

做开发这几年，我一直觉得类似"Python基于Vue的宾馆客房管理系统"这种题目，是性价比很高的练手项目。它没有特别复杂的算法，但覆盖了一个真实Web系统该有的全部环节：前端页面、后端接口、数据库设计、权限控制、状态流转，甚至还能塞进统计报表。用Django或Flask提供接口，Vue负责页面交互，PyCharm作为主力开发工具，整套流程做完，你对全栈开发的理解会比闷头看书深得多。

很多朋友拿这个题目做毕业设计或者求职项目，但实际动手时经常卡在"不知道从哪下手"。这篇就把宾馆客房管理系统从需求拆解、技术选型、数据库设计到前后端联调、常见坑位，完整走一遍。我会把每一步为什么这么做讲清楚，最后再分享一些我在实际开发中踩过的坑和解决办法。不管你是刚入门Python，还是对Vue有一定基础想练全栈，这篇文章都值得你看到最后。

1. 项目全貌与选型思路：为什么是Vue加Python

1.1 从需求出发拆解系统边界

宾馆客房管理系统，本质上是把线下前台的人工操作搬到线上。前台要管什么？客人来了要订房、入住要登记、住完要退房结账、经理要每天看哪些房间空着、哪些在住、今天收了多少钱。所以核心模块绕不开这几块：

• 客房信息管理：房型、楼层、价格、房间状态（空闲/已预订/已入住/维修）
• 客户信息管理：散客和会员的基本资料、联系方式、入住历史
• 预订管理：客人提前订房，系统锁定房间，避免重复预订
• 入住退房办理：办理入住的登记动作，办理退房的结算动作
• 账单管理：房费、押金、加收费用、退款，最终给出结算单
• 统计看板：实时房态、入住率、今日营收、月度趋势

把这些需求列出来，系统边界就清楚了。千万别一上来就想着搞一堆花哨功能，比如会员积分、早餐券、扫码开门，那些是后话。先把上面六块做扎实，系统已经能应付日常运营了。

1.2 技术选型：Django还是Flask，Vue 2还是Vue 3

技术选型这块，我直接说结论，再解释理由。

后端框架：如果你需要"开箱即用"的管理后台、用户认证、ORM和自动生成接口文档，选Django。它是全家桶，自带Admin后台，你做毕设的时候可以直接用Django Admin管理数据，省去写一堆后台管理前端页面。如果你希望项目更轻量、更灵活，想要自己掌控每个环节，选Flask。它核心代码量很小，数据库用SQLAlchemy，很多教程也是Flask配SQLAlchemy。

我自己的建议是：项目周期短、对Django不熟悉但学过，选Flask；项目周期长、想系统学习Web框架完整生态，选Django。这两个都可以和Vue完美配合，因为前后端分离后，后端只提供API接口，前端只负责渲染页面，框架选型对Vue这边基本没有影响。

前端框架：Vue 3 + Vite + Element Plus是目前的主流搭配。Vue 3的Composition API写起来更清晰，Vite启动速度快，Element Plus组件库做管理后台特别顺手。如果你还在用Vue 2 + Vue CLI，也能做，但长远看新项目建议直接上Vue 3。如果你的课程要求或者模板生成的工程是Vue 2，那也问题不大，下面的思路完全可以平移。

开发工具：PyCharm是JetBrains家专门针对Python的工具，社区版就够用。Vue前端代码可以用PyCharm打开，也可以配VSCode写前端。我习惯这样分工：PyCharm开后端Django/Flask工程，VSCode开前端Vue工程，两个IDE各管一摊，互不干扰。当然你把前端也放到PyCharm里统一管理也没问题，个人习惯而已。

1.3 前后端分离到底怎么理解

很多新手对前后端分离的"分离"理解不透。一句话说清楚：后端不再返回HTML页面，只返回JSON数据。前端拿到JSON数据，用JavaScript渲染成页面。

打个比方，后端是餐厅后厨，把菜做成半成品装盒，前端是外卖包装和摆盘，负责把半成品摆好看端给顾客。顾客（用户）看到的是前端摆好的盘，但他吃的菜是后厨做的。前后端之间通过"接口"（API）传菜，也就是HTTP请求。前端请求某个URL，后端返回对应的JSON，前端再把JSON渲染成表格、卡片、图表。

这套模式的好处是：后端和前端可以并行开发，后端改接口不影响前端联调，前端改页面也不用重启后端服务。项目结构清晰，维护起来也方便。

2. 数据库与后端核心设计：先把房态流转想明白

2.1 数据库表设计：六张表撑起整个系统

数据库设计是整个系统的地基，地基没打好，后面写接口全是坑。宾馆客房管理的核心是"房间状态流转"，所以表设计要围绕房间、客户、订单来展开。

我实际用的表结构是这么设计的：

这几张表的关系是：房型1对多房间，房间1对多预订，客户1对多订单，订单1对1账单。预订表的作用是"占住"房间，入住订单是真正在住的记录。预订被确认后，房间状态变为"已预订"；客人到店办理入住，把预订转成入住订单，房间状态变为"已入住"；退房结算完成，房间状态恢复"空闲"。

这里有个关键点：房间状态不要直接存一个字符串，而是通过当前是否存在未完成的预订/订单来推算。这样设计更安全，不容易数据不一致。比如房间状态是"已入住"，你就去order表里查有没有该房间且check_out_time为null的记录。如果你直接存冗余状态字段，程序里忘记同步改状态，就会出现"订单显示在住，房间却显示空闲"的尴尬状况。不过为了查询方便，也可以在room表里加一个冗余status字段，但必须在业务代码里统一处理，不能东改一个西改一个。

2.2 Django模型与Django REST Framework示例

后端我用Django + Django REST Framework（DRF）来演示，这套组合写接口效率很高。

先定义模型，以room和order为例：

python复制from django.db import models

class RoomType(models.Model):
    name = models.CharField(max_length=50, verbose_name="房型名称")
    base_price = models.DecimalField(max_digits=10, decimal_places=2, verbose_name="基础价格")
    bed_type = models.CharField(max_length=20, verbose_name="床型")
    area = models.FloatField(verbose_name="面积(平米)")

    class Meta:
        db_table = "room_type"
        verbose_name = "房型"

    def __str__(self):
        return self.name

class Room(models.Model):
    ROOM_STATUS = (
        ("available", "空闲"),
        ("reserved", "已预订"),
        ("occupied", "已入住"),
        ("maintenance", "维修"),
    )
    room_no = models.CharField(max_length=10, unique=True, verbose_name="房间号")
    floor = models.IntegerField(verbose_name="楼层")
    room_type = models.ForeignKey(RoomType, on_delete=models.PROTECT, verbose_name="房型")
    status = models.CharField(max_length=20, choices=ROOM_STATUS, default="available", verbose_name="房间状态")

    class Meta:
        db_table = "room"
        verbose_name = "房间"

    def __str__(self):
        return self.room_no

class Customer(models.Model):
    name = models.CharField(max_length=50, verbose_name="姓名")
    phone = models.CharField(max_length=20, verbose_name="手机号")
    id_card = models.CharField(max_length=18, verbose_name="身份证号")
    is_member = models.BooleanField(default=False, verbose_name="是否会员")
    created_at = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")

    class Meta:
        db_table = "customer"
        verbose_name = "客户"

    def __str__(self):
        return self.name

class Reservation(models.Model):
    RESERVATION_STATUS = (
        ("pending", "待入住"),
        ("checked_in", "已入住"),
        ("cancelled", "已取消"),
    )
    room = models.ForeignKey(Room, on_delete=models.CASCADE, verbose_name="房间")
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE, verbose_name="客户")
    check_in_date = models.DateField(verbose_name="预计入住日期")
    check_out_date = models.DateField(verbose_name="预计离店日期")
    status = models.CharField(max_length=20, choices=RESERVATION_STATUS, default="pending", verbose_name="预订状态")

    class Meta:
        db_table = "reservation"
        verbose_name = "预订记录"

    def __str__(self):
        return f"{self.room.room_no} - {self.customer.name}"

class Order(models.Model):
    ORDER_STATUS = (
        ("open", "在住"),
        ("closed", "已退房"),
    )
    room = models.ForeignKey(Room, on_delete=models.CASCADE, verbose_name="房间")
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE, verbose_name="客户")
    reservation = models.ForeignKey(Reservation, on_delete=models.SET_NULL, null=True, blank=True, verbose_name="关联预订")
    check_in_time = models.DateTimeField(verbose_name="入住时间")
    check_out_time = models.DateTimeField(null=True, blank=True, verbose_name="退房时间")
    status = models.CharField(max_length=20, choices=ORDER_STATUS, default="open", verbose_name="订单状态")

    class Meta:
        db_table = "order_info"
        verbose_name = "入住订单"

    def __str__(self):
        return f"{self.room.room_no} - {self.customer.name}"

class Bill(models.Model):
    order = models.OneToOneField(Order, on_delete=models.CASCADE, verbose_name="关联订单")
    room_fee = models.DecimalField(max_digits=10, decimal_places=2, default=0, verbose_name="房费")
    deposit = models.DecimalField(max_digits=10, decimal_places=2, default=0, verbose_name="押金")
    extra_fee = models.DecimalField(max_digits=10, decimal_places=2, default=0, verbose_name="额外费用")
    total_amount = models.DecimalField(max_digits=10, decimal_places=2, default=0, verbose_name="应收总额")
    status = models.CharField(max_length=20, default="unpaid", verbose_name="账单状态")

    class Meta:
        db_table = "bill"
        verbose_name = "账单"

    def __str__(self):
        return f"Bill-{self.order_id}"

这里有几个设计细节我特别说一下。一是on_delete用PROTECT保护房型关联，房型被引用时不允许直接删除，避免房间变成"无主孤魂"。二是金额用DecimalField，千万别用FloatField，浮点数在计算机里是二进制近似表示，算钱会产生精度问题，比如0.1+0.2不等于0.3。三是Order表名我特意设置成order_info，因为order在SQL里是保留字，直接用容易出问题。

2.3 接口设计与核心业务逻辑：入住退房的状态机

有了模型，还需要设计URL路由和视图函数。以Django + DRF为例，接口设计如下：

办理入住是系统里最核心的动作，它不是"往order表插一条记录"这么简单。完整的入住接口逻辑应该是这样的：

python复制from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from django.utils import timezone
from decimal import Decimal
from .models import Room, Customer, Order, Bill, Reservation

class CheckInView(APIView):
    def post(self, request):
        room_id = request.data.get("room_id")
        customer_id = request.data.get("customer_id")
        reservation_id = request.data.get("reservation_id")
        deposit = request.data.get("deposit", 0)

        try:
            room = Room.objects.get(id=room_id)
        except Room.DoesNotExist:
            return Response({"message": "房间不存在"}, status=status.HTTP_404_NOT_FOUND)

        if room.status not in ("available", "reserved"):
            return Response({"message": "当前房间状态不可办理入住"}, status=status.HTTP_400_BAD_REQUEST)

        customer = Customer.objects.get(id=customer_id)

        order = Order.objects.create(
            room=room,
            customer=customer,
            reservation_id=reservation_id,
            check_in_time=timezone.now(),
            status="open",
        )
        Bill.objects.create(
            order=order,
            deposit=Decimal(deposit),
        )
        room.status = "occupied"
        room.save()

        if reservation_id:
            Reservation.objects.filter(id=reservation_id).update(status="checked_in")

        return Response({"order_id": order.id}, status=status.HTTP_201_CREATED)

退房接口要做的事更多：计算实住时长、算房费、算额外费用、改订单和房间状态、生成账单明细。房费怎么算？我先定义规则：按天计费，当天中午12点前退房不收取当天的整天费用，超过中午12点但不超过18点加收半天房费，超过18点加收全天房费。这个规则直接和行业习惯挂钩。

退房的核心逻辑大致如下：

python复制class CheckOutView(APIView):
    def post(self, request):
        order_id = request.data.get("order_id")
        extra_fee = request.data.get("extra_fee", 0)

        order = Order.objects.select_related("room", "room__room_type").get(id=order_id)
        if order.status == "closed":
            return Response({"message": "该订单已退房"}, status=status.HTTP_400_BAD_REQUEST)

        check_out_time = timezone.now()
        duration = check_out_time - order.check_in_time
        days = duration.days
        seconds = duration.seconds
        room_price = order.room.room_type.base_price

        # 房费计算逻辑
        if seconds <= 12 * 3600:
            pass  # 不足半天，不额外记天数
        elif seconds <= 18 * 3600:
            days += Decimal("0.5")
        else:
            days += 1

        room_fee = room_price * Decimal(days)
        bill = order.bill
        bill.room_fee = room_fee
        bill.extra_fee = Decimal(extra_fee)
        bill.total_amount = bill.room_fee + bill.extra_fee
        bill.status = "paid"
        bill.save()

        order.check_out_time = check_out_time
        order.status = "closed"
        order.save()

        room = order.room
        room.status = "available"
        room.save()

        return Response({"room_fee": room_fee, "total_amount": bill.total_amount})

退房逻辑看起来简单，但实际开发时特别容易忽略几个点。比如退房后房间状态要改回available，但是当天的预订如果已经被占用了呢？这里需要判断有没有同一天的预订。再比如押金处理，如果客人有额外消费，要从押金里扣，多退少补。这些逻辑看起来多，但都是真实业务场景里一定会碰到的问题。我建议在做的时候把业务规则先写成文字文档，比如"退房时如果订单关联的预订还在有效期内但客人没住，预订要自动取消"，然后再写代码。

2.4 用Flask实现的话需要注意什么

如果你选的是Flask，整体思路是一样的，但有几个地方要特别处理。Flask本身不带ORM，一般用SQLAlchemy，数据库迁移用Flask-Migrate。和Django自带Admin不同，Flask需要自己写管理接口或者用Flask-Admin扩展。

这里我给出Flask + SQLAlchemy的模型示例，方便你看差异：

python复制from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class Room(db.Model):
    __tablename__ = "room"
    id = db.Column(db.Integer, primary_key=True)
    room_no = db.Column(db.String(10), unique=True, nullable=False)
    floor = db.Column(db.Integer, nullable=False)
    status = db.Column(db.String(20), default="available")
    room_type_id = db.Column(db.Integer, db.ForeignKey("room_type.id"))
    room_type = db.relationship("RoomType", backref=db.backref("rooms", lazy=True))

class RoomType(db.Model):
    __tablename__ = "room_type"
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50), nullable=False)
    base_price = db.Column(db.Numeric(10, 2), nullable=False)

Flask的路由用装饰器，写法上比Django更自由，但自由也意味着约束少，如果项目大了容易混乱。所以Flask项目一定要自己做好蓝图（Blueprint）划分，比如auth蓝图管登录，room蓝图管房间，order蓝图管订单。对于毕设级别的项目，Flask写起来确实快，但如果你不确定自己的代码组织能力能不能撑起整个项目，Django的规范化约束反而是一种保护。

3. Vue前端页面与接口联调：从登录页到房态看板

3.1 Vue工程结构和路由设计

前端我用Vue 3 + Vite + Element Plus来演示，先看工程结构：

text复制frontend/
  src/
    api/            # 接口请求封装
      auth.js
      room.js
      order.js
      stats.js
      request.js    # axios实例
    router/         # 路由配置
      index.js
    store/          # Pinia状态管理
      user.js
    views/
      Login.vue
      Layout.vue
      Dashboard.vue
      RoomManage.vue
      ReservationManage.vue
      OrderManage.vue
      CustomerManage.vue
      BillManage.vue
      Stats.vue
    App.vue
    main.js

路由配置是前端项目的骨架，我通常这样设计：

javascript复制import { createRouter, createWebHistory } from "vue-router"

const routes = [
  {
    path: "/login",
    component: () => import("@/views/Login.vue"),
  },
  {
    path: "/",
    component: () => import("@/views/Layout.vue"),
    redirect: "/dashboard",
    children: [
      { path: "dashboard", component: () => import("@/views/Dashboard.vue"), meta: { title: "首页看板" } },
      { path: "rooms", component: () => import("@/views/RoomManage.vue"), meta: { title: "房间管理" } },
      { path: "reservations", component: () => import("@/views/ReservationManage.vue"), meta: { title: "预订管理" } },
      { path: "orders", component: () => import("@/views/OrderManage.vue"), meta: { title: "入住管理" } },
      { path: "customers", component: () => import("@/views/CustomerManage.vue"), meta: { title: "客户管理" } },
      { path: "bills", component: () => import("@/views/BillManage.vue"), meta: { title: "账单管理" } },
      { path: "stats", component: () => import("@/views/Stats.vue"), meta: { title: "统计报表" } },
    ],
  },
]

const router = createRouter({
  history: createWebHistory(),
  routes,
})

// 全局前置守卫：登录检查
router.beforeEach((to, from, next) => {
  const token = localStorage.getItem("token")
  if (to.path !== "/login" && !token) {
    next("/login")
  } else {
    next()
  }
})

export default router

这段代码里有个很容易被忽略的点：createWebHistory使用的是HTML5 History模式，URL路径是美观的"/rooms"这种，但生产环境部署到Nginx时如果不做try_files配置，刷新页面就会404。开发调试没问题，但如果你的部署环境不好配，直接用createWebHashHistory反而省心。路由守卫是前端登录控制的常见方式，但要注意它只是"体验优化"层面的控制，真正的鉴权还得靠后端接口验证，前端守卫防君子不防小人。

3.2 登录模块与接口封装

登录模块是前后端联调的第一道关卡。前端流程是：用户输入用户名密码，前端调用后端登录接口，后端校验通过后返回一个token，前端把token存到localStorage，之后每次请求都带上这个token。

请求封装用axios，代码不长但很关键：

javascript复制import axios from "axios"
import { ElMessage } from "element-plus"
import router from "@/router"

const request = axios.create({
  baseURL: "http://localhost:8000/api",
  timeout: 10000,
})

// 请求拦截器：自动携带token
request.interceptors.request.use((config) => {
  const token = localStorage.getItem("token")
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

// 响应拦截器：统一处理错误
request.interceptors.response.use(
  (response) => {
    return response.data
  },
  (error) => {
    if (error.response && error.response.status === 401) {
      localStorage.removeItem("token")
      router.push("/login")
    }
    ElMessage.error(error.response?.data?.message || "请求失败")
    return Promise.reject(error)
  }
)

export default request

登录页面本身没什么好说的，一个表单，两个输入框，一个按钮。重点讲一下登录按钮的loading状态，我见过很多项目忽略这个细节。用户点击登录后，如果接口响应要两三秒，按钮没有loading状态，用户会以为没点着，又点一次，结果创建了两个会话。加上loading状态是举手之劳，但对用户体验影响很大。

vue复制<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="0">
    <el-form-item prop="username">
      <el-input v-model="form.username" placeholder="用户名" autocomplete="username" />
    </el-form-item>
    <el-form-item prop="password">
      <el-input v-model="form.password" type="password" placeholder="密码" show-password autocomplete="current-password" @keyup.enter="handleLogin" />
    </el-form-item>
    <el-button type="primary" style="width: 100%" :loading="loading" @click="handleLogin">
      {{ loading ? "登录中..." : "登录" }}
    </el-button>
  </el-form>
</template>

<script setup>
import { ref, reactive } from "vue"
import { useRouter } from "vue-router"
import { ElMessage } from "element-plus"
import { login } from "@/api/auth"

const router = useRouter()
const formRef = ref()
const loading = ref(false)
const form = reactive({ username: "", password: "" })
const rules = {
  username: [{ required: true, message: "请输入用户名", trigger: "blur" }],
  password: [{ required: true, message: "请输入密码", trigger: "blur" }],
}

async function handleLogin() {
  await formRef.value.validate()
  loading.value = true
  try {
    const res = await login(form)
    localStorage.setItem("token", res.token)
    localStorage.setItem("username", res.username)
    ElMessage.success("登录成功")
    router.push("/dashboard")
  } finally {
    loading.value = false
  }
}
</script>

3.3 房间管理页面和房态可视化

房间管理是宾馆系统的门面页面。如果只是做一个普通的表格，列出房间号、房型、价格、状态，那这个项目只能算及格。真正像样的宾馆管理系统，应该有一个直观的"房态图"——和酒店前台墙上挂着的房态板类似，每间房是一个小方块，不同颜色代表不同状态，点击某个房间可以查看详情或者操作入住退房。

用Element Plus的Card组件加上CSS可以快速实现：

vue复制<template>
  <div class="room-board">
    <el-row :gutter="12">
      <el-col v-for="room in roomList" :key="room.id" :xs="6" :sm="4" :md="3" :lg="2">
        <el-card
          :class="['room-card', room.status]"
          shadow="hover"
          @click="openRoomDetail(room)"
        >
          <div class="room-no">{{ room.room_no }}</div>
          <div class="room-type">{{ room.room_type_name }}</div>
          <div class="room-status">{{ statusMap[room.status] }}</div>
        </el-card>
      </el-col>
    </el-row>
  </div>
</template>

CSS部分对不同状态给不同颜色：空闲用绿色，已入住用红色，已预订用橙色，维修用灰色。这样一眼扫过去，整个宾馆的经营状况清清楚楚。上面对应的卡片颜色是后端返回的status字段，前端用字典映射成中文。

房间详情弹窗里，可以放房间基本信息、当前订单信息、最近预订记录，再加上"办理入住""办理退房""设为维修"三个操作按钮。这样操作员不需要跳转页面，在一个弹窗里完成日常动作，效率高很多。

3.4 预订和入住退房的前端交互流程

预订管理页面，核心是"选房"这个动作。用户选择入住日期、离店日期，系统先查出这个时间段内可用的房间列表，然后用户挑一间下单。前端要做的是在日期选择变化时，调用后端接口重新查询可用房间。

后端查询可用房间的接口可以这样设计：接收开始日期和结束日期，排除在这段时间内已有预订或已有入住订单的房间。

python复制class AvailableRoomsView(APIView):
    def get(self, request):
        check_in = request.query_params.get("check_in")
        check_out = request.query_params.get("check_out")

        # 获取在check_in到check_out时间段内被占用或预订的房间id
        conflict_room_ids = set()

        reserved_rooms = Reservation.objects.filter(
            status__in=["pending", "checked_in"],
            check_in_date__lt=check_out,
            check_out_date__gt=check_in,
        ).values_list("room_id", flat=True)

        occupied_rooms = Order.objects.filter(
            status="open",
            check_in_time__date__lt=check_out,
        ).filter(
            check_out_time__isnull=True,
        ).values_list("room_id", flat=True)

        conflict_room_ids = set(reserved_rooms) | set(occupied_rooms)

        available_rooms = Room.objects.exclude(
            status="maintenance"
        ).exclude(
            id__in=conflict_room_ids
        )

        serializer = RoomSerializer(available_rooms, many=True)
        return Response(serializer.data)

判断房间是否冲突这个逻辑，不是简单地"开始日期不在已有预订范围内"，而是要考虑到重叠区间。假设房间A在2025年1月3日入住、2025年1月5日退房，如果有客人想在1月4日入住、1月6日离开，这个时间段就重叠了，房间不能分配。区间重叠判断的标准是：新预订的开始日期 < 已有预订的结束日期 且 新预订的结束日期 > 已有预订的开始日期。

入住退房的交互流程，我建议做成一个"操作向导"。点入住时弹出一个对话框，选择客户（可以输入手机号快速查找，如果不存在就当场登记新客户）、关联预订（可选）、输入押金金额。点退房时弹出订单详情确认框，显示该房间的入住时间、当前时间、房费明细、额外费用输入框，确认后生成结算单。

4. 开发环境搭建与实操过程：PyCharm配置到前后端联调

4.1 PyCharm环境配置与项目初始化

开发环境这块，我先说几个新手容易踩的坑，然后再走流程。

坑一：直接在全局Python环境装包。Python是一门会"污染"的语言，如果你直接用系统Python装Django，装了一堆乱七八糟的包，每个项目之间很可能会相互干扰。这就像你在一个房间里住着好几个互不相干的人，今天A要装个Django 4，明天B要装Django 2，两个人打架。所以每个项目必须建虚拟环境。

坑二：虚拟环境路径带中文或空格。PyCharm创建虚拟环境如果路径里有中文，后面跑Django项目有时候会莫名其妙报错，最好所有项目路径都用英文。

具体流程是这样的：先用PyCharm新建一个项目，选择虚拟环境作为项目解释器。

bash复制# 创建后端项目目录
mkdir hotel-backend
cd hotel-backend

# 创建虚拟环境（venv是Python自带的工具，不需要额外安装）
python -m venv venv

# 激活虚拟环境（Windows）
venv\Scripts\activate
# 激活虚拟环境（macOS/Linux）
source venv/bin/activate

# 安装依赖
pip install django djangorestframework django-cors-headers

装完依赖后，创建一个Django项目和应用：

bash复制django-admin startproject hotel .
python manage.py startapp rooms
python manage.py startapp orders
python manage.py startapp customers
python manage.py startapp bills

新建应用后，记得把应用注册到settings.py的INSTALLED_APPS里，这个步骤忘了做，数据库迁移的时候会提示"No installed app with label"。

4.2 数据库配置与迁移

如果做毕设，我推荐直接用SQLite开发期存储，原因很简单：零配置，文件型数据库，PyCharm自带的Database面板就能直接查看数据。等到部署上线再切换到MySQL。在settings.py里，默认配置就是SQLite，不需要改。

但这里我要多说一句。SQLite虽然开发期方便，但不适合生产环境并发访问，尤其是酒店这种有多个前台同时操作的场景。所以最终部署时，建议换成PostgreSQL或者MySQL。切换数据库其实不复杂，改一下settings.py的DATABASES配置，安装对应的驱动，然后重新跑一次迁移命令即可。

迁移命令：

bash复制python manage.py makemigrations
python manage.py migrate

makemigrations会根据模型变化生成迁移文件，migrate把迁移文件应用到数据库。这两个命令一定要分步执行，不要合并成一条，因为有时候makemigrations会提示模型冲突或者字段问题，需要你手动处理。

4.3 创建超级管理员与测试数据

创建超级管理员是Django的福利，一条命令搞定：

bash复制python manage.py createsuperuser

用管理员账号登录Django Admin后台，你可以直接往表里加数据。毕竟你的前端页面还没做出来，没有数据你联调个啥。

在实际开发中，我习惯写一个自定义management command来自动生成测试数据，这样每次清库重建不用手动重复输入：

python复制# rooms/management/commands/seed_data.py
from django.core.management.base import BaseCommand
from rooms.models import RoomType, Room

class Command(BaseCommand):
    help = "生成房间测试数据"

    def handle(self, *args, **options):
        standard = RoomType.objects.create(name="标准间", base_price=199, bed_type="1.5m大床", area=20)
        deluxe = RoomType.objects.create(name="豪华间", base_price=399, bed_type="2m大床", area=35)
        suite = RoomType.objects.create(name="套房", base_price=699, bed_type="2m大床+客厅", area=60)

        for floor in range(1, 6):
            for num in range(1, 9):
                room_no = f"{floor}0{num}"
                if floor <= 2:
                    room_type = standard
                elif floor <= 4:
                    room_type = deluxe
                else:
                    room_type = suite
                Room.objects.create(room_no=room_no, floor=floor, room_type=room_type)

        self.stdout.write(self.style.SUCCESS("测试数据生成完毕"))

执行：

bash复制python manage.py seed_data

有了测试数据，前端页面调接口就有东西可看，真实感完全不同。

4.4 前端环境准备与启动

前端我用Vite创建Vue 3工程：

bash复制npm create vite@latest hotel-frontend -- --template vue
cd hotel-frontend
npm install
npm install element-plus axios vue-router pinia echarts
npm run dev

打开浏览器访问http://localhost:5173，看到Vue欢迎页就说明前端环境没问题。但这时候前端还连不上后端，因为Django服务还没启动，而且跨域问题没解决。

4.5 跨域配置：前后端联调必做的一步

前后端分离开发时，前端跑在5173端口，后端跑在8000端口，浏览器会发起跨域请求。浏览器默认拦截跨域请求，所以后端必须配合开启CORS（跨域资源共享）。

Django配置跨域很简单，安装django-cors-headers：

bash复制pip install django-cors-headers

然后在settings.py里配置：

python复制INSTALLED_APPS = [
    ...
    "corsheaders",
]

MIDDLEWARE = [
    "corsheaders.middleware.CorsMiddleware",
    ...
]

# 开发环境允许所有来源跨域，生产环境请改为具体域名
CORS_ALLOW_ALL_ORIGINS = True

# 允许携带凭证
CORS_ALLOW_CREDENTIALS = True

如果你的前端用了token认证方式，请求头里带Authorization字段，还需要额外配置允许的请求头。django-cors-headers默认允许Authorization，所以基本不用额外配。如果前端用cookie会话认证，那要设置CORS_ALLOW_CREDENTIALS = True，但这里有个坑：当allow_credentials为True时，浏览器不允许后端设置"*"作为允许来源，必须指定具体域名。这也是为什么很多教程里强调开发环境用CORS_ALLOW_ALL_ORIGINS = True，但生产环境必须明确配置域名白名单。

Flask配置CORS也有对应的Flask-CORS扩展，用法类似。

4.6 整体联调流程：一条数据的完整旅程

联调不是等所有接口写完了才开始，而是每写完一个模块就联调一个。我建议按这个顺序推进：

1. 先做登录接口，前端登录页能拿到token并跳转
2. 再做房间列表接口，前端房间管理页能展示房态图
3. 再做客户创建接口，前端入住弹窗能登记客户
4. 再做预订接口，前端预订页能成功下单
5. 再做入住接口，前端能办理入住
6. 再做退房接口，前端能结算账单
7. 最后做统计接口，前端图表能展示数据

一条数据完整走一圈是什么样的？我举个例子。某天前台接到电话，客人王先生要预订3号晚上标准间一间。操作员打开预订页面，选1月3日到1月5日，系统查询可用房间，结果显示"301"可用。操作员录入王先生的姓名和手机号，提交预订，前端调用POST /api/reservations/，后端创建一条reservation记录，room.status变为"reserved"。1月3日王先生到店，操作员搜索手机号找到客户，点办理入住，选择关联那条预订，输入押金200元，提交。后端创建order和bill，room.status变为"occupied"。1月5日王先生退房，操作员点退房，系统算出房费399元，押金扣除房费，再补刷199元，生成退房账单，room.status变回"available"。整个过程，每个环节前端都有数据实时反馈，才算真正联调通过。

5. 常见问题排查与避坑记录

5.1 问题速查表

下面这些坑，是我自己开发这类系统时真实踩过的，有的甚至花了一整天才排查出来。整理成速查表，希望对你有帮助。

5.2 我花过最长的一次排查：明明逻辑对但数据不显示

有一次我写完统计接口，前端图表死活不显示数据。用浏览器开发者工具看Network，接口返回200，数据也有，就是渲染不出来。后来我发现是字段名对不上——后端返回的字段叫total_revenue，前端图表里用的是revenue，key不匹配，数据拿不到自然没展示。

这个问题很基础，但很能说明前后端联调的核心难题：接口契约不统一。后端定义接口的时候，字段名是什么就固定什么，前端必须严格按这个字段名取数据。团队开发时接口文档很重要，自己一个人开发时也要养成"后端先定义好返回值结构，前端再按结构写代码"的习惯。

我后来的做法是给每个接口写一个简单的返回格式说明，标注字段名、类型、含义。虽然多花几分钟，但能省下很多联调时左右来回看代码的时间。

5.3 防患于未然：开发阶段就要注意的六个细节

有些问题在开发阶段就可以提前规避，不用等到上线了才发现。

第一，数据库表名和字段名尽量用英文，不要用中文命名。虽然SQLite和MySQL都支持中文表名，但你在写SQL查询、排错的时候会遇到各种编码问题，纯属给自己找麻烦。

第二，接口返回结构尽量统一。比如统一用{code, message, data}包裹，前端拦截器统一处理。别一个接口直接返回数组，另一个接口返回对象，前端写起来很痛苦。

第三，不要在前端代码里硬编码后端地址。axios的baseURL应该通过环境变量来配，开发环境用.dev文件，生产环境用.production文件。不然你部署的时候，要一个文件一个文件地找localhost替换。

第四，前后端本地时间一定要对齐。如果你的电脑时区是UTC+8，服务器时区是UTC，前后端时间对不上，会出现"客人明明预定了今天，系统显示昨天"这种离谱问题。后端接口返回时间全部用UTC的ISO格式，前端获取到之后用dayjs转换成本地时区展示。

第五，Git从第一天就开始用。不要等代码写了一大堆再初始化仓库，每天提交一次，改一个功能提交一次。你做系统的时候经常要改数据库字段，改错了还能回滚，没Git就只能靠记忆恢复，太痛苦了。

第六，备份数据库。SQLite是一个文件，开发阶段每天备份一次数据库文件，放进一个不提交到Git的backup目录里。真到了数据库坏了只能重建数据的时候，你会感谢这个习惯。

5.4 从开发到部署：这个项目还能怎么扩展

项目跑通后，如果你还有余力，下面这几个方向的价值很大。第一，增加房间清洁管理，退房后房间状态变成"待清洁"，清洁完改为"可售"，这是真实酒店系统里一定有的一环。第二，增加会员系统和积分管理，会员价和非会员价不同，积分可以抵扣房费。第三，接入支付接口，比如生成微信/支付宝付款二维码，方便线上收款。第四，把统计报表做得更丰富，用ECharts画出月度入住率趋势、房型营收占比、客户来源分布。第五，部署上线，用Nginx托管前端静态文件，用Gunicorn或uWSGI跑Django应用，数据库换成MySQL或PostgreSQL，再配一个HTTPS证书。

这些扩展不是异想天开，而是我在做类似项目时真实收到过的"需求迭代"。从系统开发到上线，再到后续维护加功能，你才能体会到写代码只是软件开发里很小的一部分。

做这个系统最大的体会是，写代码前先把业务流程想透，比直接打开IDE猛敲重要得多。我在动手前，先写了一份业务规则文档，包括预订规则、入住规则、退房规则、房费计算规则，后面前后端开发全都按这份文档对齐，少走了很多弯路。你在做这个项目的时候，也不妨先做这件事——把"宾馆怎么运作"这个问题查明白、写清楚，后面每一步开发都会顺畅很多。