# My Page Overview API

本文定义 App 底部 `我的` 页首屏聚合接口。该接口只返回首屏渲染需要的轻量摘要：用户资料、我的邀请码、核心资产余额、身份开关、消息红点和入口显隐。流水、成员列表、背包完整列表、工资明细、邀请列表和团队统计必须放到二级页接口。

## Goals

- `我的` 页首屏一次请求拿到稳定摘要，减少 App 冷启动后的接口数量。
- 聚合已有轻量能力：`/users/me`、`/wallet/me/balances`、`/users/me/host-identity`、`/messages/tabs`。
- 避免实时 `COUNT(*)`、扫流水、扫成员、扫背包、现算工资。
- 后端控制入口显隐，App 不硬编码复杂身份组合。
- 所有数据按 `app_code` 和当前 JWT `user_id` 隔离。

## 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": {},
    "wallet": {},
    "invite": {},
    "roles": {},
    "badges": {},
    "entries": [],
    "server_time_ms": 1777996800000
  }
}
```

## Response Shape

```json
{
  "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",
    "gender": "female",
    "birth": "2000-01-01",
    "country": "US",
    "country_id": 1,
    "country_name": "United States",
    "country_display_name": "United States",
    "region_id": 10,
    "region_code": "north_america",
    "region_name": "North America",
    "language": "en",
    "profile_completed": true,
    "onboarding_status": "completed"
  },
  "wallet": {
    "balances": [
      {
        "asset_type": "COIN",
        "available_amount": 12000,
        "frozen_amount": 0,
        "version": 8
      },
      {
        "asset_type": "DIAMOND",
        "available_amount": 300,
        "frozen_amount": 0,
        "version": 3
      },
      {
        "asset_type": "USD_BALANCE",
        "available_amount": 2500,
        "frozen_amount": 500,
        "version": 2
      }
    ],
    "recharge_enabled": true,
    "diamond_exchange_enabled": true,
    "withdraw_enabled": true
  },
  "invite": {
    "my_invite_code": "A1B2C3",
    "invite_enabled": true,
    "invite_count": 12,
    "valid_invite_count": 3,
    "valid_invite_threshold_coin": 80000
  },
  "roles": {
    "is_host": true,
    "is_agent": false,
    "is_bd": false,
    "is_bd_leader": false,
    "is_coin_seller": false
  },
  "badges": {
    "unread_system_messages": 2,
    "unread_activity_messages": 1,
    "pending_role_invitations": 0
  },
  "entries": [
    {
      "key": "wallet",
      "title": "Wallet",
      "visible": true,
      "badge_count": 0
    },
    {
      "key": "host_center",
      "title": "Host Center",
      "visible": true,
      "badge_count": 0
    },
    {
      "key": "coin_seller_center",
      "title": "Coin Seller",
      "visible": false,
      "badge_count": 0
    },
    {
      "key": "backpack",
      "title": "Backpack",
      "visible": true,
      "badge_count": 0
    },
    {
      "key": "settings",
      "title": "Settings",
      "visible": true,
      "badge_count": 0
    }
  ],
  "server_time_ms": 1777996800000
}
```

## Field Sources

| Field | Source | Query Pattern |
| --- | --- | --- |
| `profile` | `user-service.GetUser` | single row by `(app_code, user_id)` |
| `wallet.balances` | `wallet-service.GetBalances` | point read for `COIN`、`DIAMOND`、`USD_BALANCE` |
| `invite.my_invite_code` | `user-service` invite code module | point read active primary code by `(app_code, user_id)` |
| `invite.invite_count` | invite read model | users that successfully filled this invite code; without read model return `0` or omit |
| `invite.valid_invite_count` | invite read model | invited users whose cumulative eligible recharge reaches the configured threshold |
| `invite.valid_invite_threshold_coin` | invite validity policy | current configured threshold, default `80000` `COIN` |
| `roles` | `user-service` host identity module | point read role facts or future role summary read model |
| `badges.unread_*` | message inbox owner | counter/read model, not message list scan |
| `entries` | gateway composition rules | computed from `roles` and feature flags |
| `server_time_ms` | gateway | current server clock |

当前实现已有 `/users/me`、`/wallet/me/balances`、`/users/me/host-identity`、`/messages/tabs`。`/users/me/overview` 可以先在 `gateway-service` 聚合这些能力；后续如果角色判断的三次 not-found RPC 变慢，再在 `user-service` 增加 `GetUserRoleSummary` 内部 RPC。

## Asset Rules

首屏只返回三类资产：

| Asset | Show Rule |
| --- | --- |
| `COIN` | 所有用户展示 |
| `DIAMOND` | 所有用户展示，但文案不能暗示可直接消费 |
| `USD_BALANCE` | 有余额、冻结金额、host/agent/bd/coin_seller 身份时展示 |

不要返回 `GIFT_POINT`。积分是后台工资/活动计算输入，不是普通用户钱包可直接操作资产。

## Entry Rules

入口显隐由后端返回，App 只负责渲染。

| Entry Key | Visible Rule |
| --- | --- |
| `wallet` | always true |
| `host_center` | `roles.is_host == true` |
| `apply_host` | `roles.is_host == false` |
| `agency_center` | `roles.is_agent == true` |
| `bd_center` | `roles.is_bd == true` |
| `bd_leader_center` | `roles.is_bd_leader == true` |
| `coin_seller_center` | `roles.is_coin_seller == true` |
| `backpack` | always true |
| `settings` | always true |
| `support` | always true |

同一个用户可能同时是 BD 和 host。不要用互斥枚举表达角色，必须使用 bool flags。

## Expensive Fields To Exclude

不要在 `overview` 中实时查询这些字段：

| Field | Reason | Replacement |
| --- | --- | --- |
| 邀请用户列表 | 需要分页，可能扫 `user_invite_relations` | 二级页 `GET /api/v1/invites/users` |
| 实时邀请人数 `COUNT(*)` | 高活跃邀请人会让首页变慢 | read model counter 或返回 `0` |
| 邀请奖励流水 | 属于钱包/活动明细 | 二级页分页 |

这些字段不要放进首屏 overview：

| Field | Reason | Replacement |
| --- | --- | --- |
| `period_mic_minutes` | 需要统计聚合，可能扫 stats | Host Center 二级页 |
| `period_gift_points` | 需要统计聚合，可能跨日汇总 | Host Center 二级页 |
| `estimated_earning_usd_minor` | 不能首屏现算工资 | 后台工资 read model 或收益页 |
| `agency_member_count` | 容易 `COUNT(*)` members | Agency Center 二级页或 summary table |
| `bd_host_count` | 团队规模统计昂贵 | BD Center 二级页或 summary table |
| `pending_withdrawals` | 扫提现/流水表 | wallet badge counter |
| `recharge_count` | 扫充值记录 | wallet 二级页 |
| `resource_count` | 扫背包权益表 | backpack 二级页 |
| `latest_transactions` | 扫交易流水 | wallet 二级页 |
| `inbox_items` | 扫消息列表 | messages 二级页 |

首屏接口禁止为了红点实时扫大表。需要红点就维护 counter/read model；没有 counter 时先不展示该红点。

## Performance Budget

目标：

- P95 backend latency: `< 120ms` in normal region deployment.
- Gateway fanout RPC count: max 4.
- No list scan.
- No transaction history query.
- No member `COUNT(*)`.
- No resource entitlement list.
- No salary calculation.

推荐并行 fanout：

```mermaid
sequenceDiagram
  participant C as Client
  participant G as gateway-service
  participant U as user-service
  participant W as wallet-service
  participant M as message inbox owner

  C->>G: GET /api/v1/users/me/overview
  par profile and roles
    G->>U: GetUser(user_id)
    G->>U: GetUserRoleSummary(user_id)
  and wallet
    G->>W: GetBalances(COIN, DIAMOND, USD_BALANCE)
  and badges
    G->>M: ListMessageTabs(user_id)
  end
  G->>G: compose entries and feature flags
  G-->>C: overview
