数据库客房管理系统中的预订、入住与退房流程怎么实现

客房管理系统看起来像一组表单：选房、登记住客、办理入住、结账退房。真正容易出错的地方却在数据库边界上：两名员工同时预订同一间房怎么办？退房日期算不算入住？顾客取消后房间何时释放？接口重试会不会重复办理？

本文以 PostgreSQL 和 Python（psycopg 3）为例，搭建一套精简但有实际约束的流程。示例关注单店、每笔预订指定一间客房的场景；多房间订单、床位管理、分房和支付对账需要在此基础上扩展。代码把关键操作放进数据库事务，适合用作业务实现的起点，而不是完整的酒店行业标准。

一、先明确业务规则

实现前，先把几个容易混淆的概念写成规则：

• 预订日期是入住日和退房日。本文使用“入住日包含、退房日不包含”的区间。例如入住 6 月 10 日、退房 6 月 12 日，占用 10 日和 11 日两晚。
• 预订状态和客房状态不是一回事。预订有待入住、已入住、已退房、已取消等状态；客房可以另有维护状态。是否被住客占用，应依据有效预订及实际入住情况判断，而不是只依赖一个可能过期的“空闲”标记。
• 房间分配是一项有并发风险的操作。应用层先查询“空房”再插入，两个请求可能同时查到同一间房。最终约束必须由数据库保证。
• 支付和预订状态应分开处理。示例不保存银行卡信息，也不把“办理退房”当作“退款成功”。接入支付渠道时，应另外设计支付流水和对账流程。

本文规定：同一间房的有效预订不能有重叠日期；已取消和已退房的预订不再占用预订区间。入住操作只能针对待入住预订，退房只能针对已入住预订。提前入住、延迟退房、改房和无预订入住都需要明确的业务规则，不能仅靠修改状态来处理。

二、建立数据库表与防重叠约束

PostgreSQL 的排斥约束可以在数据库层防止日期区间重叠。下面使用 btree_gist 扩展，让房间编号和日期范围一起参与约束。创建扩展通常需要数据库管理员或具备相应权限的账号；如果环境不允许安装扩展，需要采用带锁的替代方案，不能删掉约束后只依赖前端判断。

CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TABLE rooms (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    room_number TEXT NOT NULL UNIQUE,
    room_type   TEXT NOT NULL,
    maintenance BOOLEAN NOT NULL DEFAULT FALSE
);

CREATE TABLE reservations (
    id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    room_id         BIGINT NOT NULL REFERENCES rooms(id),
    guest_name      TEXT NOT NULL,
    guest_phone     TEXT,
    check_in_date   DATE NOT NULL,
    check_out_date  DATE NOT NULL,
    status          TEXT NOT NULL DEFAULT 'reserved',
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    checked_in_at   TIMESTAMPTZ,
    checked_out_at  TIMESTAMPTZ,

    CONSTRAINT reservation_dates_valid
        CHECK (check_out_date > check_in_date),

    CONSTRAINT reservation_status_valid
        CHECK (status IN ('reserved', 'checked_in', 'checked_out', 'cancelled')),

    CONSTRAINT reservation_stay_no_overlap
        EXCLUDE USING gist (
            room_id WITH =,
            daterange(check_in_date, check_out_date, '[)') WITH &&
        )
        WHERE (status IN ('reserved', 'checked_in'))
);

CREATE INDEX reservations_status_dates_idx
    ON reservations (status, check_in_date, check_out_date);

daterange(..., '[)') 表示左闭右开区间，所以一笔预订在 10 日退房，另一笔可以在 10 日入住，两者不会被视为重叠。排斥约束会在并发写入时由数据库裁决；竞争失败的一方会得到约束错误，而不是悄悄造成双重预订。

约束只覆盖 reserved 和 checked_in 状态。把记录改为 cancelled 后，该区间不再占用房间。生产系统应限制谁能修改状态，并记录取消时间、操作人和原因。本文的简化表没有包含操作审计、住客证件、房价快照、税费或多住客关系，实际系统需要依据隐私和当地合规要求另行设计。

注意，排斥约束检查的是预订上的计划日期，不会自动知道住客是否实际晚退房。若住客延迟离店，下一笔预订仍可能从原定退房日开始。系统应在允许延迟时更新可售安排、阻止后续入住或执行换房流程，不能把计划退房时间等同于实际空房时间。

三、预订：校验输入，并让数据库处理竞争

应用侧应先检查输入格式和基本业务条件，但不能把“查到房间可用”当作并发安全保证。可用性查询主要用于向用户展示候选房间；最终插入仍必须依赖数据库约束。

下面的示例使用 psycopg 3。先安装依赖：python -m pip install "psycopg[binary]"。连接串从环境变量读取，避免把数据库密码写进源代码。代码里的日期必须是 Python date 对象，房间 ID 必须来自已存在的客房记录。

import os
from datetime import date
import psycopg
from psycopg.errors import ExclusionViolation

DSN = os.environ["DATABASE_URL"]

