topfans/docs/API_CALLS_SUMMARY.md

# TopFans Frontend 接口调用总览

> 范围：`frontend` 源码（排除 `unpackage/dist` 编译产物）。

## 1. 请求基础设施

- **统一入口**：`frontend/utils/api.js` 的 `request(options)`，底层使用 `uni.request`。
- **Base URL**：`http://101.132.250.62:8080`（硬编码）。
- **鉴权注入**：
  - 登录/注册接口（`/api/v1/auth/login`、`/api/v1/auth/register`）不注入 token。
  - 其余接口自动从 `uni.getStorageSync('access_token')` 注入 `Authorization: Bearer <token>`。
- **统一响应解析**：
  - HTTP `401`：清理 `access_token`/`user`，`reLaunch` 到登录页，`reject(Error('登录已过期，请重新登录'))`。
  - HTTP `200` 且有 `res.data.code`：
    - `code === 200`：`resolve(res.data)`。
    - `code === 401/400/403`：同样清会话并跳登录。
    - 其他业务码：`reject(Error(res.data.message || '请求失败'))`。
  - 其他 HTTP 状态：`reject(Error(res.data?.message || 请求失败(statusCode)))`。
- **超时/重试**：未设置统一 `timeout`，无自动重试机制。

---

## 2. API 清单（函数名 / 参数 / 响应解析 / 用途）

### 2.1 认证与账号

#### `loginApi(mobile, password)`
- **Method/Path**：`POST /api/v1/auth/login`
- **参数**：`{ mobile, password }`
- **调用位置**：
  - `store/modules/user.js` -> `actions.login`
  - `pages/login/login.vue` -> `handleLogin`（触发 `store.dispatch('user/login')`）
- **响应解析**：
  - `res.code === 200 && res.data` 成功。
  - 读取 `res.data.access_token`、`res.data.user` 写入本地缓存与 store。
  - 若 `user.avatar_url` 存在，继续调用 `getOssPresignedUrlApi` 取 `res.data.url` 并本地缓存头像。
- **用途**：登录并初始化会话（token、用户信息、头像缓存）。

#### `registerApi(mobile, password, star_id, nickname)`
- **Method/Path**：`POST /api/v1/auth/register`
- **参数**：`{ mobile, password, star_id, nickname }`
- **调用位置**：
  - `store/modules/user.js` -> `actions.register`
  - `pages/profile/selectRole.vue` -> `handleNext`（触发 `store.dispatch('user/register')`）
- **响应解析**：
  - 成功同登录流程：读取 `access_token` 与 `user`，并尝试头像预缓存。
  - 对 `409`（昵称冲突）做显式分支，向上抛 `{ code: 409, message }`。
- **用途**：注册并建立登录态。

#### `getUserProfileApi()`
- **Method/Path**：`GET /api/v1/auth/me`
- **参数**：无
- **调用位置**：
  - `pages/profile/profile.vue` -> `fetchUserInfo`
- **响应解析**：
  - 读取 `res.data` 字段：`uid`、`nickname`、`avatar_url`、`current_identity`、`assets_num`、`slot_limit`、`starbook_limit`、`blockchain_address` 等。
  - 页面侧将 `current_identity` 转换为缓存结构 `fan_identity`，并回写本地 `user`。
- **用途**：个人中心刷新用户主数据（以服务端为准）。

#### `updateNicknameApi(nickname)`
- **Method/Path**：`PUT /api/v1/me/nickname`
- **参数**：`{ nickname }`
- **调用位置**：
  - `pages/profile/profile.vue` -> `confirmChangeNickname`
- **响应解析**：检查 `res.code === 200` 后触发 `fetchUserInfo(true)` 全量刷新。
- **用途**：修改当前身份昵称。

#### `updatePasswordApi(oldPassword, newPassword)`
- **Method/Path**：`POST /api/v1/account/password`
- **参数**：`{ old_password, new_password }`
- **调用位置**：
  - `pages/profile/profile.vue` -> `confirmChangePassword`
- **响应解析**：`res.code === 200` 后提示成功并强制登出、清缓存、跳登录页。
- **用途**：密码修改与会话重置。

#### `deleteAccountApi()`
- **Method/Path**：`POST /api/user/delete-account`
- **参数**：无
- **调用位置**：
  - `pages/profile/profile.vue` -> `confirmDeleteAccount`
- **响应解析**：`result.code === 200` 后执行登出流程并跳登录页。
- **用途**：注销账号。

#### `updateUserInfoApi(nickname)`
- **Method/Path**：`POST /api/user/update`
- **参数**：`{ nickname }`
- **调用位置**：当前源码未发现调用。
- **用途**：历史/预留接口（当前未接入）。

