项目管理 API

项目管理模块提供了学习项目的完整生命周期管理，包括创建、查询、更新和删除项目。

📋 接口概览

方法	路径	描述	权限
GET	`/api/projects`	获取项目列表	所有用户
GET	`/api/projects/:id`	获取单个项目详情	所有用户
POST	`/api/projects`	创建新项目	所有用户
PUT	`/api/projects/:id`	更新项目信息	项目所有者/管理员
DELETE	`/api/projects/:id`	删除项目	项目所有者/管理员
POST	`/api/projects/:id/image`	上传项目图片	项目所有者/管理员
POST	`/api/projects/batch-assign`	批量指派项目	管理员

🔍 获取项目列表

获取当前用户的所有项目列表，支持分页和筛选。

请求

http

GET /api/projects?page=1&limit=10&status=active&search=关键词
Authorization: Bearer <token>

查询参数

参数	类型	必填	默认值	描述
page	number	否	1	页码
limit	number	否	10	每页数量
status	string	否	all	项目状态 (active, completed, paused, all)
search	string	否	-	搜索关键词
sort	string	否	created_at	排序字段
order	string	否	desc	排序方向 (asc, desc)

响应

json

{
  "success": true,
  "data": {
    "projects": [
      {
        "id": 1,
        "name": "数学学习",
        "description": "高等数学课程学习",
        "status": "active",
        "category": "academic",
        "target_hours": 120,
        "current_hours": 45.5,
        "progress": 37.9,
        "rating_standard": "excellent",
        "image": "/uploads/projects/math-project.jpg",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "user_id": 1
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "pages": 3
    }
  },
  "message": "获取项目列表成功"
}

🔍 获取单个项目

获取指定项目的详细信息。

请求

http

GET /api/projects/1
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "数学学习",
    "description": "高等数学课程学习",
    "status": "active",
    "category": "academic",
    "target_hours": 120,
    "current_hours": 45.5,
    "progress": 37.9,
    "rating_standard": "excellent",
    "image": "/uploads/projects/math-project.jpg",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "user_id": 1,
    "sessions_count": 15,
    "last_session": "2024-01-15T10:30:00Z",
    "achievements": [
      {
        "id": 1,
        "name": "学习新手",
        "description": "完成第一个学习项目",
        "icon": "/assets/ico/achievements/first-study.svg"
      }
    ]
  },
  "message": "获取项目详情成功"
}

➕ 创建项目

创建新的学习项目。

请求

http

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

{
  "name": "新项目名称",
  "description": "项目描述",
  "category": "academic",
  "target_hours": 100,
  "rating_standard": "good"
}

请求参数

参数	类型	必填	描述
name	string	是	项目名称 (2-50字符)
description	string	否	项目描述 (最大500字符)
category	string	否	项目分类 (academic, skill, hobby, other)
target_hours	number	否	目标学习时长(小时)
rating_standard	string	否	评级标准 (excellent, good, normal)

响应

json

{
  "success": true,
  "data": {
    "id": 2,
    "name": "新项目名称",
    "description": "项目描述",
    "status": "active",
    "category": "academic",
    "target_hours": 100,
    "current_hours": 0,
    "progress": 0,
    "rating_standard": "good",
    "created_at": "2024-01-16T12:00:00Z",
    "updated_at": "2024-01-16T12:00:00Z",
    "user_id": 1
  },
  "message": "项目创建成功"
}

✏️ 更新项目

更新指定项目的信息。

请求

http

PUT /api/projects/1
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "更新后的项目名称",
  "description": "更新后的描述",
  "status": "completed",
  "target_hours": 150
}

请求参数

参数	类型	必填	描述
name	string	否	项目名称 (2-50字符)
description	string	否	项目描述 (最大500字符)
status	string	否	项目状态 (active, completed, paused)
category	string	否	项目分类
target_hours	number	否	目标学习时长(小时)
rating_standard	string	否	评级标准
assigned_user_id	number	否	指派给单个用户ID
assigned_user_ids	array	否	指派给多个用户ID数组

响应

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "更新后的项目名称",
    "description": "更新后的描述",
    "status": "completed",
    "category": "academic",
    "target_hours": 150,
    "current_hours": 45.5,
    "progress": 30.3,
    "rating_standard": "excellent",
    "updated_at": "2024-01-16T12:30:00Z"
  },
  "message": "项目更新成功"
}

🗑️ 删除项目

删除指定的项目。

请求

http

DELETE /api/projects/1
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "message": "项目删除成功"
}

📸 上传项目图片

为项目上传封面图片。

请求

http

POST /api/projects/1/image
Content-Type: multipart/form-data
Authorization: Bearer <token>

# Form Data:
# image: [文件]

请求参数

参数	类型	必填	描述
image	file	是	图片文件 (jpg, png, gif, webp)

响应

json

{
  "success": true,
  "data": {
    "image_url": "/uploads/projects/abc123-def456.jpg",
    "filename": "abc123-def456.jpg"
  },
  "message": "项目图片上传成功"
}

👥 批量指派项目

管理员可以批量指派项目给多个用户。

请求

http

POST /api/projects/batch-assign
Content-Type: application/json
Authorization: Bearer <token>

