# My Page Overview API

本文定义 App 底部 `我的` 页首屏聚合接口。首屏只返回设计稿可直接展示的轻量摘要：基础资料、顶部计数、金币卡片、VIP 卡片、身份入口和固定功能入口。

## Endpoint

```http
GET /api/v1/users/me/overview
Authorization: Bearer <access_token>
```

响应使用 gateway `/api/v1` envelope：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_01",
  "data": {
    "profile": {
      "user_id": "10001",
      "display_user_id": "163000",
      "default_display_user_id": "163000",
      "display_user_id_kind": "default",
      "display_user_id_expires_at_ms": 0,
      "username": "Alice",
      "avatar": "https://cdn.example.com/avatar.png",
      "language": "en",
      "profile_completed": true,
      "onboarding_status": "completed"
    },
    "profile_stats": {
      "visitors_count": 12,
      "following_count": 34,
      "friends_count": 56,
      "updated_at_ms": 1777996800000
    },
    "wallet": {
      "coin_amount": 12000,
      "updated_at_ms": 1777996800000
    },
    "vip": {
      "level": 3,
      "name": "VIP3",
      "active": true,
      "started_at_ms": 1777392000000,
      "expires_at_ms": 1777996800000
    },
    "roles": {
      "is_host": true,
      "is_agency": false,
      "is_manager": false,
      "is_bd": false,
      "is_bd_leader": false,
      "is_coin_seller": false,
      "host_status": "active",
      "agency_id": 0,
      "bd_id": 0,
      "pending_role_invitations": 0
    },
    "entries": [
      {
        "key": "store",
        "visible": true,
        "enabled": true,
        "route": "/store",
        "icon_key": "store",
        "badge_count": 0,
        "order": 10
      },
      {
        "key": "apply_host",
        "visible": false,
        "enabled": false,
        "route": "/host/apply",
        "icon_key": "apply_host",
        "badge_count": 0,
        "order": 70
      },
      {
        "key": "host_center",
        "visible": true,
        "enabled": true,
        "route": "/host",
        "icon_key": "host_center",
        "badge_count": 0,
        "order": 80
      }
    ],
    "server_time_ms": 1777996800000
  }
}
```

## Field Sources

| Field | Source | Rule |
| --- | --- | --- |
| `profile` | `user-service.GetUser` | 只取头像、昵称、展示 ID、语言等基础资料 |
| `profile_stats` | `user-service.GetMyProfileStats` | 读 `user_profile_stats` 计数表，不实时扫访问、关注、好友大表 |
| `wallet` | `wallet-service.GetWalletValueSummary` | 首屏只返回金币余额，不返回钻石和美元余额 |
| `vip` | `wallet-service.GetMyVip` | 只取等级、名称、有效期和 active 状态 |
| `roles` | `user-service.GetUserRoleSummary` | 所有身份统一判断，避免 gateway 多 RPC fanout |
| `entries` | gateway composition | 根据 `roles` 生成入口显隐；标题由 App 按 key 做多语言 |
| `server_time_ms` | gateway | 当前服务端毫秒时间 |

`我的` 页首屏不调用 `ListMessageTabs`，不返回系统消息红点、活动消息红点、邀请码、钻石、美元余额，也不返回钱包操作开关。充值、提现、兑换能力在钱包二级页取。

## Entry Rules

| Entry Key | Visible Rule |
| --- | --- |
| `store` | always true |
| `bag` | always true |
| `level` | always true |
| `task` | always true |
| `apply_host` | `roles.is_host == false` |
| `host_center` | `roles.is_host == true` |
| `agency_center` | `roles.is_agency == true` |
| `manager_center` | `roles.is_manager == true` |
| `bd_center` | `roles.is_bd == true` |
| `bd_leader_center` | `roles.is_bd_leader == true` |
| `coin_seller_center` | `roles.is_coin_seller == true` |
| `settings` | always true |
| `language` | always true |

同一个用户可能同时拥有多个身份。角色必须用 bool flags 表达，不要用互斥枚举。

## Excluded From Overview

这些内容不能放进首屏接口：

| Field | Reason | Replacement |
| --- | --- | --- |
| 消息 tab、系统消息、活动消息 | 我的页设计稿不展示消息红点 | 消息 tab 页面接口 |
| 邀请码入口和邀请统计 | 截图首屏没有邀请码入口 | 邀请页或活动入口 |
| `wallet.recharge_enabled` / `withdraw_enabled` / `diamond_exchange_enabled` | 首屏卡片不需要操作开关 | `GET /api/v1/wallet/me/overview` |
| `DIAMOND` / `USD_BALANCE` | 首屏钱包卡片只展示金币 | 钱包二级页余额接口 |
| 邀请用户列表、钱包流水、工资明细、团队成员、背包完整列表、任务列表 | 都需要分页或聚合 | 对应二级页接口 |

## Performance Budget

- 聚合超时预算：`200ms`。
- 必须并行请求 profile、profile stats、wallet value summary、VIP、role summary。
- 允许 wallet、VIP、profile stats、role summary 降级并返回 `unavailable=true`。
- `user-service.GetUser` 失败时整体失败，因为基础资料是首屏主数据。
- 首屏不得实时 `COUNT(*)`、不得扫流水、不得扫成员、不得查完整背包、不得现算工资。

```mermaid
sequenceDiagram
  participant C as Client
  participant G as gateway-service
  participant U as user-service
  participant W as wallet-service

  C->>G: GET /api/v1/users/me/overview
  par profile
    G->>U: GetUser(user_id)
  and stats
    G->>U: GetMyProfileStats(user_id)
  and roles
    G->>U: GetUserRoleSummary(user_id)
  and wallet
    G->>W: GetWalletValueSummary(user_id)
    G->>W: GetMyVip(user_id)
  end
  G->>G: compose entries
  G-->>C: overview
```

## Secondary Endpoints

| Endpoint | Purpose |
| --- | --- |
| `GET /api/v1/users/me/visitors` | 访问记录列表 |
| `GET /api/v1/users/me/following` | 关注列表 |
| `GET /api/v1/users/me/friends` | 好友列表 |
| `GET /api/v1/users/me/friend-requests` | 好友申请列表 |
| `GET /api/v1/users/me/role-summary` | 单独刷新身份摘要 |
| `GET /api/v1/wallet/me/overview` | 钱包二级页余额和操作开关 |
| `GET /api/v1/wallet/recharge/products` | 当前区域充值渠道和档位 |
| `GET /api/v1/wallet/diamond-exchange/config` | 钻石兑换金币/余额配置 |
| `POST /api/v1/wallet/withdrawals/apply` | 创建待审核提现申请并冻结 `USD_BALANCE` |
| `GET /api/v1/wallet/transactions` | 钱包流水分页 |
| `GET /api/v1/vip/me` | 当前 VIP 状态 |
| `GET /api/v1/vip/packages` | 可购买 VIP 包 |
| `POST /api/v1/vip/purchase` | 购买、续期或升级 VIP |