ios-projects/AIStudyApp/docs/缺失项与待补全方向.md

缺失项与待补全方向

基于 v0.1 创业计划文档与当前 iOS 代码对比分析 整理时间：2026-05-10

本文档系统性列出知习 iOS App 当前在架构、页面、功能、设计等方面的缺失项，并给出优先级建议。

---

一、架构层缺失

1.1 MVVM 分层

现状：全部代码写在 SwiftUI View 中，无任何 ViewModel/ObservableObject/@Published。grep 搜索 ViewModel、ObservableObject、@Published 均为零结果。

缺失：

• 无 ViewModel 层，业务逻辑、状态管理、数据转换全部堆在 View 里
• 无 Model 层，数据结构通过 View 内的局部 struct 或硬编码数据隐式定义
• 代码不可测试，无法单独验证业务逻辑

计划要求（官网与技术基础.md 第 5.3 节）：

AIStudyApp/
├── Features/
│   ├── Onboarding/
│   │   ├── Views/       ← 当前有，但无 ViewModel/Model 子目录
│   │   ├── ViewModels/  ← 缺失
│   │   └── Models/      ← 缺失

1.2 Service 层

现状：无任何 Service 类，AI 分析、学习记录、用户管理等概念没有对应的服务抽象。

缺失：

Service	职责	设计文档
AuthService	Apple 登录、Token 管理、会话维护	docs/AI对话.md（详细设计）
LearningService	学习记录 CRUD、进度追踪	—
AIService	AI 分析请求代理、结果解析	—
ReviewService	复习任务生成、调度	—
KnowledgeService	知识库/路径/课程查询	—
FeedbackService	用户反馈提交	—

Auth 模块已有详细文件清单（来自 docs/AI对话.md）：

Features/Auth/Views/LoginView.swift
Features/Auth/ViewModels/LoginViewModel.swift

Core/Services/AuthService.swift
Core/Services/AuthServiceProtocol.swift

Core/Storage/KeychainStore.swift
Core/Storage/TokenStore.swift

App/AppSession.swift

Core/Models/AuthModels.swift
Core/Models/User.swift

1.3 Repository 层

现状：零数据持久化，所有"数据"均为 View 中硬编码的 mock。

缺失：

• 无数据访问抽象（未来可能切换 CoreData → API，需要 Repository 隔离）
• 无本地缓存层
• 无网络数据源层

1.4 网络层

现状：无任何网络请求代码，无 APIClient，无 URLSession 调用。

缺失：

• APIClient（封装 URLSession，注入 baseURL、header、token）
• APIEndpoint（枚举化 API 路径，统一请求构建）
• APIError（统一错误模型和处理）
• 请求/响应拦截器（日志、token 刷新）
• Mock 层（本地开发和 UI 预览用）

1.5 依赖注入

现状：无任何 DI 模式，Service 和 ViewModel 尚未创建，暂时不存在注入问题。但需要在架构搭建时建立模式。

建议：初期使用构造函数注入 + @EnvironmentObject，避免引入第三方 DI 框架。

---

二、核心能力缺失

2.1 Sign in with Apple（已有详细设计文档）

现状：LoginPage 有 UI（手机号/邮箱/微信/Apple 入口），但 AIStudyAppApp 仅用 @AppStorage("hasCompletedOnboarding") 控制是否进入主界面，无实际认证。

计划要求：第一版登录方式仅为 Sign in with Apple（Demo与MVP.md 第 5.2 节）。

详细设计方案见 docs/AI对话.md，核心结论：

登录页只保留一个入口：

Sign in with Apple

删除的入口：手机号登录、邮箱登录、微信登录、验证码登录

"跳过"按钮处理：

#if DEBUG
Button("跳过，进入演示模式") { ... }
#endif

正式环境不展示跳过入口，避免后续匿名用户迁移问题。

登录流程设计：

App 启动
    ↓
AppSession 检查 Keychain 是否有 refreshToken
    ↓
有 token → 调用 /auth/refresh 或 /users/me
    ↓
成功 → 进入主界面
失败 → 清空 token，进入登录页
    ↓
无 token → 进入登录页
    ↓
用户点击 Sign in with Apple
    ↓
获取 identityToken / authorizationCode / userIdentifier
    ↓
POST /api/auth/apple
    ↓
后端返回 accessToken / refreshToken / user
    ↓
token 存入 Keychain（不要 UserDefaults）
    ↓
判断 user.onboardingCompleted
    ↓
未完成 → 引导/目标设置
已完成 → 主界面

登录相关新增文件：

Features/Auth/Views/LoginView.swift          # 仅 Apple 登录按钮
Features/Auth/ViewModels/LoginViewModel.swift # @MainActor, @Published isLoading/errorMessage

