# 活动管理系统

<cite>
**本文档引用的文件**
- [src/index.ts](file://src/index.ts)
- [src/command/index.ts](file://src/command/index.ts)
- [src/client/cosmoe.ts](file://src/client/cosmoe.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/login.ts](file://src/command/handlers/login.ts)
- [src/command/handlers/cancel.ts](file://src/command/handlers/cancel.ts)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts)
- [src/scheduler/index.ts](file://src/scheduler/index.ts)
- [wrangler.jsonc](file://wrangler.jsonc)
- [package.json](file://package.json)
</cite>

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

## 简介

活动管理系统是一个基于 Telegram 的摄影活动管理机器人，为用户提供活动浏览、详情查看、预约管理等完整功能。系统采用 Cloudflare Workers 架构，通过 API 客户端与外部摄影平台进行数据交互。

该系统的核心功能包括：
- 活动列表获取与展示（支持分页和筛选）
- 活动详情页面设计（图片展示、时间槽信息、价格显示、可用性状态）
- 实时通知机制（新活动提醒）
- 用户认证与会话管理
- 预约历史查询与管理

## 项目结构

项目采用模块化架构设计，主要分为以下几个层次：

```mermaid
graph TB
subgraph "应用入口层"
A[src/index.ts] --> B[src/command/index.ts]
end
subgraph "命令处理层"
B --> C[src/command/handlers/events.ts]
B --> D[src/command/handlers/eventDetails.ts]
B --> E[src/command/handlers/bookEvent.ts]
B --> F[src/command/handlers/history.ts]
B --> G[src/command/handlers/login.ts]
B --> H[src/command/handlers/cancel.ts]
B --> I[src/command/handlers/logout.ts]
end
subgraph "服务客户端层"
J[src/client/cosmoe.ts] --> K[外部摄影平台API]
end
subgraph "调度服务层"
L[src/scheduler/index.ts] --> M[Cloudflare Cron触发器]
end
subgraph "配置层"
N[wrangler.jsonc] --> O[环境变量配置]
P[package.json] --> Q[依赖管理]
end
C --> J
D --> J
E --> J
F --> J
G --> J
H --> J
L --> J
```

**图表来源**
- [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#L1-L503)

**章节来源**
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)

## 核心组件

### API 客户端 (CosmoeClient)

CosmoeClient 是系统的核心数据访问组件，负责与外部摄影平台 API 进行通信。该类提供了完整的 CRUD 操作能力：

```mermaid
classDiagram
class CosmoeClient {
-string baseUrl
-number userId
-string token
+getToken(username, password) ApiResponse~TokenResponse~
+setCredentials(userId, token) void
+getCredentials() Object|null
+isAuthenticated() boolean
+getEvents() ApiResponse~Event[]~
+getEventDetail(eventId) ApiResponse~EventDetail~
+getProfile() ApiResponse~ProfileData~
+getMyBookings() ApiResponse~Booking[]~
+bookEvent(bookingRequest) ApiResponse~any~
+getAvailableCoupons(eventId) ApiResponse~Coupon[]~
+cancelBooking(bookingId) ApiResponse~any~
+updatePaymentOrder(bookingId, paymentOrderId) ApiResponse~any~
+updateBookingNote(bookingId, note) ApiResponse~any~
+selfReschedule(bookingId, newTimeSlot) ApiResponse~any~
+selfTransfer(bookingId, recipientUsername) ApiResponse~any~
+register(key, username, email, password, userIdentity) ApiResponse~Object~
}
class Event {
+string id
+string name
+string description
+string event_date
+string cover_image_url
+string description_brief
}
class EventDetail {
+number id
+string name
+string description
+string event_date
+string time_slots_with_prices
+string cover_image_url
+string detail_image_urls
+number is_listed
+number login_required
+number allow_coupons
+string created_at
+TimeSlot[] slots
+string[] gallery
}
class TimeSlot {
+string range
+string price
+number capacity
+number remaining
}
class Booking {
+number id
+string status
+string booking_date
+string time_slot
+string final_price
+string payment_order_id
+string notes_by_user
+string created_at
+string event_name
}
CosmoeClient --> Event : "获取活动列表"
CosmoeClient --> EventDetail : "获取活动详情"
CosmoeClient --> TimeSlot : "包含时间槽信息"
CosmoeClient --> Booking : "管理预约"
```

**图表来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)

### 命令处理器系统

系统采用命令模式处理用户输入，每个命令都有专门的处理器：

```mermaid
sequenceDiagram
participant U as 用户
participant B as Bot核心
participant C as 命令处理器
participant A as API客户端
participant S as 外部服务
U->>B : 发送命令
B->>C : 路由到对应处理器
C->>A : 调用API方法
A->>S : 发起HTTP请求
S-->>A : 返回响应数据
A-->>C : 处理后的业务数据
C-->>U : 格式化后的消息
```

**图表来源**
- [src/command/index.ts](file://src/command/index.ts#L20-L110)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L177-L184)

**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)

## 架构概览

系统采用分层架构设计，确保各组件职责清晰、耦合度低：

```mermaid
graph TB
subgraph "表现层"
UI[Telegram界面]
end
subgraph "控制层"
CMD[命令路由]
CONV[对话管理]
end
subgraph "业务逻辑层"
EVT[活动管理]
BK[预约管理]
ACC[账户管理]
HIS[历史记录]
end
subgraph "数据访问层"
KV[KV存储]
API[API客户端]
end
subgraph "外部服务"
EXT[摄影平台API]
TG[Telegram API]
end
UI --> CMD
CMD --> CONV
CONV --> EVT
CONV --> BK
CONV --> ACC
CONV --> HIS
EVT --> KV
BK --> KV
ACC --> KV
HIS --> KV
EVT --> API
BK --> API
ACC --> API
HIS --> API
API --> EXT
KV --> TG
```

**图表来源**
- [src/index.ts](file://src/index.ts#L13-L46)
- [src/command/index.ts](file://src/command/index.ts#L20-L110)

### 数据流处理

系统的数据流遵循以下模式：

```mermaid
flowchart TD
A[用户请求] --> B[命令解析]
B --> C[参数验证]
C --> D{需要认证?}
D --> |是| E[读取KV存储]
D --> |否| F[直接处理]
E --> G[验证凭据]
G --> H[调用API客户端]
F --> H
H --> I[处理业务逻辑]
I --> J[格式化响应]
J --> K[发送Telegram消息]
K --> L[更新状态]
L --> M[结束]
```

**图表来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L11-L118)
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L4-L107)

## 详细组件分析

### 活动列表获取与展示

活动列表功能通过 `/events` 命令实现，提供最新的摄影活动信息：

```mermaid
sequenceDiagram
participant U as 用户
participant B as Bot
participant H as EventsHandler
participant C as CosmoeClient
participant S as API服务
U->>B : /events
B->>H : handleEventsCommand
H->>C : getEvents()
C->>S : GET /api.php?action=get_events
S-->>C : 活动列表数据
C-->>H : ApiResponse<Event[]>
H->>H : 处理数据(取前10条)
H->>U : 发送Markdown格式消息
```

**图表来源**
- [src/command/handlers/events.ts](file://src/command/handlers/events.ts#L4-L27)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L177-L184)

#### 分页处理机制

系统实现了简单的分页策略：
- 默认只显示最新的10个活动
- 支持按事件ID排序（降序）
- 自动截断超出限制的消息内容

#### 活动过滤与排序

```mermaid
flowchart TD
A[获取所有活动] --> B[按ID排序(降序)]
B --> C[取前N条记录]
C --> D[生成Markdown列表]
D --> E[发送给用户]
F[用户点击活动链接] --> G[解析活动ID]
G --> H[调用getEventDetail]
H --> I[返回详细信息]
```

**图表来源**
- [src/command/handlers/events.ts](file://src/command/handlers/events.ts#L8-L17)

**章节来源**
- [src/command/handlers/events.ts](file://src/command/handlers/events.ts#L1-L27)

### 活动详情页面设计

活动详情页面提供了丰富的信息展示：

```mermaid
sequenceDiagram
participant U as 用户
participant B as Bot
participant DH as EventDetailsHandler
participant C as CosmoeClient
participant S as API服务
U->>B : /event_{id}
B->>DH : handleEventDetails
DH->>C : getEventDetail(eventId)
C->>S : GET /api.php?action=get_event_detail
S-->>C : 活动详情数据
C-->>DH : ApiResponse<EventDetail>
DH->>DH : 处理时间槽和价格信息
DH->>DH : 计算可用性状态
DH->>U : 发送包含图片、时间槽、价格的详细信息
```

**图表来源**
- [src/command/handlers/eventDetails.ts](file://src/command/handlers/eventDetails.ts#L4-L61)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L191-L199)

#### 图片展示机制

系统支持多种图片展示：
- 封面图片：用于活动的主要视觉展示
- 详情图片：活动的扩展图片集合
- 图片URL验证：确保图片链接的有效性

#### 时间槽信息管理

```mermaid
flowchart TD
A[获取活动详情] --> B[解析时间槽数组]
B --> C[按时间段排序]
C --> D[计算剩余容量]
D --> E{是否在活动日期内?}
E --> |是| F[显示预约按钮]
E --> |否| G[仅显示信息]
F --> H[标记可预约状态]
G --> I[标记不可预约状态]
```

**图表来源**
- [src/command/handlers/eventDetails.ts](file://src/command/handlers/eventDetails.ts#L22-L45)

#### 价格显示与可用性状态

系统实现了智能的价格和状态显示：
- 显示原价和剩余容量
- 根据活动日期动态调整可用性状态
- 提供预约链接（仅对可预约的时间槽）

**章节来源**
- [src/command/handlers/eventDetails.ts](file://src/command/handlers/eventDetails.ts#L1-L61)

### 预约管理功能

预约功能是系统的核心业务逻辑：

```mermaid
sequenceDiagram
participant U as 用户
participant B as Bot
participant BH as BookEventHandler
participant C as CosmoeClient
participant S as API服务
participant K as KV存储
U->>B : /book_{event_id}_{slot_index}
B->>BH : handleBookEvent
BH->>K : 读取用户凭据
K-->>BH : 凭据数据
BH->>C : setCredentials
BH->>C : getEventDetail(eventId)
C-->>BH : 活动详情
BH->>BH : 验证时间槽可用性
BH->>C : getAvailableCoupons(eventId)
C-->>BH : 可用优惠券
BH->>U : 显示优惠券选择
U->>B : 选择优惠券
B->>BH : handleCouponSelection
BH->>C : bookEvent(bookingRequest)
C-->>BH : 预约结果
BH-->>U : 预约确认信息
```

**图表来源**
- [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)

#### 优惠券系统集成

系统支持多种类型的优惠券：
- 固定金额折扣
- 百分比折扣
- 自动选择最优优惠券
- 手动选择特定优惠券

#### 实时状态更新

```mermaid
flowchart TD
A[用户发起预约] --> B[检查时间槽剩余容量]
B --> C{剩余容量 > 0?}
C --> |否| D[提示已满]
C --> |是| E[检查可用优惠券]
E --> F[处理优惠券应用]
F --> G[提交预约请求]
G --> H[等待API响应]
H --> I[更新本地状态]
I --> J[发送确认消息]
```

**图表来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L60-L63)

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

### 用户认证与会话管理

系统采用交互式对话方式进行用户认证：

```mermaid
sequenceDiagram
participant U as 用户
participant B as Bot
participant LC as LoginConversation
participant C as CosmoeClient
participant S as API服务
participant K as KV存储
U->>B : /login
B->>LC : 启动登录对话
LC->>U : 请求用户名
U->>LC : 输入用户名
LC->>U : 请求密码
U->>LC : 输入密码
LC->>C : getToken(username, password)
C->>S : POST 认证请求
S-->>C : 返回token
C-->>LC : 认证结果
LC->>K : 存储凭据
K-->>LC : 存储成功
LC-->>U : 登录成功消息
```

**图表来源**
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L13-L75)
- [src/command/index.ts](file://src/command/index.ts#L54-L57)

#### 凭据存储策略

系统使用 Cloudflare KV 存储用户凭据：
- 使用 Telegram 用户ID作为键
- 存储用户ID、token和时间戳
- 支持凭据的读取、写入和删除操作

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

### 预约历史管理

历史记录功能允许用户查看和管理过去的预约：

```mermaid
flowchart TD
A[用户请求历史] --> B[读取KV存储中的凭据]
B --> C{凭据存在?}
C --> |否| D[提示先登录]
C --> |是| E[初始化CosmoeClient]
E --> F[调用getMyBookings]
F --> G[处理预约数据]
G --> H{有历史记录?}
H --> |否| I[提示无记录]
H --> |是| J[格式化历史消息]
J --> K[按日期排序(最新在前)]
K --> L[限制显示数量]
L --> M[发送历史记录]
```

**图表来源**
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L4-L107)

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

### 实时通知系统

系统通过 Cloudflare Cron 触发器实现定时任务：

```mermaid
sequenceDiagram
participant CRON as Cron触发器
participant SCH as Scheduler
participant C as CosmoeClient
participant S as API服务
participant K as KV存储
participant U as 用户
CRON->>SCH : 每分钟触发
SCH->>C : getEvents()
C->>S : 获取活动列表
S-->>C : 返回最新活动
C-->>SCH : 活动数据
SCH->>K : 读取最新活动ID
K-->>SCH : 最新ID
SCH->>SCH : 过滤新活动
SCH->>K : 获取所有用户ID
K-->>SCH : 用户列表
SCH->>U : 发送新活动通知
SCH->>K : 更新最新活动ID
```

**图表来源**
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L12-L88)

#### 通知策略

系统实现了智能的新活动通知机制：
- 持续监控活动变化
- 仅向注册用户发送通知
- 使用 KV 存储跟踪最新活动ID
- 支持 Markdown 格式的富文本通知

**章节来源**
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)

## 依赖关系分析

系统依赖关系清晰，各组件职责明确：

```mermaid
graph TB
subgraph "外部依赖"
A[grammy - Telegram Bot框架]
B[@grammyjs/conversations - 对话插件]
C[@grammyjs/storage-cloudflare - KV存储适配器]
D[Cloudflare Workers Runtime]
end
subgraph "内部模块"
E[src/index.ts - 应用入口]
F[src/command/index.ts - 命令路由]
G[src/client/cosmoe.ts - API客户端]
H[src/command/handlers/* - 业务处理器]
I[src/scheduler/index.ts - 定时任务]
end
E --> F
F --> G
F --> H
I --> G
A --> E
B --> F
C --> F
D --> E
D --> I
```

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

### 外部服务集成

系统与多个外部服务进行集成：

```mermaid
erDiagram
TELEGRAM_BOT {
string BOT_TOKEN
object BOT_INFO
string USER_ID
string MESSAGE
}
COSMOE_API {
string BASE_URL
string API_KEY
string TOKEN
number USER_ID
}
CLOUDFLARE_KV {
string COSMOE_CREDENTIALS
string COSMOE_STORAGE
string LATEST_EVENT_ID
}
USER {
number TELEGRAM_ID
string USERNAME
string PASSWORD
string ACCESS_TOKEN
}
EVENT {
string ID
string NAME
string DESCRIPTION
string EVENT_DATE
string COVER_IMAGE_URL
}
BOOKING {
number ID
number USER_ID
string EVENT_ID
string TIME_SLOT
string STATUS
string FINAL_PRICE
}
TELEGRAM_BOT ||--o{ USER : "认证"
USER ||--o{ BOOKING : "创建"
BOOKING ||--|| EVENT : "关联"
COSMOE_API ||--o{ EVENT : "提供"
COSMOE_API ||--o{ BOOKING : "管理"
CLOUDFLARE_KV ||--o{ USER : "存储凭据"
CLOUDFLARE_KV ||--o{ EVENT : "跟踪活动"
```

**图表来源**
- [wrangler.jsonc](file://wrangler.jsonc#L21-L30)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)

**章节来源**
- [package.json](file://package.json#L1-L24)
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)

## 性能考虑

### 缓存策略

系统采用多层缓存策略优化性能：

1. **KV存储缓存**
   - 用户凭据缓存（短期有效）
   - 最新活动ID缓存（避免重复通知）
   - 会话状态缓存（对话管理）

2. **内存缓存**
   - API响应缓存（短期）
   - 配置信息缓存
   - 统计数据缓存

### 并发处理

系统支持高并发场景：
- 异步处理用户请求
- 非阻塞的API调用
- 流水线化的数据处理

### 错误处理与重试

```mermaid
flowchart TD
A[API调用] --> B{请求成功?}
B --> |是| C[正常处理]
B --> |否| D{错误类型}
D --> |网络错误| E[指数退避重试]
D --> |认证失败| F[重新认证]
D --> |业务错误| G[返回用户友好错误]
E --> H{重试次数}
H --> |达到上限| I[记录日志并返回错误]
H --> |未达上限| A
F --> J[刷新凭据]
J --> A
```

**图表来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L114-L117)

## 故障排除指南

### 常见问题诊断

#### 认证相关问题

**症状**: 用户无法登录或收到认证错误
**排查步骤**:
1. 检查用户凭据是否正确存储在 KV 中
2. 验证 API 令牌是否过期
3. 确认用户 ID 和 token 格式正确

#### API连接问题

**症状**: 系统无法获取活动数据
**排查步骤**:
1. 检查网络连接状态
2. 验证 API 端点可达性
3. 查看 API 响应状态码

#### 会话管理问题

**症状**: 对话无法正常结束或状态丢失
**排查步骤**:
1. 检查 KV 存储的会话数据
2. 验证会话超时设置
3. 确认对话生命周期管理

### 日志记录与监控

系统实现了全面的日志记录机制：
- 关键操作的执行日志
- 错误和异常的详细记录
- 性能指标的监控数据
- 用户行为的追踪记录

**章节来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L114-L117)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L81-L83)

## 结论

活动管理系统是一个功能完整、架构清晰的 Telegram 机器人应用。系统通过模块化设计实现了良好的可维护性和扩展性，同时采用了多种优化策略确保了良好的用户体验。

### 主要优势

1. **架构清晰**: 分层设计使得各组件职责明确，便于维护和测试
2. **功能完整**: 覆盖了活动管理的全流程需求
3. **性能优化**: 采用缓存和异步处理提升系统响应速度
4. **用户体验**: 提供直观的界面和及时的通知机制

### 改进建议

1. **增加搜索功能**: 实现基于关键词的活动搜索
2. **增强过滤选项**: 支持按日期、价格、地点等条件过滤
3. **优化移动端体验**: 针对移动设备优化界面布局
4. **添加数据分析**: 提供活动参与率等统计信息

## 附录

### API 接口规范

系统主要 API 接口包括：
- 获取活动列表：`GET /api.php?action=get_events`
- 获取活动详情：`GET /api.php?action=get_event_detail&event_id={id}`
- 用户认证：`POST /api.php?action=login`
- 预约管理：`POST /api.php?action=book_event`

### 配置选项

系统支持的配置项：
- BOT_TOKEN: Telegram 机器人的访问令牌
- BOT_INFO: 机器人基本信息
- COSMOE_CREDENTIALS: KV 命名空间绑定
- COSMOE_STORAGE: KV 存储命名空间

### 部署要求

- Node.js 版本: 16+
- Wrangler CLI: 3.0+
- Cloudflare Workers: 免费套餐即可运行