def create_reservation(
    room_id: int,
    guest_name: str,
    guest_phone: str | None,
    check_in: date,
    check_out: date,
) -> int:
    if not guest_name or not guest_name.strip():
        raise ValueError("住客姓名不能为空")
    if check_out <= check_in:
        raise ValueError("退房日期必须晚于入住日期")

    try:
        with psycopg.connect(DSN) as conn:
            with conn.cursor() as cur:
                cur.execute(
                    """
                    SELECT maintenance
                    FROM rooms
                    WHERE id = %s
                    FOR UPDATE
                    """,
                    (room_id,),
                )
                room = cur.fetchone()
                if room is None:
                    raise ValueError("客房不存在")
                if room[0]:
                    raise ValueError("客房正在维护，不能预订")

                cur.execute(
                    """
                    INSERT INTO reservations
                        (room_id, guest_name, guest_phone,
                         check_in_date, check_out_date, status)
                    VALUES (%s, %s, %s, %s, %s, 'reserved')
                    RETURNING id
                    """,
                    (room_id, guest_name.strip(), guest_phone,
                     check_in, check_out),
                )
                reservation_id = cur.fetchone()[0]
            # psycopg 的连接上下文正常退出时提交；
            # 发生异常时回滚。
        return reservation_id
    except ExclusionViolation as exc:
        raise ValueError("该客房在所选日期已被预订") from exc

%s 是 psycopg 的参数占位符。参数化查询可以避免把用户输入拼接进 SQL，从而降低 SQL 注入风险；它不负责校验姓名、电话是否符合业务要求，也不替代权限控制。不要把占位符替换成字符串格式化，例如 f"…{guest_name}…"。

FOR UPDATE 锁定客房行，在本事务结束前阻止其他事务同时修改该客房行。这对于与客房记录关联的维护状态检查有帮助，但它本身不是日期重叠保护：只有所有写入路径都遵守相同锁策略时，应用层锁方案才可靠。此处真正防止同房日期重叠的是排斥约束。无论是否保留这把锁，约束都应存在。

捕获排斥冲突后，示例把它转为便于界面展示的业务错误。正式接口还应区分输入错误、房间不存在、房间维护、日期冲突和数据库暂时不可用；不要把所有异常都回复为“房间已被预订”。在事务中发生 SQL 异常后，事务通常已进入失败状态，不能在同一事务里继续执行其他查询，应该回滚后再处理。

四、入住：检查状态、日期与客房条件

入住时不能仅凭预订编号直接改状态。至少要检查该预订是否存在、是否仍为待入住、是否到达允许办理入住的日期，以及客房是否仍可使用。政策允许提前入住时，应把允许提前的规则显式写入系统；下面的示例只接受入住日期当天或之后、且早于退房日的办理日期。

代码使用客房行锁和预订行锁，并在同一事务中完成校验与状态更新。实际到店日期由应用显式传入，方便使用酒店营业地的当地日期；不要随意拿服务器所在地的日期代替门店时区。

def check_in(reservation_id: int, local_today: date) -> None:
    with psycopg.connect(DSN) as conn:
        with conn.cursor() as cur:
            cur.execute(
                """
                SELECT room_id, check_in_date, check_out_date, status
                FROM reservations
                WHERE id = %s
                FOR UPDATE
                """,
                (reservation_id,),
            )
            reservation = cur.fetchone()
            if reservation is None:
                raise ValueError("预订不存在")

            room_id, start, end, status = reservation
            if status != "reserved":
                raise ValueError("当前预订状态不能办理入住")
            if local_today < start or local_today >= end:
                raise ValueError("当前日期不在可办理入住的预订区间内")

            cur.execute(
                """
                SELECT maintenance
                FROM rooms
                WHERE id = %s
                FOR UPDATE
                """,
                (room_id,),
            )
            room = cur.fetchone()
            if room is None:
                raise ValueError("预订对应的客房不存在")
            if room[0]:
                raise ValueError("客房正在维护，不能办理入住")

            cur.execute(
                """
                UPDATE reservations
                SET status = 'checked_in',
                    checked_in_at = now()
                WHERE id = %s
                """,
                (reservation_id,),
            )

这里将入住记录时间保存为 TIMESTAMPTZ，由数据库记录时间点；酒店当地日历日期则由业务层明确传入。部署时应统一时区策略，并在接口层校验日期来源。若入住操作可能由多个服务或员工终端触发，可以在更新语句中再加状态条件，例如 WHERE id = %s AND status = 'reserved'，并检查受影响行数是否为 1，避免基于过期状态完成更新。

行锁应尽量按固定顺序获取，降低不同操作交叉锁定导致死锁的概率。示例先锁预订再锁客房；其他会同时锁这两类记录的流程也应遵循同一顺序。数据库仍可能在复杂业务中检测到死锁，应用可以对明确可重试的死锁错误进行有限次数重试，但不能无条件重试所有异常。

五、退房：完成状态迁移，不代表结清所有款项

