cosmoe-bot/.qoder/repowiki/zh/content/核心模块/活动管理系统.md

活动管理系统

本文档引用的文件

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

目录

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

简介

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

该系统的核心功能包括：

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

项目结构

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

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
• src/command/index.ts
• src/client/cosmoe.ts

章节来源

• src/index.ts
• src/command/index.ts
• wrangler.jsonc

核心组件

API 客户端 (CosmoeClient)

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

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

命令处理器系统

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

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
• src/client/cosmoe.ts

章节来源

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

架构概览

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

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
• src/command/index.ts

数据流处理

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

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
• src/command/handlers/history.ts

详细组件分析

活动列表获取与展示

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

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
• src/client/cosmoe.ts

分页处理机制

系统实现了简单的分页策略：

• 默认只显示最新的10个活动
• 支持按事件ID排序（降序）
• 自动截断超出限制的消息内容

活动过滤与排序

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

章节来源

• src/command/handlers/events.ts

活动详情页面设计

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

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
• src/client/cosmoe.ts

图片展示机制

系统支持多种图片展示：

• 封面图片：用于活动的主要视觉展示
• 详情图片：活动的扩展图片集合
• 图片URL验证：确保图片链接的有效性

时间槽信息管理

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

图表来源

• src/command/handlers/eventDetails.ts

价格显示与可用性状态

系统实现了智能的价格和状态显示：

• 显示原价和剩余容量
• 根据活动日期动态调整可用性状态
• 提供预约链接（仅对可预约的时间槽）

章节来源

• src/command/handlers/eventDetails.ts

预约管理功能

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

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
• src/command/handlers/bookEvent.ts

优惠券系统集成

系统支持多种类型的优惠券：

• 固定金额折扣
• 百分比折扣
• 自动选择最优优惠券
• 手动选择特定优惠券

实时状态更新

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

章节来源

• src/command/handlers/bookEvent.ts

用户认证与会话管理

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

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
• src/command/index.ts

凭据存储策略

系统使用 Cloudflare KV 存储用户凭据：

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

章节来源

• src/command/handlers/login.ts
• src/command/index.ts

预约历史管理

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

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

章节来源

• src/command/handlers/history.ts

实时通知系统

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

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

通知策略

系统实现了智能的新活动通知机制：

• 持续监控活动变化
• 仅向注册用户发送通知
• 使用 KV 存储跟踪最新活动ID
• 支持 Markdown 格式的富文本通知

章节来源

• src/scheduler/index.ts

依赖关系分析

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

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
• src/index.ts

外部服务集成

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

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
• src/client/cosmoe.ts

章节来源

• package.json
• wrangler.jsonc

性能考虑

缓存策略

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

1. KV存储缓存

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

2. 内存缓存

   • API响应缓存（短期）
   • 配置信息缓存
   • 统计数据缓存

并发处理

系统支持高并发场景：

• 异步处理用户请求
• 非阻塞的API调用
• 流水线化的数据处理

错误处理与重试

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

故障排除指南

常见问题诊断

认证相关问题

症状: 用户无法登录或收到认证错误 排查步骤:

1. 检查用户凭据是否正确存储在 KV 中
2. 验证 API 令牌是否过期
3. 确认用户 ID 和 token 格式正确

API连接问题

症状: 系统无法获取活动数据 排查步骤:

1. 检查网络连接状态
2. 验证 API 端点可达性
3. 查看 API 响应状态码

会话管理问题

症状: 对话无法正常结束或状态丢失 排查步骤:

1. 检查 KV 存储的会话数据
2. 验证会话超时设置
3. 确认对话生命周期管理

日志记录与监控

系统实现了全面的日志记录机制：

• 关键操作的执行日志
• 错误和异常的详细记录
• 性能指标的监控数据
• 用户行为的追踪记录

章节来源

• src/command/handlers/bookEvent.ts
• src/scheduler/index.ts

结论

活动管理系统是一个功能完整、架构清晰的 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: 免费套餐即可运行