WangDL
a96d6cb159
- 移除 3 处强制深色模式，用 @AppStorage 全局切换 - 设置页「外观」按钮实时切换深色/浅色/跟随系统 - 底部导航栏 inactive 颜色改为自适应 Color.zxF03 - 12 个子页面修复：保留返回按钮 + 消除顶部空白 - 新增 LearningSessionView/ReviewCardView/ActiveRecallView - 新增 NotificationListView/SettingsView 等子页面 - 补全所有按钮 NavigationLink 跳转（0 个空白 action） - KnowledgeBase 模型对齐服务器数据 - Info.plist 补充 CFBundleIdentifier + ATS - 新增缺口分析文档 gap-analysis-1/2.md
9.8 KiB
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