# 用量统计

## Purpose

TBD - 提供请求用量统计的记录和查询功能

## Requirements

### Requirement: 记录请求统计

网关 SHALL 为每次 API 调用记录请求统计。

#### Scenario: 记录成功请求

- **WHEN** 请求成功转发到供应商
- **THEN** 网关 SHALL 增加该供应商和模型的请求计数
- **THEN** 网关 SHALL 记录当前日期的统计

#### Scenario: 记录流式请求

- **WHEN** 流式请求成功完成
- **THEN** 网关 SHALL 增加该供应商和模型的请求计数
- **THEN** 网关 SHALL 在流结束后记录统计

#### Scenario: 不记录失败请求

- **WHEN** 请求在到达供应商前失败（路由错误、验证错误）
- **THEN** 网关 SHALL NOT 增加请求计数

#### Scenario: 记录供应商错误

- **WHEN** 请求到达供应商但供应商返回错误
- **THEN** 网关 SHALL 仍然增加请求计数（请求已被处理）

### Requirement: 按供应商查询统计

网关 SHALL 允许按供应商过滤查询统计。

#### Scenario: 查询特定供应商的统计

- **WHEN** 向 `/api/stats?provider_id=<provider_id>` 发送 GET 请求
- **THEN** 网关 SHALL 仅返回指定供应商的统计

#### Scenario: 查询不存在供应商的统计

- **WHEN** 向 `/api/stats?provider_id=<non_existent_id>` 发送 GET 请求
- **THEN** 网关 SHALL 返回空结果或零计数

### Requirement: 按模型查询统计

网关 SHALL 允许按模型过滤查询统计。

#### Scenario: 查询特定模型的统计

- **WHEN** 向 `/api/stats?model_name=<model_name>` 发送 GET 请求
- **THEN** 网关 SHALL 仅返回指定模型的统计

#### Scenario: 查询不存在模型的统计

- **WHEN** 向 `/api/stats?model_name=<non_existent_name>` 发送 GET 请求
- **THEN** 网关 SHALL 返回空结果或零计数

### Requirement: 按日期范围查询统计

网关 SHALL 允许在日期范围内查询统计。

#### Scenario: 使用日期范围查询统计

- **WHEN** 向 `/api/stats?start=<start_date>&end=<end_date>` 发送 GET 请求
- **THEN** 网关 SHALL 仅返回指定范围内的日期统计
- **THEN** 日期格式 SHALL 为 YYYY-MM-DD

#### Scenario: 不使用日期范围查询统计

- **WHEN** 向 `/api/stats` 发送 GET 请求，不带 start 和 end 参数
- **THEN** 网关 SHALL 返回所有可用日期的统计

#### Scenario: 仅使用开始日期查询统计

- **WHEN** 向 `/api/stats?start=<start_date>` 发送 GET 请求
- **THEN** 网关 SHALL 返回从开始日期到当前日期的统计

#### Scenario: 仅使用结束日期查询统计

- **WHEN** 向 `/api/stats?end=<end_date>` 发送 GET 请求
- **THEN** 网关 SHALL 返回从最早可用日期到结束日期的统计

### Requirement: 聚合统计

网关 SHALL 按日期聚合统计。

#### Scenario: 同一天多次请求

- **WHEN** 同一天对同一供应商和模型发起多次请求
- **THEN** 网关 SHALL 为该天维护单条统计记录
- **THEN** 请求计数 SHALL 为所有请求的总和

#### Scenario: 跨多天请求

- **WHEN** 跨不同天发起请求
- **THEN** 网关 SHALL 为每一天维护独立的统计记录

### Requirement: 以结构化格式返回统计

网关 SHALL 以结构化 JSON 格式返回统计。

#### Scenario: 统计响应格式

- **WHEN** 查询统计
- **THEN** 响应 SHALL 为统计对象数组
- **THEN** 每个对象 SHALL 包含 provider_id, model_name, request_count 和 date

#### Scenario: 空统计

- **WHEN** 没有统计匹配查询条件
- **THEN** 网关 SHALL 返回空数组

### Requirement: 支持并发统计记录

网关 SHALL 支持并发请求统计记录而无冲突。

#### Scenario: 并发请求

- **WHEN** 同时处理多个并发请求
- **THEN** 网关 SHALL 正确为每个请求增加请求计数
- **THEN** 不 SHALL 因并发写入而丢失统计

### Requirement: 仅将统计限制为请求计数

网关 SHALL 在 MVP 中仅记录请求计数，不记录其他指标。

#### Scenario: 仅请求计数

- **WHEN** 记录统计
- **THEN** 网关 SHALL 仅跟踪请求数量
- **THEN** 网关 SHALL NOT 在 MVP 中跟踪 token 使用、成本、延迟或其他指标

### Requirement: 为新组合初始化统计

网关 SHALL 为新的供应商-模型-日期组合自动创建统计记录。

#### Scenario: 组合的首次请求

- **WHEN** 在新日期首次对供应商-模型组合发起请求
- **THEN** 网关 SHALL 创建新的统计记录，request_count = 1

### Requirement: 查询所有统计

网关 SHALL 允许不带过滤条件查询所有统计。

#### Scenario: 查询所有统计

- **WHEN** 向 `/api/stats` 发送 GET 请求，不带任何查询参数
- **THEN** 网关 SHALL 返回所有可用统计
- **THEN** 结果 SHALL 按日期排序（最近的在前）