---

### 2.2 社交（好友关系）

#### `friendListApi(page = 1, pageSize = 10)`
- **Method/Path**：`GET /api/v1/social/friends?page={page}&page_size={pageSize}`
- **参数**：分页参数
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `loadFriendList`
- **响应解析**：
  - 读取 `res.data.items`、`res.data.total`。
  - 字段映射：`friend_id -> user_id`，`friend_nickname -> nickname`，`friend_fan_level -> fan_level`，`friend_avatar -> avatar_url`。
  - 头像会再经 `getFriendAvatarRealUrl()` 调 `getOssPresignedUrlApi` 转真实 URL。
- **用途**：好友列表页及分页加载。

#### `searchUserApi(friendUserId)`
- **Method/Path**：`GET /api/v1/social/search-user?friend_user_id={friendUserId}`
- **参数**：目标用户 ID（UID）
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `watch(searchUid, ...)` 防抖回调
- **响应解析**：
  - 成功读取 `res.data` 并解析 `res.data.avatar_url` 为预签名 URL。
  - 失败时对 `404` 走“用户不存在”分支。
- **用途**：按 UID 搜索可添加的用户。

#### `sendFriendRequestApi(friendUserId)`
- **Method/Path**：`POST /api/v1/social/friend-requests`
- **参数**：`{ friend_user_id }`
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `confirmAddFriend`
- **响应解析**：调用成功后刷新“已发送请求”列表。
- **用途**：发送好友申请。

#### `getSentFriendRequestsApi(page = 1, pageSize = 10)`
- **Method/Path**：`GET /api/v1/social/friend-requests?type=sent&status=pending&page={page}&page_size={pageSize}`
- **参数**：分页参数
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `fetchSentRequests`
- **响应解析**：
  - 读取 `res.data.items`。
  - 解析 `to_user_avatar_url` 为预签名 URL 后渲染。
- **用途**：我的已发送申请列表。

#### `getReceivedFriendRequestsApi(page = 1, pageSize = 10)`
- **Method/Path**：`GET /api/v1/social/friend-requests?type=received&status=pending&page={page}&page_size={pageSize}`
- **参数**：分页参数
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `loadReceivedRequests`
- **响应解析**：
  - 读取 `res.data.items` 分页追加。
  - 解析 `from_user_avatar_url` 为预签名 URL。
- **用途**：收到的好友请求列表。

#### `handleFriendRequestApi(requestId, action)`
- **Method/Path**：`POST /api/v1/social/friend-requests/handle`
- **参数**：`{ request_id, action }`，`action ∈ {accept, reject}`
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `handleAcceptRequest`
  - `pages/components/FriendsContent.vue` -> `handleRejectRequest`
- **响应解析**：成功后本地移除对应请求项。
- **用途**：接受/拒绝好友请求。

#### `deleteFriendApi(friendUserId)`
- **Method/Path**：`DELETE /api/v1/social/friends`
- **参数**：`{ friend_user_id }`
- **调用位置**：
  - `pages/components/FriendsContent.vue` -> `confirmDeleteFriend`
- **响应解析**：成功后本地删除好友项并更新计数。
- **用途**：解除好友关系。

---

### 2.3 身份（粉丝身份）

#### `getFanIdentitiesApi()`
- **Method/Path**：`GET /api/v1/fan-identities`
- **参数**：无
- **调用位置**：
  - `pages/profile/profile.vue` -> `handleSwitchRole`
- **响应解析**：读取 `res.data.items` 作为可选明星列表。
- **用途**：拉取可新增的粉丝身份候选。

#### `addFanIdentityApi(starId, nickname)`
- **Method/Path**：`POST /api/v1/my/fan-identities`
- **参数**：`{ star_id, nickname }`
- **调用位置**：
  - `pages/profile/profile.vue` -> `confirmAddIdentity`
- **响应解析**：`res.code === 200` 后刷新用户信息。
- **用途**：新增某明星身份。

#### `getMyFanIdentitiesApi()`
- **Method/Path**：`GET /api/v1/my/fan-identities`
- **参数**：无
- **调用位置**：
  - `pages/profile/profile.vue` -> `handleFanTagClick`
- **响应解析**：读取 `res.data.items` 与 `res.data.current_star_id`。
- **用途**：身份切换前加载身份列表与当前身份。

#### `switchFanIdentityApi(newStarId)`
- **Method/Path**：`POST /api/v1/my/fan-identities/switch`
- **参数**：`{ new_star_id }`
- **调用位置**：
  - `pages/profile/profile.vue` -> `handleSwitchIdentity`
