StepToDo API 文档

API 基础路径: /api/v1

所有 API 响应格式统一为: { code, message, data }

🔐 认证说明

需要认证的接口请在请求头中添加: Authorization: Bearer {access_token}

认证接口

POST/api/v1/auth/sms/send

发送短信验证码

请求参数:

  • phoneNumber: string - 手机号
  • type: string - 类型: "register" | "login" | "reset_password"

响应示例:

{
  "code": 0,
  "message": "验证码已发送",
  "data": {
    "expireAt": "Date - 过期时间"
  }
}
POST/api/v1/auth/register/sms

验证码注册

请求参数:

  • phoneNumber: string - 手机号
  • smsCode: string - 6位验证码
  • nickname: string? - 昵称（可选）
  • password: string? - 密码（可选）

响应示例:

{
  "code": 0,
  "message": "注册成功",
  "data": {
    "user": "User对象",
    "token": "Token对象（accessToken, refreshToken, expiresAt）"
  }
}
POST/api/v1/auth/login/sms

验证码登录

请求参数:

  • phoneNumber: string - 手机号
  • smsCode: string - 6位验证码

响应示例:

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "user": "User对象",
    "token": "Token对象"
  }
}
POST/api/v1/auth/login/password

密码登录

请求参数:

  • phoneNumber: string - 手机号
  • password: string - 密码

响应示例:

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "user": "User对象",
    "token": "Token对象"
  }
}
POST/api/v1/auth/refresh

刷新 Token

请求参数:

  • refreshToken: string - 刷新令牌

响应示例:

{
  "code": 0,
  "message": "Token 刷新成功",
  "data": {
    "accessToken": "string - 新的访问令牌",
    "expiresAt": "Date - 过期时间"
  }
}
POST/api/v1/auth/logout需要认证

退出登录

请求参数:

无

响应示例:

{
  "code": 0,
  "message": "退出登录成功",
  "data": null
}

用户接口

GET/api/v1/user/profile需要认证

获取用户信息

请求参数:

无

响应示例:

{
  "code": 0,
  "message": "success",
  "data": "User对象"
}
PUT/api/v1/user/profile需要认证

更新用户信息

请求参数:

  • nickname: string? - 昵称（2-20个字符）

响应示例:

{
  "code": 0,
  "message": "更新成功",
  "data": "User对象"
}
POST/api/v1/user/avatar需要认证

上传头像

请求参数:

  • file: File - 图片文件（multipart/form-data）

响应示例:

{
  "code": 0,
  "message": "上传成功",
  "data": {
    "avatarURL": "string - 头像URL"
  }
}
PUT/api/v1/user/password需要认证

修改密码

请求参数:

  • oldPassword: string - 旧密码
  • newPassword: string - 新密码（8-20位，包含字母和数字）

响应示例:

{
  "code": 0,
  "message": "密码修改成功",
  "data": null
}
POST/api/v1/user/password/reset

重置密码（通过短信验证码）

请求参数:

  • phoneNumber: string - 手机号
  • smsCode: string - 验证码
  • newPassword: string - 新密码

响应示例:

{
  "code": 0,
  "message": "密码重置成功",
  "data": null
}

任务接口

GET/api/v1/tasks/sync需要认证

同步任务（增量）

请求参数:

  • lastSyncAt: string? - 最后同步时间（ISO 8601格式）

响应示例:

{
  "code": 0,
  "message": "success",
  "data": {
    "tasks": "Task[] - 任务列表",
    "recurringTasks": "RecurringTask[] - 周期任务列表",
    "deletedTaskIds": "string[] - 已删除的任务ID",
    "serverTime": "Date - 服务器时间"
  }
}
POST/api/v1/tasks需要认证

创建任务

请求参数:

  • title: string - 任务标题
  • scheduledTime: string? - 提醒时间（ISO 8601格式）
  • createdAt: string? - 创建时间
  • parsedContext: string? - NLP解析结果

响应示例:

{
  "code": 0,
  "message": "创建成功",
  "data": "Task对象"
}
PUT/api/v1/tasks/:taskId需要认证

更新任务

请求参数:

  • taskId: string - 任务ID（URL参数）
  • title: string? - 任务标题
  • isCompleted: boolean? - 是否完成
  • scheduledTime: string? - 提醒时间
  • completedAt: string? - 完成时间
  • pomodoroCount: number? - 番茄钟数量

响应示例:

{
  "code": 0,
  "message": "更新成功",
  "data": "Task对象"
}
DELETE/api/v1/tasks/:taskId需要认证

删除任务（软删除，归档）

请求参数:

  • taskId: string - 任务ID（URL参数）

响应示例:

{
  "code": 0,
  "message": "删除成功",
  "data": null
}
POST/api/v1/tasks/batch需要认证

批量操作任务

请求参数:

  • create: Task[]? - 要创建的任务列表
  • update: Task[]? - 要更新的任务列表
  • delete: string[]? - 要删除的任务ID列表

响应示例:

{
  "code": 0,
  "message": "批量操作成功",
  "data": {
    "created": "Task[] - 已创建的任务",
    "updated": "Task[] - 已更新的任务",
    "deleted": "string[] - 已删除的任务ID"
  }
}

📝 错误码说明

0 - 成功

1001 - 参数错误

1002 - 手机号格式错误

1003 - 验证码错误

1004 - 验证码已过期

1005 - 用户已存在

1006 - 用户不存在

1007 - 密码错误

1008 - Token 无效

1009 - Token 已过期

1010 - 未授权

2001 - 任务不存在

5000 - 服务器内部错误