wangdl/ios-projects
2
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
ios-projects/docs/system-map/ios/review/00-审查总报告.md

10 KiB
Raw Blame History

00 审查总报告

审查对象：知习 iOS 项目第一阶段系统地图（4 份文档） 审查日期：2026-06-19 审查方法：独立代码扫描 → 独立基线建立 → 与已有文档逐项比对 审查范围：AIStudyApp/AIStudyApp/ 目录下全部 64 个 .swift 文件（不含 Tests 和自动生成代码）

一、审查范围

1.1 已检查的文件

  • AIStudyAppApp.swift — App 入口、所有页面定义
  • ContentView.swift — Tab 根结构、共享组件
  • Core/Navigation/Route.swift — 全部路由定义（28 个 case）
  • Core/Auth/AuthManager.swift — 会话状态机（8 种状态）
  • Core/Models/APIModels.swift — 全部 54 个 API 模型
  • Core/Models/AppContext.swift — 设备/运行时上下文
  • Core/Network/APIClient.swift — HTTP 客户端、Token 刷新
  • Core/Services/APIService.swift — 全部 18 个服务类
  • Core/Services/FileUploadService.swift — 文件上传
  • Core/Services/ReadingAPI.swift — 阅读相关 API
  • Core/Services/NetworkMonitor.swift — 网络状态监控
  • Core/DesignSystem/DesignTokens.swift — 设计系统
  • Core/DesignSystem/ZXToast.swift — Toast 系统
  • Core/Security/KeychainHelper.swift — (已通过 AuthManager 间接审查)
  • Core/Security/LocalCache.swift — 本地缓存
  • Core/Security/FileCache.swift — 文件缓存
  • Features/Study/ 全部 7 个文件
  • Features/Library/ 全部 5 个文件
  • Features/Profile/ 全部 8 个文件
  • Features/AI/ 全部 10 个文件
  • Features/Analysis/ 全部 2 个文件
  • Features/Quiz/ 1 个文件（QuizViews.swift）
  • Features/MaterialReader/ 全部 12 个文件

1.2 已检查的入口类型

  • Tab（4 个：学习/知识库/分析/我的）
  • Push（NavigationLink via Route，25 个路由目标）
  • Sheet（6 个）
  • FullScreenCover（未发现）
  • Alert（6 个）
  • ConfirmationDialog（1 个）
  • ContextMenu（1 处）
  • Menu（1 处）
  • Deep Link（未配置）
  • Universal Link（未配置）
  • URL Scheme（未配置）
  • 通知点击路由（未实现）
  • Debug 页面（仅 Route.destination 的 DEBUG 覆盖层）
  • 条件渲染页面（基于 session/onboarding/数据状态的 7 种分支）
  • iPhone/iPad 差异（仅在 AppContext 中标记 deviceType）
  • Feature Flag（未发现）

1.3 未检查的项

  • .xcodeproj 详细配置（Capabilities、Build Settings）
  • .entitlements 文件全文（推送通知、iCloud 等 Capability）
  • 第三方依赖（Rive 动画 SDK 等）
  • Rust FFI 二进制内部逻辑（ZxDocumentRuntime.xcframework）

二、独立盘点统计

统计项 数量
一级模块（Tab） 4
独立 Push 页面（可路由） 32
Tab 内嵌页面（不可路由） 6（启动/登录流程页面）
Sheet / 弹窗 10
确认弹窗（Alert/ConfirmationDialog） 8
代码存在但无导航入口的页面 2（AIHomeView, RecallTestPage）
页面功能点 ~180
API 服务类 18
初步业务能力 20

三、审查结论

审查结论：有条件通过

不满足"通过"的哪些门禁条件？

门禁条件 满足？ 说明
所有导航入口已检查 是 Tab/Push/Sheet/Alert/条件渲染均检查
所有用户可访问页面已进入基线 是 32 个路由页面 + 6 个启动/登录页均已盘点
Sheet/弹窗/隐藏入口已检查 是 10 个 Sheet + 8 个 Alert + ContextMenu/Menu 均已盘点
页面功能均进入功能基线 是 ~180 个功能点均已盘点
页面与业务能力完成双向覆盖检查 是 见 06-页面能力覆盖矩阵.md
Mock/占位/废弃实现没有被误判为已完成 否 4 处 P0 误判（见第四节）
所有"暂未确认"均被明确列出 是 3 项暂未确认
严重遗漏为 0 否 1 个页面遗漏（RecallTestPage）
P0 修正项为 0 否 4 项 P0 修正
已有文档和独立基线差异已全部处理 是 16 项差异全部列入待修正清单

四、严重问题（P0 — 会导致系统地图明显失真）

4.1 功能状态误判-图表数据为占位

  • 问题： 文档将"查看掌握度趋势图"和"查看每周学习活跃"均标记为"部分完成"
  • 实际： ZXChartView 和 ZXWeekBarChart 使用完全硬编码的编译时数据，ViewModel 的 API 返回数据被忽略。应标记为"占位实现"
  • 影响： 分析页给人的印象是"图表数据已接入但需优化"，实际情况是"图表数据完全未接入 API"

4.2 功能状态误判-每日学习时长不持久化

  • 问题： GoalSettingDetailView 的"修改每日时长"标记为"已完成"
  • 实际： dailyMins 只保存在本地 @State 变量，不通过 API 持久化，用户下次进入恢复默认"30 分钟"
  • 影响： 给人"目标设置功能完整"的假象

