预约管理系统

本文档引用的文件

src/index.ts
src/command/index.ts
src/command/handlers/start.ts
src/command/handlers/login.ts
src/command/handlers/events.ts
src/command/handlers/eventDetails.ts
src/command/handlers/bookEvent.ts
src/command/handlers/history.ts
src/command/handlers/cancel.ts
src/command/handlers/logout.ts
src/client/cosmoe.ts
src/scheduler/index.ts
package.json

简介

这是一个基于 Telegram 的预约管理系统，专门为摄影活动提供预约服务。系统集成了 Cloudflare Workers 和 KV 存储，通过与 Cosmoe API 交互实现完整的预约生命周期管理。

该系统的核心功能包括：

活动浏览和详情查看
时间槽选择和预约
优惠券应用和价格计算
预约历史查询和状态管理
取消预约和退款处理
定时任务通知新活动

项目结构

系统采用模块化设计，主要分为以下几个层次：

graph TB
subgraph "入口层"
A[src/index.ts] --> B[命令设置]
end
subgraph "命令处理器层"
B --> C[事件命令]
B --> D[预约命令]
B --> E[历史命令]
B --> F[取消命令]
B --> G[登录命令]
B --> H[登出命令]
end
subgraph "客户端层"
I[CosmoeClient] --> J[API 调用]
J --> K[认证]
J --> L[预约]
J --> M[历史]
J --> N[取消]
end
subgraph "存储层"
O[KV 存储]
P[会话存储]
end
subgraph "调度层"
Q[scheduler/index.ts] --> R[定时任务]
end
C --> I
D --> I
E --> I
F --> I
G --> I
H --> I
I --> O
I --> P
R --> A

图表来源

src/index.ts
src/command/index.ts
src/client/cosmoe.ts

章节来源

src/index.ts
src/command/index.ts
package.json

核心组件

1. 主入口应用

文件路径: src/index.ts
功能: 初始化 Telegram Bot，配置命令路由，设置 Webhook 和定时任务

2. 命令处理器系统

文件路径: src/command/index.ts
功能:
- 管理所有命令路由
- 配置会话存储（使用 KV 存储）
- 处理回调查询
- 管理用户对话流程

3. Cosmoe API 客户端

文件路径: src/client/cosmoe.ts
功能:
- 用户认证和凭证管理
- 活动数据获取
- 预约操作执行
- 历史记录查询
- 取消和退款处理

4. 调度系统

文件路径: src/scheduler/index.ts
功能: 定时检查新活动并发送通知给注册用户

章节来源

src/index.ts
src/command/index.ts
src/client/cosmoe.ts
src/scheduler/index.ts

架构概览

系统采用分层架构设计，确保职责分离和可维护性：

graph TB
subgraph "用户界面层"
A[Telegram Bot]
B[Inline Keyboard]
C[消息格式化]
end
subgraph "应用逻辑层"
D[命令处理器]
E[会话管理]
F[业务逻辑]
end
subgraph "数据访问层"
G[CosmoeClient]
H[API 适配器]
I[数据模型]
end
subgraph "存储层"
J[KV 存储]
K[会话状态]
L[用户凭证]
end
subgraph "外部服务"
M[Cosmoe API]
N[Cloudflare Workers]
O[Telegram API]
end
A --> D
D --> E
E --> F
F --> G
G --> H
H --> J
J --> M
N --> O
O --> A

图表来源

src/index.ts
src/command/index.ts
src/client/cosmoe.ts

数据流架构

sequenceDiagram
participant U as 用户
participant B as Bot
participant C as 命令处理器
participant A as CosmoeClient
participant S as KV存储
participant API as Cosmoe API
U->>B : 发送命令
B->>C : 路由到相应处理器
C->>S : 读取用户凭证
C->>A : 执行业务操作
A->>API : 调用API接口
API-->>A : 返回数据
A-->>C : 处理结果
C->>S : 更新状态
C-->>U : 返回响应

图表来源

src/command/index.ts
src/client/cosmoe.ts

详细组件分析

预约流程组件

1. 预约处理流程

flowchart TD
A[用户输入 /book_eventId_slotIndex] --> B[解析参数]
B --> C[验证用户登录状态]
C --> D[获取活动详情]
D --> E[验证时间槽有效性]
E --> F{是否有优惠券?}
F --> |是| G[显示优惠券选择]
F --> |否| H[直接预约]
G --> I[用户选择优惠券]
I --> J[执行预约]
H --> J
J --> K{预约成功?}
K --> |是| L[返回成功信息]
K --> |否| M[返回错误信息]
L --> N[结束]
M --> N

