# 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`。