API文档

通用约定

所有接口均遵循同一套认证与响应规范

认证方式

登录后通过 Cookie auth_token 维持会话；也可在请求头携带 Authorization: Bearer <token>。

统一响应结构

响应体统一包裹为 {success, message, data, error}，业务数据位于 data 字段；success=false 时请读取 message。

错误码

400 参数错误 · 401 未登录 · 402 积分不足 · 413 文件超限 · 500 服务异常，均以 HTTP 状态码返回。

// 统一响应示例
{
  "success": true,
  "message": "操作成功",
  "data": { ... },
  "error": null
}

核心接口

以下为当前开放的主要 REST 端点（前缀均为 /api）

认证 · /api/auth

POST /api/auth/register/phone 手机号 + 密码注册
POST /api/auth/code/phone 发送登录短信验证码
POST /api/auth/login/phone 手机号 + 密码登录
POST /api/auth/login/phone-code 手机号 + 验证码登录
POST /api/auth/logout 退出登录并销毁会话

翻译 · /api/translation

GET /api/translation/supported-languages 支持的语言列表
GET /api/translation/engines 可用翻译引擎列表
POST /api/translation/translate 文本翻译（按字符扣积分）
POST /api/translation/detect-language 语言自动检测
POST /api/translation/batch-translate 批量文本翻译
GET /api/translation/history 分页查询翻译历史
GET /api/translation/platform-stats 平台统计总览

文档翻译 · /api/document

POST /api/document/upload 上传文档（multipart/form-data）
GET /api/document/list 我的文档任务列表
POST /api/document/start/{id} 开始翻译任务
GET /api/document/progress/{id} 查询翻译进度
GET /api/document/download-url/{id} 获取译文下载链接
DELETE /api/document/delete/{id} 删除文档任务

其他

GET /api/terminology 术语库列表（POST 新增 / PUT /{id} 修改 / DELETE /{id} 删除）
POST /api/quality/assess 翻译质量多维评估
GET /api/user/profile 当前用户资料（PUT 修改）
GET /api/points/balance 积分余额查询
GET /api/moments/list 朋友圈动态列表（POST /create 发布）

调用示例

# 文本翻译（已登录会话）
curl -X POST 'http://localhost:8090/api/translation/translate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
        "sourceText": "Hello, world!",
        "sourceLanguage": "en",
        "targetLanguage": "zh",
        "engine": "QWEN"
      }'
// 浏览器同源调用自动携带 Cookie
const res = await fetch('/api/translation/translate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sourceText: 'Hello, world!',
    sourceLanguage: 'en',
    targetLanguage: 'zh',
    engine: 'QWEN'
  })
});
const json = await res.json();
const result = json.data;  // 统一封装，业务数据在 data 字段