16 KiB
16 KiB
01 独立页面基线
本文件不参考已有系统地图文档，完全基于代码扫描独立建立。 扫描日期：2026-06-19 扫描范围：AIStudyApp/AIStudyApp/ 目录下全部 .swift 文件（不含 Tests 和 Generated）
一、独立盘点统计
| 统计项 | 数量 |
|---|---|
| 一级模块（Tab） | 4 |
| 独立页面（含可路由页面） | 32 |
| Sheet / 弹窗 | 10 |
| 确认弹窗（Alert/ConfirmationDialog） | 8 |
| 页面内嵌子视图（非独立路由） | 2 |
| 代码存在但无入口的页面 | 1 |
| 页面功能点（估算） | ~180 |
二、应用根结构
2.1 入口点
AIStudyAppApp.swift是@main入口。- 使用
WindowGroup，UIApplicationSupportsMultipleScenes = false。 - 无 URL Scheme、Universal Link、Deep Link 配置（Info.plist 中无相关条目）。
- 无通知点击路由（未发现
UNUserNotificationCenterdelegate 或onOpenURL）。 - 无"恢复上次页面"逻辑（每次启动由 AuthManager 状态决定初始页面）。
2.2 会话状态机（AuthManager.AppSession）
unknown → SplashScreen
unauthenticated → PreLoginFlow (WelcomePage → LoginPage)
authenticating / refreshing → SplashScreen
authenticated → ContentView (if hasCompletedOnboarding) else PostLoginOnboardingFlow
disabled → AccountStatusView (禁用)
deleted → AccountStatusView (注销)
expired → PreLoginFlow
2.3 Tab 根结构（ContentView）
TabView(selection: $selectedTab)
├─ "学习" (tag: "study") → NavigationStack → StudyHomeView
├─ "知识库" (tag: "library") → NavigationStack → LibraryHomeView
├─ "分析" (tag: "analysis") → NavigationStack → AnalysisHomeView
└─ "我的" (tag: "profile") → NavigationStack → ProfileView
所有 Tab 使用 NavigationStack + .navigationDestination(for: Route.self) 统一路由。
2.4 条件性入口
| 条件 | 影响的页面/行为 |
|---|---|
| hasCompletedOnboarding = false | 显示 PostLoginOnboardingFlow (OnboardingPage → GoalSetupPage) |
| hasCompletedOnboarding = true | 直接进入 ContentView |
| session = .disabled | 显示 AccountStatusView（禁用） |
| session = .deleted | 显示 AccountStatusView（注销） |
| session = .expired / .unauthenticated | 显示 PreLoginFlow |
| selectedTab 值变化 | StudyHomeView 通过 Binding 接收，可被其他 Tab 修改 |
| 有 continueLearning API 数据 | 学习主页显示"继续上次学习"卡片 |
| reviewCards.count > 0 | 学习主页显示"今日复习"卡片 |
| quizzes.count > 0 | 学习主页显示"资料自测"卡片 |
| knowledgeBases.count > 0 | 学习主页显示"开始学习"卡片 |
| 以上全为空 | 学习主页显示空状态引导 |
| iPhone / iPad | AppContext 中记录 deviceType，但不影响页面布局 |
| Debug / Release | DEBUG 宏仅在 Route.destination 中用于显示页面标签覆盖层 |
三、完整页面清单（按入口类型分类）
3.1 启动/登录流程页面
| 序号 | 页面 | Swift 类型 | 入口方式 | 是否可路由 |
|---|---|---|---|---|
| P01 | 启动页 | SplashScreen | 应用冷启动（session = .unknown/.authenticating/.refreshing） | 否 |
| P02 | 欢迎页 | WelcomePage | PreLoginFlow step 0 | 否 |
| P03 | 登录页 | LoginPage | PreLoginFlow step 1 | 否 |
| P04 | 账号禁用页 | AccountStatusView | session = .disabled | 否 |
| P05 | 账号注销页 | AccountStatusView | session = .deleted | 否 |
| P06 | 引导页 | OnboardingPage | PostLoginOnboardingFlow step 0 | 否 |
| P07 | 目标设置页 | GoalSetupPage | PostLoginOnboardingFlow step 1 | 否 |
3.2 学习 Tab 页面（NavigationLink Push）
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P08 | 学习主页 | Route.studyHome | Tab "学习" 默认 |
| P09 | 学习会话页 | Route.learningSession | 资料阅读页工具栏 |
| P10 | 复习卡片页 | Route.reviewCard | 学习主页 / AIHomeView |
| P11 | 主动回忆页 | Route.activeRecall | 学习主页底部链接 / AIHomeView |
3.3 知识库 Tab 页面（NavigationLink Push）
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P12 | 知识库首页 | Tab "知识库" 直接渲染 | Tab "知识库" |
| P13 | 知识库搜索页 | Route.librarySearch | 知识库首页搜索图标 |
| P14 | 知识库详情页 | Route.libraryDetail | 知识库首页卡片点击 |
| P15 | 创建知识库页 | Route.libraryCreate | 知识库首页 + 按钮 / 我的页学习资产 |
| P16 | 添加知识点页 | Route.addKnowledge | 知识库详情页操作菜单"添加" |
| P17 | 知识点详情页 | Route.knowledgeDetail | 知识库详情页点击知识点 |
| P18 | 编辑知识点页 | Route.editKnowledge | 知识点详情页工具栏菜单 |
| P19 | 导入资料页 | Route.libraryImport | 知识库详情页操作菜单"上传" |
| P20 | 导入候选审核页 | Route.importReview | 导入资料完成后 |
| P21 | 发现公开库页 | Route.discoverPublic | 我的页"发现公开库" |
3.4 分析 Tab 页面
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P22 | 学习分析页 | Tab "分析" 直接渲染 | Tab "分析" |
3.5 我的 Tab 页面
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P23 | 个人中心页 | Tab "我的" 直接渲染 | Tab "我的" |
| P24 | 编辑资料页 | Route.editProfile | 个人中心页资料卡片 / 设置页 |
| P25 | 设置页 | Route.settings | 个人中心页设置图标 / 复习提醒行 |
| P26 | 学习目标设置页 | Route.goalSetting | 设置页 / 我的页 |
| P27 | 学习方法偏好页 | Route.methodPreference | 设置页 / 我的页 |
| P28 | 通知列表页 | Route.notificationList | 我的页通知图标 / 消息中心 |
| P29 | 帮助与反馈页 | Route.feedbackForm | 我的页 / 设置页 |
3.6 AI 辅助页面（跨模块 Push）
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P30 | AI 对话页 | Route.aiChat | 知识库详情页底部 / 资料阅读页工具栏 / AI 反馈页 |
| P31 | 每日思考页 | Route.dailyThinking | AI 反馈页"再来一题" / AIHomeView |
| P32 | AI 反馈页 | Route.aiFeedback | 主动回忆完成后 / 每日思考提交后 |
| P33 | 薄弱知识点页 | Route.weakPoints | 分析页"全部 N 个"链接 / AIHomeView |
3.7 测验页面
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P34 | 测验列表页 | Route.quizList | 知识库详情页操作菜单"测验" |
| P35 | 测验作答页 | Route.quizTake | 测验列表点击 / 学习主页自我测试 |
| P36 | 测验结果页 | Route.quizResult | 测验作答提交后 |
3.8 资料阅读页面
| 序号 | 页面 | Route 枚举 | 入口 |
|---|---|---|---|
| P37 | 资料阅读页 | Route.materialReader | 学习主页"继续学习" / 分析页"继续阅读" / 来源文件 / 知识点详情 |
| P38 | 资料详情页 | Route.materialDetail | 资料阅读页工具栏"信息"按钮 |
3.9 Sheet / 弹窗（非独立 Push 页面）
| 序号 | 名称 | 类型 | 所在页面 | 入口 |
|---|---|---|---|---|
| S01 | AI 会话列表 Sheet | .sheet (medium/large) | AIChatPage | 工具栏"会话列表"按钮 |
| S02 | 快速笔记 Sheet | .sheet | MaterialReaderView | 工具栏笔记按钮 |
| S03 | 系统预览 (QuickLook) | .sheet (QLPreviewController) | MaterialReaderView | "系统预览"按钮 |
| S04 | 封面选择 Sheet | .sheet (height 220) | CreateLibraryPage | 封面区域点击 |
| S05 | 文件夹管理 Sheet | .sheet | LibraryDetailPage | 操作菜单"文件夹管理" |
| S06 | 链接导入 Alert | .alert (with TextField) | ImportPage | "链接导入"按钮 |
3.10 确认弹窗（Alert / ConfirmationDialog）
| 序号 | 名称 | 类型 | 所在页面 |
|---|---|---|---|
| A01 | 结束学习确认 | ConfirmationDialog | LearningSessionView |
| A02 | 删除知识库确认 | Alert | LibraryDetailPage |
| A03 | 批量删除确认 | Alert | LibraryDetailPage |
| A04 | 新建文件夹 | Alert (with TextField) | FolderManageView |
| A05 | 重命名文件夹 | Alert (with TextField) | FolderManageView |
| A06 | 退出登录确认 | Alert | SettingsView |
| A07 | 新建分类 | Alert (with TextField) | FolderManageView |
| A08 | 链接导入 | Alert (with TextField) | ImportPage |
3.11 代码存在但无入口的页面
| 名称 | Swift 类型 | 情况说明 |
|---|---|---|
| AI 首页 | AIHomeView | 完整页面代码，含 NavigationLink 到 AIChatPage/ActiveRecallView/WeakPointsPage/ReviewCardView/DailyThinkingPage，但 Route 中无对应 case，无任何其他页面跳转到此页 |
四、入口类型检查清单
| 入口类型 | 是否检查 | 发现情况 |
|---|---|---|
| Tab | 是 | 4 个：学习、知识库、分析、我的 |
| Push (NavigationLink via Route) | 是 | 约 25 个路由目标 |
| Sheet | 是 | 6 个 Sheet |
| FullScreenCover | 是 | 未发现 |
| Alert | 是 | 6 个 Alert |
| ConfirmationDialog | 是 | 1 个 |
| Popover | 是 | 未发现 |
| ContextMenu | 是 | LibraryDetailPage 知识点行 |
| Menu | 是 | LibraryDetailPage 工具栏 |
| Deep Link | 是 | 未配置 |
| Universal Link | 是 | 未配置 |
| URL Scheme | 是 | 未配置 |
| 通知点击路由 | 是 | 未发现 |
| Debug 页面 | 是 | 仅 DEBUG 标签覆盖层，无专用调试页面 |
| 条件渲染页面 | 是 | 基于 session / onboarding / 数据状态的 7 种分支 |
| iPhone/iPad 差异 | 是 | 仅在 AppContext 记录，无布局差异 |
| Feature Flag | 是 | 未发现 |
| 管理员/内部账号 | 是 | 未发现 |
| 首次启动 vs 非首次 | 是 | hasCompletedOnboarding @AppStorage |
五、页面跳转关系（基于 Route 枚举和 NavigationLink 分析）
5.1 Tab 内跳转
| 源页面 | 目标页面 | Route |
|---|---|---|
| StudyHomeView | MaterialReaderView | .materialReader |
| StudyHomeView | ReviewCardView | .reviewCard |
| StudyHomeView | QuizTakerView | .quizTake |
| StudyHomeView | QuizListView | .quizList |
| StudyHomeView | ActiveRecallView | .activeRecall |
| StudyHomeView | 切换到 library Tab | selectedTab 绑定 |
| LibraryHomeView | LibrarySearchView | .librarySearch |
| LibraryHomeView | CreateLibraryPage | .libraryCreate |
| LibraryHomeView | LibraryDetailPage | .libraryDetail |
| LibraryDetailPage | KnowledgeDetailPage | .knowledgeDetail |
| LibraryDetailPage | EditKnowledgePage | .editKnowledge |
| LibraryDetailPage | ImportPage | .libraryImport |
| LibraryDetailPage | AddKnowledgePage | .addKnowledge |
| LibraryDetailPage | QuizListView | .quizList |
| LibraryDetailPage | AIChatPage | .aiChat |
| LibraryDetailPage | MaterialReaderView | .materialReader |
| LibraryDetailPage | FolderManageView (Sheet) | - |
| CreateLibraryPage | 封面选择 Sheet | - |
| AddKnowledgePage | (文件选择器/相册) | 系统组件 |
| KnowledgeDetailPage | MaterialReaderView | .materialReader |
| KnowledgeDetailPage | QuickLook (Sheet) | - |
| KnowledgeDetailPage | QuickNoteSheet | - |
| ImportPage | ImportReviewPage | .importReview |
| ImportPage | (文件选择器/相册/链接Alert) | 系统组件 |
| AnalysisHomeView | WeakPointsPage | .weakPoints |
| AnalysisHomeView | MaterialReaderView | .materialReader |
| ProfileView | EditProfilePage | .editProfile |
| ProfileView | GoalSettingDetailView | .goalSetting |
| ProfileView | SettingsView | .settings |
| ProfileView | MethodPreferenceView | .methodPreference |
| ProfileView | FeedbackFormView | .feedbackForm |
| ProfileView | CreateLibraryPage | .libraryCreate |
| ProfileView | DiscoverView | .discoverPublic |
| ProfileView | NotificationListView | .notificationList |
| SettingsView | GoalSettingDetailView | .goalSetting |
| SettingsView | MethodPreferenceView | .methodPreference |
| SettingsView | EditProfilePage | .editProfile |
| SettingsView | FeedbackFormView | .feedbackForm |
5.2 跨模块跳转
| 源页面 | 目标页面 | 触发方式 |
|---|---|---|
| ActiveRecallView | AIFeedbackPageView | 提交完所有回答后"查看 AI 分析" |
| AIFeedbackPageView | StudyHomeView | "加入待巩固" |
| AIFeedbackPageView | AIChatPage | "深入提问" |
| AIFeedbackPageView | DailyThinkingPage | "再来一题" |
| DailyThinkingPage | AIFeedbackPageView | 提交回答后 |
| MaterialReaderView | AIChatPage | 工具栏 AI 按钮 |
| MaterialReaderView | MaterialDetailView | 工具栏信息按钮 |
| MaterialReaderView | LearningSessionView | 工具栏学习按钮 |
| MaterialReaderView | QuickNoteSheet | 工具栏笔记按钮 |
| AIHomeView | AIChatPage | NavigationLink（页面自身无入口） |
| AIHomeView | ActiveRecallView | NavigationLink（页面自身无入口） |
| AIHomeView | WeakPointsPage | NavigationLink（页面自身无入口） |
| AIHomeView | ReviewCardView | NavigationLink（页面自身无入口） |
| AIHomeView | DailyThinkingPage | NavigationLink（页面自身无入口） |
六、API 服务清单（每个对应一组后端端点）
| 服务类 | 主要端点 | 被哪些页面使用 |
|---|---|---|
| AuthService | /auth/apple, /auth/refresh, /auth/logout | LoginPage, AuthManager |
| UserService | /users/me (GET/PATCH), /users/me/preferences, /users/me/profile, /users/me/deletion-request, /users/me/devices, /users/me/assets-summary, /users/me/storage | ProfileView, EditProfilePage, SettingsView, GoalSettingDetailView, MethodPreferenceView |
| KnowledgeBaseService | /knowledge-bases (CRUD), /knowledge-bases/subscribed, /knowledge-bases/:id/subscribe | LibraryHomeView, LibraryDetailPage, CreateLibraryPage, DiscoverView, StudyHomeView |
| KnowledgeItemService | /knowledge-items (CRUD, batch-delete) | LibraryDetailPage, AddKnowledgePage, KnowledgeDetailPage, EditKnowledgePage |
| KnowledgeFolderService | /knowledge-bases/:id/folders (CRUD) | FolderManageView |
| KnowledgeSourceService | /knowledge-bases/:id/sources (CRUD, parse) | LibraryDetailPage, MaterialReaderView |
| DocumentImportService | /imports (create, status) | ImportPage |
| ImportCandidateService | /import-candidates (list, accept, reject, batch-accept) | ImportReviewPage |
| QuizService | /quizzes (generate, list, detail, start, submit, results, history) | QuizListView, QuizTakerView, QuizResultView |
| RagChatService | /rag-chat/sessions (CRUD, messages, stream) | AIChatPage |
| ActiveRecallService | /active-recalls (list, submit) | ActiveRecallView |
| AIAnalysisService | /ai-analysis | (ViewModel 中有调用，但 ActiveRecallView 使用硬编码数据) |
| ReviewService | /reviews (due, submit, generate-cards) | ReviewCardView (View 中硬编码，ViewModel 调用 API) |
| FocusItemService | /focus-items (list, update, complete) | AnalysisHomeView (via ActivityViewModel) |
| ActivityService | /activity (summary, heatmap, trend, streak, recommendations) | AnalysisHomeView, ProfileView, StudyHomeView |
| LearningSessionService | /learning-sessions (list, start, end) | LearningSessionView, StudyHomeView |
| ReadingAPIService | /learning/reading-events/batch, /materials/:id/reading-progress, /learning/continue, /learning/summary, /learning/trend, /learning/records | MaterialReaderView, StudyHomeView, AnalysisHomeView |
| FileUploadService | /files/upload-url, /files/complete, /files/:id | CreateLibraryPage, AddKnowledgePage, ImportPage, EditProfilePage |
| FeedbackService | /feedback | FeedbackFormView |
| NotificationService | /notifications (list, markRead, markAllRead, preferences, push-token) | NotificationListView, SettingsView |
| WaitlistService | /waitlist | (API 定义存在，iOS 代码中未发现使用入口) |
七、免责说明
- 本基线完全基于对 AIStudyApp/AIStudyApp/ 目录下全部 64 个 .swift 文件的逐文件阅读建立。
- 未检查 .xcassets、.entitlements、.xcodeproj 中的详细配置。
- iOS 推送通知的深度链接处理在代码中未发现，但可能在 Capabilities 中配置（未检查 .entitlements 文件全文）。
- WaitlistService 代码存在但未在任何 View 或 ViewModel 中使用，判定为无 C 端入口。