topfans/HTTP REST API接口文档.md at 73d9b969988ce2a067c359998e9fab94e9a51b18

xiaoyu/topfans

Fork 0

zerosaturation 06f4038a75 提交后端代码

2026-04-07 22:29:48 +08:00

16 KiB

Raw Blame History

统一约定

鉴权与会话保持

登录成功后返回 access_token，前端请求统一带：Authorization: Bearer <access_token>。access_token由服务器生成的与uid唯一绑定的JWT+粉丝身份id拼接构成。
需要登录的接口：统一返回 401（token 失效）。

通用响应结构（JSON）

建议后端响应返回格式统一 envelope，便于移动端处理：

{
  "code": 200,
  "message": "ok",
  "data": {}
}

分页：

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [],
    "page": 1,
    "page_size": 20,
    "total": 123
  }
}

A. 认证与账户（Auth）

接口名：Register
路径：POST ``https://localhost:3000/api/``v1/``auth/register
参数（Body）：

{
  "uid": "13800000000",
  "password": "PlainOrHashed",
  "fan_identity_id": "fan_xz",
  "nickname": "爱战战"
}

返回（data）：注册完成即登录、，返回 token + 用户基础信息（含 UID、托管链地址、当前身份）。如果帐号已经存在了要返回专门的message。

{
    "code": 200,
    "message": "ok",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoyLCJzdGFyX2lkIjo4NywidXBkYXRlZF9hdCI6MTc2NzU5MTQ2NzIxNywiZXhwIjoxNzY4MTk2MjY3LCJpYXQiOjE3Njc1OTE0Njd9.buYchnXLfdv9WAE6zgGwn1ATKgcrTjgomFmIHFXTkIk",
        "expires_in": 604800,
        "user": {
            "uid": 2,
            "nickname": "爱战战",
            "fan_identity": {
                "identity_id": "xz",
                "name": "肖战",
                "tag": "小飞侠"
            },
            "fan_level": 1,
            "starbook_limit": 3,
            "slot_limit": 3,
            "assets_num": 0,
            "crystal_balance": 0
        }
    }
}

接口名：Login
路径：POST ``https://localhost:3000/api/``v1/``auth/login
参数（Body）：

{ "uid": "13800000000", "password": "xxx" }

返回（data）：同注册（token + user + identities 简表可选）。

{
    "code": 200,
    "message": "ok",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoyLCJzdGFyX2lkIjo4NywidXBkYXRlZF9hdCI6MTc2NzU5MTQ2NzIxNywiZXhwIjoxNzY4MTk2MjY3LCJpYXQiOjE3Njc1OTE0Njd9.buYchnXLfdv9WAE6zgGwn1ATKgcrTjgomFmIHFXTkIk",
        "expires_in": 604800,
        "user": {
            "uid": 2,
            "nickname": "爱战战",
            "fan_identity": {
                "identity_id": "xz",
                "name": "肖战",
                "tag": "小飞侠"
            },
            "fan_level": 1,
            "starbook_limit": 3,
            "slot_limit": 3,
            "assets_num": 0,
            "crystal_balance": 0
        }
    }
}

退出登录

接口名：Logout
路径：POST https://localhost:3000/api/``v1/``auth/logout
参数：无（Header 带 access_token）
返回：

{"code":200,"message":"ok","data":{}}

获取当前登录态用户（用于启动时恢复会话，需要JWT）

接口名：Get Me
路径：GET https://localhost:3000/api/``v1/``auth/me
参数：无
返回（data）：用于个人信息页/首页初始化。

{
    "code": 200,
    "message": "ok",
    "data": {
        "uid": 2,
        "nickname": "爱战战",
        "current_identity": {
            "identity_id": "xz",
            "identity_name": "肖战",
            "tag": "小飞侠",
            "level": 1,
            "crystal_balance": 0
        }
    }
}

修改密码

接口名：Change Password
路径：POST https://localhost:3000/api/``v1/``account/password
参数（Body）：

{ "old_password": "xxx", "new_password": "yyy" }

返回：空 data

B. 粉丝身份（Identity / Isolation）

获取可选粉丝身份列表（首次注册/身份新增）

