# VIP 首页 API 字段映射建议

后端默认：`api.hackrobot.cn`。以下为 Mock 数据与真实 API 的字段映射建议，便于后续接入。

---

## 1. 资产统计 (ASSET_STATS)

**Mock 位置**: `app/data/vip.mock.ts` → `ASSET_STATS`

**建议接口**: `GET /vip/stats` 或 `GET /vip/dashboard/summary`

| 前端字段 | 建议 API 字段 | 说明 |
|----------|----------------|------|
| topics | `topics_count` / `topic_count` | 专题数量 |
| ebooks | `ebooks_count` | 电子书数量 |
| videos | `videos_count` | 视频数量 |
| templates | `templates_count` | 模板数量 |
| updateFrequency | `update_frequency` | 更新频率，如 "每周" |

**响应示例**:
```json
{
  "topics_count": 4,
  "ebooks_count": 2,
  "videos_count": 12,
  "templates_count": 8,
  "update_frequency": "每周"
}
```

---

## 2. 专题入口 (TOPICS)

**Mock 位置**: `app/data/vip.mock.ts` → `TOPICS`

**建议接口**: `GET /vip/topics` 或复用现有内容路由配置

| 前端字段 | 建议 API 字段 | 说明 |
|----------|----------------|------|
| id | `id` | 专题唯一标识 |
| icon | `icon` / `emoji` | 图标或 emoji |
| title | `title` | 标题 |
| desc | `description` / `desc` | 描述 |
| href | `href` / `url` / `path` | 链接，null 表示未开放 |

---

## 3. 权益对比 (COMPARE_ITEMS)

**Mock 位置**: `app/data/vip.mock.ts` → `COMPARE_ITEMS`

**建议**: 可配置化，接口 `GET /vip/compare` 或静态配置

| 前端字段 | 建议 API 字段 |
|----------|----------------|
| feature | `feature` |
| single | `single_label` |
| member | `member_label` |

---

## 4. 最近更新 (RECENT_UPDATES) - 已登录

**Mock 位置**: `app/data/vip.mock.ts` → `RECENT_UPDATES`

**建议接口**: `GET /vip/recent-updates` 或 `GET /vip/dashboard/recent`

| 前端字段 | 建议 API 字段 | 说明 |
|----------|----------------|------|
| id | `id` | 记录 ID |
| title | `title` | 更新标题 |
| date | `updated_at` / `date` | 日期，建议 ISO 或 "MM月DD日" |
| href | `href` / `url` | 跳转链接 |

**需鉴权**: 需携带 `user_id` 或 session/cookie

---

## 5. 社区精选 (COMMUNITY_HIGHLIGHTS) - 已登录

**Mock 位置**: `app/data/vip.mock.ts` → `COMMUNITY_HIGHLIGHTS`

**建议接口**: `GET /vip/community/highlights`

| 前端字段 | 建议 API 字段 |
|----------|----------------|
| id | `id` |
| text | `text` / `title` |
| href | `href` / `url` |

---

## 6. 本周推荐 (WEEKLY_ACTIONS) - 已登录

**Mock 位置**: `app/data/vip.mock.ts` → `WEEKLY_ACTIONS`

**建议接口**: `GET /vip/weekly-actions` 或 `GET /vip/dashboard/actions`

| 前端字段 | 建议 API 字段 | 说明 |
|----------|----------------|------|
| id | `id` | 动作 ID |
| text | `text` / `title` | 动作描述 |
| href | `href` / `url` | 跳转链接 |
| priority | `priority` / `order` | 优先级/排序 |

---

## 7. 继续学习 (ContinueLearning)

**当前实现**: 使用 `app/cloudphone/lib/learning.ts` 的 `getLastWatched()` + `getProgress()`，数据来自 localStorage。

**建议接口**: `GET /vip/learning/progress`（若后端统一管理学习进度）

| 前端使用 | 建议 API 字段 |
|----------|----------------|
| last.moduleIndex | `last_module_index` |
| last.lessonIndex | `last_lesson_index` |
| progress.completed | `completed_count` |
| progress.percent | `progress_percent` |

**鉴权**: 需 `user_id` 或 session

---

## 8. 登录/会员验证

**当前实现**: PocketBase `payments` 集合，按 `user_id` 查询最新支付记录。

**兼容 future shared cookie/session**:
- 建议后端提供 `GET /vip/me` 或 `GET /auth/me`，通过 Cookie/Session 返回当前用户及会员状态
- 响应字段建议: `user_id`, `user_name`, `is_vip`, `vip_expires_at` 等
- 前端可优先调用此接口，失败时回退到 localStorage + PocketBase 校验

---

## 9. 统一请求封装建议

在 `app/lib/` 下新增 `api.ts`:

```ts
const API_BASE = process.env.NEXT_PUBLIC_API_URL || "https://api.hackrobot.cn";

export async function fetchVip<T>(path: string, options?: RequestInit): Promise<T> {
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    credentials: "include", // 携带 cookie，兼容 future session
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}
```

后续将各 Mock 数据替换为 `fetchVip("/vip/stats")` 等调用即可。