- **响应解析**：
  - 读取 `res.data.access_token` 覆盖本地 token。
  - 读取 `res.data.current_identity`（`identity_id`、`identity_name`、`tag`、`level`）刷新 UI 与缓存。
- **用途**：切换当前生效身份并刷新会话上下文。

---

### 2.4 资产/NFT（星册、详情、点赞）

#### `getMyAssetsApi(page = 1, pageSize = 20)`
- **Method/Path**：`GET /api/v1/assets/me/items?page={page}&page_size={pageSize}`
- **参数**：分页参数
- **调用位置**：
  - `pages/components/StarbookContent.vue` -> `loadAssetsList`
  - `pages/exhibition/exhibition.vue` -> `handleAddAssetClick`
- **响应解析**：
  - 读取 `response.data.items`。
  - 常用字段：`asset_id`、`name`、`cover_url`、`tx_hash`、`like_count`、`status`。
  - `cover_url` 会通过 `getAssetCoverRealUrl()` -> `getOssPresignedUrlApi(type=asset)` 转真实访问 URL。
- **用途**：我的藏品列表（星册页、展馆上架弹窗）。

#### `getAssetDetailApi(assetId)`
- **Method/Path**：`GET /api/v1/assets/{assetId}`
- **参数**：`assetId`
- **调用位置**：
  - `pages/components/StarbookContent.vue` -> `handleCardClick`
  - `pages/exhibition/exhibition.vue` -> `handleNftClick`
- **响应解析**：
  - 读取 `response.data.asset` 作为详情对象。
  - 点赞态兼容读取：`asset.is_liked`，部分调用还兜底 `response.data.is_liked`。
- **用途**：点击藏品卡片时拉取完整详情。

#### `likeAssetApi(assetId)`
- **Method/Path**：`POST /api/v1/social/assets/{assetId}/like`
- **参数**：`assetId`
- **调用位置**：
  - `pages/components/NftDetailModal.vue` -> `handleLike`（点赞分支）
- **响应解析**：`response.code === 200` 后本地 `isLiked=true`、`likeCount+1`。
- **用途**：点赞藏品。

#### `unlikeAssetApi(assetId)`
- **Method/Path**：`DELETE /api/v1/social/assets/{assetId}/like`
- **参数**：`assetId`
- **调用位置**：
  - `pages/components/NftDetailModal.vue` -> `handleLike`（取消点赞分支）
- **响应解析**：`response.code === 200` 后本地 `isLiked=false`、`likeCount-1`。
- **用途**：取消点赞。

---

### 2.5 展馆（槽位、上架、下架）

#### `getMyGalleriesApi()`
- **Method/Path**：`GET /api/v1/mygalleries`
- **参数**：无
- **调用位置**：
  - `pages/exhibition/exhibition.vue` -> `loadGallerySlots`（`isMyGallery === true` 分支）
- **响应解析**：
  - 读取 `response.data.gallery_owner_id`、`response.data.slots`。
  - `slots` 按 `visibility(public/private)` 分板，并读取 `slot.asset`（`asset_id`、`cover_url`、`like_count`、`remain_time` 等）。
- **用途**：加载当前用户展馆槽位状态。

#### `getUserGalleriesApi(targetUid)`
- **Method/Path**：`GET /api/v1/galleries/{targetUid}`
- **参数**：目标用户 UID
- **调用位置**：
  - `pages/exhibition/exhibition.vue` -> `loadGallerySlots`（`isMyGallery === false` 分支）
- **响应解析**：与 `getMyGalleriesApi` 同结构解析。
- **用途**：加载目标用户展馆。

#### `placeAssetToGalleryApi(assetId, galleryOwnerId, slotId)`
- **Method/Path**：`POST /api/v1/galleries/place`
- **参数**：`{ asset_id, gallery_owner_id, slot_id }`
- **调用位置**：
  - `pages/exhibition/exhibition.vue` -> `confirmPlaceAsset`
- **响应解析**：`response.code === 200` 后关闭弹窗并重新拉取槽位数据。
- **用途**：上架藏品到指定展位槽位。

#### `removeAssetFromGalleryApi(slotId)`
- **Method/Path**：`DELETE /api/v1/galleries/slots/{slotId}/asset`
- **参数**：`slotId`
- **调用位置**：
  - `pages/exhibition/exhibition.vue` -> `confirmRemoveAsset`
- **响应解析**：`response.code === 200` 后刷新展馆槽位。
- **用途**：下架槽位中的藏品。

---

### 2.6 OSS（上传签名 / 预签名读取 / 头像更新）

