's'

2026-03-11 23:47:45 -05:00
parent 296d703307
commit 0c2ccadb6b
35 changed files with 2399 additions and 195 deletions
--- a/docs/API_FIELD_MAPPING.md
+++ b/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")` 等调用即可。
--- a/docs/VIP_HOMEPAGE_IA.md
+++ b/docs/VIP_HOMEPAGE_IA.md
@@ -0,0 +1,112 @@
+# VIP 首页信息架构 (vip.hackrobot.cn)
+
+## 一、页面信息架构
+
+### 1. 路由结构（保持现有）
+
+| 路径 | 说明 |
+|------|------|
+| `/` | 首页（根据登录态切换 A/B 两种视图） |
+| `/paid` | 支付结果页（不变） |
+| `/ebook` | 电子书（不变） |
+| `/cloudphone/*` | 云手机课程（不变） |
+
+### 2. 首页双态逻辑
+
+```
+/ (首页)
+├── 未登录 / 非 VIP → 会员落地页 (Landing)
+└── 已登录 + VIP → 会员控制台 (Dashboard)
+```
+
+---
+
+## 二、未登录首页 - 会员落地页
+
+| 区块 | 内容 | 优先级 |
+|------|------|--------|
+| **Hero** | 异度星球会员中心 + 一句话价值主张 | P0 |
+| **数字资产统计** | 专题数、电子书数、视频数、模板数、更新频率 | P0 |
+| **四个核心专题入口** | 卡片式入口，链接到具体内容 | P0 |
+| **权益对比** | 单品 vs 会员 表格/卡片 | P0 |
+| **社区价值预览** | 社群、问答、沙龙等价值点 | P1 |
+| **FAQ** | 常见问题折叠 | P1 |
+| **CTA** | 立即加入 / 已有账号登录 | P0 |
+
+---
+
+## 三、已登录首页 - 会员控制台
+
+| 区块 | 内容 | 优先级 |
+|------|------|--------|
+| **欢迎区** | 用户名 + 简短问候 | P0 |
+| **已解锁统计** | 专题/电子书/视频/模板 数量 | P0 |
+| **最近更新** | 最新内容列表（3-5 条） | P0 |
+| **继续学习** | 上次学习进度 + 跳转 | P0 |
+| **四个专题卡片** | 与落地页一致，可点击进入 | P0 |
+| **社区精选** | 社群/问答精选 2-3 条 | P1 |
+| **本周任务/推荐动作** | 1-3 个推荐动作 | P1 |
+
+---
+
+## 四、与 digital / meetup 的区分
+
+| 站点 | 定位 | 首页气质 |
+|------|------|----------|
+| digital | 公开内容入口 + 单品销售 | 内容展示、购买转化 |
+| meetup | 城市/活动/连接/工具 | 活动列表、城市、工具 |
+| **vip** | 会员中心 + 全专题解锁 + 社区 + 持续更新 | **会员感、控制台感、资产感** |
+
+---
+
+## 五、组件树
+
+```
+Page (app/page.tsx)
+├── VipLayout (共享)
+│   ├── VipHeader
+│   │   ├── Logo
+│   │   ├── Nav (ThemeToggle, 登录/用户)
+│   │   └── [可选] UserMenu
+│   └── main
+│
+├── [未登录] LandingPage
+│   ├── LandingHero
+│   ├── AssetStats
+│   ├── TopicEntries (4 个专题)
+│   ├── CompareSection (单品 vs 会员)
+│   ├── CommunityPreview
+│   ├── FAQSection
+│   └── LandingCTA
+│
+└── [已登录] DashboardPage
+    ├── WelcomeBlock
+    ├── UnlockedStats
+    ├── RecentUpdates
+    ├── ContinueLearning
+    ├── TopicCards (4 个专题)
+    ├── CommunityHighlights
+    └── WeeklyActions
+```
+
+---
+
+## 六、组件职责
+
+| 组件 | 职责 |
+|------|------|
+| VipLayout | 深色主题容器、Header、主内容区 |
+| VipHeader | Logo、主题切换、登录/用户入口 |
+| LandingHero | 标题、价值主张 |
+| AssetStats | 大数字统计展示 |
+| TopicEntries / TopicCards | 专题入口，复用同一数据源 |
+| CompareSection | 权益对比表格 |
+| CommunityPreview | 社区价值简述 |
+| FAQSection | 折叠 FAQ |
+| LandingCTA | 加入会员 + 登录按钮 |
+| WelcomeBlock | 欢迎语 |
+| UnlockedStats | 已解锁数量 |
+| RecentUpdates | 最近更新列表 |
+| ContinueLearning | 学习进度 + 继续按钮 |
+| CommunityHighlights | 社区精选 |
+| WeeklyActions | 推荐动作 |