# 技术侧 API 设计

## 目标

本文档定义产品化阶段建议新增或调整的 API，覆盖：

- 认证与安全
- 文件与阅读
- TTS 生成
- 配额与用量
- 异步任务
- 管理员后台

设计原则：

- 尽量兼容现有接口
- REST 风格优先
- 返回结构统一
- 为前台页面和后台管理预留字段

## 1. 通用返回结构

成功：

```json
{
  "success": true,
  "data": {}
}
```

失败：

```json
{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "今日配额已用尽"
  }
}
```

## 2. 认证与安全

## 2.1 注册

`POST /api/auth/register`

请求体：

```json
{
  "username": "demo_user",
  "password": "strong_password",
  "email": "demo@example.com"
}
```

返回：

```json
{
  "success": true,
  "data": {
    "user_id": 1001
  }
}
```

## 2.2 登录

`POST /api/auth/login`

请求体：

```json
{
  "username": "demo_user",
  "password": "strong_password",
  "remember_me": true
}
```

返回：

```json
{
  "success": true,
  "data": {
    "username": "demo_user",
    "is_admin": false,
    "plan_code": "free"
  }
}
```

## 2.3 登出

`POST /api/auth/logout`

## 2.4 当前用户

`GET /api/auth/me`

返回：

```json
{
  "success": true,
  "data": {
    "id": 1001,
    "username": "demo_user",
    "is_admin": false,
    "is_active": true,
    "plan": {
      "code": "free",
      "name": "免费版"
    }
  }
}
```

## 2.5 修改密码

`POST /api/auth/change-password`

请求体：

```json
{
  "old_password": "oldpass",
  "new_password": "newpass"
}
```

## 3. 文件与阅读

## 3.1 上传 PDF

`POST /api/files/upload`

表单：

- `file`

返回：

```json
{
  "success": true,
  "data": {
    "file_id": 2001,
    "file_name": "sample.pdf",
    "file_url": "/static/files/demo_user/sample.pdf"
  }
}
```

限制建议：

- 文件大小限制
- 仅允许 PDF
- 每用户文件数量上限

## 3.2 文件列表

`GET /api/files`