Core/Services/AuthService.swift
Core/Services/AuthServiceProtocol.swift

Core/Storage/KeychainStore.swift
Core/Storage/TokenStore.swift

App/AppSession.swift                         # 全局登录状态管理

Core/Models/AuthModels.swift                 # AppleLoginRequest, AuthResponse
Core/Models/User.swift

API Contract（Auth）：

// 请求
struct AppleLoginRequest: Encodable {
    let identityToken: String
    let authorizationCode: String?
    let userIdentifier: String
    let fullName: AppleFullName?
    let email: String?
}

// 响应
struct AuthResponse: Decodable {
    let accessToken: String
    let refreshToken: String
    let expiresIn: Int
    let user: User
}

关键约束：

• 不再用 @AppStorage("hasCompletedOnboarding") 单独决定是否进入主界面
• 登录状态必须由 AppSession + Keychain token 决定
• Token 不存 UserDefaults
• View 里不写网络请求，不直接处理 Apple 登录细节

2.2 后端 API 对接

现状：所有页面为静态 UI，无任何网络请求。

计划定义的 P0 API：

• POST /ai/analyze-learning-input — AI 分析用户学习输入
• POST /ai/chat — AI 对话
• 用户/知识库/学习记录/反馈 CRUD

2.3 真实 AI 集成

现状：AI 相关页面全为静态文本。

需对接：

• 后端 AI Provider 抽象层（MiniMax/DeepSeek/OpenAI 等）
• 结构化 JSON 输出解析
• AI 分析结果展示（掌握度评分、优缺点、建议）
• AI 对话流式响应

2.4 本地数据持久化

现状：零持久化实现。

需实现：

• UserDefaults / @AppStorage（简单偏好）
• Keychain（Token、敏感信息）
• 后续可考虑 CoreData 或 SwiftData（学习记录离线缓存）

2.5 多语言本地化

现状：所有文案硬编码在 View 中，无 Localizable.xcstrings 文件。

计划要求（Demo与MVP.md 第 6 节）：

• 默认简体中文
• 预留英文
• App UI 文案使用本地化资源

需实现：

• 创建 Localizable.xcstrings
• 将所有硬编码文案迁移为 LocalizedStringKey
• 支持语言切换

2.6 错误/加载/空状态处理

现状：无任何错误处理、加载态、空状态 UI。

至少需要：

• 网络请求 loading 指示器
• 网络错误提示和重试按钮
• AI 分析中的等待状态
• 列表空状态（如知识库为空时的引导）
• 登录失败错误提示

---

三、页面层面差距

3.1 与计划页面对比

计划页面	计划优先级	当前状态	说明
启动页/欢迎页	P1	✅ 已实现	SplashPage + WelcomePage
登录页	P0	✅ 已实现	新 LoginView 替换旧 LoginPage，仅 Apple 登录
语言与偏好页	P1	❌ 未实现	无页面
学习方向选择页	P0	⚠️ 部分实现	GoalSetupPage 有目标选择，但非学习方向选择
学习路径页	P0	✅ 已实现	LibraryDetailPage
今日学习任务页	P0	✅ 已实现	StudyHomeView
内容阅读页	P0	✅ 已实现	KnowledgeDetailPage
主动回忆/笔记输入页	P0	✅ 已实现	DailyThinkingPage + RecallTestPage
AI 分析结果页	P0	✅ 已实现	AIFeedbackPage
AI 对话页	P0	✅ 已实现	AIChatPage
复习计划页	P0	✅ 已实现	ReviewPlanView，含今天/明天/本周分组 + 复习类型标签
学习进度页	P1	✅ 已实现	AnalysisHomeView
设置页	P1	⚠️ 部分实现	ProfileView 有设置菜单，但功能入口为空
反馈页	P1	✅ 已实现	FeedbackView + FeedbackViewModel，分类选择 + 提交确认

3.2 复习计划页（P0 ✅）

计划描述：系统生成复习任务，用户查看待复习内容，按推荐时间安排学习。

当前：已实现 Features/Review/ReviewPlanView.swift，含今天/明天/本周三组、复习类型标签（间隔重复/费曼/回忆/薄弱）、完成勾选、播放按钮。数据层使用 ReviewTask Model + mock 数据。

待对接：接入 ReviewService 后端数据。

3.3 反馈页（P1 ✅）

计划描述：App 内反馈入口，让内测用户提交问题和建议。

当前：已实现 Features/Feedback/FeedbackView.swift + FeedbackViewModel.swift，含 4 类反馈分类（Bug/功能建议/内容问题/其他）的图标选择器、文本描述输入、提交通知。入口位于 ProfileView 菜单末项。