接口名：List Fan Identities
路径：GET https://localhost:3000/api/``v1/``fan-identities
参数（Query，可选）： keyword, page, page_size
返回（data.items）：

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "star_id": 87,
        "identity_id": "xz",
        "name": "肖战",
        "tag": "小飞侠"
      },
      {
        "star_id": 88,
        "identity_id": "wyb",
        "name": "王一博",
        "tag": "小摩托"
      }
    ],
    "total": 2
  }
}

新增第二粉丝身份（最多两个）

接口名：add Fan Identity
路径：POST https://localhost:3000/api/``v1/``my/fan-identities
参数（Body）：

{ "identity_id": "fan_wyb" }

返回（data）：

{ "bound": true, "identity_id": "fan_wyb" }

切换当前粉丝身份

接口名：Switch Fan Identity
路径：POST https://localhost:3000/api/``v1/``my/fan-identities/switch
参数（Body）：

{"new_star_id": 88}

curl -X POST "${BASE_URL}/api/${API_VERSION}/my/fan-identities/switch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "new_star_id": 88
  }' | jq .

返回（data）：建议返回新 token（避免旧 token claims 与身份不一致），并返回该身份下的概览数据（余额、等级等）。

{
  "code": 200,
  "message": "ok",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJzdGFyX2lkIjo4OCwidXBkYXRlZF9hdCI6MTc2NzU5MDU1MDI1MywiZXhwIjoxNzY4MTk5NzIzLCJpYXQiOjE3Njc1OTQ5MjN9.26Fn5NaAmP6ttMV-1k39zlIyTzzx_Ue0cf8udJbhpZE",
    "expires_in": 604800,
    "current_identity": {
      "identity_id": "wyb",
      "identity_name": "王一博",
      "tag": "小摩托",
      "level": 1,
      "crystal_balance": 0
    }
  }
}

C. 个人信息页（Profile）

获取个人信息数据

接口名：Get Profile
路径：GET https://localhost:3000/api/``v1/``me/profile
参数：无（Header 带 token；建议同时带 X-Fan-Identity-Id）
返回（data）：字段与文档一致（UID/链地址只读、头像系统生成不可改）。

{
    "code": 200,
    "message": "ok",
    "data": {
        "uid": 2,
        "nickname": "爱战战",
        "fan_identity": {
            "identity_id": "xz",
            "name": "肖战",
            "tag": "小飞侠"
        },
        "fan_level": 1,
        "starbook_limit": 3,
        "slot_limit": 3,
        "assets_num": 0,
        "crystal_balance": 0
    }
}

修改昵称

接口名：Update Nickname
路径：POST https://localhost:3000/api/``v1/``me/profile
参数（Body）：

{ "nickname": "新昵称" }

返回（data）：

{ "nickname": "新昵称" }

D. 数字藏品（Mint / Starbook）

覆盖“铸造（链下记录+链上确权）、星册收纳、素材来源（平台素材/用户上传+合规审查+AI封面）”。

上传藏品封面图片（等待审核和AI生成）

路径：POST ``https://localhost:3000/api/uplo``adPic
HTTP Method：POST
Content-Type：multipart/form-data
请求方式（uniapp）：uni.uploadFile
返回（data）
- ```
{
    "pic_url":""
}
```

上传图片后取消铸造

路径：DELETE ``https://localhost:3000/api/``cancelMint

创建铸造订单（链下）并触发链上确权（异步）

接口名：Create Mint
路径：POST https://localhost:3000/api/mints
参数（Body）：

{
  "name": "藏品名称",
  "type": "poster",
  "pic_url": " ",
  "material": { "event" : "", "memo" : "" },
}

返回（data）（建议异步：立即返回任务 id，前端轮询/订阅状态）：

{
  "mint_id": "mint_001",
  "status": "PENDING",
  "asset_id": null
}

星册：获取我的藏品列表

接口名：List Starbook Items
路径：GET https://localhost:3000/api/starbooks/me/items
参数（Query）： page, page_size
返回（data.items）：

