技术侧 API 设计

目标

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

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

设计原则：

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

1. 通用返回结构

成功：

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

失败：

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

2. 认证与安全

2.1 注册

POST /api/auth/register

请求体：

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

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

2.2 登录

POST /api/auth/login

请求体：

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

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

2.3 登出

POST /api/auth/logout

2.4 当前用户

GET /api/auth/me

{
  "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

请求体：

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

3. 文件与阅读

3.1 上传 PDF

POST /api/files/upload

表单：

file

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

限制建议：

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

3.2 文件列表

GET /api/files

{
  "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

请求体：

{
  "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

适合：

单句
短段落

请求体：

{
  "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

请求体：

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

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

4.3 查询任务状态

GET /api/tts/tasks/{task_id}

{
  "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

{
  "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

{
  "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

{
  "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

请求体：

{
  "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

请求体：

{
  "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

请求体：

{
  "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

请求体：

{
  "mode": "expired_only"
}

可选值：

expired_only
least_recently_used
all

7. 监控与健康检查

7.1 健康检查

GET /api/health

{
  "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 雏形。

技术侧-API设计.md 7.2 KB Historia Czysty

技术侧 API 设计

目标

1. 通用返回结构

2. 认证与安全

2.1 注册

2.2 登录

2.3 登出

2.4 当前用户

2.5 修改密码

3. 文件与阅读

3.1 上传 PDF

3.2 文件列表

3.3 删除文件

3.4 保存阅读进度

3.5 获取阅读进度

4. TTS 生成

4.1 短文本同步生成

4.2 长文本异步生成

4.3 查询任务状态

4.4 获取任务结果

4.5 用户当前配额

5. 用量与统计

5.1 我的使用情况

5.2 我的套餐

6. 管理员后台 API

6.1 仪表盘统计

6.2 用户列表

6.3 用户详情

6.4 创建或编辑用户

6.5 禁用/启用用户

6.6 重置密码

6.7 套餐列表

6.8 创建或更新套餐

6.9 分配用户套餐

6.10 TTS 日志列表

6.11 异步任务列表

6.12 重试任务

6.13 缓存概览

6.14 清理缓存

7. 监控与健康检查

7.1 健康检查

7.2 系统指标摘要

8. 接口中间件建议

统一中间件建议做这些事

对关键接口加的通用逻辑

9. API 实施优先级

第一批必须上线

第二批建议上线

第三批按商业需要上线

总结

技术侧-API设计.md 7.2 KB

Historia Czysty