#### `getOssSignatureApi(type)`
- **Method/Path**：`GET /api/v1/assets/oss/signature?type={type}`
- **参数**：`type`（实际使用：`avatar`、`asset`）
- **调用位置**：
  - `pages/profile/profile.vue` -> `uploadAvatarToOss`（`type='avatar'`）
  - `pages/components/CastloveContent.vue` -> `uploadImageToOss`（`type='asset'`）
- **响应解析**：
  - 头像上传与素材上传都会读取：
    - `host`, `dir`, `policy`, `x_oss_credential`, `x_oss_date`, `security_token`, `signature`, `x_oss_signature_version`。
  - `type=asset` 时额外读取 `signRes.data.order_id`（铸造订单草稿 ID）。
- **用途**：向 OSS 直传前获取签名凭证。

#### `getOssPresignedUrlApi(fileName, expires = 3600, type = 'avatar')`
- **Method/Path**：`GET /api/v1/assets/oss/presigned-url?file_name={encodeURIComponent(fileName)}&expires={expires}&type={type}`
- **参数**：文件名/路径、有效期、类型
- **调用位置**：
  - `store/modules/user.js` -> `actions.login`、`actions.register`
  - `pages/profile/profile.vue` -> `handleAvatarUpdateSuccess`
  - `pages/components/Avatar.vue` -> `fetchOwnAvatarWithCache`
  - `utils/assetImageHelper.js` -> `getAssetCoverRealUrl`、`getFriendAvatarRealUrl`
- **响应解析**：通用读取 `res.data.url`；失败时回退默认图或空值。
- **用途**：将 OSS 对象标识转换为可读 URL（头像、藏品封面）。

#### `updateAvatarApi(avatarUrl)`
- **Method/Path**：`PUT /api/v1/me/avatar`
- **参数**：`{ avatar_url }`
- **调用位置**：
  - `pages/profile/profile.vue` -> `uploadAvatarToOss`（OSS 上传成功后）
- **响应解析**：`updateRes.code === 200` 后更新本地 user 缓存、触发 `avatarUpdated` 事件并刷新组件。
- **用途**：头像上传成功后回写用户头像地址。

---

### 2.7 铸造（Castlove）

#### `createMintOrderApi(orderData)`
- **Method/Path**：`POST /api/v1/assets/mints`
- **参数**：`orderData`（页面构造字段）
  - `name`, `event`, `description`, `material_type`, `material_url`, `rarity`, `tags`, `order_id`
- **调用位置**：
  - `pages/components/CastloveContent.vue` -> `handleConfirm`
- **响应解析**：`response.code === 200` 后视为铸造成功，保存临时展示数据并跳转成功页。
- **用途**：提交铸造订单。

#### `deleteMintOrderApi(orderId)`
- **Method/Path**：`DELETE /api/v1/assets/mints/{orderId}`
- **参数**：`orderId`
- **调用位置**：
  - `pages/components/CastloveContent.vue` -> `handleBack`（用户确认返回时清理未完成订单）
- **响应解析**：仅调用，不依赖返回体字段（失败仅记录日志，不阻断返回流程）。
- **用途**：清理中断铸造产生的草稿订单。

---

## 3. 非封装直连网络调用（不经过 `request()`）

### `uni.uploadFile`（OSS 直传）
- **位置**：
  - `pages/profile/profile.vue` -> `uploadAvatarToOss`
  - `pages/components/CastloveContent.vue` -> `uploadImageToOss`
- **前置**：先调 `getOssSignatureApi` 获取签名字段。
- **成功判定**：`uploadRes.statusCode === 200 || 204`。
- **后续动作**：
  - 头像上传：调用 `updateAvatarApi` 回写业务系统头像地址。
  - 藏品素材上传：生成 `uploadedImageUrl`，用于 `createMintOrderApi`。
- **说明**：不走 `request()`，因此不受其统一鉴权/错误码分流逻辑约束。

### `uni.downloadFile`（头像文件缓存）
- **位置**：
  - `utils/avatarCache.js` -> `downloadAndCacheAvatar`
- **调用链**：`getOssPresignedUrlApi -> downloadAndCacheAvatar(avatarUrl, realUrl) -> uni.downloadFile`
- **成功判定**：`res.statusCode === 200`
- **用途**：将头像下载到本地并 `saveFile`，提升后续展示性能与稳定性。

---

## 4. 调用覆盖与观察

- `utils/api.js` 共导出 **31** 个 API 函数。
- 其中 **30 个已在源码业务层使用**，`updateUserInfoApi` 当前未发现调用。
- 响应处理范式基本统一：
  - 成功分支：`res.code === 200` + 按需读取 `res.data.*`
  - 失败分支：依赖 `throw Error(message)`，页面显示 `error.message`。