API 接口总览

MootingBackend 提供的 REST API 接口完整列表。

基础信息

属性	值
基础 URL	http://localhost:8080
协议	HTTP/HTTPS
数据格式	JSON
认证方式	JWT Bearer Token

认证说明

除公开接口外，所有接口需要在请求头携带 JWT Token：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

接口列表

验证码模块

方法	路径	认证	说明
POST	/api/verify-code/send	否	发送验证码
POST	/api/verify-code/verify	否	验证码登录

认证模块

方法	路径	认证	说明
POST	/api/auth/register	否	用户注册
POST	/api/auth/login	否	密码登录
POST	/api/auth/logout	是	登出

用户模块

方法	路径	认证	说明
GET	/api/users/me	是	获取当前用户信息

设备模块

方法	路径	认证	说明
POST	/api/devices	是	注册/绑定设备
GET	/api/devices	是	获取设备列表

转写模块

方法	路径	认证	说明
POST	/api/transcriptions	是	提交转写记录
GET	/api/transcriptions	是	获取转写记录列表
GET	/api/transcriptions/usage	是	获取使用量统计

行为模块

方法	路径	认证	说明
POST	/api/behavior/login	是	记录登录事件
GET	/api/behavior/login	是	获取登录记录
POST	/api/behavior/events	是	记录通用事件
GET	/api/behavior/translation	是	获取翻译事件
GET	/api/behavior/voice-provider	是	获取语音服务商事件
GET	/api/behavior/language-choice	是	获取语言选择事件
GET	/api/behavior/stats	是	获取统计数据

---

详细接口文档

发送验证码

发送邮箱或短信验证码。

POST /api/verify-code/send
Content-Type: application/json

请求体:

{
  "type": "email",
  "target": "user@example.com"
}

字段	类型	必填	说明
type	string	是	email 或 sms
target	string	是	邮箱或手机号

成功响应 (200):

{
  "code": 0,
  "message": "验证码发送成功"
}

失败响应 (400):

{
  "code": 1,
  "message": "请求过于频繁，请60秒后重试"
}

---

验证码登录

验证验证码并自动登录/注册。

POST /api/verify-code/verify
Content-Type: application/json

请求体:

{
  "target": "user@example.com",
  "verifyCode": "123456"
}

成功响应 (200):

{
  "code": 0,
  "message": "验证码校验成功",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": 123,
  "phone": null,
  "email": "user@example.com"
}

---

获取当前用户

获取当前登录用户的详细信息。

GET /api/users/me
Authorization: Bearer <token>

成功响应 (200):

{
  "userId": 123,
  "phone": "13800138000",
  "email": "user@example.com",
  "createdAt": "2026-01-29T10:30:00Z",
  "updatedAt": "2026-01-30T15:45:00Z"
}

---

注册设备

绑定新设备到当前用户。

POST /api/devices
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "sn": "MG1-2024-001234",
  "mac": "AA:BB:CC:DD:EE:FF",
  "productModel": "Mooting G1"
}

成功响应 (200):

{
  "sn": "MG1-2024-001234",
  "userId": 123,
  "mac": "AA:BB:CC:DD:EE:FF",
  "productModel": "Mooting G1",
  "createdAt": "2026-01-29T10:30:00Z"
}

---

获取设备列表

获取当前用户的所有设备。

GET /api/devices
Authorization: Bearer <token>

成功响应 (200):

[
  {
    "sn": "MG1-2024-001234",
    "userId": 123,
    "mac": "AA:BB:CC:DD:EE:FF",
    "productModel": "Mooting G1",
    "createdAt": "2026-01-29T10:30:00Z"
  }
]

---

提交转写记录

保存一条转写记录。

POST /api/transcriptions
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "recordTitle": "会议记录 2026-01-29",
  "text": "这是转写的完整文本内容...",
  "language": "zh-CN",
  "durationSeconds": 300
}

成功响应 (200):

{
  "transcriptionRecordId": 999,
  "userId": 123,
  "recordTitle": "会议记录 2026-01-29",
  "text": "这是转写的完整文本内容...",
  "textLength": 2543,
  "language": "zh-CN",
  "durationSeconds": 300,
  "createdAt": "2026-01-29T10:30:00Z",
  "updatedAt": null
}

---

获取使用量统计

获取当前用户的转写使用量。

GET /api/transcriptions/usage
Authorization: Bearer <token>

成功响应 (200):

{
  "userId": 123,
  "totalUsage": 36000,
  "dailyUsage": [
    {
      "date": "2026-01-29",
      "usage": 3600
    },
    {
      "date": "2026-01-28",
      "usage": 2400
    }
  ]
}

---

记录行为事件

记录用户行为事件。

POST /api/behavior/events
Authorization: Bearer <token>
Content-Type: application/json

请求体:

{
  "eventType": "language_choice",
  "eventValue": "zh-CN"
}

eventType	说明	eventValue 示例
translation_on	翻译开关	true / false
voice_provider	语音服务商	tencent / iflytek
language_choice	语言选择	zh-CN / en-US
ambient_sound	环境音	enabled / disabled
subtitle_layout	字幕布局	top / bottom

成功响应 (200):

{
  "code": 0,
  "message": "事件记录成功"
}

---

错误码

code	说明
0	成功
1	通用错误
401	未授权（Token 无效或过期）
400	请求参数错误
500	服务器内部错误

OpenAPI 规范

完整的 OpenAPI 3.0 规范文件位于：

MootingBackend/docs/apifox-openapi.json

可导入 Apifox、Postman 等工具进行测试。

下一步

• 认证接口 - 认证相关接口详解
• 用户接口 - 用户相关接口详解
• 设备接口 - 设备相关接口详解