预约项目分组表(dou_book_class)

简介

本文件面向“预约项目分组管理”的数据模型与配置继承机制，围绕数据库表 dou_book_class 的字段设计、层级关系、排序与状态控制，以及分组级别的默认时段时长、容量、提前预约天数、最小最大提前小时数、取消截止时间等配置进行系统化说明。同时给出同科室当天最多预约次数、同科室时间范围限制等业务约束规则，并明确分组的继承优先级与覆盖规则，帮助分类管理员与系统开发者正确配置与管理预约项目分组。

项目结构

与 dou_book_class 相关的关键代码位置如下：

数据定义：模块备份 SQL 中定义了 dou_book_class 表结构与注释
后台模型与服务：用于增删改查、树形展示、表单默认值与上传处理
前台模型：提供按唯一标识查询与名称获取能力
核心业务：实现配置继承解析与预约限制校验

graph TB
A["SQL定义<br/>dou_book_class"] --> B["后台模型<br/>BookClass"]
B --> C["后台服务<br/>BookClassService"]
C --> D["后台控制器<br/>ClassController"]
E["前台模型<br/>BookClass"] --> F["核心业务<br/>BookService"]
A --> F

核心组件

数据表：dou_book_class，承载分组基本信息、层级关系、排序与状态，以及分组级预约配置与限制
后台模型 BookClass：声明表名、主键、类型转换与可写入字段集合，并提供编辑、删除等辅助方法
后台服务 BookClassService：构建列表树、编辑页数据、新增/更新/删除流程，处理图标附件存储与审计日志
后台控制器 ClassController：路由到视图，组装页面动作与数据，调用服务完成CRUD
前台模型 BookClass：通过唯一标识 slug 查找分组，或根据 id 获取名称
核心业务 BookService：实现配置继承解析 resolveItemConfig，以及基于 class/item/参数层级的取值逻辑；同时实现分组树与子ID递归

架构总览

分组管理的整体流程包括：

列表与树形展示：从 book_class 全量读取并按 parent_id 组织为树，附带 URL 与图标
新增/编辑：表单校验后写入 book_class，支持图标上传与审计记录
删除：二次确认后物理删除并记录审计日志
配置继承：在预约流程中，按 item → class → 系统参数 → 默认值的顺序解析具体配置
预约限制：在提交预约时，依据分组与项目的限制规则进行计数校验

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "ClassController"
participant Svc as "BookClassService"
participant Model as "BookClass(后台)"
participant DB as "数据库"
Admin->>Ctrl : 访问分组列表/新增/编辑/删除
Ctrl->>Svc : 调用服务方法
Svc->>Model : 查询/创建/更新/删除
Model->>DB : 执行SQL
DB-->>Model : 返回结果
Model-->>Svc : 返回对象/影响行数
Svc-->>Ctrl : 返回视图数据/操作结果
Ctrl-->>Admin : 渲染页面/跳转/提示

详细组件分析

数据表 dou_book_class 字段设计

分组标识与名称
- id：分组自增主键
- slug：唯一标识符（用于前端路由与链接）
- name：分组名称
- icon：图标路径或附件ID
- description：描述信息
层级与展示
- parent_id：上级分组ID，0表示顶级
- sort：排序权重，越小越靠前
- status：状态（0禁用，1启用）
分组级预约配置（继承用）
- duration：默认时段时长（分钟），-1表示继承全局，0表示不拆分
- capacity：单时段可预约人数，-1表示继承全局
- advance_days：提前预约天数，-1表示继承全局
- min_advance_hours：最小提前小时数，-1继承全局，0不限
- max_advance_hours：最大提前小时数，-1继承全局，0不限
- cancel_deadline_hours：取消截止小时前，-1继承全局，0不限
分组级预约限制规则
- class_day_limit：同科室当天最多预约次数（-1继承，0不限）
- class_period_days：同科室时间范围（天数），-1继承，0不限
- class_period_limit：同科室时间范围内最多预约次数（-1继承，0不限）
项目级预约限制规则（分组内项目继承）
- item_day_limit：同项目当天最多预约次数（-1继承，0不限）
- item_period_days：同项目时间范围（天数），-1继承，0不限
- item_period_limit：同项目时间范围内最多预约次数（-1继承，0不限）

