# API 客户端模块

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

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

## 简介

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

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

## 项目结构

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

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

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

## 核心组件

### CosmoeClient 主类

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

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

#### 关键属性
- `baseUrl`: API 基础 URL (`https://cos.cx/api/v1`)
- `userId`: 当前认证用户的 ID
- `token`: 认证令牌

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)

## 架构概览

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

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

## 详细组件分析

### 认证机制

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

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

**参数**:
- `username`: 用户名 (字符串)
- `password`: 密码 (字符串)

**返回值**: `ApiResponse<TokenResponse>`
- `code`: HTTP 状态码
- `msg`: 错误消息 (可选)
- `data`: 包含 `user_id` 和 `token` 的响应数据

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

**使用示例路径**:
- [登录处理器](file://src/command/handlers/login.ts#L47-L69)

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L124-L140)
- [login.ts](file://src/command/handlers/login.ts#L47-L69)

#### setCredentials 和 getCredentials 方法
提供手动设置和获取用户凭证的功能。

**setCredentials 方法**:
- 参数: `userId: number, token: string`
- 功能: 手动设置认证信息
- 返回: `void`

**getCredentials 方法**:
- 返回: `{ userId: number, token: string } | null`
- 功能: 获取当前认证信息，如果未认证则返回 null

**isAuthenticated 方法**:
- 返回: `boolean`
- 功能: 检查用户是否已认证

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L147-L171)

### 用户管理功能

#### getUserProfile 方法
获取用户个人信息和统计信息。

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

**返回值**: `ApiResponse<UserProfile>`
- `user_info`: 用户基本信息
- `statistics`: 预约统计信息

**UserProfile 接口**:
- `user_info`: UserInfo 对象
- `statistics`: Statistics 对象

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L308-L321)

#### changePassword 方法
修改用户密码。

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

**参数**:
- `currentPassword`: 当前密码
- `newPassword`: 新密码 (至少6个字符)

**错误处理**:
- 新密码长度不足时抛出 `Error("New password must be at least 6 characters")`

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L279-L301)

#### 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](file://src/client/cosmoe.ts#L487-L502)

### 活动管理功能

#### getEvents 方法
获取活动列表。

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

**返回值**: `ApiResponse<Event[]>`
- `Event` 接口包含活动的基本信息

**Event 接口字段**:
- `id`: 活动ID (字符串)
- `name`: 活动名称
- `description`: 活动描述
- `event_date`: 活动日期
- `cover_image_url`: 封面图片URL
- `description_brief`: 简短描述

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L177-L184)

#### 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](file://src/client/cosmoe.ts#L191-L199)

### 预约管理功能

#### 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](file://src/client/cosmoe.ts#L226-L239)

#### bookEvent 方法
预订活动。

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

**参数**: `BookingRequest` 对象
- `event_id`: 活动ID
- `time_slot`: 时间段
- `user_note`: 用户备注 (可选)
- `coupon_code`: 优惠码 (可选)

**返回值**: 预订结果

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L247-L270)

#### 取消和修改功能

##### cancelBooking 方法
取消预约。

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

**参数**:
- `bookingId`: 预约ID

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L405-L422)

##### updatePaymentOrder 方法
更新支付订单ID。

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

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L352-L370)

##### updateBookingNote 方法
更新预约备注。

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

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L379-L397)

##### selfReschedule 方法
自助改期。

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

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L431-L449)

##### selfTransfer 方法
自助转让。

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

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L458-L476)

### 优惠券系统

#### getAvailableCoupons 方法
获取活动可用的优惠券。

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

**返回值**: `ApiResponse<Coupon[]>`
- `Coupon` 接口包含优惠券信息

**Coupon 接口字段**:
- `id`: 优惠券ID
- `code`: 优惠码
- `type`: 类型 ('percentage' 或 'fixed')
- `value`: 优惠值
- `valid_to`: 有效期

**章节来源**
- [cosmoe.ts](file://src/client/cosmoe.ts#L329-L343)

## 依赖关系分析

### 外部依赖

项目使用以下关键依赖：

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

### 内部依赖关系

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

**章节来源**
- [package.json](file://package.json#L18-L23)

## 性能考虑

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

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

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

## 故障排除指南

### 常见问题及解决方案

#### 认证失败
**症状**: `Authentication required` 错误
**原因**: 凭证过期或无效
**解决**: 
1. 重新执行 `/login` 命令
2. 检查用户名和密码
3. 验证网络连接

#### API 调用超时
**症状**: 请求在合理时间内无响应
**原因**: 网络延迟或服务器负载过高
**解决**:
1. 检查网络连接稳定性
2. 实施重试机制
3. 调整超时参数

#### 数据格式错误
**症状**: 解析响应时出现类型错误
**原因**: API 响应格式变化
**解决**:
1. 更新数据模型定义
2. 添加类型验证
3. 实施向后兼容性检查

### 调试技巧

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

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

**章节来源**
- [login.ts](file://src/command/handlers/login.ts#L70-L73)
- [bookEvent.ts](file://src/command/handlers/bookEvent.ts#L114-L117)

## 结论

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

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

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

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

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