返回：

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "file_id": 2001,
        "file_name": "sample.pdf",
        "file_url": "/static/files/demo_user/sample.pdf",
        "updated_at": "2026-04-30 12:00:00"
      }
    ]
  }
}
```

## 3.3 删除文件

`DELETE /api/files/{file_id}`

## 3.4 保存阅读进度

`POST /api/reader/progress`

请求体：

```json
{
  "file_path": "/static/files/demo_user/sample.pdf",
  "page": 12
}
```

## 3.5 获取阅读进度

`GET /api/reader/progress?file_path=...`

## 4. TTS 生成

## 4.1 短文本同步生成

`POST /api/tts/generate`

适合：

- 单句
- 短段落

请求体：

```json
{
  "text": "This is a test sentence.",
  "voice": "af_sky",
  "speed": 1.0,
  "file_path": "/static/files/demo_user/sample.pdf",
  "page": 12,
  "sentence_index": 4
}
```

返回头建议：

- `X-Cache-Hit: 1/0`
- `X-Request-Id: xxx`

返回体：

- 直接 `audio/wav`

## 4.2 长文本异步生成

`POST /api/tts/tasks`

请求体：

```json
{
  "text": "very long content ...",
  "voice": "af_sky",
  "speed": 1.0,
  "file_path": "/static/files/demo_user/sample.pdf",
  "page": 12
}
```

返回：

```json
{
  "success": true,
  "data": {
    "task_id": "task_123456",
    "status": "queued"
  }
}
```

## 4.3 查询任务状态

`GET /api/tts/tasks/{task_id}`

返回：

```json
{
  "success": true,
  "data": {
    "task_id": "task_123456",
    "status": "processing",
    "progress": 60,
    "audio_url": null
  }
}
```

## 4.4 获取任务结果

`GET /api/tts/tasks/{task_id}/result`

返回：

- 音频流
- 或音频下载地址

## 4.5 用户当前配额

`GET /api/tts/quota`

返回：

```json
{
  "success": true,
  "data": {
    "plan_code": "free",
    "daily_tts_chars_used": 5200,
    "daily_tts_chars_limit": 10000,
    "monthly_tts_chars_used": 23000,
    "monthly_tts_chars_limit": 100000
  }
}
```

## 5. 用量与统计

## 5.1 我的使用情况

`GET /api/me/usage/summary`

返回：

```json
{
  "success": true,
  "data": {
    "today_requests": 21,
    "today_chars": 5200,
    "today_audio_seconds": 910,
    "month_requests": 210,
    "month_chars": 23000
  }
}
```

## 5.2 我的套餐

`GET /api/me/plan`

## 6. 管理员后台 API

## 6.1 仪表盘统计

`GET /api/admin/dashboard`

返回：

```json
{
  "success": true,
  "data": {
    "today_active_users": 18,
    "today_tts_requests": 540,
    "today_cache_hit_rate": 0.63,
    "running_tasks": 3,
    "failed_tasks_today": 6
  }
}
```

## 6.2 用户列表

`GET /api/admin/users?page=1&page_size=20&keyword=demo`

## 6.3 用户详情

`GET /api/admin/users/{user_id}`

返回建议包含：

- 基本信息
- 当前套餐
- 今日/月度用量
- 最近任务

## 6.4 创建或编辑用户

`POST /api/admin/users`

## 6.5 禁用/启用用户

`POST /api/admin/users/{user_id}/status`

请求体：

```json
{
  "is_active": false
}
```

## 6.6 重置密码

`POST /api/admin/users/{user_id}/reset-password`

## 6.7 套餐列表

`GET /api/admin/plans`

## 6.8 创建或更新套餐

`POST /api/admin/plans`

请求体：

```json
{
  "code": "pro_monthly",
  "name": "专业版月付",
  "daily_tts_chars": 50000,
  "monthly_tts_chars": 500000,
  "daily_tts_requests": 200,
  "max_text_length": 3000,
  "max_parallel_tasks": 2,
  "price_month": 29.00
}
```

## 6.9 分配用户套餐

`POST /api/admin/users/{user_id}/plan`

请求体：

```json
{
  "plan_code": "pro_monthly",
  "start_at": "2026-05-01 00:00:00",
  "end_at": "2026-06-01 00:00:00"
}
```

## 6.10 TTS 日志列表

`GET /api/admin/tts-logs?page=1&page_size=20&status=failed&user_id=1001`

## 6.11 异步任务列表

`GET /api/admin/tasks?page=1&page_size=20&status=processing`

## 6.12 重试任务

`POST /api/admin/tasks/{task_id}/retry`

## 6.13 缓存概览

`GET /api/admin/cache/summary`

返回建议：

- 缓存文件数
- 总体积
- 命中率
- 最近热点项

## 6.14 清理缓存

`POST /api/admin/cache/cleanup`

请求体：

```json
{
  "mode": "expired_only"
}
```

可选值：

- `expired_only`
- `least_recently_used`
- `all`

## 7. 监控与健康检查

## 7.1 健康检查

`GET /api/health`

返回：

```json
{
  "success": true,
  "data": {
    "app": "ok",
    "db": "ok",
    "tts_upstream": "ok",
    "redis": "ok"
  }
}
```

## 7.2 系统指标摘要

`GET /api/admin/system/metrics`

返回建议：

- CPU
- 内存
- 磁盘
- 队列长度
- 错误率

## 8. 接口中间件建议

### 统一中间件建议做这些事

- 生成 `request_id`
- 记录访问日志
- 计算耗时
- 捕获异常
- 注入当前用户信息

### 对关键接口加的通用逻辑

- 认证校验
- 配额校验
- 限流校验
- 缓存命中判断
- 日志落库

## 9. API 实施优先级

### 第一批必须上线

- `/api/auth/*`
- `/api/files/*`
- `/api/reader/progress`
- `/api/tts/generate`
- `/api/tts/quota`
- `/api/me/usage/summary`
- `/api/health`

### 第二批建议上线

- `/api/tts/tasks`
- `/api/tts/tasks/{task_id}`
- `/api/admin/dashboard`
- `/api/admin/tts-logs`
- `/api/admin/users/{user_id}/plan`

### 第三批按商业需要上线

- 套餐管理
- 缓存清理
- 任务重试
- 系统指标页

## 总结

API 设计的目标不是一次做大，而是先把“认证、文件、TTS、配额、后台”这五条主链路跑通。第一批接口上线后，你就已经具备一个可运营的基础版 SaaS 雏形。