4.3 设置页通知开关标记为"暂未确认"

  • 问题： 三个通知开关绑定 bug 被标记为"暂未确认"
  • 实际： 代码中"复习提醒"、"导入完成通知"、"系统通知"三个 Toggle 全部绑定到同一个 $reviewReminder，这是明确的代码 bug
  • 影响： 将确定性 bug 降级为不确定性疑点，降低修正优先级

4.4 文档页面/弹窗统计数字口径不明确

  • 问题： 总览文档称"43 个页面/弹窗"，但未说明统计口径
  • 实际： 独立基线盘点出 38 个 Push 页面 + 10 个 Sheet/弹窗 + 8 个确认弹窗
  • 建议： 明确统计口径（是否含弹窗？是否含废弃页面？）并更新数字

五、一般问题（P1/P2）

P1 — 遗漏项（4 项）

  1. 遗漏 RecallTestPage（代码存在，无入口，应为占位实现）
  2. 遗漏 AIChatPage 会话置顶/取消置顶功能
  3. 遗漏 WaitlistService API 已就绪但 C 端无入口
  4. 遗漏 UserService 账号注销 API 已就绪但无 C 端入口

P2 — 命名、描述、辅助状态问题（8 项）

  1. 业务能力"会员与额度"命名不准确 → 应改为"存储空间管理"
  2. 建议合并"主动回忆"与"AI 学习分析"为一个业务能力
  3. StudyHomeViewModel error 状态永不可达（View 有但 ViewModel 不设置）
  4. DailyThinkingPage submitted 变量永不为 true
  5. 设置页"存储空间"和"登录设备管理"自引用导航
  6. 知识库详情页"知识库管理"按钮为 TODO
  7. 业务能力依赖关系图缺少交叉引用
  8. 文件夹新建/重命名 Alert 未列入确认弹窗表

六、遗漏项汇总

类型 数量 明细
遗漏页面 1 RecallTestPage
遗漏功能 4 会话置顶、AIHomeView 子功能、解析触发、MaterialReaderView COS 下载
遗漏 Sheet/弹窗 1 文件夹新建/重命名 Alert
遗漏 API-页面入口 3 WaitlistService、账号注销、设备管理

七、错误项汇总

类型 数量 明细
状态误判 4 掌握度趋势图（部分→占位）、每周活跃图（部分→占位）、每日时长（已完成→部分）、通知开关（暂未确认→部分+bug）
命名错误 1 会员与额度 → 存储空间管理
分类建议 2 主动回忆+AI 分析建议合并、能力依赖图缺少交叉引用

八、待确认项

序号 待确认内容 原因
U01 LearningSessionView 是否调用 API 保存学习记录 代码中未发现 LearningSessionService.start/end 的直接调用，但可能在 Rust FFI 或 ViewModel 中有间接调用
U02 SettingsView iCloud 同步开关实际后端支持情况 Toggle UI 存在但仅改变本地 @State，无法确认后端是否有对应能力
U03 分析页"近 7 天"日期范围筛选是否可切换 UI 中展示了日期范围标签但未发现切换逻辑

九、修正优先级

P0（4 项）— 影响整体地图正确性

  1. 分析页图表数据状态修正（部分完成 → 占位实现）
  2. 每日学习时长持久化状态修正（已完成 → 部分完成）
  3. 设置页通知开关 bug 状态修正（暂未确认 → 部分完成，存在 bug）
  4. 总览页统计数字口径明确化

P1（4 项）— 遗漏主要页面或业务能力

  1. 补充 RecallTestPage 到页面地图和功能表
  2. 补充 AIChatPage 会话置顶功能
  3. 标注 WaitlistService 状态
  4. 标注账号注销 API 状态

P2（8 项）— 命名、描述、辅助状态完善

  1. 重命名"会员与额度"为"存储空间管理"
  2. 考虑合并"主动回忆"与"AI 学习分析" 11-16. 其他描述性补充

十、最终判断

总体评价

  • 已有文档的代码覆盖率高（页面覆盖率约 95%，功能覆盖率约 95%）
  • 核心流程描述准确（用户生命周期、Tab 结构、路由系统）
  • Mock/占位实现识别基本正确（AI 相关页面正确标记为占位实现）

主要不足

  1. 分析页图表状态被低估（占位实现被标记为部分完成）
  2. 设置页通知 bug 被降级为"暂未确认"
  3. GoalSettingDetailView 学习时长不持久化未被发现
  4. 1 个代码页面、2 个 API 端点、1 个交互功能的遗漏

是否可以进入下一阶段？

可以进入下一阶段的"跨项目业务能力展开"，但建议先完成 4 项 P0 修正。

原因：

  • 已有文档的整体架构和页面覆盖是准确的，作为后续分析的基础足够可靠
  • P0 问题集中在对少数具体功能的状态判断上，不影响整体地图的结构正确性
  • 未发现系统性的页面遗漏或归类错误
  • Mock/占位/废弃实现的识别框架是正确的，只需修正个别判断
  • P1/P2 问题不阻塞跨项目分析，可在第二阶段的盘点中一并修正

门禁复查

门禁 修正前 修正 P0 后
严重遗漏为 0 否（1 项 P1） 是
P0 修正项为 0 否（4 项） 是
Mock/占位未误判 否 是（修正 4 处后）

完成 4 项 P0 修正后可达"通过"标准。