预约项目表(dou_book_item) | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

预约项目表(dou_book_item)

简介

本文件面向项目管理与系统开发者，系统性说明 DouPHP 预约系统中的“预约项目”数据模型 dou_book_item。内容覆盖字段设计、价格体系、时长与容量、预约规则、项目级限制、描述与排序、状态管理，以及项目配置的继承机制与优先级规则，帮助管理员正确配置并让开发者在实现中遵循一致的业务约束。

项目结构

围绕 dou_book_item 的数据与规则，涉及以下关键位置：

数据库定义：系统表结构与模块备份脚本
模型层：后台 BookItem 模型，声明可写字段与类型转换
服务层：核心 BookService 负责预约校验与配置继承解析
表单参数：BookParameterFormRequest 定义全局参数键名，用于继承链的兜底值
后台业务：BookItemService 负责项目数据的持久化与清洗

graph TB
DB["数据库: dou_book_item"] --> Model["模型: admin/model/book/BookItem.php"]
Model --> ServiceCore["核心服务: _'/module/book/core/service/book/BookService.php"]
ServiceCore --> Rules["规则与排班: dou_book_rule / dou_book_schedule"]
AdminSvc["后台业务: admin/service/book/BookItemService.php"] --> Model
ParamReq["参数白名单: BookParameterFormRequest.php"] --> ServiceCore

图表来源

系统表结构.sql:412-439
book.sql:97-126
BookItem.php（后台模型）:28-76
BookService.php（核心服务）:1054-1183
BookParameterFormRequest.php:26-66
BookItemService.php（后台业务）:229-236

章节来源

系统表结构.sql:412-439
book.sql:97-126
BookItem.php（后台模型）:28-76
BookService.php（核心服务）:1054-1183
BookParameterFormRequest.php:26-66
BookItemService.php（后台业务）:229-236

核心组件

数据表 dou_book_item：承载预约项目的全部元数据与规则开关
后台模型 BookItem：声明可写字段、类型转换与关联查询能力
核心服务 BookService：实现项目级限制的计算与继承逻辑
参数白名单 BookParameterFormRequest：提供全局参数的键名集合，作为继承链的兜底
后台业务 BookItemService：负责项目新增/编辑时的数据组装与落库

章节来源

BookItem.php（后台模型）:28-76
BookService.php（核心服务）:1054-1183
BookParameterFormRequest.php:26-66
BookItemService.php（后台业务）:229-236

架构总览

预约项目在创建与使用时，会经历“配置读取 → 继承解析 → 限制校验 → 结果返回”的流程。其中项目级限制（同项目当天/周期次数）由 BookService 根据项目、科室、全局三层配置进行合并计算。

sequenceDiagram
participant Admin as "管理员/前台"
participant ItemSvc as "BookItemService"
participant Model as "BookItem(模型)"
participant Core as "BookService(核心)"
participant DB as "数据库"
Admin->>ItemSvc : 提交项目数据
ItemSvc->>Model : 组装并写入字段
Model->>DB : INSERT/UPDATE dou_book_item
Admin->>Core : 发起预约校验
Core->>DB : 读取项目/科室/全局参数
Core->>Core : 计算继承后的限制值
Core->>DB : 统计历史预约计数
Core-->>Admin : 返回是否允许预约

图表来源

BookItemService.php（后台业务）:229-236
BookService.php（核心服务）:1054-1183
系统表结构.sql:412-439

详细组件分析

数据表 dou_book_item 字段说明

主键与标识
- id：项目ID
- class_id：所属分组ID
- name：项目名称
- tag：标签/职称
- code：项目编号（唯一索引）
- image：图片
价格体系
- price：价格
- original_price：原价
时长与容量
- duration：默认时长（分钟）
- capacity：单次预约最大人数
预约时间窗口
- advance_days：提前预约天数
- min_advance_hours：最小提前预约小时数
- max_advance_hours：最大提前预约小时数
- cancel_deadline_hours：取消截止时间（小时前）
项目级限制
- item_day_limit：同项目当天最多预约次数（-1 表示继承，0 表示不限）
- item_period_days：同项目时间范围（天数）（-1 表示继承，0 表示不限）
- item_period_limit：同项目时间范围内最多预约次数（-1 表示继承，0 表示不限）
描述与展示
- brief：简介
- content：详细介绍
- sort：排序
状态与审计
- status：状态（0禁用，1启用）
- add_time/update_time 或 created_at/updated_at：创建/更新时间（不同脚本版本略有差异）

章节来源

系统表结构.sql:412-439
book.sql:97-126

后台模型 BookItem 的可写字段与类型

可写字段包含：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
类型转换：id/class_id/sort 为整型；image 使用附件处理；created_at 按日期时间格式化
关联：通过 class_id 关联 book_class

章节来源

BookItem.php（后台模型）:28-76

项目级限制与继承机制

继承层级与优先级（从高到低）
1. 项目自身配置（dou_bookitem 中的 item* 字段）
2. 所属科室配置（bookclass 中的 class* 字段）
3. 全局参数（book_item_day_limit、book_item_period_days、book_item_period_limit 等）
取值规则
- 若项目值为 -1：尝试从科室获取；若科室也未设置或无效，则回退到全局参数
- 若项目值 > 0：直接使用项目值
- 若项目值 = 0：视为“不限”
生效范围
- item_day_limit：对同一用户在同一项目、同一天的有效预约次数进行限制
- item_period_days + item_period_limit：对同一用户在同一项目、指定天数范围内的有效预约次数进行限制
统计口径
- 仅统计非终止/过期/作废状态的预约记录（排除特定状态码）