{
  "project_ids": [1, 2, 3],
  "user_ids": [10, 11, 12],
  "assign_type": "add"
}

请求参数

参数	类型	必填	描述
project_ids	array	是	项目ID数组
user_ids	array	是	用户ID数组
assign_type	string	是	指派类型 (add, remove, replace)

响应

json

{
  "success": true,
  "data": {
    "assigned_count": 9,
    "failed_count": 0,
    "details": [
      {
        "project_id": 1,
        "project_name": "数学学习",
        "assigned_users": [
          {
            "user_id": 10,
            "username": "user1",
            "status": "success"
          }
        ]
      }
    ]
  },
  "message": "批量指派完成"
}

📊 项目统计

获取项目的学习统计数据。

请求

http

GET /api/projects/1/stats
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": {
    "total_sessions": 15,
    "total_hours": 45.5,
    "average_session_length": 3.03,
    "longest_session": 8.5,
    "shortest_session": 0.5,
    "study_days": 12,
    "current_streak": 3,
    "longest_streak": 7,
    "completion_rate": 37.9,
    "weekly_progress": [
      {
        "week": "2024-W01",
        "hours": 12.5
      },
      {
        "week": "2024-W02",
        "hours": 18.2
      }
    ]
  },
  "message": "获取项目统计成功"
}

🏷️ 项目分类

获取系统支持的项目分类。

请求

http

GET /api/projects/categories
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": [
    {
      "id": "academic",
      "name": "学术学习",
      "description": "学校课程、考试准备等",
      "icon": "graduation-cap"
    },
    {
      "id": "skill",
      "name": "技能提升",
      "description": "职业技能、兴趣爱好等",
      "icon": "tools"
    },
    {
      "id": "hobby",
      "name": "兴趣爱好",
      "description": "个人爱好、娱乐学习等",
      "icon": "heart"
    },
    {
      "id": "other",
      "name": "其他",
      "description": "其他类型的学习项目",
      "icon": "ellipsis-h"
    }
  ],
  "message": "获取项目分类成功"
}

⚠️ 错误响应

验证错误

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": [
      {
        "field": "name",
        "message": "项目名称不能为空"
      }
    ]
  }
}

权限错误

json

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "您没有权限操作此项目"
  }
}

资源不存在

json

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "项目不存在"
  }
}

🚀 使用示例

JavaScript 示例

javascript

// 获取项目列表
async function getProjects(token, params = {}) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(`/api/projects?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return await response.json();
}

// 创建项目
async function createProject(token, projectData) {
  const response = await fetch('/api/projects', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(projectData)
  });
  return await response.json();
}

// 上传项目图片
async function uploadProjectImage(token, projectId, imageFile) {
  const formData = new FormData();
  formData.append('image', imageFile);
  
  const response = await fetch(`/api/projects/${projectId}/image`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    },
    body: formData
  });
  return await response.json();
}

cURL 示例

bash

# 获取项目列表
curl -k -X GET "https://localhost:3001/api/projects?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 创建项目
curl -k -X POST https://localhost:3001/api/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Python编程",
    "description": "学习Python编程语言",
    "category": "skill",
    "target_hours": 80
  }'

# 上传项目图片
curl -k -X POST https://localhost:3001/api/projects/1/image \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "image=@/path/to/image.jpg"

📝 注意事项

权限控制: 用户只能操作自己创建的项目，管理员可以操作所有项目
图片上传: 支持 jpg、png、gif、webp 格式，最大 5MB
状态管理: 项目状态会影响学习记录的统计
软删除: 删除项目时会保留相关的学习记录
缓存策略: 项目列表支持缓存，提高响应速度

💡 提示

项目是学习追踪的核心，建议为每个学习目标创建独立的项目，便于管理和统计。

项目管理 API ​

📋 接口概览 ​

🔍 获取项目列表 ​

请求 ​

查询参数 ​

响应 ​

🔍 获取单个项目 ​

请求 ​

响应 ​

➕ 创建项目 ​

请求 ​

请求参数 ​

响应 ​

✏️ 更新项目 ​

请求 ​

请求参数 ​

响应 ​

🗑️ 删除项目 ​

请求 ​

响应 ​

📸 上传项目图片 ​

请求 ​

请求参数 ​

响应 ​

👥 批量指派项目 ​

请求 ​

请求参数 ​

响应 ​

📊 项目统计 ​

请求 ​

响应 ​

🏷️ 项目分类 ​

请求 ​

响应 ​

⚠️ 错误响应 ​

验证错误 ​

权限错误 ​

资源不存在 ​

🚀 使用示例 ​

JavaScript 示例 ​

cURL 示例 ​

📝 注意事项 ​

项目管理 API

📋 接口概览

🔍 获取项目列表

请求

查询参数

响应

🔍 获取单个项目

请求

响应

➕ 创建项目

请求

请求参数

响应

✏️ 更新项目

请求

请求参数

响应

🗑️ 删除项目

请求

响应

📸 上传项目图片

请求

请求参数

响应

👥 批量指派项目

请求

请求参数

响应

📊 项目统计

请求

响应

🏷️ 项目分类

请求

响应

⚠️ 错误响应

验证错误

权限错误

资源不存在

🚀 使用示例

JavaScript 示例

cURL 示例

📝 注意事项