图表来源

src/command/handlers/bookEvent.ts
src/command/handlers/bookEvent.ts

2. 预约状态管理

系统支持以下预约状态：

待确认: 新创建的预约
已完成: 活动已结束
已取消: 用户主动取消
待支付: 需要完成支付

3. 时间槽管理

classDiagram
class TimeSlot {
+string range
+string price
+number capacity
+number remaining
+validateAvailability() boolean
+updateRemaining(change) void
}
class EventDetail {
+number id
+string name
+TimeSlot[] slots
+validateTimeSlot(range) boolean
+getAvailableSlots() TimeSlot[]
}
class Booking {
+number id
+string status
+string time_slot
+string final_price
+string payment_order_id
+validateConflict(other) boolean
}
EventDetail --> TimeSlot : "包含多个"
Booking --> TimeSlot : "关联"

图表来源

src/client/cosmoe.ts
src/client/cosmoe.ts

章节来源

src/command/handlers/bookEvent.ts
src/client/cosmoe.ts

历史查询组件

1. 历史记录展示

sequenceDiagram
participant U as 用户
participant B as Bot
participant H as 历史处理器
participant C as CosmoeClient
participant API as Cosmoe API
U->>B : /history
B->>H : 处理历史命令
H->>C : 获取用户凭证
H->>C : 调用 getMyBookings()
C->>API : 请求历史数据
API-->>C : 返回历史记录
C-->>H : 处理后的数据
H->>H : 格式化显示
H-->>U : 发送历史消息

图表来源

src/command/handlers/history.ts

2. 分页和筛选机制

系统实现了智能的历史记录分页：

默认显示最新的 8 条记录
支持按日期排序（最新在前）
自动过滤过期记录
限制消息长度避免 Telegram API 限制

章节来源

src/command/handlers/history.ts

取消预约组件

1. 取消流程

flowchart TD
A[用户输入 /cancel_bookingId] --> B[验证用户登录]
B --> C[获取用户历史]
C --> D[查找目标预约]
D --> E[显示确认对话框]
E --> F{用户确认?}
F --> |是| G[调用取消API]
F --> |否| H[取消操作]
G --> I{取消成功?}
I --> |是| J[返回成功信息]
I --> |否| K[返回错误信息]
J --> L[结束]
K --> L
H --> L

图表来源

src/command/handlers/cancel.ts
src/command/handlers/cancel.ts

2. 业务规则和约束

取消预约的业务规则：

只能取消状态为"待确认"或"待支付"的预约
不能取消已完成或已取消的预约
不能取消过去的预约
需要用户确认才能执行

章节来源

src/command/handlers/cancel.ts

认证和会话管理

1. 交互式登录流程

sequenceDiagram
participant U as 用户
participant B as Bot
participant L as 登录处理器
participant C as CosmoeClient
participant API as Cosmoe API
participant S as KV存储
U->>B : /login
B->>L : 进入登录会话
L->>U : 请求用户名
U->>L : 输入用户名
L->>U : 请求密码
U->>L : 输入密码
L->>C : 调用getToken()
C->>API : 验证凭据
API-->>C : 返回token
C-->>L : 认证结果
L->>S : 存储凭证
L-->>U : 登录成功

图表来源

src/command/handlers/login.ts

章节来源

src/command/handlers/login.ts

优惠券系统

1. 优惠券应用流程

flowchart TD
A[用户选择时间槽] --> B[检查可用优惠券]
B --> C{有多张优惠券?}
C --> |是| D[显示优惠券选择键盘]
C --> |否| E{有单张优惠券?}
D --> F[用户选择优惠券]
E --> |是| F
E --> |否| G[直接预约]
F --> H[执行预约带优惠券]
G --> H
H --> I[计算最终价格]
I --> J[返回预约结果]

图表来源

src/command/handlers/bookEvent.ts

2. 优惠券类型支持

系统支持两种优惠券类型：

百分比折扣: 基于原价的百分比减免
固定金额折扣: 固定金额减免

章节来源

src/command/handlers/bookEvent.ts

依赖关系分析

外部依赖

graph LR
subgraph "核心框架"
A[grammy]
B[@grammyjs/conversations]
C[@grammyjs/storage-cloudflare]
end
subgraph "运行时环境"
D[Cloudflare Workers]
E[KV 存储]
F[Webhook]
end
subgraph "外部服务"
G[Telegram API]
H[Cosmoe API]
end
A --> D
B --> D
C --> E
D --> F
D --> G
A --> H

