From b55e4971614c6ed4a2063031b8cc9bf64e814ae5 Mon Sep 17 00:00:00 2001 From: WangDL Date: Sun, 17 May 2026 22:31:38 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=80=BB=E5=BE=85?= =?UTF-8?q?=E5=AE=8C=E6=88=90=E6=B8=85=E5=8D=95=20=E2=80=94=20iOS=20P2=20?= =?UTF-8?q?=E5=8A=A8=E6=95=88/=E6=97=A0=E9=9A=9C=E7=A2=8D=E5=AE=8C?= =?UTF-8?q?=E6=88=90=EF=BC=8CCOS=20=E6=8E=A5=E5=85=A5=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - I12 动效补充 ✅ - I13 无障碍基础适配 ✅ - B16/B17/B19 COS 对象存储接入 ✅ - 移除 iOS CI/CD 项（Apple 项目本地编译发布） - 更新执行顺序建议 Co-Authored-By: Claude Opus 4.7 --- 技术设计/ios-projects/缺失项与待补全方向.md | 75 +++++++++++++-------- 技术设计/总待完成清单.md | 53 +++++++-------- 2 files changed, 73 insertions(+), 55 deletions(-) diff --git a/技术设计/ios-projects/缺失项与待补全方向.md b/技术设计/ios-projects/缺失项与待补全方向.md index 234a5cc..9337d15 100644 --- a/技术设计/ios-projects/缺失项与待补全方向.md +++ b/技术设计/ios-projects/缺失项与待补全方向.md @@ -6,44 +6,61 @@ --- -## 一、后端 API 对接（当前最优先） +## 一、后端 API 对接（✅ 已完成 2026-05-17） -Auth 已对接。以下页面仍使用静态 Mock 数据，待接后端： - -| 页面 | 需对接的 API | -|------|-------------| -| LibraryHomeView | GET /api/knowledge-bases | -| LibraryDetailPage | GET /api/knowledge-bases/:id/items | -| StudyHomeView | GET /api/learning-sessions | -| DailyThinkingPage | POST /api/active-recall/answers | -| AIFeedbackPage | GET /api/ai-analysis/:id | -| ReviewPlanView | GET /api/reviews/due | -| AnalysisHomeView | GET /api/learning-activity/summary | +所有页面已对接后端 API，包括知识库列表/详情、学习会话、主动回忆、AI 分析、复习计划、学习活跃统计。全局下拉刷新 + 上拉加载更多已接入，Toast 通知系统已就位。 --- -## 二、架构层待推进 +## 二、架构层（✅ 已完成 2026-05-17） -### ViewModel 迁移（部分完成） +### ViewModel 迁移（已完成） -ReviewPlanViewModel、AIChatViewModel、StudyHomeViewModel 已完成。其余页面仍为 View 内聚状态，待逐步迁移。 +所有页面的 ViewModel 已就位： +- `AIChatViewModel` — AI 对话消息管理 +- `StudyHomeViewModel` — 学习主页任务/进度计算 +- `ReviewPlanViewModel` — 复习计划分组管理 +- `ProfileViewModel` — 用户资料/偏好 +- `LibraryViewModel` / `LibraryDetailViewModel` — 知识库/知识点分页 +- `ActivityViewModel` — 分析统计 +- `StudyViewModel` / `ReviewViewModel` — 学习会话/复习 -### Repository 层 +### 本地缓存层（已完成） -当需要本地缓存 + 网络切换时再建，当前阶段不紧急。 +- `FileCache` — JSON 文件缓存（泛型 save/load/remove/clear） +- `LocalCache` — 高层缓存服务（缓存优先 + TTL 过期 + 后台刷新） + +### 本地化（已完成） + +`zh-Hans.lproj/Localizable.strings` 含 180+ key，覆盖所有页面文案。添加新语言只需创建对应 `.lproj` 翻译文件。 --- -## 三、动效 +## 三、动效（✅ 已完成 2026-05-17） -计划要求（P0）：页面过渡、按钮反馈、加载状态、AI 分析中状态、学习完成反馈。当前仅有基础 SwiftUI 隐式动画。 +计划要求（P0）：页面过渡、按钮反馈、加载状态、AI 分析中状态、学习完成反馈。 + +已完成内容： +- `ZXAnimations.swift` — 6 个动效组件：`ZXButtonStyle`（按钮缩放+触觉反馈）、`ZXPressModifier`/`.zxPressable()`（任意视图按压效果）、`ZXPageTransition`（页面滑入+淡入淡出）、`ZXThinkingOverlay`（AI 分析全屏叠加层+脑图标光环动画）、`ZXCelebrationView`（五彩纸屑粒子系统+成就卡片）、`ZXAIAnalysisProgress`（分步分析进度条+旋转加载器） +- 所有关键按钮已接入 `.zxPressable()`：提交回答、暂停/继续学习、结束学习、发送消息、任务行、复习评分按钮 +- AI 分析流程已接入 `ZXThinkingOverlay` + `ZXAIAnalysisProgress` +- 学习/复习完成已接入 `ZXCelebrationView` +- 页面切换已接入 Tab 过渡动画 --- -## 四、无障碍 +## 四、无障碍（✅ 已完成 2026-05-17） 关键按钮添加 `.accessibilityLabel`，确保 Dynamic Type 下布局不破碎，重点页面 VoiceOver 测试。 +已完成内容： +- Tab 栏 5 个标签页均添加 `.accessibilityLabel` +- 所有关键按钮添加无障碍标签：提交回答、发送消息、暂停/继续/结束学习、复习评分（完全不会/有点难/基本会/很简单）、导航按钮（搜索、通知、设置、创建知识库）、快捷操作、个人资料编辑 +- 问答卡片添加 `.accessibilityElement(children: .combine)` + `.accessibilityLabel` + `.accessibilityHint` +- 复习卡片翻转状态通过 `.accessibilityLabel` 区分问题/答案模式，添加 `.accessibilityAddTraits(.isButton)` +- 输入框添加 `.accessibilityLabel`（搜索知识库、AI 学习问题输入框） +- 任务行添加完成状态提示 + --- ## 五、测试 @@ -54,11 +71,9 @@ ReviewPlanViewModel、AIChatViewModel、StudyHomeViewModel 已完成。其余页 --- -## 六、CI/CD +## 六、崩溃监控 -- GitHub Actions / Xcode Cloud 自动构建 -- TestFlight 自动分发 -- 崩溃监控（Firebase Crashlytics 或类似） +- Firebase Crashlytics 或 Sentry --- @@ -80,8 +95,12 @@ ReviewPlanViewModel、AIChatViewModel、StudyHomeViewModel 已完成。其余页 ## 当前最应该推进 ```text -1. 后端 API 对接（知识库列表 → 学习会话 → 复习 → 学习活跃） -2. ViewModel 层逐步迁移（不阻塞功能） -3. 动效补充（页面过渡 + AI 分析中状态） -4. 无障碍基础适配 +1. ✅ 后端 API 对接（已完成） +2. ✅ ViewModel 层迁移（已完成） +3. ✅ 动效补充（页面过渡 + AI 分析中状态）— 已完成 +4. ✅ 无障碍基础适配 — 已完成 +5. ✅ 本地缓存接入 ViewModel — 已完成 +6. 数据埋点 — P3 +7. 崩溃监控 — P3 +8. 测试 — P3 ``` diff --git a/技术设计/总待完成清单.md b/技术设计/总待完成清单.md index d09b814..86a4b26 100644 --- a/技术设计/总待完成清单.md +++ b/技术设计/总待完成清单.md @@ -54,12 +54,12 @@ ### 🟡 P2 — 存储/文件 -| # | 事项 | 说明 | 详见 | -|---|------|------|------| -| B16 | COS 对象存储接入 | 文件上传/下载/签名 URL | [Redis缓存设计](./api-server/Redis缓存设计.md) | -| B17 | 文件上传完整流程 | POST /api/files/upload-url → COS → complete | [后端开发路线图 P5](./api-server/后端开发路线图.md) | -| B18 | 文档导入真实解析 | 替换 3 层 setTimeout mock | [潜在问题清单 #24](./潜在问题清单.md) | -| B19 | Storage Service 实现 | 当前只有 getUploadPath + healthCheck，无真正读写 | [潜在问题清单 #25](./潜在问题清单.md) | +| # | 事项 | 说明 | 详见 | 状态 | +|---|------|------|------|------| +| B16 | COS 对象存储接入 | 文件上传/下载/签名 URL | [Redis缓存设计](./api-server/Redis缓存设计.md) | ✅ | +| B17 | 文件上传完整流程 | POST /api/files/upload-url → COS → complete | [后端开发路线图 P5](./api-server/后端开发路线图.md) | ✅ | +| B18 | 文档导入真实解析 | 替换 3 层 setTimeout mock | [潜在问题清单 #24](./潜在问题清单.md) | | +| B19 | Storage Service 实现 | 当前只有 getUploadPath + healthCheck，无真正读写 | [潜在问题清单 #25](./潜在问题清单.md) | ✅ | ### 🟡 P2 — 基础设施补全 @@ -98,29 +98,28 @@ ### 🟠 P1 — 架构补全 -| # | 事项 | 说明 | 详见 | -|---|------|------|------| -| I8 | ViewModel 层迁移 | 其余页面从 View 内聚状态迁移到 ViewModel | [缺失项 二](./ios-projects/缺失项与待补全方向.md) | -| I9 | 本地缓存层 | UserDefaults/SwiftData 缓存学习数据，支持离线浏览 | [潜在问题清单 #18](./潜在问题清单.md) | -| I10 | 测试修复 | 4 个 Test 文件引用的 ViewModel/FileCache 已创建，验证可编译 | [潜在问题清单 #13](./潜在问题清单.md) | -| I11 | LocalizedStringKey 接入 | 180+ key 已写好，View 需从硬编码文案切换 | [潜在问题清单 #20](./潜在问题清单.md) | +| # | 事项 | 说明 | 详见 | 状态 | +|---|------|------|------|------| +| I8 | ViewModel 层迁移 | 其余页面从 View 内聚状态迁移到 ViewModel | [缺失项 二](./ios-projects/缺失项与待补全方向.md) | ✅ | +| I9 | 本地缓存层 | UserDefaults/SwiftData 缓存学习数据，支持离线浏览 | [潜在问题清单 #18](./潜在问题清单.md) | ✅ | +| I10 | 测试修复 | 4 个 Test 文件引用的 ViewModel/FileCache 已创建，验证可编译 | [潜在问题清单 #13](./潜在问题清单.md) | ✅ | +| I11 | LocalizedStringKey 接入 | 180+ key 已写好，View 需从硬编码文案切换 | [潜在问题清单 #20](./潜在问题清单.md) | ✅ | ### 🟡 P2 — 体验/动效 -| # | 事项 | 说明 | 详见 | -|---|------|------|------| -| I12 | 动效补充 | 页面过渡、按钮反馈、AI 分析中状态、学习完成反馈 | [缺失项 三](./ios-projects/缺失项与待补全方向.md) | -| I13 | 无障碍基础适配 | accessibilityLabel、Dynamic Type、VoiceOver | [缺失项 四](./ios-projects/缺失项与待补全方向.md) | +| # | 事项 | 说明 | 详见 | 状态 | +|---|------|------|------|------| +| I12 | 动效补充 | 页面过渡、按钮反馈、AI 分析中状态、学习完成反馈 | [缺失项 三](./ios-projects/缺失项与待补全方向.md) | ✅ | +| I13 | 无障碍基础适配 | accessibilityLabel、Dynamic Type、VoiceOver | [缺失项 四](./ios-projects/缺失项与待补全方向.md) | ✅ | ### 🟢 P3 — TestFlight 前 | # | 事项 | 说明 | 详见 | |---|------|------|------| | I14 | 数据埋点 | 产品行为事件追踪（PostHog/Firebase） | [缺失项 八](./ios-projects/缺失项与待补全方向.md) | -| I15 | CI/CD | GitHub Actions 自动构建 + TestFlight 分发 | [缺失项 六](./ios-projects/缺失项与待补全方向.md) | -| I16 | 崩溃监控 | Firebase Crashlytics 或 Sentry | [缺失项 六](./ios-projects/缺失项与待补全方向.md) | -| I17 | ViewModel/Service 单元测试 | Mock Repository 测试 | [缺失项 五](./ios-projects/缺失项与待补全方向.md) | -| I18 | Tab 结构调整决策 | 保持 5-Tab 或合并为 4-Tab | [缺失项 七](./ios-projects/缺失项与待补全方向.md) | +| I15 | 崩溃监控 | Firebase Crashlytics 或 Sentry | [缺失项 六](./ios-projects/缺失项与待补全方向.md) | +| I16 | ViewModel/Service 单元测试 | Mock Repository 测试 | [缺失项 五](./ios-projects/缺失项与待补全方向.md) | +| I17 | Tab 结构调整决策 | 保持 5-Tab 或合并为 4-Tab | [缺失项 七](./ios-projects/缺失项与待补全方向.md) | --- @@ -185,17 +184,17 @@ B1 → B2 → B3 → B4 → B5 → B6 CI/CD脱敏 → BullMQ → AI await修复 → 限流注册 → 拦截器注册 → 分页 -第 2 批（本月，核心链路）： - B7-B11 → B12-B15 → I1-I7 ✅ - AI Workflows → 异步化 → iOS 前后端打通（已打通） +第 2 批（✅ 已完成 2026-05-17）： + B7-B11 → B12-B15 → I1-I7 ✅ → I8-I11 ✅ + AI Workflows → 异步化 → iOS 前后端打通 → iOS 架构补全 第 3 批（TestFlight 前）： - I8-I13 → B16-B22 → S6-S9 → W1-W3 - iOS ViewModel迁移 → 存储补全 → 验证机制 → 官网修复 + ✅ I12-I13 → ✅ B16/B17/B19 → B18 → B20-B22 → S6-S9 → W1-W3 + ✅ iOS 动效/无障碍（已完成） → ✅ COS 接入（已完成） → 文档导入解析 → 基础设施补全 → 验证机制 → 官网修复 第 4 批（App Store 前）： - I14-I18 → S10-S13 → W4-W7 - 埋点/CI/CD/测试 → 运营准备 → 官网细节 + I14-I17 → S10-S13 → W4-W7 + 埋点/崩溃监控/测试/Tab决策 → 运营准备 → 官网细节 第 5 批（远期）： B23-B26