flowchart TD
Start(["开始"]) --> ReadItem["读取项目配置<br/>item_day_limit/item_period_days/item_period_limit"]
ReadItem --> CheckNeg{"是否为 -1 ?"}
CheckNeg -- 是 --> ReadClass["读取科室配置<br/>class_* 对应项"]
CheckNeg -- 否 --> UseItem["使用项目值"]
ReadClass --> ClassValid{"科室值 > 0 ?"}
ClassValid -- 是 --> UseClass["使用科室值"]
ClassValid -- 否 --> ReadGlobal["读取全局参数<br/>book_item_*"]
ReadGlobal --> GlobalValid{"全局值 > 0 ?"}
GlobalValid -- 是 --> UseGlobal["使用全局值"]
GlobalValid -- 否 --> Unlimited["视为不限(0)"]
UseItem --> Count["统计历史预约次数"]
UseClass --> Count
UseGlobal --> Count
Unlimited --> End(["结束"])
Count --> Compare{"是否达到上限?"}
Compare -- 是 --> Block["拒绝预约"]
Compare -- 否 --> Allow["允许预约"]
Block --> End
Allow --> End

图表来源

BookService.php（核心服务）:1054-1183
BookParameterFormRequest.php:26-66

章节来源

BookService.php（核心服务）:1054-1183
BookParameterFormRequest.php:26-66

价格、时长与容量

价格：price 与 original_price 支持小数精度，便于展示折扣信息
时长：duration 以分钟为单位，配合时段切分与排班使用
容量：capacity 控制单次预约的最大人数，可与规则时段叠加调整

章节来源

系统表结构.sql:412-439
book.sql:97-126

描述、排序与状态

brief/content：分别用于简短介绍与详细内容展示
sort：列表排序依据（升序优先）
status：启用/禁用控制，影响前端可见性与可用性

章节来源

系统表结构.sql:412-439
BookItem.php（后台模型）:28-76

后台数据持久化要点

新增/更新时，服务层会对输入数据进行类型转换与安全过滤（如 content 的 XSS 清理）
时间戳统一写入 created_at/updated_at（或 add_time/update_time，视版本脚本而定）
删除项目时会级联清理其排班数据

章节来源

BookItemService.php（后台业务）:229-236
BookItem.php（后台模型）:102-116

依赖关系分析

表间关系
- dou_book_item.class_id → dou_book_class.id（项目归属科室）
- 预约校验时结合 dou_book（预约单）、dou_book_rule/dou_book_schedule（规则与时段）共同决定可用性与容量
代码依赖
- 后台模型依赖 ORM 与附件处理
- 核心服务依赖配置中心与数据库访问，实现继承与限制计算
- 参数白名单确保全局参数键名稳定可控

graph LR
A["dou_book_item"] --> B["dou_book_class"]
A --> C["dou_book"]
A --> D["dou_book_rule"]
A --> E["dou_book_schedule"]

图表来源

系统表结构.sql:412-439
BookService.php（核心服务）:1054-1183

章节来源

系统表结构.sql:412-439
BookService.php（核心服务）:1054-1183

性能考虑

限制校验涉及按用户、项目、日期的聚合计数，建议：
- 为 book 表的 user_id、item_id、book_date、status 建立合适索引
- 对高频查询场景引入缓存（如 Redis）暂存当日/周期计数
项目列表排序与筛选：
- 利用 sort 字段与状态位快速过滤
大文本字段（content）避免在列表页加载，按需详情读取

故障排查指南

预约被拒：检查项目/科室/全局三层的 item_day_limit 与 itemperiod* 是否生效，确认继承链是否正确
限额未生效：确认项目字段是否为 -1（继承），且科室/全局已正确配置；核对统计时排除的状态码是否符合预期
数据不一致：核对后台写入的 created_at/updated_at 与脚本版本是否匹配；确认 content 是否被安全过滤
排班异常：删除项目前确保已清理相关排班；检查 schedule 与 rule 的关联

章节来源

BookService.php（核心服务）:1054-1183
BookItemService.php（后台业务）:229-236
BookItem.php（后台模型）:102-116

结论

dou_book_item 是预约系统的核心实体之一，既承载项目基础信息与价格时长，也定义了项目级的预约限制。通过“项目→科室→全局”的继承机制，系统可在保持灵活性的同时确保一致的约束策略。管理员应合理设置项目级限制与时间窗口，开发者应在实现中严格遵循继承与统计口径，以保证预约流程的正确性与稳定性。

附录

相关表参考
- dou_book_class：科室/分组配置，参与继承链
- dou_book_rule / dou_book_schedule：规则与时段，影响可用性与容量
- dou_book：预约单，用于限制统计
常用配置键名（全局参数）
- book_item_day_limit、book_item_period_days、book_item_period_limit
- book_class_day_limit、book_class_period_days、book_class_period_limit
- book_user_day_limit、book_user_period_days、book_user_period_limit

章节来源

BookParameterFormRequest.php:26-66
系统表结构.sql:412-439

添加日期：2026-10-05