436 lines
16 KiB
Markdown
436 lines
16 KiB
Markdown
# iOS 差距分析
|
||
|
||
---
|
||
|
||
## 第一轮分析
|
||
|
||
# AIStudyApp 现状与缺口分析 - 第一篇：现有资源盘点
|
||
|
||
> 生成日期：2026-05-11
|
||
> 后端地址：http://81.70.187.179:3001
|
||
|
||
---
|
||
|
||
## 一、项目文件结构
|
||
|
||
```
|
||
AIStudyApp/
|
||
├── AIStudyAppApp.swift # 应用入口，含 5 步 Onboarding 流程
|
||
├── ContentView.swift # 主 Tab 框架（5 个 Tab + 自定义底部栏）
|
||
│
|
||
├── Core/
|
||
│ ├── DesignSystem/DesignTokens.swift # 颜色/渐变/间距/字体全局设计令牌
|
||
│ ├── Models/APIModels.swift # 20+ DTO 数据模型
|
||
│ ├── Network/
|
||
│ │ ├── APIClient.swift # 通用 HTTP 客户端（actor, async/await）
|
||
│ │ ├── APIConfig.swift # baseURL 配置
|
||
│ │ └── APIError.swift # 错误枚举（网络/服务端/解码/认证）
|
||
│ └── Services/APIService.swift # 8 个服务类，15 个公开方法
|
||
│
|
||
├── Features/
|
||
│ ├── AI/
|
||
│ │ ├── AIHomeView.swift # AI 首页 + ZXQuickAction + ZXAIInteractionRow 组件
|
||
│ │ └── DailyThinkingPage.swift # 每日思考题 + RecallTestPage / WeakPointsPage /
|
||
│ │ # AIFeedbackPageView / AIChatPage 子页面
|
||
│ ├── Analysis/
|
||
│ │ └── AnalysisHomeView.swift # 学习分析页 + ZXChartView 折线图 + ZXWeakRow 薄弱点
|
||
│ ├── Library/
|
||
│ │ ├── LibraryHomeView.swift # 知识库列表首页
|
||
│ │ └── LibrarySubpages.swift # CreateLibraryPage / LibraryDetailPage /
|
||
│ │ # AddKnowledgePage / KnowledgeDetailPage /
|
||
│ │ # ImportPage / EditKnowledgePage
|
||
│ ├── Profile/
|
||
│ │ └── ProfileView.swift # 个人中心页
|
||
│ └── Study/
|
||
│ └── StudyHomeView.swift # 学习工作台 + 今日任务 + 周活跃柱状图
|
||
│
|
||
└── Info.plist # 手动管理（ATS例外 / Bundle元数据等）
|
||
```
|
||
|
||
---
|
||
|
||
## 二、5 个 Tab 页面清单
|
||
|
||
| Tab | 标签 | SF Symbol | View |
|
||
|-----|------|-----------|------|
|
||
| 1 | AI | `brain.head.profile` | AIHomeView |
|
||
| 2 | 知识库 | `books.vertical.fill` | LibraryHomeView |
|
||
| 3 | 学习 | `bolt.fill` | StudyHomeView |
|
||
| 4 | 分析 | `chart.bar.fill` | AnalysisHomeView |
|
||
| 5 | 我的 | `person.fill` | ProfileView |
|
||
|
||
---
|
||
|
||
## 三、所有页面/子页面总览（共 21 个）
|
||
|
||
### AI 模块（1 主 + 4 子）
|
||
|
||
| 页面 | 数据来源 | 核心功能 |
|
||
|------|---------|---------|
|
||
| AIHomeView | 🔴硬编码 | API 状态检测、思考题卡片、快捷操作、互动记录、提问输入栏 |
|
||
| DailyThinkingPage | 🔴硬编码 | AI 思考题展示 + 回答提交 |
|
||
| RecallTestPage | 🔴硬编码 | 回忆测试输入 |
|
||
| WeakPointsPage | 🔴硬编码 | 薄弱知识点静态列表 |
|
||
| AIFeedbackPageView | 🔴硬编码 | AI 反馈评分 + 操作入口 |
|
||
| AIChatPage | 🔴硬编码 | AI 对话气泡界面 |
|
||
|
||
### 知识库模块（1 主 + 6 子）
|
||
|
||
| 页面 | 数据来源 | 核心功能 |
|
||
|------|---------|---------|
|
||
| LibraryHomeView | 🔴硬编码 | 知识库列表 + 搜索框 + 创建入口 |
|
||
| CreateLibraryPage | 🔴静态 | 创建表单（名称+描述） |
|
||
| LibraryDetailPage | 🔴硬编码 | 知识点静态列表 |
|
||
| AddKnowledgePage | 🔴静态 | 添加知识点表单 |
|
||
| KnowledgeDetailPage | 🔴硬编码 | 知识点详情+标签+复习/费曼入口 |
|
||
| ImportPage | 🔴静态 | 导入方式选择（拍照/文件/链接/相册） |
|
||
| EditKnowledgePage | 🔴静态 | 编辑知识点表单 |
|
||
|
||
### 学习模块（1 主）
|
||
|
||
| 页面 | 数据来源 | 核心功能 |
|
||
|------|---------|---------|
|
||
| StudyHomeView | 🔴硬编码 | 今日进度环、任务列表（5个任务）、本周活跃柱状图 |
|
||
|
||
### 分析模块（1 主）
|
||
|
||
| 页面 | 数据来源 | 核心功能 |
|
||
|------|---------|---------|
|
||
| AnalysisHomeView | 🔴硬编码 | 4项统计徽章、掌握度7日折线图、薄弱知识点列表 |
|
||
|
||
### 个人中心（1 主）
|
||
|
||
| 页面 | 数据来源 | 核心功能 |
|
||
|------|---------|---------|
|
||
| ProfileView | 🔴硬编码 | 个人卡片、菜单列表、成就徽章 |
|
||
|
||
### 启动流程（5 步 Onboarding）
|
||
|
||
| 步骤 | 页面 | 功能 |
|
||
|------|------|------|
|
||
| Step 0 | SplashPage | 品牌开屏，2 秒自动跳转 |
|
||
| Step 1 | WelcomePage | 3 大功能介绍 |
|
||
| Step 2 | LoginPage | 手机号/邮箱 + 密码表单 + 微信/Apple 登录入口 |
|
||
| Step 3 | OnboardingPage | 4 步功能轮播 |
|
||
| Step 4 | GoalSetupPage | 学习目标/方法/每日时长选择 |
|
||
|
||
---
|
||
|
||
## 四、APIService 已封装方法（15 个）
|
||
|
||
| 服务类 | 方法 | 接口 |
|
||
|--------|------|------|
|
||
| WaitlistService | `join(...)` | POST /waitlist |
|
||
| | `stats()` | GET /waitlist/stats |
|
||
| AuthService | `appleLogin(...)` | POST /auth/apple |
|
||
| | `logout()` | POST /auth/logout |
|
||
| UserService | `myProfile()` | GET /users/me |
|
||
| | `updateProfile(...)` | PATCH /users/me |
|
||
| KnowledgeBaseService | `list()` | GET /knowledge-bases |
|
||
| | `create(...)` | POST /knowledge-bases |
|
||
| | `detail(id:)` | GET /knowledge-bases/:id |
|
||
| KnowledgeItemService | `list(baseId:)` | GET /knowledge-items |
|
||
| | `detail(id:)` | GET /knowledge-items/:id |
|
||
| | `create(...)` | POST /knowledge-items |
|
||
| AIAnalysisService | `analyze(...)` | POST /ai-analysis |
|
||
| ActivityService | `summary()` | GET /activity/summary |
|
||
| ReviewService | `due()` | GET /reviews/due |
|
||
| FocusItemService | `list()` | GET /focus-items |
|
||
| FeedbackService | `submit(...)` | POST /feedback |
|
||
|
||
---
|
||
|
||
## 五、后端接口 vs App 覆盖对照表
|
||
|
||
| 后端模块 | 接口数 | App 覆盖 | 状态 |
|
||
|----------|--------|---------|------|
|
||
| System | 3 | 0 | ❌ 无 |
|
||
| Auth | 3 | 2（Service 有，View 未接） | 🔶 |
|
||
| Users | 3 | 2（Service 有，View 未接） | 🔶 |
|
||
| KnowledgeBase | 5 | 3（Service 有，View 未接） | 🔶 |
|
||
| KnowledgeItems | 4 | 3（Service 有，View 未接） | 🔶 |
|
||
| DocumentImport | 2 | 0 | ❌ 无 |
|
||
| LearningSession | 3 | 0 | ❌ 无 |
|
||
| ActiveRecall | 2 | 0 | ❌ 无 |
|
||
| AIAnalysis | 3 | 1（Service 有，View 未接） | 🔶 |
|
||
| FocusItems | 4 | 1（Service 有，View 未接） | 🔶 |
|
||
| Review | 2 | 1（Service 有，View 未接） | 🔶 |
|
||
| LearningActivity | 2 | 1（Service 有，View 未接） | 🔶 |
|
||
| Notifications | 2 | 0 | ❌ 无 |
|
||
| Feedback | 4 | 1（Service 有，View 未接） | 🔶 |
|
||
| Waitlist | 3 | 2（Service 有，View 未接） | 🔶 |
|
||
|
||
> 覆盖率：Service 层 15/48 = 31%，View 层实际接入 0/48 = 0%
|
||
|
||
---
|
||
|
||
## 第二轮分析
|
||
|
||
# AIStudyApp 现状与缺口分析 - 第二篇：缺失功能与实施路线
|
||
|
||
> 接第一篇《现有资源盘点》
|
||
> 生成日期：2026-05-11
|
||
|
||
---
|
||
|
||
## 一、优先级总览
|
||
|
||
```
|
||
P0（核心闭环，本周必须） 4 项
|
||
P1（数据接入，下周） 5 项
|
||
P2（新页面/功能，后续） 5 项
|
||
P3（体验增强，优化期） 5 项
|
||
```
|
||
|
||
---
|
||
|
||
## 二、P0 —— 核心学习闭环（4 项）
|
||
|
||
### P0-1：真实 Apple 登录流程
|
||
|
||
**现状：** LoginPage 是静态表单，没有调 API，Token 没有持久化。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 |
|
||
|--------|---------|
|
||
| 集成 `AuthenticationServices`，添加 `ASAuthorizationAppleIDButton` | LoginPage（内嵌在 AIStudyAppApp.swift） |
|
||
| 拿到 `identityToken` 后调用 `AuthService.appleLogin(...)` | LoginPage |
|
||
| 登录成功后用 `@AppStorage` 或 Keychain 存储 Token | APIClient |
|
||
| `@main` 启动时检查已有 Token，跳过 Onboarding | AIStudyAppApp.swift |
|
||
| 处理登录失败/网络错误的 UI 提示 | LoginPage |
|
||
| 接入 `POST /auth/refresh` Token 自动刷新 | APIClient |
|
||
|
||
涉及接口：`POST /auth/apple`、`POST /auth/refresh`、`POST /auth/logout`
|
||
|
||
---
|
||
|
||
### P0-2：知识库 + 知识点接入真实 API
|
||
|
||
**现状：** LibraryHomeView 硬编码 4 个知识库，子页面表单没有提交。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 |
|
||
|--------|---------|
|
||
| `LibraryHomeView` 的 `.task {}` 中调 `KnowledgeBaseService.list()` | LibraryHomeView.swift |
|
||
| 替换硬编码卡片为 `ForEach(bases)` 真实数据 | LibraryHomeView.swift |
|
||
| `CreateLibraryPage` 表单提交调 `KnowledgeBaseService.create(...)` | LibrarySubpages.swift |
|
||
| `LibraryDetailPage` 加载真实知识点列表 `KnowledgeItemService.list(baseId:)` | LibrarySubpages.swift |
|
||
| `AddKnowledgePage` 表单提交调 `KnowledgeItemService.create(...)` | LibrarySubpages.swift |
|
||
| `EditKnowledgePage` 提交调 `PATCH /knowledge-items/:id`（APIService 需新增 update 方法） | LibrarySubpages.swift + APIService.swift |
|
||
| 增加 loading / empty / error 三种状态处理 | 各 Library 页面 |
|
||
|
||
涉及接口：`GET/POST /knowledge-bases`、`GET/POST/PATCH /knowledge-items`
|
||
|
||
---
|
||
|
||
### P0-3：学习会话追踪
|
||
|
||
**现状：** StudyHomeView 的"今日任务"是静态列表，没有学习计时，没有调任何接口。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 / 新建文件 |
|
||
|--------|-------------------|
|
||
| 新建 `LearningSessionView.swift`：含计时器（`Timer.publish`）+ 暂停/结束按钮 | **新文件** Features/Study/LearningSessionView.swift |
|
||
| 点击 StudyHomeView 任务 → push 到 LearningSessionView | StudyHomeView.swift |
|
||
| 入场调 `POST /learning-sessions`（传入 knowledgeBaseId） | LearningSessionView.swift |
|
||
| 结束/暂停时调 `POST /learning-sessions/:id/end` | LearningSessionView.swift |
|
||
| APIService 新增 `LearningSessionService` | APIService.swift |
|
||
| APIModels 新增 `LearningSessionCreateRequest` / `LearningSessionResponse` | APIModels.swift |
|
||
|
||
涉及接口：`POST /learning-sessions`、`POST /learning-sessions/:id/end`、`GET /learning-sessions`
|
||
|
||
---
|
||
|
||
### P0-4：间隔复习卡片
|
||
|
||
**现状：** 没有复习页面。后端 `GET /reviews/due` + `POST /reviews/:id/submit` 已就绪。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 新建文件 |
|
||
|--------|---------|
|
||
| 新建 `ReviewCardView.swift`：正面问题 → 点击翻转 → 显示答案 → 评分按钮 | **新文件** Features/Study/ReviewCardView.swift |
|
||
| 评分按钮：Again(1) / Hard(2) / Good(3) / Easy(4)，调 `POST /reviews/:id/submit` | ReviewCardView.swift |
|
||
| 复习入口放在 StudyHomeView "今日任务"区域顶部 | StudyHomeView.swift |
|
||
| 复习入口放在 AIHomeView 快捷操作中 | AIHomeView.swift |
|
||
| 到期卡片数为 0 时显示空状态"🎉 都复习完啦" | ReviewCardView.swift |
|
||
|
||
涉及接口：`GET /reviews/due`、`POST /reviews/:id/submit`
|
||
|
||
---
|
||
|
||
## 三、P1 —— 数据接入（5 项）
|
||
|
||
### P1-1：薄弱点 / AI 分析接真实数据
|
||
|
||
**现状：** AnalysisHomeView / WeakPointsPage 硬编码 3 条数据。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 |
|
||
|--------|---------|
|
||
| AnalysisHomeView `.task {}` 中调 `FocusItemService.list()` | AnalysisHomeView.swift |
|
||
| 替换硬编码 ZXWeakRow 为 `ForEach(focusItems)` | AnalysisHomeView.swift |
|
||
| RecallTestPage 提交回答时调 `AIAnalysisService.analyze(...)` | DailyThinkingPage.swift |
|
||
| AIFeedbackPageView 展示真实分析结果 | DailyThinkingPage.swift |
|
||
| APIModels 增补 FocusItem 字段对齐后端 | APIModels.swift |
|
||
|
||
涉及接口：`GET /focus-items`、`POST /ai-analysis`、`GET /ai-analysis/:id`
|
||
|
||
---
|
||
|
||
### P1-2：StudyHomeView 数据真实化
|
||
|
||
**现状：** 进度环、任务列表、周活跃柱状图全是硬编码。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 |
|
||
|--------|---------|
|
||
| 调 `ActivityService.summary()` 获取真实统计数据 | StudyHomeView.swift |
|
||
| 进度环用真实 `totalMinutes` / `streakDays` | StudyHomeView.swift |
|
||
| 周活跃图调 `GET /activity/heatmap`（APIService 需新增 heatmap 方法） | StudyHomeView.swift + APIService.swift |
|
||
| 今日任务从 `GET /reviews/due` + `GET /focus-items` 拼接 | StudyHomeView.swift |
|
||
|
||
涉及接口：`GET /activity/summary`、`GET /activity/heatmap`
|
||
|
||
---
|
||
|
||
### P1-3：ProfileView 接入用户资料
|
||
|
||
**现状：** ProfileView 全部静态假数据（昵称"学习者"、假统计）。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 |
|
||
|--------|---------|
|
||
| `.task {}` 调 `UserService.myProfile()` | ProfileView.swift |
|
||
| 替换头像（emoji → 真实 avatar URL / 默认头像） | ProfileView.swift |
|
||
| 替换昵称、邮箱、统计数字 | ProfileView.swift |
|
||
| 菜单项"学习目标设置"跳设置表单页 → `PATCH /users/me/preferences` | ProfileView.swift + 新 SettingsView |
|
||
|
||
涉及接口：`GET /users/me`、`PATCH /users/me`、`PATCH /users/me/preferences`
|
||
|
||
---
|
||
|
||
### P1-4：通知中心页面
|
||
|
||
**现状：** 完全没有通知页面。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 新建/涉及文件 |
|
||
|--------|-------------|
|
||
| 新建 `NotificationListView.swift` | **新文件** Features/Profile/NotificationListView.swift |
|
||
| `.task {}` 调 `GET /notifications` | NotificationListView.swift |
|
||
| 列表项点击标记已读 `POST /notifications/:id/read` | NotificationListView.swift |
|
||
| ProfileView 右上角铃铛 badge 显示未读数 | ProfileView.swift |
|
||
| APIService 新增 `NotificationService` | APIService.swift |
|
||
|
||
涉及接口：`GET /notifications`、`POST /notifications/:id/read`
|
||
|
||
---
|
||
|
||
### P1-5：反馈提交
|
||
|
||
**现状：** 没有反馈提交入口。
|
||
|
||
**需要做：**
|
||
|
||
| 子任务 | 涉及文件 |
|
||
|--------|---------|
|
||
| ProfileView 菜单加"帮助与反馈" → 跳反馈表单 | ProfileView.swift + 新 FeedbackView |
|
||
| 调 `FeedbackService.submit(...)` | 新 FeedbackView |
|
||
| 提交后显示"感谢反馈"提示 | 新 FeedbackView |
|
||
|
||
涉及接口：`POST /feedback`
|
||
|
||
---
|
||
|
||
## 四、P2 —— 新页面/功能（5 项）
|
||
|
||
### P2-1：文件导入真实接入
|
||
|
||
**现状：** ImportPage 只有 4 个静态按钮。
|
||
|
||
**需要做：** 接入 `PHPickerViewController`（相册选图）、`UIDocumentPickerViewController`（文件选择）、AVCaptureSession（拍照），上传后调 `POST /imports`，轮询 `GET /imports/:id/status`。APIService 新增 `DocumentImportService`。
|
||
|
||
---
|
||
|
||
### P2-2：全局搜索
|
||
|
||
**现状：** LibraryHomeView 有搜索框但无效。
|
||
|
||
**需要做：** 新建 `SearchView.swift`，调 `GET /knowledge-items?keyword=xxx`，支持搜索知识点/知识库/标签，展示搜索结果列表。
|
||
|
||
---
|
||
|
||
### P2-3：设置页面完善
|
||
|
||
**现状：** ProfileView 5 个菜单项全是假的。
|
||
|
||
**需要做：** 每个菜单项对应一个设置表单页：学习目标、复习提醒时间、学习报告邮件、学习方法偏好（费曼/回忆/间隔/综合）、数据同步状态。
|
||
|
||
---
|
||
|
||
### P2-4：主动回忆（Active Recall）流程
|
||
|
||
**现状：** RecallTestPage 只提交假的 AI 分析，没有调 `GET /active-recalls`。
|
||
|
||
**需要做：** 新建 ActiveRecallView，展示问题卡片 → 输入回答 → 调 `POST /active-recalls/:id/submit`。
|
||
|
||
---
|
||
|
||
### P2-5：Token 自动刷新与登录态管理
|
||
|
||
**现状：** Token 没有持久化，没有 refresh 逻辑。
|
||
|
||
**需要做：** Keychain 存储 accessToken + refreshToken；APIClient 拦截 401 → 自动调 `POST /auth/refresh` → 重试原请求；refresh 也失败 → 清 Token → 跳登录页。
|
||
|
||
---
|
||
|
||
## 五、P3 —— 体验增强（5 项）
|
||
|
||
| # | 项目 | 说明 |
|
||
|---|------|------|
|
||
| P3-1 | 下拉刷新 | 所有列表页 `.refreshable {}` + 页码分页 |
|
||
| P3-2 | 加载/空/错误三态 | 每个数据加载页加 ProgressView / 空状态插图+文案 / 错误重试按钮 |
|
||
| P3-3 | 离线缓存 | 用 UserDefaults 或本地 JSON 缓存最近数据，断网可展示 |
|
||
| P3-4 | 深色模式 | 当前强制 `.dark`，需支持跟随系统 |
|
||
| P3-5 | 无障碍 | VoiceOver labels、Dynamic Type 适配、高对比度 |
|
||
|
||
---
|
||
|
||
## 六、实施建议顺序
|
||
|
||
```
|
||
第 1 周 ─ P0-1 登录 → P0-2 知识库CRUD → P0-3 学习会话
|
||
第 2 周 ─ P0-4 复习卡片 → P1-1 薄弱点/AI分析 → P1-2 StudyHomeView 真实化
|
||
第 3 周 ─ P1-3 ProfileView → P1-4 通知中心 → P1-5 反馈
|
||
第 4 周 ─ P2-1 文件导入 → P2-2 搜索 → P2-3 设置页
|
||
第 5 周 ─ P2-4 主动回忆 → P2-5 Token刷新
|
||
第 6 周 ─ P3 体验增强
|
||
```
|
||
|
||
---
|
||
|
||
## 七、后端接口未封装清单（需新增 Service 方法）
|
||
|
||
| 模块 | 后端口 | 未封装接口 |
|
||
|------|--------|----------|
|
||
| KnowledgeBase | PATCH/DELETE | update / delete |
|
||
| KnowledgeItems | PATCH/DELETE | update / delete |
|
||
| LearningSession | POST/GET | start / end / list |
|
||
| ActiveRecall | GET/POST | list / submit |
|
||
| AIAnalysis | GET | result / job status |
|
||
| Activity | GET | heatmap |
|
||
| Notifications | GET/POST | list / markRead |
|
||
| DocumentImport | POST/GET | create / status |
|
||
| Review | POST | submit |
|
||
| FocusItems | POST/PATCH | create / update / complete |
|
||
|
||
> 需新增约 15 个 Service 方法 + 对应 Request/Response DTO
|