cosmoe-bot/.qoder/repowiki/zh/content/核心模块/API 客户端模块.md

API 客户端模块

本文档引用的文件

• cosmoe.ts
• index.ts
• login.ts
• bookEvent.ts
• events.ts
• eventDetails.ts
• history.ts
• cancel.ts
• logout.ts
• start.ts
• package.json

目录

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

简介

Cosmoe API 客户端模块是一个基于 TypeScript 的现代化 API 客户端库，专为与 Cosmoe 摄影平台进行交互而设计。该模块提供了完整的认证机制、用户管理、活动管理和预约管理功能，支持通过 Telegram 机器人界面进行用户友好的操作。

该客户端模块采用现代 JavaScript 特性，包括异步/等待模式、接口定义和类型安全，确保了代码的可维护性和可靠性。模块设计遵循单一职责原则，将 API 交互逻辑与业务逻辑分离，便于测试和扩展。

项目结构

项目采用模块化架构，主要包含以下核心目录和文件：

graph TB
subgraph "客户端层"
C1[src/client/cosmoe.ts<br/>主客户端类]
end
subgraph "命令处理器层"
H1[src/command/handlers/]
H2[login.ts<br/>登录处理]
H3[bookEvent.ts<br/>预约处理]
H4[events.ts<br/>活动列表]
H5[eventDetails.ts<br/>活动详情]
H6[history.ts<br/>历史记录]
H7[cancel.ts<br/>取消处理]
H8[logout.ts<br/>登出处理]
H9[start.ts<br/>启动命令]
end
subgraph "入口点"
E1[src/command/index.ts<br/>命令注册]
E2[src/index.ts<br/>应用入口]
end
subgraph "配置文件"
P1[package.json<br/>依赖管理]
W1[wrangler.jsonc<br/>Cloudflare Workers配置]
end
C1 --> H1
E1 --> H1
E2 --> E1

图表来源

• cosmoe.ts
• index.ts

章节来源

• cosmoe.ts
• index.ts

核心组件

CosmoeClient 主类

CosmoeClient 是整个模块的核心类，提供了所有与 Cosmoe API 交互的功能。该类采用面向对象设计，封装了所有 API 调用逻辑，并提供了清晰的方法接口。

主要特性

• 认证管理: 支持用户名密码认证和手动凭证设置
• 数据模型: 完整的 TypeScript 接口定义
• 错误处理: 统一的响应格式和错误处理机制
• 类型安全: 全面的 TypeScript 类型定义

关键属性