待对接：接入后端 /feedback API（FeedbackService）。

3.4 等待名单入口

计划：官网 /waitlist 页面收集用户，App 内也需要引导用户加入等待名单/申请内测。

需考虑：是否在 App 内嵌等待名单入口（如 Welcome 页或设置页）。

---

四、设计与交互差距

4.1 Tab 结构调整

计划设计：4 个 Tab — 学习 | 知识库 | AI助手 | 我的

当前实现：5 个 Tab — AI | 知识库 | 学习 | 分析 | 我的

差异分析：

• 当前把"学习"和"分析"拆成了两个独立 Tab
• 计划把"AI助手"独立为一个 Tab，当前 AI 已是独立 Tab
• "分析"在计划中属于"学习"Tab 下的子页面，不需要顶层 Tab

建议（两种方案）：

• 方案 A：完全对齐计划 → 合并学习和分析为一个 Tab，保持 4 Tab
• 方案 B：保留 5 Tab 结构 → 更新计划文档，论证"分析"独立为 Tab 的合理性（学习数据可视化、学习进度监控是独立价值）

4.2 登录流程简化（已有详细设计）

计划要求：仅 Sign in with Apple，不做手机号/邮箱/微信登录。

当前 UI：包含 4 种登录方式入口。

最终方案（详见 docs/AI对话.md）：

• 登录页只保留 Sign in with Apple 一个按钮
• 删除手机号、邮箱、微信、验证码登录
• 跳过按钮仅限 #if DEBUG，Release 不展示
• 登录页文案极简：品牌 + 一句话价值主张 + Apple 登录按钮 + 协议入口

4.3 浅色/深色模式双主题（P1 新增）✅ 已完成

实现方式：

改造项	状态
Color(light:dark:) 自适应 helper	✅ DesignTokens.swift 新增基于 UITraitCollection.userInterfaceStyle 的动态颜色
28 个颜色 token 双主题化	✅ 背景(4) + 文字(9) + 边框(5) + 填充(6) + 品牌色/彩色半透不变
渐变自适应	✅ page/splash 渐变改用自适应 Color token
硬编码色值替换	✅ 13 处内联 Color(hex:) 替换为自适应 token
ColorSchemeManager	✅ Core/Appearance/ColorSchemeManager.swift，@AppStorage 持久化，支持系统/浅色/深色
移除强制深色	✅ 移除 4 处 .preferredColorScheme(.dark)
设置页切换入口	✅ ProfileView 外观行改为可点击，confirmationDialog 三选一

文件变更：

• 新增：Core/Appearance/ColorSchemeManager.swift
• 修改：DesignTokens.swift（颜色全量自适应 + 渐变）
• 修改：AIStudyAppApp.swift（根视图用 manager 控制 scheme）
• 修改：ContentView.swift、LoginView.swift（移除强制暗黑）
• 修改：ProfileView.swift（外观切换入口）
• 修改：SplashPage.swift、ZXTabBar.swift、ZXAIInteractionRow.swift、ZXChartView.swift、AIFeedbackPage.swift、WelcomePage.swift、OnboardingPage.swift、GoalSetupPage.swift、ZXSTaskRow.swift、ZXIconBtn.swift（内联色值→token）

4.4 语言系统（P1 新增）

现状：所有文案硬编码中文在 SwiftUI View 中，无 Localizable.strings。

要求：先只支持中文，但搭建好本地化基础设施，后续加语言时只需加翻译文件。

需实现：

步骤	说明
创建 Localizable.strings (Base)	中文作为 Base 语言，不设 zh-Hans
封装 ZXLocalized 辅助	String(localized:) + Text("key") 的 SwiftUI 原生方式
迁移硬编码文案	逐文件将文案替换为 LocalizedStringKey
设置页语言入口	预留语言切换 UI，当前仅显示"中文"

4.5 无障碍

现状：未考虑 VoiceOver、Dynamic Type、高对比度等无障碍需求。

至少需做：

• 关键按钮添加 .accessibilityLabel
• 确保 Dynamic Type 下布局不破碎
• 重点页面 VoiceOver 测试

4.6 样式规范

已于 docs/样式规范.md 中梳理完整的样式规范文档，涵盖：

• 色彩系统（背景/文字/品牌语义色/边框/填充）
• 渐变体系（页面、品牌、卡片、进度条、CTA 等 11 组渐变）
• 圆角、间距、尺寸 token
• 字体层级（12 级定义）
• 共享组件目录（20+ 组件，含导航、按钮、卡片行、数据展示、输入、标签等）
• 页面布局模式（主 Tab 页、子页面、卡片、输入框、状态标签的标准写法）
• 设计决策与约束

