# 数据模型设计
**本文档引用的文件**
- [src/index.ts](file://src/index.ts)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts)
- [src/command/handlers/history.ts](file://src/command/handlers/history.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/index.ts](file://src/command/index.ts)
- [src/scheduler/index.ts](file://src/scheduler/index.ts)
- [wrangler.jsonc](file://wrangler.jsonc)
- [worker-configuration.d.ts](file://worker-configuration.d.ts)
- [package.json](file://package.json)
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心数据实体](#核心数据实体)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 引言
本文件为 Cosmoe 摄影活动预约机器人项目的数据模型设计综合文档。该系统通过 Telegram 机器人与 Cosmoe API 进行交互，实现用户认证、活动查询、预约管理、优惠券使用等功能。本文档详细定义了核心数据实体（用户、活动、预约、优惠券）的结构、字段定义、关系以及数据验证规则，并提供了数据转换映射策略、版本管理与兼容性处理方案，以及数据安全考虑。
## 项目结构
该项目采用基于功能模块的组织方式，主要分为以下层次：
- 入口层：负责初始化机器人、设置命令菜单、处理 Webhook 请求
- 命令处理器层：处理各类用户命令（登录、查询活动、查看历史、预约等）
- 客户端层：封装对 Cosmoe API 的调用，定义数据接口模型
- 调度器层：定时任务，用于新活动通知
- 存储层：使用 Cloudflare Workers KV 存储用户凭证和系统状态
```mermaid
graph TB
subgraph "入口层"
Index["src/index.ts
机器人初始化与Webhook"]
Scheduler["src/scheduler/index.ts
定时任务调度"]
end
subgraph "命令处理器层"
Login["src/command/handlers/login.ts
登录处理"]
Events["src/command/handlers/events.ts
活动列表"]
EventDetails["src/command/handlers/eventDetails.ts
活动详情"]
History["src/command/handlers/history.ts
预约历史"]
BookEvent["src/command/handlers/bookEvent.ts
预约处理"]
CommandIndex["src/command/index.ts
命令注册与会话存储"]
end
subgraph "客户端层"
CosmoeClient["src/client/cosmoe.ts
Cosmoe API 客户端"]
end
subgraph "存储层"
KV["Cloudflare KV
COSMOE_CREDENTIALS/COSMOE_STORAGE"]
end
Index --> CommandIndex
CommandIndex --> Login
CommandIndex --> Events
CommandIndex --> EventDetails
CommandIndex --> History
CommandIndex --> BookEvent
Login --> CosmoeClient
Events --> CosmoeClient
EventDetails --> CosmoeClient
History --> CosmoeClient
BookEvent --> CosmoeClient
CosmoeClient --> KV
Scheduler --> CosmoeClient
Scheduler --> KV
```
**图表来源**
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L30-L76)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
**章节来源**
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L30-L76)
- [wrangler.jsonc](file://wrangler.jsonc#L21-L30)
## 核心数据实体
### 用户模型 (User)
用户模型用于描述系统中的用户身份信息，支持认证与授权操作。
- 字段定义
- id: 数字型用户标识符
- username: 用户名
- email: 邮箱地址
- user_identity: 用户身份（如 coser/photographer/other）
- role: 角色
- is_active: 是否激活（数值型布尔值）
- created_at: 创建时间
- 关系
- 与预约模型存在一对多关系（一个用户可有多条预约记录）
- 数据验证规则
- 必填字段：id、username、email、user_identity、role、is_active、created_at
- 数据类型：id 为数字；is_active 为数值型布尔值；created_at 为字符串格式的时间戳
- 范围验证：无特定范围限制
- 数据转换与映射
- API 响应到内部模型：直接映射字段，保持原始数据结构
- 格式标准化：统一使用字符串表示时间戳
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L52-L60)
### 活动模型 (Event)
活动模型描述摄影活动的基本信息，支持活动列表展示与详情查询。
- 字段定义
- id: 字符串型活动标识符（API 返回为字符串）
- name: 活动名称
- description: 活动描述
- event_date: 活动日期（字符串格式）
- cover_image_url: 封面图片 URL
- description_brief: 简短描述
- 关系
- 与时间槽模型存在一对多关系（一个活动可有多个时间槽）
- 与预约模型存在一对多关系（一个活动可被多次预约）
- 数据验证规则
- 必填字段：id、name、description、event_date、cover_image_url、description_brief
- 数据类型：id 为字符串；其他为字符串
- 范围验证：无特定范围限制
- 数据转换与映射
- API 响应到内部模型：字段直接映射，保持原始数据结构
- 格式标准化：统一使用字符串表示日期和时间
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L20-L27)
### 活动详情模型 (EventDetail)
活动详情模型扩展了活动基本信息，包含更详细的描述和时间槽信息。
- 字段定义
- id: 数字型活动标识符
- name: 活动名称
- description: 活动描述
- event_date: 活动日期（字符串格式）
- time_slots_with_prices: 时间槽与价格的原始字符串
- cover_image_url: 封面图片 URL
- detail_image_urls: 详情图片 URL 列表
- is_listed: 是否发布（数值型布尔值）
- login_required: 是否需要登录（数值型布尔值）
- allow_coupons: 是否允许使用优惠券（数值型布尔值）
- created_at: 创建时间
- slots: 时间槽数组
- gallery: 图片画廊 URL 数组
- 关系
- 与时间槽模型存在一对多关系
- 与预约模型存在一对多关系
- 数据验证规则
- 必填字段：id、name、description、event_date、cover_image_url、detail_image_urls、is_listed、login_required、allow_coupons、created_at、slots、gallery
- 数据类型：id 为数字；is_listed、login_required、allow_coupons 为数值型布尔值；slots 为数组
- 范围验证：无特定范围限制
- 数据转换与映射
- API 响应到内部模型：字段直接映射，保持原始数据结构
- 格式标准化：统一使用字符串表示日期和时间
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L36-L50)
### 时间槽模型 (TimeSlot)
时间槽模型描述活动的具体时间段安排。
- 字段定义
- range: 时间段范围（如 "13:30-14:30"）
- price: 价格（字符串形式）
- capacity: 总容量
- remaining: 剩余座位数
- 关系
- 与活动模型存在一对多关系
- 与预约模型存在一对多关系
- 数据验证规则
- 必填字段：range、price、capacity、remaining
- 数据类型：range 为字符串；price 为字符串；capacity 和 remaining 为数字
- 范围验证：capacity 和 remaining 应为非负整数
- 数据转换与映射
- API 响应到内部模型：字段直接映射，保持原始数据结构
- 格式标准化：价格统一使用字符串表示
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L29-L34)
### 预约模型 (Booking)
预约模型描述用户的活动预约信息。
- 字段定义
- id: 数字型预约标识符
- status: 预约状态（字符串）
- booking_date: 预约日期（字符串格式）
- time_slot: 时间槽（字符串）
- final_price: 最终价格（字符串）
- payment_order_id: 支付订单号（字符串）
- notes_by_user: 用户备注（字符串）
- created_at: 创建时间（字符串）
- event_name: 活动名称（字符串）
- 关系
- 与用户模型存在多对一关系
- 与活动模型存在多对一关系
- 数据验证规则
- 必填字段：id、status、booking_date、time_slot、final_price、payment_order_id、notes_by_user、created_at、event_name
- 数据类型：id 为数字；其他为字符串
- 范围验证：无特定范围限制
- 数据转换与映射
- API 响应到内部模型：字段直接映射，保持原始数据结构
- 格式标准化：统一使用字符串表示日期和时间
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L95-L105)
### 优惠券模型 (Coupon)
优惠券模型描述可用于活动预约的折扣券信息。
- 字段定义
- id: 数字型优惠券标识符
- code: 优惠券代码（字符串）
- type: 优惠券类型（字符串，'percentage' 或 'fixed'）
- value: 优惠券数值（数字）
- valid_to: 有效期截止时间（字符串格式）
- 关系
- 与活动模型存在多对一关系
- 与预约模型存在多对一关系
- 数据验证规则
- 必填字段：id、code、type、value、valid_to
- 数据类型：id 为数字；type 为字符串且仅限 'percentage' 或 'fixed'；value 为数字；valid_to 为字符串
- 范围验证：type 必须为 'percentage' 或 'fixed'
- 数据转换与映射
- API 响应到内部模型：字段直接映射，保持原始数据结构
- 格式标准化：统一使用字符串表示日期和时间
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L68-L74)
## 架构概览
系统采用分层架构，各层职责明确，耦合度低，便于维护和扩展。
```mermaid
graph TB
subgraph "表现层"
TelegramBot["Telegram Bot API"]
InlineKeyboard["内联键盘"]
end
subgraph "应用层"
CommandHandlers["命令处理器"]
ConversationStorage["会话存储"]
end
subgraph "服务层"
CosmoeAPIClient["Cosmoe API 客户端"]
ValidationRules["验证规则"]
end
subgraph "数据层"
KVStore["Cloudflare KV 存储"]
APIServer["Cosmoe API 服务器"]
end
TelegramBot --> CommandHandlers
CommandHandlers --> ConversationStorage
CommandHandlers --> CosmoeAPIClient
CosmoeAPIClient --> ValidationRules
CosmoeAPIClient --> APIServer
ConversationStorage --> KVStore
KVStore --> APIServer
```
**图表来源**
- [src/command/index.ts](file://src/command/index.ts#L30-L76)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L503)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
## 详细组件分析
### 登录流程
登录流程涉及用户凭证的获取、存储和验证。
```mermaid
sequenceDiagram
participant User as "用户"
participant Bot as "Telegram Bot"
participant Handler as "登录处理器"
participant Client as "Cosmoe 客户端"
participant KV as "KV 存储"
participant API as "Cosmoe API"
User->>Bot : 发送 /login 命令
Bot->>Handler : 调用登录处理器
Handler->>User : 请求用户名
User->>Handler : 输入用户名
Handler->>User : 请求密码
User->>Handler : 输入密码
Handler->>Client : 获取令牌
Client->>API : POST /CreatToken.php
API-->>Client : 返回令牌
Client-->>Handler : 返回认证结果
alt 认证成功
Handler->>KV : 存储凭证
KV-->>Handler : 存储成功
Handler-->>User : 登录成功消息
else 认证失败
Handler-->>User : 登录失败消息
end
```
**图表来源**
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L13-L75)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L124-L140)
**章节来源**
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)
### 预约流程
预约流程包含活动选择、时间槽选择、优惠券使用和最终确认。
```mermaid
flowchart TD
Start([开始预约]) --> CheckAuth["检查用户认证"]
CheckAuth --> AuthOK{"已认证？"}
AuthOK --> |否| PromptLogin["提示登录"]
AuthOK --> |是| FetchEvents["获取活动列表"]
FetchEvents --> SelectEvent["选择活动"]
SelectEvent --> FetchDetails["获取活动详情"]
FetchDetails --> CheckSlots{"有可用时间槽？"}
CheckSlots --> |否| NoSlots["提示无可用时间槽"]
CheckSlots --> |是| ShowSlots["显示时间槽"]
ShowSlots --> SelectSlot["选择时间槽"]
SelectSlot --> CheckCoupons{"有可用优惠券？"}
CheckCoupons --> |否| ConfirmBooking["确认预约"]
CheckCoupons --> |是| ShowCoupons["显示优惠券"]
ShowCoupons --> ApplyCoupon["应用优惠券"]
ApplyCoupon --> ConfirmBooking
ConfirmBooking --> SubmitBooking["提交预约请求"]
SubmitBooking --> BookingOK["预约成功"]
NoSlots --> End([结束])
PromptLogin --> End
BookingOK --> End
```
**图表来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L39-L103)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L247-L270)
**章节来源**
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L39-L103)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L247-L270)
### 数据验证与业务约束
系统在多个层面实施数据验证和业务约束：
- 字段完整性验证
- 必填字段检查：所有核心模型的关键字段都必须存在
- 类型验证：严格的数据类型检查，确保字段类型正确
- 范围验证：对数值字段进行合理的范围检查
- 业务逻辑验证
- 时间槽容量验证：确保剩余座位数大于零
- 优惠券有效性验证：检查优惠券类型和有效期
- 用户权限验证：某些操作需要有效的认证状态
- 数据转换策略
- API 响应标准化：统一处理不同 API 版本的数据格式
- 类型转换：在必要时进行类型转换以满足内部模型要求
- 格式规范化：统一日期和时间的表示格式
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L284-L286)
- [src/command/handlers/bookEvent.ts](file://src/command/handlers/bookEvent.ts#L60-L63)
### 数据转换与映射策略
系统实现了多种数据转换和映射策略：
- API 响应到内部模型的转换
- 直接字段映射：大部分情况下采用一对一的字段映射
- 结构重组：对复杂的数据结构进行扁平化处理
- 类型转换：在必要时进行类型转换以满足内部要求
- 数据格式标准化
- 日期时间格式：统一使用 ISO 8601 格式
- 数值格式：统一使用字符串表示货币金额
- 布尔值：统一使用数值型布尔值表示
- 向后兼容性处理
- 字段类型兼容：支持字符串和数字类型的混合处理
- 接口版本管理：通过类型声明和注释标记版本差异
- 渐进式迁移：逐步更新数据结构而不影响现有功能
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L107-L111)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L177-L184)
### 数据版本管理与兼容性
系统采用了多层次的版本管理和兼容性处理机制：
- 接口版本控制
- 明确的接口版本标记：通过注释和类型声明标识 API 版本
- 向后兼容策略：保持旧接口的同时引入新功能
- 渐进式更新：分阶段更新数据结构和接口定义
- 数据迁移策略
- 字段类型迁移：从数字类型迁移到字符串类型
- 结构变化处理：通过适配器模式处理结构变化
- 兼容性测试：确保新旧版本之间的数据兼容性
- 版本演进路径
- 当前状态：API 返回字符串类型的活动 ID
- 迁移计划：逐步统一为数字类型
- 兼容措施：同时支持两种类型的数据
**章节来源**
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L20-L27)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L37-L49)
### 数据安全考虑
系统在数据安全方面采取了多项措施：
- 敏感信息保护
- 凭证加密存储：用户凭据存储在 KV 中，避免明文传输
- 密码强度验证：强制至少 6 位字符的密码长度
- 会话管理：通过令牌机制管理用户会话状态
- 访问权限控制
- 认证要求：大部分操作需要有效的认证状态
- 权限分离：区分普通用户和管理员权限
- 资源访问控制：限制对敏感资源的访问
- 数据传输安全
- HTTPS 通信：所有 API 调用使用 HTTPS 协议
- 参数验证：对所有输入参数进行严格的验证
- 错误处理：避免泄露敏感信息的错误消息
**章节来源**
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L49-L63)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L284-L286)
## 依赖关系分析
系统依赖关系清晰，各组件之间耦合度低，便于维护和扩展。
```mermaid
graph TB
subgraph "外部依赖"
Grammy["@grammyjs/conversations
对话插件"]
Cloudflare["@grammyjs/storage-cloudflare
存储适配器"]
WorkerRuntime["Cloudflare Workers Runtime
运行时环境"]
end
subgraph "内部模块"
Index["src/index.ts
主入口"]
CommandIndex["src/command/index.ts
命令注册"]
LoginHandler["src/command/handlers/login.ts
登录处理器"]
CosmoeClient["src/client/cosmoe.ts
API 客户端"]
end
Index --> CommandIndex
CommandIndex --> LoginHandler
LoginHandler --> CosmoeClient
CosmoeClient --> WorkerRuntime
CommandIndex --> Grammy
CommandIndex --> Cloudflare
```
**图表来源**
- [package.json](file://package.json#L18-L22)
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L30-L76)
**章节来源**
- [package.json](file://package.json#L18-L22)
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
## 性能考量
系统在性能方面考虑了多个因素：
- 异步处理
- 使用 Promise 和 async/await 处理异步操作
- 避免阻塞主线程的操作
- 合理的并发控制
- 缓存策略
- KV 存储作为缓存层
- 会话状态的持久化存储
- 定时任务优化
- 内存管理
- 及时清理不再使用的变量
- 合理的数据结构选择
- 避免内存泄漏
- 网络优化
- 批量请求处理
- 错误重试机制
- 超时控制
## 故障排除指南
常见问题及解决方案：
- 认证失败
- 检查用户名和密码是否正确
- 验证网络连接是否正常
- 查看 API 返回的错误信息
- 预约失败
- 确认活动是否有可用时间槽
- 检查优惠券的有效性
- 验证支付订单号的正确性
- 数据同步问题
- 检查 KV 存储的状态
- 验证 API 响应的完整性
- 查看日志中的错误信息
**章节来源**
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L67-L69)
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L34-L37)
## 结论
本数据模型设计文档全面阐述了 Cosmoe 摄影活动预约机器人的核心数据实体、关系结构、验证规则和转换策略。系统采用分层架构，实现了良好的模块化和可维护性。通过严格的验证规则、数据转换策略和安全措施，确保了系统的稳定性和可靠性。建议在未来版本中进一步完善数据模型的规范化和性能优化，以提升用户体验和系统效率。