## 统一约定

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