简介

本设计文档聚焦 DouPHP 预约系统的数据库表结构与数据模型，覆盖预约主表、预约项目、时段配置、规则与时段明细、黑名单、日志与通知等核心表。文档面向开发者与业务运营人员，提供：

• 表字段说明、索引与约束
• 预约状态流转与冲突检测的数据支撑
• 时段管理与规则配置的数据模型
• 通知提醒与审计日志的关联设计
• 并发控制策略建议（基于现有索引与事务）

项目结构

预约模块相关代码主要分布在以下位置：

• 数据库定义：_'\module\book\storage\backup\book.sql
• 后台模型：admin/model/book/*
• 前端路由：front/route/book.php
• 审计日志写入：core/service/audit/AuditService.php
• 语言常量：languages/zh_tw/book.lang.php

graph TB
A["数据库定义<br/>book.sql"] --> B["后台模型<br/>admin/model/book/*"]
B --> C["业务服务/控制器<br/>front/route/book.php"]
C --> D["审计日志写入<br/>AuditService.php"]
C --> E["通知记录表<br/>dou_book_notify"]
B --> F["黑名单表<br/>dou_book_blacklist"]

核心组件

本节概述预约系统的关键数据实体及其职责：

• 预约主表：记录一次预约的核心信息、状态、支付与签到等
• 预约项目表：定义可预约的服务或医生项目及其默认时长、容量、价格等
• 预约时段表：按周几配置项目的可用时段、时长、容量与加价
• 预约规则表与时段明细：对特定日期范围/星期进行时段覆盖、增减容量与价格调整
• 黑名单表：限制特定用户或全局的预约权限
• 操作日志表：记录预约状态变更的操作轨迹
• 通知记录表：记录短信、邮件、微信、App 等通知发送情况

架构总览

预约系统通过“项目—时段—规则”三层配置，结合“黑名单—日志—通知”保障业务闭环。

erDiagram
dou_book ||--o{ dou_book_log : "关联"
dou_book ||--o{ dou_book_notify : "关联"
dou_book }o--|| dou_book_item : "item_id"
dou_book }o--|| dou_book_class : "class_id(间接)"
dou_book_schedule ||--|| dou_book_item : "item_id"
dou_book_rule ||--o{ dou_book_rule_slot : "rule_id"
dou_book_blacklist ||--|| dou_book_item : "item_id(0=全局)"

详细组件分析

预约主表（dou_book）

• 作用：承载一次预约的完整生命周期数据，包括预约人信息、时间、人数、价格、支付、状态、确认/取消/完成/过期、签到等。
• 关键字段
  • 标识与关联：id、book_sn、user_id、item_id、contact_id
  • 时间与容量：book_date、start_time、end_time、people_count
  • 价格与订单：price、pay_status、paid_at、order_sn
  • 状态与审计：status、confirmed_at、cancelled_at、cancel_reason、released_at、checkin_status、checked_in_at、confirm_work_id、confirm_admin_id、checkin_work_id、checkin_admin_id
  • 其他：ip、created_at、updated_at
• 索引与查询优化
  • 唯一键 book_sn
  • 复合索引 (book_date, start_time) 用于冲突检测与排班查询
  • 单列索引 user_id、item_id、contact_id、status、created_at、released_at
• 状态语义（来自语言常量）
  • 0 待确认、1 已确认、2 已完成、3 已取消、4 已过期、5 已拒绝

flowchart TD
Start(["创建预约"]) --> CheckBlacklist{"是否命中黑名单?"}
CheckBlacklist --> |是| Reject["拒绝/不可预约"]
CheckBlacklist --> |否| CheckConflict{"时段是否冲突?"}
CheckConflict --> |是| Reject
CheckConflict --> |否| CreateOrder["生成预约单号并落库"]
CreateOrder --> Log["写入操作日志"]
Log --> Notify["生成通知记录"]
Notify --> End(["等待确认/支付"])

预约项目表（dou_book_item）

• 作用：定义可预约的项目（如科室、医生、服务），包含默认时长、容量、提前预约天数、取消截止时间、价格、简介与详情等。
• 关键字段
  • 分类与标识：class_id、name、tag、code、image
  • 价格与时长：price、original_price、duration
  • 容量与限制：capacity、advance_days、min_advance_hours、max_advance_hours、cancel_deadline_hours
  • 限额策略：item_day_limit、item_period_days、item_period_limit
  • 展示与排序：brief、content、sort、status、created_at、updated_at
• 索引
  • 唯一键 code
  • 索引 class_id、status

预约时段表（dou_book_schedule）

• 作用：为项目按周几配置可用时段、时长、容量与加价，支持按项目默认时长自动切分。
• 关键字段
  • item_id、weekday、start_time、end_time、duration、capacity、price_extra、sort、status、created_at
• 索引
  • 复合索引 (weekday, start_time) 用于快速检索某日某周的可用时段

预约规则表与时段明细（dou_book_rule / dou_book_rule_slot）

• 作用：对特定日期范围或星期进行时段覆盖、容量增减与价格调整，支持优先级与启用状态。
• 规则表关键字段
  • name、item_id（0表示全局）、rule_type（closed/replace/add/override）、priority、date_type（single/range/weekly/monthly）、start_date、end_date、weekdays、status、created_at、updated_at
• 时段明细关键字段
  • rule_id、start_time、end_time、duration、capacity、capacity_mode（set/inc/dec）、price_extra、price_mode（set/inc/dec/percent_inc/percent_dec）、sort、created_at
• 索引
  • 规则表：item_id、(start_date, end_date)、status
  • 时段明细：rule_id

黑名单表（dou_book_blacklist）

• 作用：限制用户预约能力，支持全局或指定项目维度，记录操作者类型/ID、原因与有效期。
• 关键字段
  • item_id（0=全局）、user_id、operator_type（admin/work）、operator_id、reason、expired_at、created_at
• 索引
  • 唯一键 (user_id, item_id)
  • 索引 expired_at 便于过期清理

操作日志表（dou_book_log）

• 作用：记录预约状态变更的操作轨迹，包括操作者类型/ID、动作、前后状态、备注、IP、时间。
• 关键字段
  • book_id、operator_type（admin/user/work）、operator_id、action、before_status、after_status、remark、ip、created_at
• 索引
  • book_id、(operator_type, operator_id)、created_at

通知记录表（dou_book_notify）

• 作用：记录预约相关的通知发送情况，包括方式、事件、接收地址、内容、发送状态与响应。
• 关键字段
  • book_id、user_id、notify_type（sms/email/wechat/app）、notify_event（confirm/remind/cancel/checkin/expire）、receiver、content、send_status、sent_at、response、created_at
• 索引
  • book_id、user_id、send_status

预约项目分组表（dou_book_class）

• 作用：组织项目分组，支持层级 parent_id，并可设置默认时长、容量、提前预约天数、取消截止时间及限额策略。
• 关键字段
  • slug、name、icon、description、parent_id、sort、status、duration、capacity、advance_days、min_advance_hours、max_advance_hours、cancel_deadline_hours、class_day_limit、class_period_days、class_period_limit、item_day_limit、item_period_days、item_period_limit、created_at
• 索引
  • parent_id、status

依赖关系分析

• 预约主表依赖项目表（item_id）获取默认时长、容量、价格与限额策略；依赖分组表（通过项目）继承部分默认值。
• 时段表按项目与周几提供基础可用时段；规则表与时段明细可对特定日期/星期进行覆盖或调整。
• 黑名单表在预约前校验，阻止被限制的用户或全局禁止。
• 操作日志与通知表在预约创建、确认、拒绝、完成、过期、签到等关键节点写入。

graph LR
Item["项目表<br/>dou_book_item"] --> Schedule["时段表<br/>dou_book_schedule"]
Rule["规则表<br/>dou_book_rule"] --> Slot["规则时段明细<br/>dou_book_rule_slot"]
Schedule --> Book["预约主表<br/>dou_book"]
Slot --> Book
Blacklist["黑名单表<br/>dou_book_blacklist"] --> Book
Book --> Log["操作日志<br/>dou_book_log"]
Book --> Notify["通知记录<br/>dou_book_notify"]

性能与并发控制

• 冲突检测
  • 使用 (book_date, start_time) 复合索引快速判断同一时间段是否已有预约，避免全表扫描。
  • 建议在插入/更新预约时以事务包裹“检查+插入”，确保原子性。
• 容量控制
  • 时段表 capacity 与预约 people_count 共同决定占用；在高并发场景下，建议使用行级锁或乐观锁（版本号）防止超卖。
• 规则与覆盖
  • 规则表 priority 与 date_type 决定生效顺序；计算可用时段时应先加载基础时段，再按规则优先级应用覆盖/增减。
• 黑名单校验
  • 使用唯一键 (user_id, item_id) 快速判定；expired_at 索引支持定时任务清理过期黑名单。
• 日志与通知
  • 日志与通知写入应异步化或批量处理，避免阻塞主流程；send_status 索引便于重试失败消息。

故障排查指南

• 预约无法提交
  • 检查黑名单：是否存在 (user_id, item_id) 记录且未过期
  • 检查时段可用性：(book_date, start_time) 是否已有预约
  • 检查项目状态：项目 status 是否为启用
• 状态异常
  • 查看操作日志：根据 book_id 查询 before_status/after_status 定位变更点
  • 检查通知记录：send_status 是否为失败，必要时重试
• 排班显示异常
  • 核对时段表 weekday 与 start_time/end_time 是否正确
  • 核对规则表 date_type 与 weekdays 是否匹配预期

结论

DouPHP 预约系统通过清晰的分层表设计实现了“项目—时段—规则”的灵活配置，配合黑名单、日志与通知形成完整的业务闭环。借助合理的索引与事务策略，可在高并发场景下保证数据一致性与性能。建议在生产环境结合监控与告警，持续优化时段计算与冲突检测逻辑。

附录

• 预约状态枚举（中文）
  • 0 待确认、1 已确认、2 已完成、3 已取消、4 已过期、5 已拒绝
• 常见接口路径（前端路由）
  • 列表、分类、排班查询、时间选择、联系人管理、预约提交、用户中心预约管理等