#收藏一键切换接口 (2026-06-18)

#接口变更

#user

• POST /api/bookmark/set_saved
  • 功能：设置 artist、artwork、service、product 的收藏状态，供前端一键收藏/取消收藏按钮使用。
  • 变更：新增统一收藏状态接口。收藏时自动加入默认文件夹；取消收藏时从所有文件夹移除。sync_folders 继续只用于文件夹归属管理。

#接口示例

#user

#POST /api/bookmark/set_saved

• 功能说明：设置指定内容是否已收藏。
• 变更说明：前端一键收藏按钮应调用本接口，不再为了快速收藏打开文件夹弹窗。文件夹多选弹窗、用户中心编辑文件夹归属仍继续调用 POST /api/bookmark/sync_folders。

#请求参数

#其他校验规则

• id >= 1
• type 只能是 artist / artwork / service / product
• is_saved 必须是 boolean

#行为说明

• is_saved=true
  • 如果用户还没有收藏该对象，自动创建或获取默认文件夹，并将对象加入默认文件夹。
  • 如果对象已经在自定义文件夹中，会保留原有文件夹归属，并补充加入默认文件夹。
  • 如果对象已收藏，不重复增加收藏计数。
• is_saved=false
  • 从当前用户所有收藏文件夹中移除该对象。
  • 如果对象原本已收藏，收藏计数减 1。
  • 如果对象原本未收藏，仍返回成功，不重复扣减计数。
• 返回的 is_saved 和 folder_ids 是服务端处理后的最终状态，前端应以响应结果刷新按钮和本地状态。

#请求示例：收藏

{
  "type": "artwork",
  "id": 456,
  "is_saved": true
}

#响应示例：收藏成功

{
  "status": "success",
  "message": "Set Saved Success",
  "code": 200,
  "data": {
    "type": "artwork",
    "id": 456,
    "is_saved": true,
    "folder_ids": [1],
    "default_folder_id": 1
  }
}

#请求示例：取消收藏

{
  "type": "artwork",
  "id": 456,
  "is_saved": false
}

#响应示例：取消收藏成功

{
  "status": "success",
  "message": "Set Saved Success",
  "code": 200,
  "data": {
    "type": "artwork",
    "id": 456,
    "is_saved": false,
    "folder_ids": [],
    "default_folder_id": null
  }
}

#错误响应

404：收藏对象不存在

{
  "status": "success",
  "message": "Artwork Not Found",
  "code": 404
}

422：参数校验失败

{
  "message": "The selected type is invalid.",
  "errors": {
    "type": [
      "The selected type is invalid."
    ]
  }
}

#兼容性说明

• POST /api/bookmark/save_artist、save_artwork、save_service、save_product 保留，不作为新一键收藏按钮的首选接口。
• POST /api/bookmark/sync_folders 语义不变：只同步文件夹归属，适用于多选文件夹弹窗和用户中心管理场景。
• 一键取消收藏统一理解为“取消这个内容的收藏状态”，因此会从所有收藏文件夹移除，而不是只移除默认文件夹。