268 lines
7.5 KiB
Markdown
268 lines
7.5 KiB
Markdown
# BMTR 资产接入实现文档
|
||
|
||
## 一、需求概述
|
||
|
||
在首页「我的资产」区域新增 **BMTR** 卡片，展示当前登录用户的 BMTR 数量。
|
||
|
||
数据来源：
|
||
|
||
```
|
||
GET /api/mxj/api/get_user
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"status": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"uid": 94227,
|
||
"nickname": "siediyer",
|
||
"avatar": "https://thirdwx.qlogo.cn/...",
|
||
"mxj_points": "99999.00",
|
||
"bmtr": "11.0000",
|
||
"is_check": 1,
|
||
"is_idcard": 1,
|
||
"is_sign": 1,
|
||
"sign_time": 1781172245,
|
||
"status": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 二、API 请求运行方式
|
||
|
||
项目中的网络请求采用三层结构：
|
||
|
||
```
|
||
页面 (pages/index/index.vue)
|
||
↓ 调用
|
||
api/assets.js 中的业务方法
|
||
↓ 调用
|
||
utils/request.js 中的通用 request 方法
|
||
↓ 调用
|
||
uni.request 发送 HTTP 请求
|
||
```
|
||
|
||
### 2.1 配置层：`config/service.js`
|
||
|
||
定义了接口基础地址和 endpoint 映射表。
|
||
|
||
### 2.2 通用请求层：`utils/request.js`
|
||
|
||
- 自动拼接 `BASE_URL` 和 `url`
|
||
- 统一注入 `Authori-zation` / `Authorization` Token
|
||
- 统一处理 `showLoading` / `hideLoading`
|
||
- 对响应进行 `statusCode` 校验，返回 `response.data`
|
||
|
||
### 2.3 业务 API 层：`api/assets.js`
|
||
|
||
- 封装 `fetchPayload` 统一处理 `{ status: 200, data: {...} }` 结构
|
||
- 提供 `createRequestOptions` 合并请求参数
|
||
- 提供 `buildHomeOverview` 将原始接口数据转换为页面渲染数据
|
||
|
||
---
|
||
|
||
## 三、本次改动文件
|
||
|
||
| 文件 | 改动内容 |
|
||
| ----------------------- | ------------------------------------------------------------------ |
|
||
| `config/service.js` | 新增 `getUser` endpoint |
|
||
| `api/assets.js` | 新增 `fetchUserData`，修改 `buildHomeOverview` 和 `fetchAssetHome` |
|
||
| `pages/index/index.vue` | 新增 BMTR 图标、背景、点击跳转 |
|
||
| `BMTR.MD` | 本文档 |
|
||
|
||
---
|
||
|
||
## 四、具体改动
|
||
|
||
### 4.1 `config/service.js`
|
||
|
||
在 `ENDPOINTS` 中新增：
|
||
|
||
```javascript
|
||
getUser: "/api/mxj/api/get_user",
|
||
```
|
||
|
||
### 4.2 `api/assets.js`
|
||
|
||
#### 4.2.1 新增获取用户数据的函数
|
||
|
||
```javascript
|
||
async function fetchUserData(requestOptions) {
|
||
return fetchPayload(
|
||
createRequestOptions(
|
||
{
|
||
url: serviceConfig.ENDPOINTS.getUser,
|
||
},
|
||
requestOptions,
|
||
),
|
||
"用户信息加载失败",
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 4.2.2 修改 `buildHomeOverview`
|
||
|
||
函数签名从：
|
||
|
||
```javascript
|
||
function buildHomeOverview(balanceData, tickerData) {
|
||
```
|
||
|
||
改为：
|
||
|
||
```javascript
|
||
function buildHomeOverview(balanceData, tickerData, userData) {
|
||
```
|
||
|
||
在 `rawQuickAssets` 中新增 `bmtr`：
|
||
|
||
```javascript
|
||
const rawQuickAssets = {
|
||
balance: toRawDisplayValue(balanceData && balanceData.brokerage_price),
|
||
points: toRawDisplayValue(balanceData && balanceData.point),
|
||
voucher: toRawDisplayValue(balanceData && balanceData.coin),
|
||
coupon: toRawDisplayValue(balanceData && balanceData.diamond_balance),
|
||
power: toRawDisplayValue(balanceData && balanceData.c_power),
|
||
bmtr: toRawDisplayValue(userData && userData.bmtr),
|
||
};
|
||
```
|
||
|
||
在 `quickAssets` 数组中新增 BMTR 项：
|
||
|
||
```javascript
|
||
{
|
||
key: "bmtr",
|
||
title: "BMTR",
|
||
value: rawQuickAssets.bmtr,
|
||
accent: "orange",
|
||
},
|
||
```
|
||
|
||
> `value` 直接使用接口返回的 `bmtr` 字符串。
|
||
> `accent` 设为 `orange`，与页面已有的 `.asset-mini-card--orange` 样式类对应。
|
||
|
||
#### 4.2.3 修改 `fetchAssetHome`
|
||
|
||
原来是同时请求价格 + 余额，现在增加用户信息请求：
|
||
|
||
```javascript
|
||
export async function fetchAssetHome(requestOptions) {
|
||
const result = await Promise.all([
|
||
fetchPriceData(requestOptions),
|
||
fetchHomeBalanceData(requestOptions),
|
||
fetchUserData(requestOptions),
|
||
]);
|
||
const overview = buildHomeOverview(result[1], result[0], result[2]);
|
||
setHomeTickerCache(overview.ticker);
|
||
return overview;
|
||
}
|
||
```
|
||
|
||
三个请求并行执行，BMTR 接口失败不会阻塞其他两个请求（但会进入 `Promise.all` 的 catch 逻辑，页面会显示错误提示）。
|
||
|
||
### 4.3 `pages/index/index.vue`
|
||
|
||
#### 4.3.1 新增图标
|
||
|
||
在 `quickAssetIcon` 的 `iconMap` 中新增：
|
||
|
||
```javascript
|
||
bmtr: "https://imgs.agrimedia.cn/bm-bmt/qianbao.png",
|
||
```
|
||
|
||
> 当前复用已有的钱包图标，后续可替换为 BMTR 专属图标。
|
||
|
||
#### 4.3.2 新增背景
|
||
|
||
在 `quickAssetBg` 的 `bgMap` 中新增：
|
||
|
||
```javascript
|
||
bmtr: "https://imgs.agrimedia.cn/bm-bmt/suanli-bg.png",
|
||
```
|
||
|
||
> 当前复用算力卡片背景，后续可替换为 BMTR 专属背景。
|
||
|
||
#### 4.3.3 新增点击跳转
|
||
|
||
在 `openQuickAsset` 的 `urlMap` 中新增：
|
||
|
||
```javascript
|
||
bmtr: "/pages/assets/bmtr",
|
||
```
|
||
|
||
用户点击 BMTR 卡片后，会跳转到 `pages/assets/bmtr.vue` 页面。
|
||
|
||
---
|
||
|
||
## 五、首页资产卡片渲染顺序
|
||
|
||
修改后，首页「我的资产」区域共 6 个卡片，顺序如下：
|
||
|
||
1. 可用积分
|
||
2. 算力
|
||
3. 消费券
|
||
4. 抵用券
|
||
5. **BMTR（新增）**
|
||
6. 余额
|
||
|
||
> 由于 `balance` 卡片设置了 `grid-column: 1 / -1`，会单独占一行，所以实际布局为：
|
||
>
|
||
> - 第一行：可用积分、算力
|
||
> - 第二行：消费券、抵用券
|
||
> - 第三行：BMTR
|
||
> - 第四行：余额（整行）
|
||
|
||
如果希望调整 BMTR 的位置，修改 `api/assets.js` 中 `quickAssets` 数组的顺序即可。
|
||
|
||
---
|
||
|
||
## 六、待替换项
|
||
|
||
| 项目 | 当前值 | 说明 |
|
||
| --------- | ------------------------------------------------------------ | ----------------------- |
|
||
| BMTR 图标 | `https://imgs.agrimedia.cn/webimg/202607171808386371853.svg` | BMTR 专属图标（已替换） |
|
||
| BMTR 背景 | `https://imgs.agrimedia.cn/webimg/202607201122331061368.svg` | BMTR 专属背景（已替换） |
|
||
|
||
---
|
||
|
||
## 七、接口字段说明
|
||
|
||
| 字段 | 类型 | 用途 |
|
||
| ------------ | ------ | --------------------------- |
|
||
| `uid` | number | 用户ID |
|
||
| `nickname` | string | 用户昵称 |
|
||
| `avatar` | string | 头像URL |
|
||
| `mxj_points` | string | MXJ积分 |
|
||
| `bmtr` | string | **BMTR 余额，本次使用字段** |
|
||
| `is_check` | number | 是否通过某种校验 |
|
||
| `is_idcard` | number | 是否实名认证 |
|
||
| `is_sign` | number | 是否签到 |
|
||
| `sign_time` | number | 签到时间戳 |
|
||
| `status` | number | 用户状态 |
|
||
|
||
---
|
||
|
||
## 八、验证建议
|
||
|
||
1. 进入首页，确认「我的资产」区域出现 BMTR 卡片
|
||
2. 确认 BMTR 显示的数值与 `/api/mxj/api/get_user` 返回的 `data.bmtr` 一致
|
||
3. 点击 BMTR 卡片，确认能跳转到 `pages/assets/bmtr`
|
||
4. 检查网络面板，确认三个请求并行发送：
|
||
- `/api/hn/getPrice`
|
||
- `/api/hn/getAllBalance`
|
||
- `/api/mxj/api/get_user`
|
||
5. 如果 BMTR 接口失败，首页应显示错误提示，不影响其他资产卡片的数据逻辑（但 Promise.all 会统一报错，如需降级处理可改为单独 catch）
|
||
|
||
---
|
||
|
||
## 九、可能的后续优化
|
||
|
||
1. **接口降级**：如果 `/api/mxj/api/get_user` 不稳定，可将 `fetchUserData` 从 `Promise.all` 中拆出，单独 catch 并给 BMTR 一个默认值 `0`。
|
||
2. **数值格式化**：当前 `bmtr` 直接显示为字符串，如需统一显示为 `11.00` 或 `11.0000`，可在 `buildHomeOverview` 中使用 `toFixedNumber` 处理。
|
||
3. **图标替换**：拿到 BMTR 专属图标和背景后，更新 `pages/index/index.vue` 中的 `iconMap` 和 `bgMap`。
|