startup-plan/技术设计/ios-projects/已完成/[已完成]-差距分析.md

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