后续新页面必须遵循 docs/样式规范.md，复用已有组件和 token，禁止随意使用内联颜色/间距/字体。

4.7 动效

计划要求（官网与技术基础.md 第 6.3 节）：

• P0：页面过渡、按钮反馈、加载状态、AI 分析中状态、学习完成反馈
• P1：今日任务卡片动效、进度条更新、AI 结果分块出现

当前：仅有基础 SwiftUI 隐式动画（withAnimation），未实现任何计划中的动效。

---

五、数据层缺失

5.1 Model 定义

现状：所有数据通过 View 内局部变量或硬编码定义，无独立 Model 文件。

计划中定义的核心实体（Demo与MVP.md）：

User
├── id, appleUserId, displayName, email
├── preferredLanguage, createdAt, lastLoginAt, status

KnowledgeBase
├── id, title, description, language, targetUser
├── createdAt, updatedAt

LearningPath
├── id, knowledgeBaseId, title, description
├── estimatedDays, order

Lesson
├── id, pathId, title, content, objectives
├── keyPoints, recallQuestions, practicePrompt
├── order, estimatedMinutes

LearningSession
├── id, userId, lessonId
├── startedAt, endedAt, userInput
├── aiAnalysis, masteryScore, weakPoints
├── nextSuggestion, reviewAt

AIAnalysis
├── id, userId, sessionId
├── inputText, outputJson, masteryScore
├── weakPoints, suggestions
├── modelName, createdAt, costEstimate

ReviewTask
├── id, userId, lessonId, sourceSessionId
├── reviewType, scheduledAt, completedAt, status

Feedback
UserLearningProfile