退房的核心是验证状态后更新记录。重复提交不能把已退房预订再次处理，也不应覆盖第一次退房时间。下面使用条件更新实现状态门槛；如果没有更新到一行，说明预订不存在，或已经处于其他状态。

def check_out(reservation_id: int) -> None:
    with psycopg.connect(DSN) as conn:
        with conn.cursor() as cur:
            cur.execute(
                """
                UPDATE reservations
                SET status = 'checked_out',
                    checked_out_at = now()
                WHERE id = %s
                  AND status = 'checked_in'
                RETURNING id
                """,
                (reservation_id,),
            )
            if cur.fetchone() is None:
                raise ValueError("预订不存在，或当前状态不能办理退房")

在自动提交关闭的事务连接中，异常会使事务回滚，因此退房更新不会只执行一半。如果退房还要生成账单、登记房费或发送消息，应区分数据库内可原子完成的操作和外部系统调用。数据库事务无法自动回滚已经发给支付服务的请求。常见做法是事务内写入账单或待发送事件，再由后台任务可靠地处理外部通知。

示例只更新预订状态，没有计算房费，也没有扣款、退款或押金结算。生产系统应保存消费明细和支付流水，明确金额、币种、支付渠道交易号及退款状态，并针对支付请求设计幂等机制。不要把卡号、安全码等敏感支付数据存进这张预订表。

六、可用房间查询与“看起来可订”的误区

下面的查询按给定日期区间列出没有有效预订冲突、且不在维护中的房间。查询中的范围同样采用左闭右开语义：

SELECT r.id, r.room_number, r.room_type
FROM rooms AS r
WHERE r.maintenance = FALSE
  AND NOT EXISTS (
      SELECT 1
      FROM reservations AS x
      WHERE x.room_id = r.id
        AND x.status IN ('reserved', 'checked_in')
        AND daterange(x.check_in_date, x.check_out_date, '[)')
            && daterange(%s::date, %s::date, '[)')
  )
ORDER BY r.room_number;

查询结果只是某一时刻的候选列表。用户选中房间到提交预订之间，其他请求可能先完成预订，所以插入仍可能收到冲突。界面应将冲突作为正常业务结果提示用户重新选择，而不是显示系统故障，也不应因为前一次查询显示“可用”就跳过数据库约束。

有些业务先收集预订需求、之后才分房。那时应把“预订订单”和“客房分配”拆开：订单保存日期和人数，分房记录在分配时建立并加约束。本文将 room_id 直接放在预订表，适用于预订时已经选定客房的简化模型，不宜直接套用到复杂的房型库存场景。

七、常见错误与需要补齐的边界

• 用字符串比较日期，或混用含不含退房日的规则。日期应使用数据库 DATE 类型和明确的区间边界。界面、报表、查询与约束必须采用同一约定。
• 只在应用里先查后写。并发请求会让“先查空房、再插入”的检查失效。使用数据库约束，或设计严格的锁和事务方案。
• 把房间是否可用存成一个孤立布尔值。预订、维修和实际占用可能改变该值；如果需要缓存房态，应能从权威数据重建，并避免缓存值成为唯一判定依据。
• 允许任意修改状态。应定义合法状态迁移，例如待入住可取消或入住，已入住可退房；已退房不能被普通接口直接改回待入住。状态更新需要权限和审计记录。
• 不考虑取消、改期和换房。取消要记录原因与操作信息；改期需在事务中重新验证新日期；换房需同时处理旧房释放和新房分配，不能先释放旧房再因新房冲突留下半完成状态。
• 把延迟退房当作普通退房。实际离店时间、计划日期和清洁完成时间是不同信息。下一位客人能否入住还取决于客房清洁和维护流程。
• 忽略请求重复提交。数据库状态条件可减少重复入住或退房，但创建预订接口在网络超时后被重试仍可能创建两笔订单。可为创建请求增加幂等键，并在数据库中对该键建立唯一约束。
• 过度返回个人信息。姓名和联系方式属于个人信息。应按业务需要收集、限制访问、设定保留期限，并避免把敏感信息、连接串或 SQL 参数原样写入日志。

八、上线前的检查清单

部署前至少验证以下情况：合法日期能成功预订；退房日等于另一笔入住日时不冲突；同一客房的重叠预订无法同时提交；取消后房间可再次预订；不存在的房间不能预订；维护中的房间不能入住；已取消或已退房记录不能办理入住；未入住的预订不能直接退房；重复的入住、退房请求不会重复产生业务结果。

还应在测试环境模拟并发请求，而不只是逐条执行 SQL。检查数据库账号是否仅拥有所需权限，迁移是否可重复部署，扩展是否已安装，并为约束冲突、死锁、连接超时设置适当的错误处理与监控。涉及日期变更时，测试跨月、跨年和酒店时区切换等情况。

核心原则是：预订负责锁定计划区间，入住和退房负责受控的状态迁移，数据库约束负责兜住并发下的数据一致性。把这三件事分清，并明确取消、延迟退房、改房和支付等边界，客房管理流程就不只是“几条更新语句”，而是一套可验证、可恢复的业务事务。