基础 URL (Base URL): https://ucenter.qoom.cn 请在浏览器内部实现逻辑：登录后获取 Token，在 Header 中携带 Token 进行同步操作。

1. 用户注册

• URL: /api/register

• Method: POST

• Body (JSON):

  JSON

  {  "username": "user1",  "password": "my_password"}

• Response: 200 OK

2. 用户登录

• URL: /api/login

• Method: POST

• Body (JSON):

  JSON

  {  "username": "user1",  "password": "my_password"}

• Response (Success):

  JSON

  {  "code": 200,  "msg": "Login success",  "data": {    "token": "a1b2c3d4...", 
      "username": "user1"
    }
  }

  注意：请将返回的 token 保存到本地加密存储中。

3. 拉取云端收藏夹 (Download)

• URL: /api/sync

• Method: GET

• Headers:

  • Authorization: Bearer <token>

• Response:

  JSON

  {  "code": 200,  "data": {    "version": 1705460000,    "bookmarks": [ ...这里是浏览器定义的收藏夹JSON树结构... ]
    }
  }

  逻辑建议：如果云端 version 大于本地 version，提示用户“云端有新数据，是否覆盖？”或自动覆盖。

4. 推送收藏夹到云端 (Upload)

• URL: /api/sync

• Method: POST

• Headers:

  • Authorization: Bearer <token>

• Body (JSON):

  JSON

  {  "bookmarks": [ ...这里是浏览器本地的收藏夹完整JSON树... ]
  }

• Response: 200 OK




请将以下这部分作为“2.0版本接口文档”发给外包团队：

需求变更重点：

1. 逻辑变更：不再是全量覆盖。浏览器端必须实现“合并逻辑”。

2. 数据结构：上传时不需要发整个JSON树，而是将书签“拍平”为数组发送。

3. 排序：服务器返回的数据是按时间“由远到近”排序的。

1. 上传头像接口 (新增)

• URL: /api/upload_avatar

• Method: POST

• Header: Authorization: Bearer <token>

• Content-Type: multipart/form-data

• Body: file (二进制图片文件，仅限 jpg, png, webp, gif)

• Response:

  JSON

  { "code": 200, "data": { "url": "/uploads/u1_123456.jpg" } }

2. 双向同步接口 (逻辑大改)

此接口同时完成上传本地新书签和拉取云端所有书签的功能。

• URL: /api/sync

• Method: POST

• Header: Authorization: Bearer <token>

• Body (JSON): 浏览器端需要将本地书签树遍历，转为以下扁平数组。

  JSON

  {  "bookmarks": [
      {      "url": "https://www.google.com",      "title": "Google",      "created_at": "2023-01-01 12:00:00" 
      },
      {      "url": "https://www.baidu.com",      "title": "Baidu",      "created_at": "2023-02-01 10:00:00"
      }
    ]
  }

  (注：只发送本地目前存在的书签即可。)

• 服务端处理逻辑：

  1. 服务器接收该列表，将数据库中不存在的 URL 插入数据库（去重）。

  2. 注意： 服务器不会删除数据库里有但你上传列表里没有的数据（实现了本地删除不影响云端）。

• Response: 服务器返回云端目前存储的所有书签（按时间正序排列）。

  JSON

  {  "code": 200,  "data": {    "bookmarks": [
          { "url": "...", "title": "...", "created_at": "..." },
          { "url": "...", "title": "...", "created_at": "..." }        // 包含刚才上传的，也包含本地之前删掉但云端还在的
      ]
    }
  }

• 客户端（浏览器）接收后处理逻辑（非常重要）：

  1. 拿到 response.data.bookmarks。

  2. 遍历这个列表。

  3. 检查本地是否存在该 URL。

  4. 如果本地不存在：在浏览器书签栏中创建该书签（实现了下载云端有的但本地没有的）。

  5. 如果本地存在：跳过（或者更新标题）。

总结

这套方案完美解决了你的四个痛点：

1. 头像：通过 /api/upload_avatar 和 uploads 目录实现。

2. 互交逻辑：通过 INSERT IGNORE (去重) 和 API 返回全量数据结合客户端对比 (补全) 实现。

3. 管理页面：通过 manage.php 独立管理，只有在这里点删除才是 DELETE FROM DB。

4. 排序：通过 SQL 的 ORDER BY created_at ASC 保证由远到近。

给外包团队的接口地址清单 (更新)

你必须告知外包团队，Base URL 或 具体路径 已经改变。根据你重命名后的文件名，接口文档调整如下：

• 注册地址: https://你的域名/api/register (Nginx 伪静态会处理到 cloud_api.php)

• 登录地址: https://你的域名/api/login

• 同步地址: https://你的域名/api/sync

• 头像上传: https://你的域名/api/upload_avatar