's'

docs/API_FIELD_MAPPING.md

@@ -0,0 +1,155 @@
+# 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")` 等调用即可。