# Fish 和 FishFriends 统计接口文档

## 基础信息

- **基础URL**: `http://localhost:3000/api`
- **认证方式**: JWT Token (需要在请求头中包含 `Authorization: Bearer <token>`)

## Fish 统计接口

### 获取 Fish 统计信息

**接口**: `GET /api/fish/statistics`

**描述**: 获取 Fish 数据的统计信息，包括总数和各状态的数量分布

**curl 命令**:
```bash
curl -X GET "http://localhost:3000/api/fish/statistics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**响应示例**:
```json
{
  "statistics": {
    "total": 1000,
    "noTag": 300,
    "tagged": 200,
    "success": 500
  }
}
```

**字段说明**:
- `total`: 总记录数
- `noTag`: 未标记状态的记录数
- `tagged`: 已标记状态的记录数
- `success`: 成功状态的记录数

## FishFriends 统计接口

### 获取 FishFriends 统计信息

**接口**: `GET /api/fish-friends/statistics`

**描述**: 获取 FishFriends 数据的统计信息，包括总数和按不同维度的分布

**curl 命令**:
```bash
curl -X GET "http://localhost:3000/api/fish-friends/statistics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**响应示例**:
```json
{
  "statistics": {
    "total": 500,
    "byFishId": {
      "123456789": 5,
      "987654321": 3,
      "111222333": 2
    },
    "byOwnerId": {
      "1": 10,
      "2": 8,
      "3": 5
    }
  }
}
```

**字段说明**:
- `total`: 总记录数
- `byFishId`: 按 Fish ID 分组的统计
  - 键: Fish ID
  - 值: 该 Fish ID 关联的 FishFriends 记录数
- `byOwnerId`: 按所有者 ID 分组的统计
  - 键: 所有者 ID
  - 值: 该所有者 ID 关联的 FishFriends 记录数

## 使用场景

### Fish 统计
- **数据概览**: 快速了解 Fish 数据的整体分布
- **状态监控**: 监控不同状态的数据量变化
- **业务分析**: 分析业务处理效率和成功率

### FishFriends 统计
- **关联分析**: 了解每个 Fish 关联的 Friends 数量
- **所有者分析**: 分析不同所有者的数据分布
- **数据分布**: 了解数据的集中度和分散度

## 错误响应

### 401 未授权
```json
{
  "message": "未授权访问"
}
```

### 500 服务器错误
```json
{
  "message": "获取统计信息失败"
}
```

## 注意事项

1. **认证要求**: 所有请求都需要有效的 JWT Token
2. **实时数据**: 统计数据是实时计算的，反映当前数据库状态
3. **性能考虑**: 统计查询会扫描相关表，大数据量时可能需要较长时间
4. **数据一致性**: 统计结果基于当前数据库状态，可能与历史数据有差异

## 使用示例

### 获取 Fish 统计
```bash
# 获取 Fish 统计信息
curl -X GET "http://localhost:3000/api/fish/statistics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
```

### 获取 FishFriends 统计
```bash
# 获取 FishFriends 统计信息
curl -X GET "http://localhost:3000/api/fish-friends/statistics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
```

### 使用 jq 格式化输出
```bash
# 格式化 Fish 统计输出
curl -X GET "http://localhost:3000/api/fish/statistics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.'

# 格式化 FishFriends 统计输出
curl -X GET "http://localhost:3000/api/fish-friends/statistics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.'
```

## 状态码说明

- `200`: 成功获取统计信息
- `401`: 未授权，需要有效的 JWT Token
- `500`: 服务器内部错误，统计查询失败