243 lines
10 KiB
Markdown
243 lines
10 KiB
Markdown
# 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 已检查的入口类型
|
||
|
||
- [x] Tab（4 个：学习/知识库/分析/我的）
|
||
- [x] Push（NavigationLink via Route，25 个路由目标）
|
||
- [x] Sheet（6 个）
|
||
- [x] FullScreenCover（未发现）
|
||
- [x] Alert（6 个）
|
||
- [x] ConfirmationDialog（1 个）
|
||
- [x] ContextMenu（1 处）
|
||
- [x] Menu（1 处）
|
||
- [x] Deep Link（未配置）
|
||
- [x] Universal Link（未配置）
|
||
- [x] URL Scheme（未配置）
|
||
- [x] 通知点击路由（未实现）
|
||
- [x] Debug 页面（仅 Route.destination 的 DEBUG 覆盖层）
|
||
- [x] 条件渲染页面（基于 session/onboarding/数据状态的 7 种分支）
|
||
- [x] iPhone/iPad 差异（仅在 AppContext 中标记 deviceType）
|
||
- [x] 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 项）— 遗漏主要页面或业务能力
|
||
|
||
5. 补充 RecallTestPage 到页面地图和功能表
|
||
6. 补充 AIChatPage 会话置顶功能
|
||
7. 标注 WaitlistService 状态
|
||
8. 标注账号注销 API 状态
|
||
|
||
### P2（8 项）— 命名、描述、辅助状态完善
|
||
|
||
9. 重命名"会员与额度"为"存储空间管理"
|
||
10. 考虑合并"主动回忆"与"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 修正后可达"通过"标准。**
|