源丰后端 API

Appearance

待办事项 ​

待办事项模块提供任务管理、分配、跟踪等功能，支持个人任务和团队协作。

接口概览 ​

基础操作 ​

方法路径描述权限要求
POST/api/v1/todos创建待办事项登录用户
GET/api/v1/todos获取待办事项列表登录用户
GET/api/v1/todos/{id}获取待办事项详情登录用户
PUT/api/v1/todos/{id}更新待办事项登录用户
DELETE/api/v1/todos/{id}删除待办事项登录用户

特殊查询 ​

方法路径描述权限要求
GET/api/v1/todos/my获取我的待办事项登录用户
GET/api/v1/todos/created获取我创建的待办事项登录用户
GET/api/v1/todos/overdue获取过期的待办事项登录用户
GET/api/v1/todos/stats获取待办事项统计登录用户

状态操作 ​

方法路径描述权限要求
PATCH/api/v1/todos/{id}/start开始待办事项登录用户
PATCH/api/v1/todos/{id}/complete完成待办事项登录用户
PATCH/api/v1/todos/{id}/assign指派待办事项登录用户
POST/api/v1/todos/{id}/batch-assign批量指派待办事项登录用户

附件管理 ​

方法路径描述权限要求
POST/api/v1/todos/{id}/attachments添加附件登录用户
GET/api/v1/todos/{id}/attachments获取附件列表登录用户
DELETE/api/v1/todos/{id}/attachments/{attachment_id}删除附件登录用户

评论管理 ​

方法路径描述权限要求
POST/api/v1/todos/{id}/comments添加评论登录用户
GET/api/v1/todos/{id}/comments获取评论列表登录用户
DELETE/api/v1/todos/{id}/comments/{comment_id}删除评论登录用户

创建待办事项 ​

创建新的待办事项任务。

接口信息 ​

  • URL: /api/v1/todos
  • 方法: POST
  • 内容类型: application/json
  • 认证: 需要登录

请求参数 ​

字段类型必填描述示例
titlestring是任务标题"完成项目文档"
descriptionstring否任务描述"编写API文档和用户手册"
priorityint否优先级（1:低, 2:中, 3:高）2
due_datestring否截止日期"2024-01-15T23:59:59Z"
assignee_idint否指派人ID2
tagsstring[]否标签列表["文档", "项目"]

请求示例 ​

json
{
  "title": "完成项目文档",
  "description": "编写API文档和用户手册，确保所有接口都有详细说明",
  "priority": 3,
  "due_date": "2024-01-15T23:59:59Z",
  "assignee_id": 2,
  "tags": ["文档", "项目", "重要"]
}

响应示例 ​

成功响应 (201) ​