{
  "items": [
    {
      "asset_id": "asset_888",
      "name": "藏品名称",
      "cover_url": "https://...",
      "like_count": 12,
      "mint_status" : "审核中",
      "on_chain": { "token_id": "123", "tx_hash": "0x..." },
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

藏品详情

接口名：Get Asset Detail
路径：GET https://localhost:3000/api/assets/{asset_id}
返回（data）：

{
  "asset_id": "asset_888",
  "name": "藏品名称",
  "type": "poster",
  "cover_url": "https://...",
  "owner_uid": 18995036422,
  "owner_nickname":"",
  "like_count": 12,
  "on_chain": { "custody_address": "0x...", "tx_hash": "0x...", "token_id": "123" }
}

藏品封面默认素材列表（新手教程）

接口名：List Platform Materials
路径：GET https://localhost:3000/api/materials/platform
返回：素材条目列表

E. 展馆与展位（Gallery / Slots）

覆盖“个人展馆初始展位 3、可解锁/购买；展示替换/下架；可展示到他人展馆空位；抢展位展出 4h 自动下架；被占位可踢走”。

获取我的展馆（含展位占用情况）

接口名：Get My Gallery
路径：GET https://localhost:3000/api/mygalleries
返回（data）：

{
  "gallery_owner_id": 10000001,
  "slot_total": 3,
  "slots": [
    {
      "slot_id": 01,
      "status": "OCCUPIED",
      "asset": {
          "asset_id": "asset_888",
          "name": "藏品名称",
          "cover_url": "https://...",
          "like_count": 12,
          "remain_time": 5000
    }
  ]
}

获取他人展馆（用于广场/好友访问）

接口名：Get User Gallery
路径：GET https://localhost:3000/api/galleries/{target_uid}
参数：无
返回：同上（注意：后端需校验粉丝身份一致才能访问）。

在某个展位展示藏品（放入自己或他人展馆空位）

接口名：Place Asset To Slot
路径：POST https://localhost:3000/api/galleries/place
参数（Body）：

{ 
    "asset_id": "asset_888"，
    "gallery_owner_id:": 10000001,
    "slot_it": 1
 }

返回（data）：

{
  "status": "OCCUPIED",
  "occupied_until": "2025-12-30T10:00:00Z",
  "occupier_uid": 18995036422
}

下架展位藏品（主动下架）

接口名：Remove Asset From Slot
路径：POST https://localhost:3000/api/galleries/remove
参数（Body，可选）：

{ 
    "asset_id": "asset_888"，
    "gallery_owner_uid:": 13800000000,
    "slot_id": 1 
}

返回：空 data

踢走占位（被占位者的操作，待定）

接口名：Kick Occupier
路径：POST https://localhost:3000/api/galleries/me/slots/{slot_id}/kick
参数（Body，可选）：

{ "confirm": true }

{ "slot_id": "slot_2", "status": "EMPTY" }

解锁/购买新展位（等级解锁或货币购买）

接口名：Unlock Slot
路径：POST https://localhost:3000/api/galleries/slots_unlock
参数（Body）：通过请求体中的JWT判断
返回（data）：

{
    "slot_total": 3,
    "crystal_balance": 120,
}

F. 广场与推荐

广场推荐小屋列表

接口名：List Square Huts
路径：GET https://localhost:3000/api/square/huts
返回：

{
  "items": [
    { "uid": 18995036422, "nickname": "A" }
  ],
}

广场 TOP 藏品展板（3 个）

接口名：Get Top Assets
路径：GET https://localhost:3000/api/square/top-assets
返回：

{
  "items": [
    { "asset_id": "asset_1", "name": "X", "cover_url": "https://...", "owner_uid": 18995036422, "like_count": 999 }
  ]
}

G. 好友

搜索 UID/系统推荐/广场随机推荐添加好友，需双向确认；好友列表可进入展馆、删除；默认上限 50，可随等级解锁。

搜索用户（按 UID）

接口名：Search User
路径：GET https://localhost:3000/api/users/search
参数（Query）：uid=18995036422
返回：

{ "uid": 10000002, "nickname": "A", "is_friend": false }

系统推荐好友列表（待定）

接口名：Recommend Friends
路径：GET https://localhost:3000/api/friends/recommendations
参数：page, page_size
返回：候选用户列表（同粉丝身份隔离）。

发起好友申请

接口名：Send Friend Request
路径：POST https://localhost:3000/api/friends/requests
参数（Body）：

{ "target_uid": 18995036422 }

{ "request_id": "fr_001" }

处理好友申请（同意/拒绝）

接口名：Respond Friend Request
路径：POST https://localhost:3000/api/friends/requests/respond
参数（Body）：

{ 
  "request_id": "fr_001"，
  "action": true
}

好友列表

接口名：List Friends
路径：GET https://localhost:3000/api/friend-list
参数（Body）：

{
    "page": 1,
    "page_size": 10
}

{ "items": [{ "uid": 18995036422, "nickname": "A", "fan_level":10 }], "page": 1, "page_size": 10, "total": 10 }

删除好友

接口名：Delete Friend
路径：DELETE https://localhost:3000/api/friends/{friend_uid}
返回：空 data

H. 点赞

支持给展馆中正在展出的藏品点赞；TOP 展板依赖点赞计数。

点赞藏品

接口名：Like Asset
路径：POST https://localhost:3000/api/assets/likes
参数（Body，可选）：

{
    "asset_id": "asset_888"，
}

{ "liked": true, "like_count": 13 }

取消点赞（可选）

接口名：Unlike Asset
路径：DELETE https://localhost:3000/api/assets/{asset_id}/likes
返回：

{ "liked": false, "like_count": 12 }

I. 任务与成长

行为触发成长值与奖励；可查看并完成日常任务。

任务中心：任务列表

接口名：List Tasks
路径：GET https://localhost:3000/api/tasks
返回：

{
  "items": [
    { "task_id": "0001", "title": "每日登录", "status": "FINISHED", "reward": { "crystal": 5, "exp": 10 }, "detail":"登录" }
  ]
}

领取任务奖励

接口名：Claim Task Reward
路径：POST https://localhost:3000/api/tasks/claim
参数：taskID
返回：

{
  "claimed": true,
  "reward": { "crystal": 5, "exp": 10 },
  "balances": { "crystal": 125, "coin": 30 },
  "growth": { "level": 2, "exp": 130 }
}

J. 新手引导（Onboarding）

包含开场动画、铸造引导、首次展示引导、首次注册登录后引导填写昵称与选择粉丝身份且不可跳过。

获取新手引导完成状态

接口名：Get Onboarding Status
路径：GET https://localhost:3000/api/onboarding/status
返回：

{
  "opened_intro": true,
  "completed_profile_setup": false,
  "completed_mint_guide": false,
  "completed_display_guide": false
}

新手引导完成

接口名：Get Onboarding Status
路径：POST https://localhost:3000/api/onboarding/status
返回：

{
  "opened_intro": true,
  "completed_profile_setup": false,
  "completed_mint_guide": false,
  "completed_display_guide": false
}

16 KiB Raw Blame History Unescape Escape

统一约定

鉴权与会话保持

通用响应结构（JSON）

A. 认证与账户（Auth）

注册（不需要校验JWT）

登录（不需要校验JWT）

退出登录

获取当前登录态用户（用于启动时恢复会话，需要JWT）

修改密码

B. 粉丝身份（Identity / Isolation）

获取可选粉丝身份列表（首次注册/身份新增）

新增第二粉丝身份（最多两个）

切换当前粉丝身份

C. 个人信息页（Profile）

获取个人信息数据

修改昵称

D. 数字藏品（Mint / Starbook）

上传藏品封面图片（等待审核和AI生成）

上传图片后取消铸造

创建铸造订单（链下）并触发链上确权（异步）

星册：获取我的藏品列表

藏品详情

藏品封面默认素材列表（新手教程）

E. 展馆与展位（Gallery / Slots）

获取我的展馆（含展位占用情况）

获取他人展馆（用于广场/好友访问）

在某个展位展示藏品（放入自己或他人展馆空位）

下架展位藏品（主动下架）

踢走占位（被占位者的操作，待定）

解锁/购买新展位（等级解锁或货币购买）

F. 广场与推荐

广场推荐小屋列表

广场 TOP 藏品展板（3 个）

G. 好友

搜索用户（按 UID）

系统推荐好友列表（待定）

发起好友申请

处理好友申请（同意/拒绝）

好友列表

删除好友

H. 点赞

点赞藏品

取消点赞（可选）

I. 任务与成长

任务中心：任务列表

领取任务奖励

J. 新手引导（Onboarding）

获取新手引导完成状态

新手引导完成

16 KiB

Raw Blame History