图表来源

package.json

内部模块依赖

graph TD
A[src/index.ts] --> B[src/command/index.ts]
B --> C[src/command/handlers/*.ts]
C --> D[src/client/cosmoe.ts]
A --> E[src/scheduler/index.ts]
D --> F[KV 存储]
C --> F

图表来源

src/index.ts
src/command/index.ts

章节来源

package.json
src/index.ts

性能考虑

1. 缓存策略

使用 KV 存储缓存用户凭证，避免重复认证
会话状态持久化，支持断线重连
定时任务优化，避免频繁 API 调用

2. 并发处理

基于 Cloudflare Workers 的无服务器架构
异步处理用户请求
会话隔离，避免状态冲突

3. 错误处理

全面的异常捕获和错误恢复
用户友好的错误提示
日志记录便于调试

故障排除指南

常见问题及解决方案

1. 登录失败

症状: 用户无法登录系统 可能原因:

用户名或密码错误
网络连接问题
Cosmoe API 服务不可用

解决步骤:

检查用户名和密码是否正确
验证网络连接
确认 Cosmoe API 服务状态
重新尝试登录

2. 预约失败

症状: 预约请求返回错误 可能原因:

时间槽已满
用户未登录
API 调用超时

解决步骤:

检查时间槽剩余容量
确认用户已登录
重试预约操作
查看系统日志

3. 历史记录为空

症状: /history 命令返回空结果 可能原因:

用户没有预约记录
API 数据同步延迟
用户凭证过期

解决步骤:

确认用户确实有预约记录
等待数据同步完成
重新登录获取新凭证
联系管理员检查系统状态

章节来源

src/command/handlers/login.ts
src/command/handlers/bookEvent.ts
src/command/handlers/history.ts

结论

这个预约管理系统展现了现代聊天机器人开发的最佳实践：

主要优势

模块化设计: 清晰的分层架构，易于维护和扩展
用户体验: 流畅的交互流程，支持多种操作场景
可靠性: 完善的错误处理和状态管理
可扩展性: 基于 Cloudflare Workers 的无服务器架构

技术亮点

会话管理: 基于 KV 存储的会话状态管理
实时通知: 定时任务自动推送新活动通知
状态机: 清晰的预约状态流转
安全认证: 客户端凭证管理和会话隔离

改进建议

添加更详细的日志记录
实现更灵活的权限控制系统
增加更多统计和报告功能
优化移动端用户体验

附录

API 接口规范

1. 预约相关接口

bookEvent(): 创建新的预约
getMyBookings(): 获取用户预约历史
cancelBooking(): 取消现有预约
updatePaymentOrder(): 更新支付订单

2. 用户相关接口

getToken(): 获取认证令牌
getProfile(): 获取用户资料
getAvailableCoupons(): 获取可用优惠券

3. 活动相关接口

getEvents(): 获取活动列表
getEventDetail(): 获取活动详情

最佳实践建议

1. 预约流程最佳实践

提前检查时间槽容量
明确展示费用明细
提供多种支付方式
及时发送确认通知

2. 用户体验优化

提供清晰的操作指引
实时反馈操作状态
支持快捷操作
保持界面简洁

3. 系统维护建议

定期备份 KV 数据
监控 API 响应时间
优化错误处理逻辑
持续改进用户体验

预约管理系统.md 14 KB 履歴 Raw

预约管理系统

目录

简介

项目结构

核心组件

1. 主入口应用

2. 命令处理器系统

3. Cosmoe API 客户端

4. 调度系统

架构概览

数据流架构

详细组件分析

预约流程组件

1. 预约处理流程

2. 预约状态管理

3. 时间槽管理

历史查询组件

1. 历史记录展示

2. 分页和筛选机制

取消预约组件

1. 取消流程

2. 业务规则和约束

认证和会话管理

1. 交互式登录流程

优惠券系统

1. 优惠券应用流程

2. 优惠券类型支持

依赖关系分析

外部依赖

内部模块依赖

性能考虑

1. 缓存策略

2. 并发处理

3. 错误处理

故障排除指南

常见问题及解决方案

1. 登录失败

2. 预约失败

3. 历史记录为空

结论

主要优势

技术亮点

改进建议

附录

API 接口规范

1. 预约相关接口

2. 用户相关接口

3. 活动相关接口

最佳实践建议

1. 预约流程最佳实践

2. 用户体验优化

3. 系统维护建议

预约管理系统.md 14 KB

履歴 Raw