分组配置的继承机制与优先级

解析入口：resolveItemConfig(item, class, field, default)
优先级顺序（从高到低）：
1. 项目层（item）：若字段不为 -1，则直接使用
2. 分组层（class）：若字段不为 -1，则使用分组值
3. 系统参数层：若存在对应参数且不为 -1，则使用
4. 默认值：否则回退到默认值
适用字段：advance_days、min_advance_hours、max_advance_hours、cancel_deadline_hours、duration、capacity 等
效果：当分组未显式设置某项配置（值为 -1）时，自动向上继承至系统参数或默认值，便于统一治理

flowchart TD
Start(["开始"]) --> CheckItem["检查项目层字段是否为 -1"]
CheckItem --> |是| UseItem["使用项目层值"]
CheckItem --> |否| CheckClass["检查分组层字段是否为 -1"]
CheckClass --> |是| UseClass["使用分组层值"]
CheckClass --> |否| CheckParam["检查系统参数层是否为 -1"]
CheckParam --> |是| UseParam["使用系统参数值"]
CheckParam --> |否| UseDefault["使用默认值"]
UseItem --> End(["结束"])
UseClass --> End
UseParam --> End
UseDefault --> End

分组层级关系与排序

层级关系：通过 parent_id 形成树形结构，支持多级分组
排序：sort 字段决定同级分组显示顺序，配合 id 作为次级排序
树形生成：getClassNolevel 全量读取并按 parent_id 递归组装，附带 URL 与图标地址
子ID收集：childId 递归收集指定父级下的所有子ID，便于批量操作或统计

flowchart TD
Load["加载所有分组"] --> Filter["筛选 parent_id=当前父级"]
Filter --> Build["构建节点(含URL/图标/标记)"]
Build --> Recurse{"是否有子节点?"}
Recurse --> |是| Child["递归处理子节点"]
Recurse --> |否| Done["完成"]
Child --> Recurse

分组的状态控制与后台管理

状态字段 status：0禁用，1启用，用于控制分组是否参与展示与预约
后台CRUD：
- 列表：调用 getClassTreeForIndex 获取树形数据
- 新增：buildClassCreateData 提供默认值，insert 写入并处理图标上传
- 编辑：buildClassEditData 填充表单数据，update 更新并处理图标
- 删除：delete 二次确认后删除并记录审计日志
审计：所有关键操作均记录管理员操作日志

分组级预约限制规则与校验

同科室当天最多预约次数：class_day_limit
- 当 > 0 时，统计该用户在该日期下属于同一分组的所有项目的有效预约数量，达到上限则拒绝
同科室时间范围限制：class_period_days、class_period_limit
- 当两者均 > 0 时，统计该用户在 [date - (days-1), date] 区间内属于同一分组的所有项目的有效预约数量，达到上限则拒绝
项目级限制（分组内项目继承）：item_day_limit、item_period_days、item_period_limit
- 与分组级限制共同作用，确保对“科室维度”和“项目维度”的双重管控
校验位置：核心业务 BookService 在预约提交流程中进行计数与限制判断

flowchart TD
Start(["提交预约"]) --> GetClassIds["获取同分组项目ID集合"]
GetClassIds --> DayLimit{"class_day_limit > 0 ?"}
DayLimit --> |是| CountDay["统计当日有效预约数"]
CountDay --> DayCheck{"是否达到上限?"}
DayCheck --> |是| RejectDay["拒绝：当天超限"]
DayCheck --> |否| PeriodCheck{"class_period_days>0 且 limit>0 ?"}
DayLimit --> |否| PeriodCheck
PeriodCheck --> |是| CountPeriod["统计周期内有效预约数"]
CountPeriod --> PeriodCheck2{"是否达到上限?"}
PeriodCheck2 --> |是| RejectPeriod["拒绝：周期超限"]
PeriodCheck2 --> |否| Pass["通过"]
PeriodCheck --> |否| Pass
RejectDay --> End(["结束"])
RejectPeriod --> End
Pass --> End