json
{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 1,
    "title": "完成项目文档",
    "description": "编写API文档和用户手册，确保所有接口都有详细说明",
    "priority": 3,
    "status": "pending",
    "due_date": "2024-01-15T23:59:59Z",
    "creator": {
      "id": 1,
      "name": "John Doe",
      "avatar": "https://example.com/avatar.jpg"
    },
    "assignee": {
      "id": 2,
      "name": "Jane Smith",
      "avatar": "https://example.com/avatar2.jpg"
    },
    "tags": ["文档", "项目", "重要"],
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取待办事项列表 ​

获取待办事项列表，支持分页和筛选。

接口信息 ​

  • URL: /api/v1/todos
  • 方法: GET
  • 认证: 需要登录

查询参数 ​

参数类型必填描述默认值
pageint否页码1
page_sizeint否每页数量10
statusstring否状态筛选（pending, in_progress, completed）-
priorityint否优先级筛选（1,2,3）-
assignee_idint否指派人ID筛选-
searchstring否搜索关键词-
due_date_fromstring否截止日期起始-
due_date_tostring否截止日期结束-

请求示例 ​

bash
GET /api/v1/todos?page=1&page_size=20&status=pending&priority=3

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "todos": [
      {
        "id": 1,
        "title": "完成项目文档",
        "description": "编写API文档和用户手册",
        "priority": 3,
        "status": "pending",
        "due_date": "2024-01-15T23:59:59Z",
        "creator": {
          "id": 1,
          "name": "John Doe"
        },
        "assignee": {
          "id": 2,
          "name": "Jane Smith"
        },
        "tags": ["文档", "项目"],
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "pages": 1
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取我的待办事项 ​

获取当前登录用户相关的待办事项。

接口信息 ​

  • URL: /api/v1/todos/my
  • 方法: GET
  • 认证: 需要登录

查询参数 ​

与获取待办事项列表相同的参数。

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "todos": [
      {
        "id": 1,
        "title": "完成项目文档",
        "description": "编写API文档和用户手册",
        "priority": 3,
        "status": "in_progress",
        "due_date": "2024-01-15T23:59:59Z",
        "creator": {
          "id": 1,
          "name": "John Doe"
        },
        "assignee": {
          "id": 2,
          "name": "Jane Smith"
        },
        "tags": ["文档", "项目"],
        "created_at": "2024-01-01T12:00:00Z",
        "started_at": "2024-01-10T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 1,
      "pages": 1
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

开始待办事项 ​

将待办事项状态更改为"进行中"。

接口信息 ​

  • URL: /api/v1/todos/{id}/start
  • 方法: PATCH
  • 认证: 需要登录

路径参数 ​

参数类型必填描述示例
idint是待办事项ID1

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "任务已开始",
  "data": {
    "id": 1,
    "status": "in_progress",
    "started_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-10T09:00:00Z"
  },
  "timestamp": "2024-01-10T09:00:00Z"
}

完成待办事项 ​

将待办事项标记为已完成。

接口信息 ​

  • URL: /api/v1/todos/{id}/complete
  • 方法: PATCH
  • 认证: 需要登录

路径参数 ​

参数类型必填描述示例
idint是待办事项ID1

请求参数（可选） ​

字段类型必填描述示例
completion_notestring否完成备注"文档已全部完成，已提交审核"

请求示例 ​

json
{
  "completion_note": "文档已全部完成，已提交审核"
}

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "任务已完成",
  "data": {
    "id": 1,
    "status": "completed",
    "completed_at": "2024-01-12T16:30:00Z",
    "completion_note": "文档已全部完成，已提交审核",
    "updated_at": "2024-01-12T16:30:00Z"
  },
  "timestamp": "2024-01-12T16:30:00Z"
}

添加评论 ​

为待办事项添加评论。

接口信息 ​

  • URL: /api/v1/todos/{id}/comments
  • 方法: POST
  • 内容类型: application/json
  • 认证: 需要登录

请求参数 ​

字段类型必填描述示例
contentstring是评论内容"进度正常，预计明天完成"

请求示例 ​

json
{
  "content": "进度正常，预计明天完成"
}

响应示例 ​

成功响应 (201) ​

json
{
  "code": 201,
  "message": "评论添加成功",
  "data": {
    "id": 1,
    "content": "进度正常，预计明天完成",
    "author": {
      "id": 2,
      "name": "Jane Smith",
      "avatar": "https://example.com/avatar2.jpg"
    },
    "created_at": "2024-01-11T14:20:00Z"
  },
  "timestamp": "2024-01-11T14:20:00Z"
}

获取待办事项统计 ​

获取待办事项的统计信息。

接口信息 ​

  • URL: /api/v1/todos/stats
  • 方法: GET
  • 认证: 需要登录

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 25,
    "by_status": {
      "pending": 8,
      "in_progress": 12,
      "completed": 5
    },
    "by_priority": {
      "low": 5,
      "medium": 15,
      "high": 5
    },
    "overdue": 3,
    "due_today": 4,
    "due_this_week": 8,
    "my_stats": {
      "assigned_to_me": 15,
      "created_by_me": 10,
      "completed_by_me": 8
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

数据模型 ​

TodoResponse ​

typescript
interface TodoResponse {
  id: number;                    // 待办事项ID
  title: string;                 // 标题
  description?: string;          // 描述
  priority: number;              // 优先级（1:低, 2:中, 3:高）
  status: string;                // 状态（pending, in_progress, completed）
  due_date?: string;             // 截止日期
  creator: User;                 // 创建人
  assignee?: User;               // 指派人
  tags: string[];                // 标签列表
  created_at: string;            // 创建时间
  updated_at: string;            // 更新时间
  started_at?: string;           // 开始时间
  completed_at?: string;         // 完成时间
  completion_note?: string;      // 完成备注
}

TodoComment ​

typescript
interface TodoComment {
  id: number;                    // 评论ID
  content: string;               // 评论内容
  author: User;                  // 评论作者
  created_at: string;            // 创建时间
}

TodoStats ​

typescript
interface TodoStats {
  total: number;                 // 总数
  by_status: {                   // 按状态统计
    pending: number;
    in_progress: number;
    completed: number;
  };
  by_priority: {                 // 按优先级统计
    low: number;
    medium: number;
    high: number;
  };
  overdue: number;               // 逾期数量
  due_today: number;             // 今日到期
  due_this_week: number;         // 本周到期
  my_stats: {                    // 个人统计
    assigned_to_me: number;      // 指派给我的
    created_by_me: number;       // 我创建的
    completed_by_me: number;     // 我完成的
  };
}

错误代码 ​

错误代码描述解决方案
400请求参数错误检查请求参数格式和必填字段
401未认证检查 JWT token 是否有效
403无权限确认用户具有相应权限
404待办事项不存在检查待办事项ID是否正确
409状态冲突检查当前状态是否支持该操作
500服务器内部错误联系系统管理员

集成示例 ​

JavaScript SDK ​

javascript
class TodoAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  // 创建待办事项
  async createTodo(todoData) {
    const response = await fetch(`${this.baseURL}/api/v1/todos`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(todoData)
    });
    return response.json();
  }

  // 获取我的待办事项
  async getMyTodos(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseURL}/api/v1/todos/my?${queryString}`, {
      headers: this.headers
    });
    return response.json();
  }

  // 开始任务
  async startTodo(todoId) {
    const response = await fetch(`${this.baseURL}/api/v1/todos/${todoId}/start`, {
      method: 'PATCH',
      headers: this.headers
    });
    return response.json();
  }

  // 完成任务
  async completeTodo(todoId, note = '') {
    const response = await fetch(`${this.baseURL}/api/v1/todos/${todoId}/complete`, {
      method: 'PATCH',
      headers: this.headers,
      body: JSON.stringify({ completion_note: note })
    });
    return response.json();
  }

  // 添加评论
  async addComment(todoId, content) {
    const response = await fetch(`${this.baseURL}/api/v1/todos/${todoId}/comments`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ content })
    });
    return response.json();
  }

  // 获取统计信息
  async getStats() {
    const response = await fetch(`${this.baseURL}/api/v1/todos/stats`, {
      headers: this.headers
    });
    return response.json();
  }
}

// 使用示例
const todoAPI = new TodoAPI('http://localhost:8080', 'your-jwt-token');

// 创建待办事项
const newTodo = await todoAPI.createTodo({
  title: '完成季度报告',
  description: '整理Q4销售数据并制作报告',
  priority: 3,
  due_date: '2024-01-20T23:59:59Z',
  tags: ['报告', '销售', 'Q4']
});

// 开始任务
await todoAPI.startTodo(newTodo.data.id);

// 添加评论
await todoAPI.addComment(newTodo.data.id, '已收集完所有数据，开始制作报告');

// 完成任务
await todoAPI.completeTodo(newTodo.data.id, '报告已提交给经理审核');

相关链接 ​

基于 MIT 许可发布

Copyright © 2024-2025 源丰科技