简介
本文件面向系统管理员与运维人员，系统化说明 DouPHP 预约系统的支撑功能数据模型与业务流程，重点覆盖：
- 预约黑名单表（book_blacklist）：字段设计、写入时机、失效策略与管理流程。
- 预约操作日志表（book_log）：审计记录机制、关键字段含义与查询要点。
- 预约通知记录表（book_notify）：通知事件、通道、接收方与发送状态管理。 并给出黑名单管理、操作审计、通知提醒的业务流程与数据流转图，帮助快速定位问题与优化系统行为。
项目结构
围绕“黑名单、日志、通知”的支撑能力，代码主要分布在以下位置：
- 黑名单数据模型：admin/model/book/BookBlacklist.php
- 预约主表及级联删除逻辑：admin/model/book/Book.php
- 预约操作审计日志写入：core/service/audit/AuditService.php
- 黑名单后台控制器与服务：admin/controller/book/BlacklistController.php、admin/service/book/BlacklistService.php
- 预约 API 路由入口（用于触发后续业务链）：api/route/book.php
graph TB
A["后台控制器<br/>BlacklistController"] --> B["黑名单服务<br/>BlacklistService"]
B --> C["黑名单模型<br/>BookBlacklist"]
D["预约主表模型<br/>Book"] --> E["日志表 book_log"]
D --> F["通知表 book_notify"]
G["API 路由<br/>api/route/book.php"] --> H["预约业务链路"]
H --> E
H --> F核心组件
- 黑名单数据访问对象（BookBlacklist）
- 表名：book_blacklist
- 主键：id
- 可写字段（fillable）：item_id、user_id、operator_type、operator_id、reason、expired_at、created_at
- 类型转换（casts）：id 为整型；created_at 按指定格式转换为日期时间
- 预约操作审计日志写入（AuditService::writeBookLog）
- 写入表：book_log
- 关键字段：book_id、operator_type、operator_id、action、before_status、after_status、remark、ip、created_at
- 预约主表模型（Book）
- 提供级联删除：删除预约时同步清理 book_log 与 book_notify
- 提供筛选、关联等常用查询方法
架构总览
预约系统在关键节点会同时落盘三类支撑数据：
- 黑名单：限制特定用户或针对特定项目的预约能力，支持过期时间控制。
- 日志：记录每次预约状态变更的操作轨迹，便于审计与排障。
- 通知：记录短信、邮件、微信、App 等通道的通知事件与发送结果。
sequenceDiagram
participant U as "调用方"
participant C as "控制器/服务"
participant M as "模型/DAO"
participant L as "日志表(book_log)"
participant N as "通知表(book_notify)"
participant BL as "黑名单表(book_blacklist)"
U->>C : 发起预约相关请求
C->>M : 校验/执行业务
C->>BL : 检查/写入黑名单
C->>L : 写入操作审计日志
C->>N : 写入通知记录
C-->>U : 返回处理结果详细组件分析
黑名单表（book_blacklist）数据模型
- 标识与关联
- id：黑名单记录唯一标识
- item_id：关联预约项目（用于项目维度的拉黑）
- user_id：被拉黑的用户 ID
- 操作者信息
- operator_type / operator_id：操作者类型与 ID（如 admin/work/user），用于追溯谁执行了拉黑
- 原因与时效
- reason：拉黑原因（文本）
- expired_at：过期时间（到期自动解除）
- 时间戳
- created_at：创建时间（由 ORM casts 统一格式化）
classDiagram
class BookBlacklist {
+int id
+int item_id
+int user_id
+string operator_type
+int operator_id
+string reason
+datetime expired_at
+datetime created_at
}预约操作日志表（book_log）记录机制
- 记录内容
- book_id：预约单 ID
- operator_type / operator_id：操作者类型与 ID
- action：动作类型（如 confirm/reject/complete/checkin/cancel 等）
- before_status / after_status：状态变更前后的值
- remark：备注（可包含人工备注或系统提示）
- ip：操作来源 IP
- created_at：记录时间
- 写入方式
- 通过 AuditService::writeBookLog 统一写入，内部对参数进行安全过滤与默认 IP 回退
flowchart TD
Start(["开始"]) --> V["参数校验与清洗<br/>book_id/operator/action/status/ip"]
V --> Check{"book_id 有效?"}
Check -- 否 --> EndFail["返回失败"]
Check -- 是 --> Insert["写入 book_log"]
Insert --> EndOK["返回成功"]预约通知记录表（book_notify）通知机制
- 字段与语义
- book_id：预约单 ID
- notify_type：通知方式（sms/email/wechat/app）
- notify_event：通知事件（confirm/remind/cancel/checkin/expire 等）
- receiver：接收地址（手机号/邮箱/OpenID/设备标识等）
- send_status：发送状态（待发送/成功/失败等）
- 使用场景
- 预约确认、提醒、取消、签到、过期等事件发生时，生成通知记录
- 结合定时任务或消息队列完成实际发送，并回填 send_status
- 与日志联动
- 通知失败时可追加到日志 remark，便于追踪
sequenceDiagram
participant S as "业务服务"
participant DB as "数据库"
participant Q as "通知队列/任务"
participant T as "第三方通道"
S->>DB : 插入 book_notify(事件/通道/接收方/状态)
S->>Q : 投递发送任务
Q->>T : 调用短信/邮件/微信/App 接口
T-->>Q : 返回发送结果
Q->>DB : 更新 send_status
Q-->>S : 回调/轮询获取结果[该图为概念流程图，不直接映射具体源码文件]
黑名单管理、操作审计、通知提醒业务流程
- 黑名单管理
- 管理员在后台对某用户或项目进行拉黑，记录 operator_type/operator_id/reason/expired_at
- 预约提交前检查黑名单，命中则拒绝并记录日志
- 操作审计
- 任何影响预约状态的变更（确认、拒绝、完成、签到、取消等）均写入 book_log，记录 before/after 状态与备注
- 通知提醒
- 根据事件类型向不同通道发送通知，并在 book_notify 中记录发送状态
- 若发送失败，可在日志中补充错误信息以便排查
flowchart TD
A["管理员拉黑/解黑"] --> B["写入 book_blacklist"]
C["用户提交预约"] --> D{"是否命中黑名单?"}
D -- 是 --> E["拒绝预约并记录日志"]
D -- 否 --> F["继续预约流程"]
F --> G["状态变更时写入 book_log"]
F --> H["生成通知记录 book_notify"]
H --> I["异步发送并更新 send_status"][该图为概念流程图，不直接映射具体源码文件]
依赖关系分析
- 控制器与服务
- BlacklistController 负责接收后台请求，委托 BlacklistService 执行业务
- BlacklistService 调用 BookBlacklist 模型进行黑名单读写
- 模型与表
- BookBlacklist 对应 book_blacklist
- AuditService 直接写入 book_log
- Book 模型在删除预约时级联删除 book_log 与 book_notify
- API 路由
- api/route/book.php 暴露预约相关接口，作为外部调用的入口点
graph LR
BC["BlacklistController"] --> BS["BlacklistService"]
BS --> BM["BookBlacklist"]
AS["AuditService"] --> BLG["book_log"]
BK["Book 模型"] --> BN["book_notify"]
BK --> BLG
AR["api/route/book.php"] --> BK性能考虑
- 黑名单查询
- 建议在 user_id、item_id、expired_at 上建立索引，提升命中率与过期清理效率
- 日志写入
- 高并发下建议批量写入或异步化，避免阻塞主流程
- 通知发送
- 采用队列异步发送，减少响应时间；失败重试与死信队列保障可靠性
- 级联删除
- 删除预约时同步清理日志与通知，注意事务与锁的使用，避免长事务
故障排查指南
- 无法写入日志
- 检查 AuditService::writeBookLog 的参数是否为空或非法
- 确认数据库连接与权限正常
- 黑名单未生效
- 核对 expired_at 是否已过期
- 检查黑名单查询条件是否包含正确的 user_id/item_id
- 通知未送达
- 查看 book_notify 的 send_status 与 receiver
- 核对第三方通道配置与配额
- 预约删除后数据不一致
- 确认 Book::deleteCascade 是否正确执行，验证 book_log 与 book_notify 是否被清理
结论
- 黑名单表以 user_id/item_id 为核心维度，配合 operator 信息与过期时间，实现精细化管控。
- 操作日志表通过 before/after 状态与备注，完整记录预约生命周期中的关键变更。
- 通知记录表将多通道通知标准化，便于追踪与排障。
- 通过控制器-服务-模型的清晰分层，以及 API 路由的统一入口，支撑功能具备良好的可扩展性与可维护性。
附录
- 常见枚举与约定
- 操作者类型：admin/user/work
- 通知方式：sms/email/wechat/app
- 通知事件：confirm/remind/cancel/checkin/expire
- 建议索引
- book_blacklist：user_id、item_id、expired_at
- book_log：book_id、created_at
- book_notify：book_id、notify_event、send_status