xiaoyu/topfans
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
confirmmodal
topfans/backend/docs/HTTP REST API接口文档.md
zerosaturation 06f4038a75 提交后端代码
2026-04-07 22:29:48 +08:00

16 KiB
Raw Permalink Blame History

统一约定

  1. 鉴权与会话保持

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

  1. 通用响应结构（JSON）

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

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

分页：

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

A. 认证与账户（Auth）

  1. 注册（不需要校验JWT）

  • 接口名：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
        }
    }
}

  1. 登录（不需要校验JWT）

  • 接口名：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
        }
    }
}

  1. 退出登录

  • 接口名：Logout
  • 路径：POST https://localhost:3000/api/``v1/``auth/logout
  • 参数：无（Header 带 access_token）
  • 返回：
{"code":200,"message":"ok","data":{}}

  1. 获取当前登录态用户（用于启动时恢复会话，需要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
        }
    }
}

  1. 修改密码

  • 接口名：Change Password
  • 路径：POST https://localhost:3000/api/``v1/``account/password
  • 参数（Body）：
{ "old_password": "xxx", "new_password": "yyy" }
  • 返回：空 data

B. 粉丝身份（Identity / Isolation）

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

  • 接口名：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
  }
}

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

  • 接口名：add Fan Identity
  • 路径：POST https://localhost:3000/api/``v1/``my/fan-identities
  • 参数（Body）：
{ "identity_id": "fan_wyb" }
  • 返回（data）：
{ "bound": true, "identity_id": "fan_wyb" }

  1. 切换当前粉丝身份

  • 接口名：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）

  1. 获取个人信息数据

  • 接口名：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
    }
}

  1. 修改昵称

  • 接口名：Update Nickname
  • 路径：POST https://localhost:3000/api/``v1/``me/profile
  • 参数（Body）：
{ "nickname": "新昵称" }
  • 返回（data）：
{ "nickname": "新昵称" }

D. 数字藏品（Mint / Starbook）

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

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

  • 路径：POST ``https://localhost:3000/api/uplo``adPic

  • HTTP Method：POST

  • Content-Type：multipart/form-data

  • 请求方式（uniapp）：uni.uploadFile

  • 返回（data）

    • {
    "pic_url":""
}

  1. 上传图片后取消铸造

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

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

  • 接口名：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
}

  1. 星册：获取我的藏品列表

  • 接口名：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
}

  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" }
}

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

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

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

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

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

  • 接口名：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
    }
  ]
}

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

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

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

  • 接口名：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
}

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

  • 接口名：Remove Asset From Slot
  • 路径：POST https://localhost:3000/api/galleries/remove
  • 参数（Body，可选）：
{ 
    "asset_id": "asset_888"，
    "gallery_owner_uid:": 13800000000,
    "slot_id": 1 
}
  • 返回：空 data

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

  • 接口名：Kick Occupier
  • 路径：POST https://localhost:3000/api/galleries/me/slots/{slot_id}/kick
  • 参数（Body，可选）：
{ "confirm": true }
  • 返回：
{ "slot_id": "slot_2", "status": "EMPTY" }

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

  • 接口名：Unlock Slot
  • 路径：POST https://localhost:3000/api/galleries/slots_unlock
  • 参数（Body）：通过请求体中的JWT判断
  • 返回（data）：
{
    "slot_total": 3,
    "crystal_balance": 120,
}

F. 广场与推荐

  1. 广场推荐小屋列表

  • 接口名：List Square Huts
  • 路径：GET https://localhost:3000/api/square/huts
  • 返回：
{
  "items": [
    { "uid": 18995036422, "nickname": "A" }
  ],
}

  1. 广场 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，可随等级解锁。

  1. 搜索用户（按 UID）

  • 接口名：Search User
  • 路径：GET https://localhost:3000/api/users/search
  • 参数（Query）：uid=18995036422
  • 返回：
{ "uid": 10000002, "nickname": "A", "is_friend": false }

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

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

  1. 发起好友申请

  • 接口名：Send Friend Request
  • 路径：POST https://localhost:3000/api/friends/requests
  • 参数（Body）：
{ "target_uid": 18995036422 }
  • 返回：
{ "request_id": "fr_001" }

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

  • 接口名：Respond Friend Request
  • 路径：POST https://localhost:3000/api/friends/requests/respond
  • 参数（Body）：
{ 
  "request_id": "fr_001"，
  "action": true
}

  1. 好友列表

  • 接口名：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 }

  1. 删除好友

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

H. 点赞

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

  1. 点赞藏品

  • 接口名：Like Asset
  • 路径：POST https://localhost:3000/api/assets/likes
  • 参数（Body，可选）：
{
    "asset_id": "asset_888"，
}
  • 返回：
{ "liked": true, "like_count": 13 }

  1. 取消点赞（可选）

  • 接口名：Unlike Asset
  • 路径：DELETE https://localhost:3000/api/assets/{asset_id}/likes
  • 返回：
{ "liked": false, "like_count": 12 }

I. 任务与成长

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

  1. 任务中心：任务列表

  • 接口名：List Tasks
  • 路径：GET https://localhost:3000/api/tasks
  • 返回：
{
  "items": [
    { "task_id": "0001", "title": "每日登录", "status": "FINISHED", "reward": { "crystal": 5, "exp": 10 }, "detail":"登录" }
  ]
}

  1. 领取任务奖励

  • 接口名：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）

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

  1. 获取新手引导完成状态

  • 接口名：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
}

  1. 新手引导完成

  • 接口名：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
}