需实现：在 Features/*/Models/ 下创建对应的 Swift struct（需 Codable、Identifiable）。

5.2 API Contract

现状：无 API 类型定义。

建议：参考计划中定义的 JSON 结构，先创建 Swift Model，再定义 API 请求/响应类型（Request/Response struct），实现前后端类型同构。

5.3 数据流规范

现状：View 直接持有 @State，无数据流管理。

建议：

• ViewModel 持有 @Published 状态
• ViewModel 通过 Service 获取数据
• Service 通过 Repository 访问数据源
• View 通过 @StateObject / @ObservedObject 绑定 ViewModel

---

六、工程化缺失

6.1 大文件拆分 ✅

已完成：

原文件	拆分结果
AIStudyAppApp.swift (~190行)	保留 App/Root/OnboardingFlowView，页面移入 Features/Onboarding/
DailyThinkingPage.swift (~200行)	拆为 5 个文件（DailyThinking / RecallTest / WeakPoints / AIFeedback / AIChat）
LibrarySubpages.swift (~112行)	已删除，拆为 6 个独立页面文件

6.2 共享组件管理 ✅

已完成：20 个共享组件集中到 Shared/Components/，原文件中的定义已移除。

Shared/Components/
├── ZXTabBar.swift          ├── ZXBackHeader.swift
├── ZXIconBtn.swift         ├── ZXScoreBox.swift
├── ZXAIInputBar.swift      ├── ZXOutlineBtn.swift
├── ZXQuickAction.swift     ├── ZXAIInteractionRow.swift
├── ZXCardRow.swift         ├── ZXChip.swift
├── ZXImportOption.swift    ├── ZXWeakRow.swift
├── ZXStatBadge.swift       ├── ZXProfileStat.swift
├── ZXProfileMenuRow.swift  ├── ZXAchievementBadge.swift
├── ZXChartView.swift       ├── ZXSTaskRow.swift
├── FeatureRow.swift        ├── ReviewTaskRow.swift
├── ZXLoadingView.swift     ├── ZXErrorView.swift
└── ZXEmptyView.swift

6.3 测试

现状：无任何测试代码。

至少需要：

• ViewModel 单元测试（当 ViewModel 创建后）
• Service 层单元测试（Mock Repository）
• 关键 UI 流程的 Snapshot 测试

6.4 CI/CD

现状：无。

建议（后续）：

• GitHub Actions / Xcode Cloud 自动构建
• TestFlight 自动分发

6.5 崩溃监控与埋点

现状：无。

建议：接入 Firebase Crashlytics 或类似服务，至少在 TestFlight 阶段要有崩溃收集能力。

---

七、优先级建议

P0 — 必须在接后端前完成

步骤	项目	理由	设计文档
①	创建 Auth Model（AuthModels + User）	所有后续步骤的数据基础	第十章 步骤 1 ✅
②	实现 Keychain 存储层	Token 安全存储是登录的前提	第十章 步骤 2 ✅
③	搭建网络层最小实现（APIClient）	所有后端交互的唯一通道	第十章 步骤 3 ✅
④	实现 AuthService（Apple 登录 + 后端调用）	用户身份是学习记录的前提	docs/AI对话.md、第十章 步骤 4 ✅
⑤	实现 AppSession（全局登录状态）	统一的登录态管理	第十章 步骤 5 ✅
⑥	实现 LoginView + LoginViewModel	替换当前过度实现的登录页	docs/AI对话.md、第十章 步骤 6 ✅
⑦	改造 App 入口启动逻辑	Token 分流替换 @AppStorage	第十章 步骤 7 ✅
—	创建 Model 层（其余数据实体）	是 Service/ViewModel/API 的基础	本文档 5.1 节 ✅
—	实现复习计划独立页	计划标记 P0	✅
—	拆分大文件 + 集中共享组件	降低后续修改的认知负担	本文档 6.1/6.2 节 ✅
—	添加加载/错误/空状态处理	真机使用的基本体验保障	Shared/Components/ (ZXLoadingView, ZXErrorView, ZXEmptyView) ✅

P1 — 与后端对接同步推进

优先级	项目	理由
P1	浅色/深色模式双主题	覆盖所有页面和 DesignTokens，工作量较大 ✅
P1	语言系统搭建（中文 Base）	先建基础设施，后续加语言不返工 ✅
P1	搭建 ViewModel 层（逐步迁移）	架构分层，但不阻塞功能开发 ✅
P1	搭建 Service 层	随 API 对接自然建立 ✅
P1	实现反馈页	TestFlight 内测必须 ✅
P1	实现设置页完整功能	外观切换、语言入口、复习提醒等 ✅

P2 — App Store 前完成

优先级	项目	理由
P2	Repository 层	当需要本地缓存 + 网络切换时再做 ✅
P2	动效补充	体验优化，不阻塞功能 ✅
P2	无障碍适配	App Store 审核加分项 ✅
P2	测试	用户量增长后需要 ✅
P2	Tab 结构调整决策	需要更多用户反馈来决策 ✅

Tab 结构分析

当前 5-Tab 结构：

Tab	页面	核心功能
AI	AIHomeView	AI 对话入口 + 每日思考 + 薄弱点
知识库	LibraryHomeView	知识库浏览 + 导入 + 搜索
学习	StudyHomeView	今日任务 + 进度 + 每周活跃
分析	AnalysisHomeView	学习时长 + 掌握度 + 雷达图
我的	ProfileView	个人信息 + 设置 + 成就

问题诊断：

1. AI 与学习边界模糊 — AI 对话产生学习记录，但学习任务在独立 Tab，用户需要在两个 Tab 间切换
2. 分析 Tab 内容单薄 — 纯展示仪表盘，无交互深度，与"学习"Tab 的进度卡片有重叠
3. 知识库入口过重 — 知识库本质是学习的前置步骤，独立 Tab 使其脱离学习流程

可选方案：

方案	结构	优点	缺点
A: 保持现状	5 Tab 不变	无改动成本	上述问题持续
B: 合并 AI+学习	4 Tab（学习/AI、知识库、分析、我的）	AI 与学习一体化	需重设计学习首页
C: 合并分析入学习	4 Tab（AI、知识库、学习+分析、我的）	分析数据有上下文	学习页信息密度增加
D: 精简 3 Tab	3 Tab（学习、知识库、我的）	最简洁，AI 内嵌学习	分析页降级为次级入口

建议：MVP 阶段保持方案 A，收集用户反馈后优先尝试方案 C（分析并入学习）。触发条件：分析 Tab 的周活跃用户 < 20%。

---

八、总结

当前 iOS 项目完成了 UI 层的全量搭建（21 页），但缺少"能让产品真正运转"的架构底座和数据能力。核心矛盾是：

UI 超前，架构滞后。页面能点，但无数据、无认证、无 AI、无服务。

当前进度（2026-05-10）

P0 — 全部完成 ✅：

1. ✅ Apple 登录 + Auth 体系（9 个文件）
2. ✅ Model 层（10 个数据实体）
3. ✅ 网络层最小实现（APIClient + Endpoint + Error）
4. ✅ App 入口重构（AppSession 驱动路由，替代 @AppStorage）
5. ✅ 复习计划独立页（ReviewPlanView）
6. ✅ 大文件拆分（3 个大文件拆为 15+ 个独立文件）
7. ✅ 共享组件集中管理（Shared/Components/ 下 20+ 个组件）
8. ✅ 加载/错误/空状态处理（ZXLoadingView / ZXErrorView / ZXEmptyView）

P1 — 部分完成：

• ✅ 浅色/深色模式双主题（DesignTokens 自适应 + ColorSchemeManager + 移除强制暗黑）
• ✅ 语言系统搭建（中文 Base，Localizable.strings + ZXStrings + LanguageManager）
• ✅ 搭建 ViewModel 层（ReviewPlanViewModel + AIChatViewModel + StudyHomeViewModel）
• ✅ 搭建 Service 层（5 个 Service 协议 + 实现 + 20 个 APIEndpoint）
• ✅ 实现反馈页（TestFlight 内测必须）
• ✅ 设置页外观切换（ColorSchemeManager + ProfileView confirmationDialog）
• ✅ 设置页完整功能（5 个子页面 + 外观/语言切换）

接下来推荐顺序：

1. 语言系统搭建（基础设施优先，避免后续返工）
   ├── 创建 Localizable.strings (Base = 中文)
   ├── 迁移硬编码文案到 LocalizedStringKey
   └── 设置页预留语言入口（当前仅显示中文）
       ↓
2. 浅色/深色模式双主题（体验升级，需全量回归）
   ├── DesignTokens 定义 light/dark 双套色值
   ├── 替换所有内联 Color(hex:) 为 token 引用
   ├── 设置页新增外观切换（跟随系统 / 浅色 / 深色）
   └── 全页面浅色模式验证
       ↓
3. 反馈页 + 设置页补全（独立页面，不依赖其他改造）
       ↓
4. ViewModel 层迁移（逐步，不阻塞功能）
       ↓
5. Service 层搭建（随 API 对接自然建立）

---

九、AI对话.md 登录方案摘要

docs/AI对话.md 是登录模块的详细实现规范。以下为关键决策的结构化提取，便于对照实施。

9.1 登录入口决策

第一版只保留：

Sign in with Apple

删除这些入口：

• 手机号登录 / 邮箱登录 / 微信登录 / 验证码登录

"跳过"按钮：

• #if DEBUG 保留，Release 不展示
• 理由：避免匿名用户后续迁移（学习记录、AI 分析绑定用户身份）

9.2 登录页内容

知习

更懂你，更会学。

用 AI 把知识库、主动回忆和间隔复习连接起来，
从"看过"走向"真正学会"。

[ Sign in with Apple ]

登录即代表你同意《用户服务协议》和《隐私政策》

9.3 完整登录流程

App 启动
    ↓
AppSession 检查 Keychain 是否有 refreshToken
    ↓
有 token → 调用 /auth/refresh 或 /users/me
    ├─ 成功 → 进入主界面
    └─ 失败 → 清空 token，进入登录页
    ↓
无 token → 进入登录页
    ↓
用户点击 Sign in with Apple
    ↓
ASAuthorizationController 获取：
  · identityToken
  · authorizationCode
  · userIdentifier
  · email / fullName（Apple 可能不返回）
    ↓
POST /api/auth/apple
    ↓
后端返回 { accessToken, refreshToken, expiresIn, user }
    ↓
accessToken / refreshToken 存入 Keychain
    ↓
判断 user.onboardingCompleted
    ├─ false → 引导页 / 学习目标设置
    └─ true  → 主界面（ContentView）

9.4 需要新增的 9 个文件

层	文件	职责
Model	Core/Models/AuthModels.swift	AppleLoginRequest、AuthResponse 等 Codable struct
Model	Core/Models/User.swift	用户实体
Storage	Core/Storage/KeychainStore.swift	通用 Keychain 读写封装
Storage	Core/Storage/TokenStore.swift	Token 专用存取（save/load/clear）
Service	Core/Services/AuthServiceProtocol.swift	AuthService 协议定义
Service	Core/Services/AuthService.swift	ASAuthorizationController 集成 + 后端调用
App	App/AppSession.swift	@MainActor 全局登录状态
View	Features/Auth/Views/LoginView.swift	纯 Apple 登录按钮 UI
ViewModel	Features/Auth/ViewModels/LoginViewModel.swift	@Published isLoading/errorMessage

9.5 API Contract

// 请求 → POST /api/auth/apple
struct AppleLoginRequest: Encodable {
    let identityToken: String
    let authorizationCode: String?
    let userIdentifier: String
    let fullName: AppleFullName?
    let email: String?
}

struct AppleFullName: Encodable {
    let givenName: String?
    let familyName: String?
}

// 响应
struct AuthResponse: Decodable {
    let accessToken: String
    let refreshToken: String
    let expiresIn: Int
    let user: User
}

9.6 关键约束

约束	说明
Token 存 Keychain	不存 UserDefaults
不用 @AppStorage 控制登录	登录状态由 AppSession + Keychain token 决定
View 不写网络请求	网络调用在 Service 层
View 不处理 Apple 登录细节	ASAuthorizationController 逻辑在 AuthService
不改变现有主页面 UI	只替换入口路由逻辑

---

十、登录模块可行实施计划

以下是按依赖关系排列的 7 个实施步骤。每步独立可验证，后一步依赖前一步完成。

整体依赖图

步骤1: Model ─────────────────────────────────────────┐
       ↓                                               │
步骤2: KeychainStore / TokenStore ────────────────────┤
       ↓                                               │
步骤4: APIClient / APIEndpoint ─┐                      │
       ↓                        │                      │
步骤3: AuthService ←────────────┘                      │
       ↓                                               │
步骤5: AppSession ─────────────────────────────────────┤
       ↓                                               │
步骤6: LoginView + LoginViewModel ────────────────────┘
       ↓
步骤7: 改造 App 入口启动逻辑（AIStudyAppApp.swift）

---

步骤 1：创建 Auth Model ✅ 已完成（2026-05-10）

产出文件：

• Core/Models/AuthModels.swift
• Core/Models/User.swift

内容：

// AuthModels.swift
struct AppleLoginRequest: Encodable { ... }
struct AppleFullName: Encodable { ... }
struct AuthResponse: Decodable { ... }

// User.swift
struct User: Codable, Identifiable {
    let id: String
    let appleUserId: String
    let displayName: String?
    let email: String?
    let preferredLanguage: String
    let onboardingCompleted: Bool
    let createdAt: String
    let lastLoginAt: String?
    let status: String
}

依赖：无

验证：Xcode 编译通过

---

步骤 2：实现 Keychain 存储层 ✅ 已完成（2026-05-10）

产出文件：

• Core/Storage/KeychainStore.swift
• Core/Storage/TokenStore.swift

KeychainStore 职责：通用 Keychain 读写，封装 SecItemAdd/SecItemCopyMatching/SecItemDelete，支持 save/load/delete 操作。

TokenStore 职责：

protocol TokenStoreProtocol {
    func saveAccessToken(_ token: String) throws
    func getAccessToken() throws -> String?
    func saveRefreshToken(_ token: String) throws
    func getRefreshToken() throws -> String?
    func clearAll() throws
}

依赖：步骤 1（Model 定义，具体来说不需要 Model 依赖，TokenStore 操作的是原始 String）

验证：可写简单单元测试验证存取清除

---

步骤 3：搭建网络层最小实现 ✅ 已完成（2026-05-10）

注意：这一步和 AuthService 互相依赖——AuthService 需要 APIClient 发请求，但可以先建网络层骨架。做的时候步骤 3 和 4 可以部分并行：先建 APIClient 基础，再写 AuthService 时补充 Auth 相关 endpoint。

产出文件：

• Core/Network/APIClient.swift
• Core/Network/APIEndpoint.swift
• Core/Network/APIError.swift

最小接口：

// APIClient
class APIClient {
    init(baseURL: URL, tokenStore: TokenStoreProtocol?)
    func request<T: Decodable>(_ endpoint: APIEndpoint) async throws -> T
    func requestVoid(_ endpoint: APIEndpoint) async throws
}

// APIEndpoint
enum APIEndpoint {
    case appleLogin(AppleLoginRequest)
    case refreshToken(String)
    case me
    // 后续扩展其他 endpoint
}

// APIError
enum APIError: Error {
    case network(Error)
    case httpError(Int)
    case decoding(Error)
    case unauthorized
}

依赖：步骤 1（Model）、步骤 2（TokenStore）

验证：Xcode 编译通过，可以先 mock 一个请求验证 pipeline 跑通

---

步骤 4：实现 AuthService ✅ 已完成（2026-05-10）

产出文件：

• Core/Services/AuthServiceProtocol.swift
• Core/Services/AuthService.swift

AuthServiceProtocol：

protocol AuthServiceProtocol {
    func loginWithApple() async throws -> AuthResponse
    func refreshSession() async throws -> AuthResponse
    func logout() async throws
    func fetchCurrentUser() async throws -> User
}

AuthService 实现要点：

1. 集成 ASAuthorizationController（需 import AuthenticationServices）
2. 获取 identityToken、authorizationCode、userIdentifier
3. 调用 APIClient.request(.appleLogin(request))
4. 将返回的 token 写入 TokenStore
5. refreshSession：用 refreshToken 换新 token

依赖：步骤 1（AuthModels）、步骤 2（TokenStore）、步骤 3（APIClient）

验证：Xcode 编译通过，可在模拟器点击 Apple 登录（后端未就绪时用 mock）

---

步骤 5：实现 AppSession ✅ 已完成（2026-05-10）

产出文件：

• App/AppSession.swift

关键代码骨架：

@MainActor
final class AppSession: ObservableObject {
    @Published var currentUser: User?
    @Published var isAuthenticated = false
    @Published var isLoading = true
    @Published var authError: String?

    private let authService: AuthServiceProtocol
    private let tokenStore: TokenStoreProtocol

    func bootstrap() async {
        // 1. 检查 Keychain 是否有 refreshToken
        // 2. 有 → 调用 refreshSession()
        // 3. 成功 → isAuthenticated=true, currentUser=user
        // 4. 失败 → 清空 token, isAuthenticated=false
        // 5. 无 → isAuthenticated=false
        // 6. isLoading = false
    }

    func loginWithApple() async { ... }
    func logout() { ... }
}

依赖：步骤 4（AuthService）、步骤 2（TokenStore）

验证：模拟器启动时可根据 Keychain 状态正确分流

---

步骤 6：实现 LoginView + LoginViewModel ✅ 已完成（2026-05-10）

产出文件：

• Features/Auth/Views/LoginView.swift
• Features/Auth/ViewModels/LoginViewModel.swift

LoginView：

• 品牌标题"知习" + 副标题
• Sign in with Apple 按钮（ASAuthorizationAppleIDButton）
• Loading 状态（ProgressView）
• Error 提示
• #if DEBUG 跳过按钮
• 协议入口链接

LoginViewModel：

@MainActor
final class LoginViewModel: ObservableObject {
    @Published var isLoading = false
    @Published var errorMessage: String?

    func loginWithApple() async {
        isLoading = true
        errorMessage = nil
        do {
            try await appSession.loginWithApple()
        } catch {
            errorMessage = "登录失败：\(error.localizedDescription)"
            isLoading = false
        }
    }
}

依赖：步骤 5（AppSession）

验证：模拟器显示登录页，点击 Apple 登录按钮触发流程，loading 状态可展示

---

步骤 7：改造 App 入口启动逻辑 ✅ 已完成（2026-05-10）

修改文件：AIStudyAppApp.swift

改动要点：

1. 注入 AppSession 为 @StateObject
2. 启动时调用 appSession.bootstrap()
3. 用 appSession.isLoading / isAuthenticated / currentUser?.onboardingCompleted 替换原来的 @AppStorage("hasCompletedOnboarding")
4. 路由逻辑：

   isLoading          → Splash（启动加载中）
   !isAuthenticated   → LoginView
   onboardingCompleted == false → OnboardingFlowView
   onboardingCompleted == true  → ContentView
   

依赖：步骤 1-6 全部完成

验证：完整启动流程测试——

• 首次启动 → 登录页 → Apple 登录（mock） → 引导页 → 目标设置 → 主界面
• 二次启动（有有效 token）→ 直接进主界面
• Token 过期 → 登录页

---

实施俯视图

步骤 1 ──→ 步骤 2 ──→ 步骤 3 ──→ 步骤 4 ──→ 步骤 5 ──→ 步骤 6 ──→ 步骤 7
Model     Keychain   网络层    AuthSvc   AppSession  LoginUI   入口改造
(0依赖)   (无依赖)   (依赖1,2) (依赖1-3)  (依赖2,4)  (依赖5)   (依赖1-6)

每一步均可独立编译验证。后端 API 未就绪时，步骤 4-7 可以用 mock 数据先行开发，后端就绪后仅替换 APIClient 的真实 endpoint。

文件目录结构（完成后）

AIStudyApp/
├── App/
│   └── AppSession.swift              ← 新增
├── Core/
│   ├── Models/
│   │   ├── AuthModels.swift          ← 新增
│   │   └── User.swift                ← 新增
│   ├── Network/
│   │   ├── APIClient.swift           ← 新增
│   │   ├── APIEndpoint.swift         ← 新增
│   │   └── APIError.swift            ← 新增
│   ├── Services/
│   │   ├── AuthServiceProtocol.swift ← 新增
│   │   └── AuthService.swift         ← 新增
│   ├── Storage/
│   │   ├── KeychainStore.swift       ← 新增
│   │   └── TokenStore.swift          ← 新增
│   └── DesignSystem/
│       └── DesignTokens.swift        （已有，不变）
├── Features/
│   ├── Auth/
│   │   ├── Views/
│   │   │   └── LoginView.swift       ← 新增
│   │   └── ViewModels/
│   │       └── LoginViewModel.swift   ← 新增
│   ├── AI/          （已有）
│   ├── Library/     （已有）
│   ├── Study/       （已有）
│   ├── Analysis/    （已有）
│   └── Profile/     （已有）
└── AIStudyAppApp.swift               ← 修改