Home Explore Help
Sign In
cosmoedev
/
cosmoe-bot
2
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 02b3919727
Branches Tags
cosmoe-bot
/
.qoder
/
repowiki
/
zh
/
content
/
核心模块
/
预约管理系统.md

预约管理系统.md 14 KB
History Raw

预约管理系统

本文档引用的文件

  • 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

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介

这是一个基于 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 服务不可用

解决步骤:

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

2. 预约失败

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

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

解决步骤:

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

3. 历史记录为空

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

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

解决步骤:

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

章节来源

  • 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 响应时间
  • 优化错误处理逻辑
  • 持续改进用户体验