188 lines
6.3 KiB
Markdown
188 lines
6.3 KiB
Markdown
# 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 |
|