707 lines
16 KiB
Markdown
707 lines
16 KiB
Markdown
## 统一约定
|
||
|
||
1. ### 鉴权与会话保持
|
||
|
||
- 登录成功后返回 `access_token`，前端请求统一带：`Authorization: Bearer <access_token>`。access_token由服务器生成的与uid唯一绑定的JWT+粉丝身份id拼接构成。
|
||
- 需要登录的接口：统一返回 401（token 失效）。
|
||
|
||
1. ### 通用响应结构（JSON）
|
||
|
||
建议后端响应返回格式统一 envelope，便于移动端处理：
|
||
|
||
```JSON
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
分页：
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{
|
||
"uid": "13800000000",
|
||
"password": "PlainOrHashed",
|
||
"fan_identity_id": "fan_xz",
|
||
"nickname": "爱战战"
|
||
}
|
||
```
|
||
|
||
- **返回（data）**：注册完成即登录、，返回 token + 用户基础信息（含 UID、托管链地址、当前身份）。如果帐号已经存在了要返回专门的message。
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{ "uid": "13800000000", "password": "xxx" }
|
||
```
|
||
|
||
- **返回（data）**：同注册（token + user + identities 简表可选）。
|
||
|
||
```JSON
|
||
{
|
||
"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）
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{"code":200,"message":"ok","data":{}}
|
||
```
|
||
|
||
1. ### 获取当前登录态用户（用于启动时恢复会话，需要JWT）
|
||
|
||
- **接口名**：Get Me
|
||
- **路径**：`GET https://localhost:3000/api/``v1/``auth/me`
|
||
- **参数**：无
|
||
- **返回（data）**：用于个人信息页/首页初始化。
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{ "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）**：
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{ "identity_id": "fan_wyb" }
|
||
```
|
||
|
||
- **返回（data）**：
|
||
|
||
```JSON
|
||
{ "bound": true, "identity_id": "fan_wyb" }
|
||
```
|
||
|
||
1. ### 切换当前粉丝身份
|
||
|
||
- **接口名**：Switch Fan Identity
|
||
- **路径**：`POST https://localhost:3000/api/``v1/``my/fan-identities/switch`
|
||
- **参数（Body）**：
|
||
|
||
```JSON
|
||
{"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 与身份不一致），并返回该身份下的概览数据（余额、等级等）。
|
||
|
||
```JSON
|
||
{
|
||
"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/链地址只读、头像系统生成不可改）。
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{ "nickname": "新昵称" }
|
||
```
|
||
|
||
- **返回（data）**：
|
||
|
||
```JSON
|
||
{ "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）**
|
||
|
||
- ```JSON
|
||
{
|
||
"pic_url":""
|
||
}
|
||
```
|
||
|
||
1. ### 上传图片后取消铸造
|
||
|
||
- **路径**：`DELETE ``https://localhost:3000/api/``cancelMint`
|
||
|
||
1. ### 创建铸造订单（链下）并触发链上确权（异步）
|
||
|
||
- **接口名**：Create Mint
|
||
- **路径**：`POST https://localhost:3000/api/mints`
|
||
- **参数（Body）**：
|
||
|
||
```JSON
|
||
{
|
||
"name": "藏品名称",
|
||
"type": "poster",
|
||
"pic_url": " ",
|
||
"material": { "event" : "", "memo" : "" },
|
||
}
|
||
```
|
||
|
||
- **返回（data）**（建议异步：立即返回任务 id，前端轮询/订阅状态）：
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{
|
||
"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）**：
|
||
|
||
```JSON
|
||
{
|
||
"asset_id": "asset_888"，
|
||
"gallery_owner_id:": 10000001,
|
||
"slot_it": 1
|
||
}
|
||
```
|
||
|
||
- **返回（data）**：
|
||
|
||
```JSON
|
||
{
|
||
"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，可选）**：
|
||
|
||
```JSON
|
||
{
|
||
"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，可选）**：
|
||
|
||
```JSON
|
||
{ "confirm": true }
|
||
```
|
||
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{ "slot_id": "slot_2", "status": "EMPTY" }
|
||
```
|
||
|
||
1. ### 解锁/购买新展位（等级解锁或货币购买）
|
||
|
||
- **接口名**：Unlock Slot
|
||
- **路径**：`POST https://localhost:3000/api/galleries/slots_unlock`
|
||
- **参数（Body）：通过请求体中的****JWT****判断**
|
||
- **返回（data）**：
|
||
|
||
```JSON
|
||
{
|
||
"slot_total": 3,
|
||
"crystal_balance": 120,
|
||
}
|
||
```
|
||
|
||
## F. 广场与推荐
|
||
|
||
1. ### 广场推荐小屋列表
|
||
|
||
- **接口名**：List Square Huts
|
||
- **路径**：`GET https://localhost:3000/api/square/huts`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{
|
||
"items": [
|
||
{ "uid": 18995036422, "nickname": "A" }
|
||
],
|
||
}
|
||
```
|
||
|
||
1. ### 广场 TOP 藏品展板（3 个）
|
||
|
||
- **接口名**：Get Top Assets
|
||
- **路径**：`GET https://localhost:3000/api/square/top-assets`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{
|
||
"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`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{ "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）**：
|
||
|
||
```JSON
|
||
{ "target_uid": 18995036422 }
|
||
```
|
||
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{ "request_id": "fr_001" }
|
||
```
|
||
|
||
1. ### 处理好友申请（同意/拒绝）
|
||
|
||
- **接口名**：Respond Friend Request
|
||
- **路径**：`POST https://localhost:3000/api/friends/requests/respond`
|
||
- **参数（Body）**：
|
||
|
||
```JSON
|
||
{
|
||
"request_id": "fr_001"，
|
||
"action": true
|
||
}
|
||
```
|
||
|
||
1. ### 好友列表
|
||
|
||
- **接口名**：List Friends
|
||
- **路径**：`GET https://localhost:3000/api/friend-list`
|
||
- **参数（Body）**：
|
||
|
||
```JSON
|
||
{
|
||
"page": 1,
|
||
"page_size": 10
|
||
}
|
||
```
|
||
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{ "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，可选）**：
|
||
|
||
```JSON
|
||
{
|
||
"asset_id": "asset_888"，
|
||
}
|
||
```
|
||
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{ "liked": true, "like_count": 13 }
|
||
```
|
||
|
||
1. ### 取消点赞（可选）
|
||
|
||
- **接口名**：Unlike Asset
|
||
- **路径**：`DELETE https://localhost:3000/api/assets/{asset_id}/likes`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{ "liked": false, "like_count": 12 }
|
||
```
|
||
|
||
## I. 任务与成长
|
||
|
||
> 行为触发成长值与奖励；可查看并完成日常任务。
|
||
|
||
1. ### 任务中心：任务列表
|
||
|
||
- **接口名**：List Tasks
|
||
- **路径**：`GET https://localhost:3000/api/tasks`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{
|
||
"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
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{
|
||
"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`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{
|
||
"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`
|
||
- **返回**：
|
||
|
||
```JSON
|
||
{
|
||
"opened_intro": true,
|
||
"completed_profile_setup": false,
|
||
"completed_mint_guide": false,
|
||
"completed_display_guide": false
|
||
}
|
||
``` |