# 预约管理系统

<cite>
**本文档引用的文件**
- [src/index.ts](file://src/index.ts)
- [src/command/index.ts](file://src/command/index.ts)
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts)
- [src/command/handlers/events.ts](file://src/command/handlers/events.ts)
- [src/command/handlers/eventDetails.ts](file://src/command/handlers/eventDetails.ts)
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts)
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts)
- [src/command/handlers/cancel.ts](file://src/command/handlers/cancel.ts)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts)
- [src/scheduler/index.ts](file://src/scheduler/index.ts)
- [package.json](file://package.json)
</cite>

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

## 简介

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

该系统的核心功能包括：
- 活动浏览和详情查看
- 时间槽选择和预约
- 优惠券应用和价格计算
- 预约历史查询和状态管理
- 取消预约和退款处理
- 定时任务通知新活动

## 项目结构

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

```mermaid
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](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)

**章节来源**
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [package.json](file://package.json#L1-L24)

## 核心组件

### 1. 主入口应用
- **文件路径**: [src/index.ts](file://src/index.ts#L1-L47)
- **功能**: 初始化 Telegram Bot，配置命令路由，设置 Webhook 和定时任务

### 2. 命令处理器系统
- **文件路径**: [src/command/index.ts](file://src/command/index.ts#L1-L110)
- **功能**: 
  - 管理所有命令路由
  - 配置会话存储（使用 KV 存储）
  - 处理回调查询
  - 管理用户对话流程

### 3. Cosmoe API 客户端
- **文件路径**: [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)
- **功能**:
  - 用户认证和凭证管理
  - 活动数据获取
  - 预约操作执行
  - 历史记录查询
  - 取消和退款处理

### 4. 调度系统
- **文件路径**: [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- **功能**: 定时检查新活动并发送通知给注册用户

**章节来源**
- [src/index.ts](file://src/index.ts#L13-L46)
- [src/command/index.ts](file://src/command/index.ts#L20-L110)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L12-L88)

## 架构概览

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

```mermaid
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](file://src/index.ts#L19-L34)
- [src/command/index.ts](file://src/command/index.ts#L52-L110)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L140)

### 数据流架构

```mermaid
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](file://src/command/index.ts#L78-L110)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L247-L270)

## 详细组件分析

### 预约流程组件

#### 1. 预约处理流程

```mermaid
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](file://src/command/handlers/bookEvent.ts#L11-L118)
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L160-L226)

#### 2. 预约状态管理

系统支持以下预约状态：
- **待确认**: 新创建的预约
- **已完成**: 活动已结束
- **已取消**: 用户主动取消
- **待支付**: 需要完成支付

#### 3. 时间槽管理

```mermaid
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](file://src/client/cosmoe.ts#L29-L50)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L95-L105)

**章节来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L11-L157)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L29-L50)

### 历史查询组件

#### 1. 历史记录展示

```mermaid
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](file://src/command/handlers/history.ts#L4-L107)

#### 2. 分页和筛选机制

系统实现了智能的历史记录分页：
- 默认显示最新的 8 条记录
- 支持按日期排序（最新在前）
- 自动过滤过期记录
- 限制消息长度避免 Telegram API 限制

**章节来源**
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L46-L92)

### 取消预约组件

#### 1. 取消流程

```mermaid
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](file://src/command/handlers/cancel.ts#L11-L84)
- [src/command/handlers/cancel.ts](file://src/command/handlers/cancel.ts#L86-L132)

#### 2. 业务规则和约束

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

**章节来源**
- [src/command/handlers/cancel.ts](file://src/command/handlers/cancel.ts#L117-L124)

### 认证和会话管理

#### 1. 交互式登录流程

```mermaid
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](file://src/command/handlers/login.ts#L13-L75)

**章节来源**
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L13-L75)

### 优惠券系统

#### 1. 优惠券应用流程

```mermaid
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](file://src/command/handlers/bookEvent.ts#L65-L110)

#### 2. 优惠券类型支持

系统支持两种优惠券类型：
- **百分比折扣**: 基于原价的百分比减免
- **固定金额折扣**: 固定金额减免

**章节来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L76-L106)

## 依赖关系分析

### 外部依赖

```mermaid
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](file://package.json#L18-L22)

### 内部模块依赖

```mermaid
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](file://src/index.ts#L3-L4)
- [src/command/index.ts](file://src/command/index.ts#L1-L11)

**章节来源**
- [package.json](file://package.json#L18-L22)
- [src/index.ts](file://src/index.ts#L1-L47)

## 性能考虑

### 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](file://src/command/handlers/login.ts#L67-L69)
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L43-L46)
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L41-L44)

## 结论

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

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

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

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

## 附录

### API 接口规范

#### 1. 预约相关接口
- `bookEvent()`: 创建新的预约
- `getMyBookings()`: 获取用户预约历史
- `cancelBooking()`: 取消现有预约
- `updatePaymentOrder()`: 更新支付订单

#### 2. 用户相关接口
- `getToken()`: 获取认证令牌
- `getProfile()`: 获取用户资料
- `getAvailableCoupons()`: 获取可用优惠券

#### 3. 活动相关接口
- `getEvents()`: 获取活动列表
- `getEventDetail()`: 获取活动详情

### 最佳实践建议

#### 1. 预约流程最佳实践
- 提前检查时间槽容量
- 明确展示费用明细
- 提供多种支付方式
- 及时发送确认通知

#### 2. 用户体验优化
- 提供清晰的操作指引
- 实时反馈操作状态
- 支持快捷操作
- 保持界面简洁

#### 3. 系统维护建议
- 定期备份 KV 数据
- 监控 API 响应时间
- 优化错误处理逻辑
- 持续改进用户体验