```

MVP 可以复用已有 `GetHostProfile`、`GetBDProfile`、`GetCoinSellerProfile` 聚合角色；优化版应增加单个 `GetUserRoleSummary`，减少 not-found RPC 和错误映射成本。

## Degraded Responses

首屏接口可以部分降级，但必须清楚标记。

| Upstream Failure | Response Rule |
| --- | --- |
| `user-service.GetUser` fail | 整体失败，资料是首屏主数据 |
| `wallet-service.GetBalances` fail | 返回空 balances，并加 `wallet.unavailable=true` |
| role summary fail | 返回 all false，并加 `roles.unavailable=true`，不要误展示特权入口 |
| message tabs fail | unread 置 0，并加 `badges.unavailable=true` |

如果某个上游超时，gateway 不应无限等待。overview 是首屏接口，应该有比普通操作接口更短的聚合超时预算。

## HTTP Handler Shape

新增路由：

```go
mux.Handle(apiV1Prefix+"/users/me/overview", h.profileAPIHandler(jwtVerifier, h.getMyOverview))
```

handler 只做协议聚合：

1. 从 JWT context 取 `user_id` 和 `app_code`。
2. 并行请求 profile、balances、roles、message tabs。
3. 把资产补齐为固定三类，缺失资产返回 0。
4. 根据 roles 和 feature flags 生成 entries。
5. 返回 envelope data。

不要在 gateway 写 SQL，也不要在 gateway 做工资、成员、资源统计。

## Verification Matrix

| Scenario | Expected |
| --- | --- |
| 普通用户打开我的页 | 返回 profile、COIN/DIAMOND/USD_BALANCE、普通入口 |
| host 打开我的页 | `roles.is_host=true`，展示 `host_center` |
| BD Leader 打开我的页 | `is_bd=true` 且 `is_bd_leader=true`，展示 leader 入口 |
| 币商打开我的页 | `is_coin_seller=true`，展示 coin seller 入口 |
| 钱包没有账户行 | 三类资产都返回 0 投影 |
| 消息服务失败 | 我的页仍可展示，消息红点降级为 0 |
| 用户资料服务失败 | overview 整体失败 |
| 大量成员/流水存在 | overview 延迟不受影响，因为不查成员和流水 |

## Implementation Order

1. 新增本文档，确认字段边界和慢查询排除规则。
2. 在 `gateway-service` 增加 `GET /api/v1/users/me/overview` handler。
3. 复用现有 `GetUser`、`GetBalances`、`GetHostProfile/GetBDProfile/GetCoinSellerProfile`、`ListMessageTabs`。
4. 增加 handler 单元测试，覆盖普通用户、host、BD Leader、币商、钱包缺失、消息降级。
5. 如果角色 RPC 成本偏高，再在 `user-service` 增加 `GetUserRoleSummary`。
6. 如果红点需要更多类型，先补 counter/read model，再把 badge 加进 overview。

## Critical Rules

- `我的` 页 overview 是轻聚合接口，不是用户全量详情接口。
- 首屏不做 `COUNT(*)`、不扫流水、不扫成员、不查完整背包、不现算工资。
- 钱包余额以 `wallet-service` 为准。
- 用户资料以 `user-service` 为准。
- 角色入口以服务端返回的 `roles` 和 `entries` 为准。
- 消息红点以 message inbox counter/read model 为准，用户私聊未读仍以腾讯云 IM SDK 为准。