前台与后台模型职责划分

前台模型 BookClass：
- findByUniqueId：通过 slug 查找分组，用于公开路由
- getClassNameByClassId：根据 id 获取分组名称，用于展示
后台模型 BookClass：
- findForAdminEdit：按 id 查询分组详情
- valueClassNameById：直接查询名称
- deleteByClassId：按 id 删除分组

依赖关系分析

控制器依赖服务：ClassController 仅做请求分发与视图渲染，业务逻辑集中在 BookClassService
服务依赖模型与核心业务：BookClassService 使用 BookClass 模型进行数据存取，并依赖核心 BookService 提供的分组树与配置解析能力
数据表依赖索引：book_class 表对 parent_id 与 status 建立索引，提升树形查询与状态过滤性能

graph LR
Ctrl["ClassController"] --> Svc["BookClassService"]
Svc --> Model["BookClass(后台)"]
Svc --> Core["BookService(核心)"]
Model --> DB["dou_book_class"]
Core --> DB

性能考虑

分组树查询：getClassNolevel 一次性加载全部分组并按 parent_id 递归组装，适合分组规模不大的场景；若分组数量较大，建议增加缓存或分页策略
索引优化：parent_id 与 status 已建索引，利于树形遍历与状态过滤
配置解析：resolveItemConfig 为轻量计算，无额外IO；但频繁调用时应避免重复解析，可在上层缓存最终配置
限制校验：class_day_limit 与 class_period_limit 涉及聚合计数，建议在高频场景下引入缓存或异步统计

故障排查指南

分组无法显示：
- 检查 status 是否为 1
- 检查 parent_id 是否正确，是否存在循环引用
- 检查 sort 是否合理，必要时调整排序
图标不显示：
- 确认 icon 字段是否为空或无效附件ID
- 查看 BookClassService 中图标上传与 URL 转换逻辑
预约被拒绝：
- 检查 class_day_limit、class_period_days、class_period_limit 是否设置过小
- 核对项目级限制 item_day_limit、item_period_days、item_period_limit
- 查看 BookService 中的计数逻辑与状态过滤条件
继承不生效：
- 确认分组层字段是否为 -1（表示继承）
- 检查系统参数与默认值是否符合预期

结论

dou_book_class 表提供了完整的预约项目分组管理能力，涵盖基本信息、层级关系、排序与状态控制，并通过 -1 继承机制实现灵活的配置继承。结合分组级与项目级的预约限制规则，系统能够在“科室维度”和“项目维度”上精细化管控预约行为。管理员可通过后台界面便捷地维护分组与配置，开发者可依据核心服务的继承解析与限制校验逻辑进行扩展与优化。

附录

字段含义速查（节选）
- duration：默认时段时长（分钟），-1继承全局，0不拆分
- capacity：单时段可预约人数，-1继承全局
- advance_days：提前预约天数，-1继承全局
- min_advance_hours：最小提前小时数，-1继承全局，0不限
- max_advance_hours：最大提前小时数，-1继承全局，0不限
- cancel_deadline_hours：取消截止小时前，-1继承全局，0不限
- class_day_limit：同科室当天最多预约次数（-1继承，0不限）
- class_period_days：同科室时间范围（天数），-1继承，0不限
- class_period_limit：同科室时间范围内最多预约次数（-1继承，0不限）
- item_day_limit：同项目当天最多预约次数（-1继承，0不限）
- item_period_days：同项目时间范围（天数），-1继承，0不限
- item_period_limit：同项目时间范围内最多预约次数（-1继承，0不限）

添加日期：2026-10-05