156 lines
4.3 KiB
Markdown
156 lines
4.3 KiB
Markdown
# 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")` 等调用即可。
|