• baseUrl: API 基础 URL (https://cos.cx/api/v1)
• userId: 当前认证用户的 ID
• token: 认证令牌

章节来源

• cosmoe.ts

架构概览

系统采用分层架构设计，实现了关注点分离：

graph TB
subgraph "表现层"
UI[Telegram 机器人界面]
CMD[命令处理器]
end
subgraph "业务逻辑层"
BC[CosmoeClient<br/>核心业务逻辑]
UT[工具函数<br/>数据验证]
end
subgraph "数据访问层"
API[Cosmoe API<br/>RESTful 接口]
KV[KV 存储<br/>凭证持久化]
end
subgraph "配置层"
CFG[环境配置]
LOG[日志系统]
end
UI --> CMD
CMD --> BC
BC --> API
BC --> KV
CMD --> KV
BC --> CFG
CMD --> LOG

图表来源

• cosmoe.ts
• index.ts

详细组件分析

认证机制

getToken 方法

负责用户身份验证，通过用户名和密码获取认证令牌。

方法签名: getToken(username: string, password: string): Promise<ApiResponse<TokenResponse>>

参数:

• username: 用户名 (字符串)
• password: 密码 (字符串)

返回值: ApiResponse<TokenResponse>

• code: HTTP 状态码
• msg: 错误消息 (可选)
• data: 包含 user_id 和 token 的响应数据

错误处理:

• 认证失败时抛出 Error("Authentication required")
• 网络请求异常时返回统一的错误格式

使用示例路径:

• 登录处理器

章节来源

• cosmoe.ts
• login.ts

setCredentials 和 getCredentials 方法

提供手动设置和获取用户凭证的功能。

setCredentials 方法:

• 参数: userId: number, token: string
• 功能: 手动设置认证信息
• 返回: void

getCredentials 方法:

• 返回: { userId: number, token: string } | null
• 功能: 获取当前认证信息，如果未认证则返回 null

isAuthenticated 方法:

• 返回: boolean
• 功能: 检查用户是否已认证

章节来源

• cosmoe.ts

用户管理功能

getUserProfile 方法

获取用户个人信息和统计信息。

方法签名: getUserProfile(): Promise<ApiResponse<UserProfile>>

返回值: ApiResponse<UserProfile>

• user_info: 用户基本信息
• statistics: 预约统计信息

UserProfile 接口:

• user_info: UserInfo 对象
• statistics: Statistics 对象

章节来源

• cosmoe.ts

changePassword 方法

修改用户密码。

方法签名: changePassword(currentPassword: string, newPassword: string): Promise<ApiResponse<any>>

参数:

• currentPassword: 当前密码
• newPassword: 新密码 (至少6个字符)

错误处理:

• 新密码长度不足时抛出 Error("New password must be at least 6 characters")

章节来源

• cosmoe.ts

register 方法

注册新用户。

方法签名: register(key: string, username: string, email: string, password: string, userIdentity: string = "photographer"): Promise<ApiResponse<{ user_id: number, username: string }>>

参数:

• key: 权限密钥 (联系管理员获取)
• username: 用户名 (2-10字符，仅允许字母数字和下划线)
• email: 邮箱地址
• password: 密码 (至少6个字符)
• userIdentity: 用户身份 (默认: "photographer")

返回值: 注册成功的用户信息

章节来源

• cosmoe.ts

活动管理功能

getEvents 方法

获取活动列表。

方法签名: getEvents(): Promise<ApiResponse<Event[]>>

返回值: ApiResponse<Event[]>

• Event 接口包含活动的基本信息

Event 接口字段:

• id: 活动ID (字符串)
• name: 活动名称
• description: 活动描述
• event_date: 活动日期
• cover_image_url: 封面图片URL
• description_brief: 简短描述

章节来源

• cosmoe.ts

getEventDetail 方法

获取活动详细信息。

方法签名: getEventDetail(eventId: number | string): Promise<ApiResponse<EventDetail>>

返回值: ApiResponse<EventDetail>

• EventDetail 接口包含活动的完整信息

EventDetail 接口字段:

• id: 活动ID (数字)
• name: 活动名称
• description: 活动描述
• event_date: 活动日期
• time_slots_with_prices: 时间段价格字符串
• cover_image_url: 封面图片URL
• detail_image_urls: 详情图片URL数组
• slots: TimeSlot 数组
• allow_coupons: 是否允许使用优惠券

TimeSlot 接口字段:

• range: 时间段范围 (如 "13:30-14:30")
• price: 价格 (字符串格式)
• capacity: 总容量
• remaining: 剩余位置

章节来源

• cosmoe.ts

预约管理功能

getMyBookings 方法

获取用户的预约历史。

方法签名: getMyBookings(): Promise<ApiResponse<Booking[]>>

返回值: ApiResponse<Booking[]>

• Booking 接口包含预约信息

Booking 接口字段:

• id: 预约ID
• status: 预约状态
• booking_date: 预约日期
• time_slot: 时间段
• final_price: 最终价格
• payment_order_id: 支付订单ID
• notes_by_user: 用户备注
• created_at: 创建时间
• event_name: 活动名称

章节来源

• cosmoe.ts

bookEvent 方法

预订活动。

方法签名: bookEvent(bookingRequest: BookingRequest): Promise<ApiResponse<any>>

参数: BookingRequest 对象

• event_id: 活动ID
• time_slot: 时间段
• user_note: 用户备注 (可选)
• coupon_code: 优惠码 (可选)

返回值: 预订结果

章节来源

• cosmoe.ts

取消和修改功能

cancelBooking 方法

取消预约。

方法签名: cancelBooking(bookingId: number): Promise<ApiResponse<any>>

参数:

• bookingId: 预约ID

章节来源

• cosmoe.ts

updatePaymentOrder 方法

更新支付订单ID。

方法签名: updatePaymentOrder(bookingId: number, paymentOrderId: string): Promise<ApiResponse<any>>

章节来源

• cosmoe.ts

updateBookingNote 方法

更新预约备注。

方法签名: updateBookingNote(bookingId: number, note: string): Promise<ApiResponse<any>>

章节来源

• cosmoe.ts

selfReschedule 方法

自助改期。

方法签名: selfReschedule(bookingId: number, newTimeSlot: string): Promise<ApiResponse<any>>

章节来源

• cosmoe.ts

selfTransfer 方法

自助转让。

方法签名: selfTransfer(bookingId: number, recipientUsername: string): Promise<ApiResponse<any>>

章节来源

• cosmoe.ts

优惠券系统

getAvailableCoupons 方法

获取活动可用的优惠券。

方法签名: getAvailableCoupons(eventId: number | string): Promise<ApiResponse<Coupon[]>>

返回值: ApiResponse<Coupon[]>

• Coupon 接口包含优惠券信息

Coupon 接口字段:

• id: 优惠券ID
• code: 优惠码
• type: 类型 ('percentage' 或 'fixed')
• value: 优惠值
• valid_to: 有效期

章节来源

• cosmoe.ts

依赖关系分析

外部依赖

项目使用以下关键依赖：

graph LR
subgraph "核心框架"
G[grammy<br/>Telegram 机器人框架]
C[conversations<br/>对话插件]
S[storage-cloudflare<br/>KV存储]
end
subgraph "开发工具"
V[vitest<br/>测试框架]
W[wrangler<br/>Cloudflare Workers]
T[typescript<br/>类型系统]
end
subgraph "项目模块"
CC[CosmoeClient]
HP[Handlers]
CM[Commands]
end
G --> C
G --> S
V --> W
CC --> HP
HP --> CM

图表来源

• package.json

内部依赖关系

graph TB
subgraph "客户端层"
CC[CosmoeClient]
MD[数据模型]
end
subgraph "命令层"
LH[登录处理器]
BH[预约处理器]
EH[事件处理器]
HH[历史处理器]
CH[取消处理器]
LOGH[登出处理器]
end
subgraph "存储层"
KV[KV 存储]
end
CC --> MD
LH --> CC
BH --> CC
EH --> CC
HH --> CC
CH --> CC
LOGH --> CC
CC --> KV
LH --> KV
BH --> KV
CH --> KV

图表来源

• cosmoe.ts
• login.ts

章节来源

• package.json

性能考虑

缓存策略

• 认证缓存: 使用 Cloudflare KV 存储用户凭证，避免重复认证
• 数据缓存: 在会话期间缓存常用数据，减少 API 调用频率
• 连接复用: 使用持久连接减少网络开销

错误处理优化

• 重试机制: 对临时性错误实施指数退避重试
• 超时控制: 设置合理的请求超时时间
• 降级策略: 在 API 不可用时提供本地降级选项

内存管理

• 对象池: 复用频繁创建的对象实例
• 垃圾回收: 及时清理不再使用的引用
• 内存泄漏防护: 确保事件监听器正确移除

故障排除指南

常见问题及解决方案

认证失败

症状: Authentication required 错误 原因: 凭证过期或无效 解决:

1. 重新执行 /login 命令
2. 检查用户名和密码
3. 验证网络连接

API 调用超时

症状: 请求在合理时间内无响应 原因: 网络延迟或服务器负载过高 解决:

1. 检查网络连接稳定性
2. 实施重试机制
3. 调整超时参数

数据格式错误

症状: 解析响应时出现类型错误 原因: API 响应格式变化 解决:

1. 更新数据模型定义
2. 添加类型验证
3. 实施向后兼容性检查

调试技巧

日志记录

• 启用详细的 API 调用日志
• 记录请求和响应的完整内容
• 监控错误发生的时间和频率

性能监控

• 监控 API 响应时间
• 跟踪内存使用情况
• 分析并发请求处理能力

章节来源

• login.ts
• bookEvent.ts

结论

Cosmoe API 客户端模块是一个设计精良、功能完整的现代化 API 客户端库。它成功地将复杂的 API 交互逻辑封装在简洁易用的接口后面，同时保持了高度的类型安全和错误处理能力。

主要优势

• 模块化设计: 清晰的关注点分离，便于维护和扩展
• 类型安全: 完整的 TypeScript 类型定义，提供编译时检查
• 错误处理: 统一的错误处理机制和用户友好的错误消息
• 性能优化: 合理的缓存策略和资源管理
• 可测试性: 清晰的接口设计，便于单元测试和集成测试

技术亮点

• 使用现代 JavaScript 特性 (async/await, TypeScript)
• 采用分层架构设计
• 实现了完整的认证和授权机制
• 提供了丰富的数据模型和验证逻辑
• 集成了 Cloudflare Workers 和 KV 存储

未来改进方向

• 添加更多的缓存策略
• 实现更精细的错误分类和处理
• 增加更多的监控和日志功能
• 扩展对更多 API 功能的支持
• 提供更丰富的配置选项

该模块为构建可靠的 Telegram 机器人应用提供了坚实的基础，能够满足摄影活动预约系统的各种需求。