224 lines
9.6 KiB
Markdown
224 lines
9.6 KiB
Markdown
# 知习 ZhiXi — iOS App
|
||
|
||
AI-first 系统化学习 App，SwiftUI + 深色主题。
|
||
|
||
## 导航关系
|
||
|
||
```
|
||
Splash（2s 自动跳转）
|
||
↓
|
||
Welcome（欢迎页）→ 已有账号 → Login
|
||
↓ 开始使用
|
||
Login（手机号/邮箱登录）
|
||
↓ 登录成功
|
||
Onboarding（4 步引导：输入知识 / 主动输出 / AI 分析 / 掌握知识）
|
||
↓ 下一步
|
||
GoalSetup（学习目标 / 方法 / 时间）
|
||
↓ 开始学习
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ 5-Tab 主界面 │
|
||
│ │
|
||
│ [AI] [知识库] [学习] [分析] [我的] │
|
||
│ │ │ │ │ │ │
|
||
│ ├─ 开始回答 ├─ 卡片点击 ├─ 任务点击 │ │ │
|
||
│ │ → Daily │ → Detail │ → Recall │ │ │
|
||
│ │ Thinking │ │ / Feedbk │ │ │
|
||
│ │ ├─ 创建 │ │ │ │
|
||
│ ├─ 快捷操作 │ → Create │ │ │ │
|
||
│ │ → Recall │ │ │ │ │
|
||
│ │ / Weak │ ┌ 知识点 │ │ │ │
|
||
│ │ │ ├ Detail │ │ │ │
|
||
│ └─ 互动列表 │ │ → KnwlD │ │ │ │
|
||
│ → AIChat │ ├ Add │ │ │ │
|
||
│ │ ├ Import │ │ │ │
|
||
│ │ └ Edit │ │ │ │
|
||
└──────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 页面清单（对照 React 原型 22 页）
|
||
|
||
| # | 页面 | 文件 | 状态 |
|
||
|---|------|------|------|
|
||
| 1 | Splash 启动页 | `AIStudyAppApp.swift` → `SplashPage` | ✅ |
|
||
| 2 | Welcome 欢迎页 | `AIStudyAppApp.swift` → `WelcomePage` | ✅ |
|
||
| 3 | Login 登录页 | `AIStudyAppApp.swift` → `LoginPage` | ✅ |
|
||
| 4 | Onboarding 引导页 | `AIStudyAppApp.swift` → `OnboardingPage` | ✅ |
|
||
| 5 | GoalSetup 目标设置 | `AIStudyAppApp.swift` → `GoalSetupPage` | ✅ |
|
||
| 6 | AIHome AI 首页 | `Features/AI/AIHomeView.swift` | ✅ |
|
||
| 7 | LibraryHome 知识库首页 | `Features/Library/LibraryHomeView.swift` | ✅ |
|
||
| 8 | StudyHome 学习工作台 | `Features/Study/StudyHomeView.swift` | ✅ |
|
||
| 9 | AnalysisHome 学习分析 | `Features/Analysis/AnalysisHomeView.swift` | ✅ |
|
||
| 10 | Profile 我的 | `Features/Profile/ProfileView.swift` | ✅ |
|
||
| 11 | AIChat AI 对话 | `Features/AI/AIChatPage.swift` | ✅ |
|
||
| 12 | DailyThinking 今日思考 | `Features/AI/DailyThinkingPage.swift` | ✅ |
|
||
| 13 | RecallTest 回忆测试 | `Features/AI/RecallTestPage.swift` | ✅ |
|
||
| 14 | WeakPoints 薄弱点分析 | `Features/AI/WeakPointsPage.swift` | ✅ |
|
||
| 15 | AIFeedback AI 反馈 | `Features/AI/AIFeedbackPageView.swift` | ✅ |
|
||
| 16 | Settings 设置 | `Features/Profile/SettingsView.swift` | ✅ |
|
||
| 17 | GoalSetting 学习目标 | `Features/Profile/GoalSettingDetailView.swift` | ✅ |
|
||
| 18 | MethodPreference 方法偏好 | `Features/Profile/MethodPreferenceView.swift` | ✅ |
|
||
| 19 | FeedbackForm 帮助反馈 | `Features/Profile/FeedbackFormView.swift` | ✅ |
|
||
| 20 | EditProfile 编辑资料 | `Features/Profile/ProfileView.swift` → `EditProfilePage` | ✅ |
|
||
| 21 | NotificationList 通知 | `Features/Profile/ProfileView.swift` → `NotificationListView` | ✅ |
|
||
| 22 | LibrarySearch 搜索知识库 | `Features/Library/LibraryHomeView.swift` | ✅ |
|
||
| 23 | LibraryDetail 知识库详情 | `Features/Library/LibrarySubpages.swift` | ✅ |
|
||
| 24 | AddKnowledge 添加知识点 | `Features/Library/LibrarySubpages.swift` | ✅ |
|
||
| 25 | KnowledgeDetail 知识点详情 | `Features/Library/LibrarySubpages.swift` | ✅ |
|
||
| 26 | EditKnowledge 编辑知识点 | `Features/Library/LibrarySubpages.swift` | ✅ |
|
||
| 27 | CreateLibrary 创建知识库 | `Features/Library/LibrarySubpages.swift` | ✅ |
|
||
| 28 | Import 导入资料 | `Features/Library/LibrarySubpages.swift` | ✅ |
|
||
| 29 | ActiveRecall 回忆测试 | `Features/Study/StudyHomeView.swift` → `ActiveRecallView` | ✅ |
|
||
| 30 | ReviewCard 间隔复习 | `Features/Study/ReviewCardView.swift` | ✅ |
|
||
| 31 | LearningSession 学习会话 | `Features/Study/LearningSessionView.swift` | ✅ |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
AIStudyApp/
|
||
├── AIStudyAppApp.swift # 根路由 + Splash/Welcome/Login/Onboarding/GoalSetup
|
||
├── ContentView.swift # 5-Tab 主界面 + ZXTabBar + ZXIconBtn + ZXScoreBox + ZXAIInputBar
|
||
├── Core/
|
||
│ ├── DesignSystem/
|
||
│ │ ├── DesignTokens.swift # 颜色 / 渐变 / 圆角 / 间距 / 字号 / zxFontScaled
|
||
│ │ └── ZXAnimations.swift # ZXPressModifier / ZXPullToRefresh / ZXLoadingView
|
||
│ ├── Models/
|
||
│ │ └── APIModels.swift # KnowledgeItem 等数据模型
|
||
│ └── Navigation/
|
||
│ └── Route.swift # 统一路由枚举 + navigationDestination 映射
|
||
└── Features/
|
||
├── AI/
|
||
│ ├── AIHomeView.swift # AI 首页
|
||
│ ├── DailyThinkingPage.swift # 今日思考
|
||
│ ├── AIChatPage.swift # AI 对话
|
||
│ ├── RecallTestPage.swift # 回忆测试
|
||
│ ├── WeakPointsPage.swift # 薄弱点分析
|
||
│ └── AIFeedbackPageView.swift # AI 反馈
|
||
├── Library/
|
||
│ ├── LibraryHomeView.swift # 知识库首页 + 搜索
|
||
│ └── LibrarySubpages.swift # 创建/详情/添加/导入/知识点详情/编辑
|
||
├── Study/
|
||
│ ├── StudyHomeView.swift # 学习工作台
|
||
│ ├── ReviewCardView.swift # 间隔复习卡片
|
||
│ └── LearningSessionView.swift # 学习会话
|
||
├── Analysis/
|
||
│ └── AnalysisHomeView.swift # 学习分析
|
||
└── Profile/
|
||
├── ProfileView.swift # 我的页 + EditProfilePage + NotificationListView
|
||
├── SettingsView.swift # 设置
|
||
├── GoalSettingDetailView.swift # 学习目标设置
|
||
├── MethodPreferenceView.swift # 学习方法偏好
|
||
└── FeedbackFormView.swift # 帮助与反馈
|
||
```
|
||
|
||
## 设计系统
|
||
|
||
| 类别 | Token | 值 |
|
||
|------|-------|-----|
|
||
| 主背景 | `Color.zxBg0` | `#0F0F1A` |
|
||
| 页面渐变 | `ZXGradient.page` | `#0F0F1A → #12122A` |
|
||
| 品牌紫 | `Color.zxPurple` | `#7C6EFA` |
|
||
| 品牌橙 | `Color.zxOrange` | `#F97316` |
|
||
| 文字主色 | `Color.zxF0` | `#F0F0FF` |
|
||
| 卡片圆角 | `ZXRadius.xl3` | `20` |
|
||
| 按钮高度 | `ZXSize.buttonH` | `42` |
|
||
| 页面水平间距 | `ZXSpacing.pageHPadding` | `20` |
|
||
| 状态栏高度 | `ZXSpacing.statusBarH` | `44` |
|
||
| TabBar 高度 | `ZXSpacing.tabBarH` | `83` |
|
||
|
||
以上全部从 React 原型 1:1 像素级提取。
|
||
|
||
## 运行
|
||
|
||
Xcode 打开 `AIStudyApp.xcodeproj`，选择 iPhone 17 Pro 模拟器，`Cmd+R`。
|
||
|
||
```
|
||
Clean Build 之前先：
|
||
rm -rf ~/Library/Developer/Xcode/DerivedData/AIStudyApp-*
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
### Debug 模式（本地开发）
|
||
|
||
Debug 构建自动连接本地 API（`http://127.0.0.1:3000`），通过 `Debug.xcconfig` 配置：
|
||
|
||
```
|
||
API_BASE_URL = http://127.0.0.1:3000
|
||
```
|
||
|
||
Info.plist 已配置 ATS 豁免 localhost。
|
||
|
||
### Release 模式（生产）
|
||
|
||
Release 构建连接生产 API（`https://api.longde.cloud`）。
|
||
|
||
### 切换 API 地址
|
||
|
||
编辑 `AIStudyApp/Config/Debug.xcconfig` 中的 `API_BASE_URL`。
|
||
|
||
## Rust FFI 集成
|
||
|
||
知习跨平台文档内核 `zhixi-document-runtime` 通过 UniFFI 生成 Swift 绑定。
|
||
|
||
### 构建流程
|
||
|
||
```bash
|
||
# 在 zhixi-document-runtime 仓库
|
||
cd zhixi-document-runtime
|
||
./scripts/build-ios.sh
|
||
|
||
# 生成的 Swift 文件复制到 iOS 项目
|
||
# → AIStudyApp/Core/FFI/zhixi_document_core.swift
|
||
```
|
||
|
||
### 集成功能
|
||
|
||
- 文件类型检测
|
||
- Markdown / TXT / EPUB 解析
|
||
- PDF 阅读位置管理
|
||
- 图片元数据提取
|
||
- 阅读时长事件
|
||
- 全文搜索和笔记锚点
|
||
|
||
详见 `zhixi-document-runtime/docs/ios-integration.md`
|
||
|
||
## App Store 提审
|
||
|
||
提审相关文档见 `ios-projects/docs/`：
|
||
- App Store 提审清单
|
||
- Firebase 集成
|
||
- Rust FFI 更新
|
||
- 阅读信息集成
|
||
|
||
## 依赖
|
||
|
||
| 依赖 | 用途 |
|
||
|------|------|
|
||
| SwiftUI | UI 框架 |
|
||
| Firebase | 推送通知 / Analytics（可选） |
|
||
| zhixi-document-runtime | 跨平台文档内核（Rust FFI） |
|
||
|
||
## 调试日志
|
||
|
||
所有 `print()` 输出使用 `[PageName]` 前缀标记页面来源：
|
||
|
||
```swift
|
||
print("[ImportPage] 文件导入完成")
|
||
print("[AIChat] 消息发送: \(message)")
|
||
```
|
||
|
||
在 Xcode Console 中可通过前缀过滤日志。
|
||
|
||
## 最近修复记录
|
||
|
||
### 2026-05-19 — NavigationStack 迁移 + Dynamic Type
|
||
|
||
- **路由系统重构**：全部 `NavigationLink(destination:)` → `NavigationLink(value: Route)`，新增 `Core/Navigation/Route.swift` 统一路由枚举
|
||
- **Dynamic Type 支持**：新增 `zxFontScaled` ViewModifier，基于 `@ScaledMetric`
|
||
- **手势冲突修复**：`ZXPressModifier` 从 `DragGesture` 改为 `onLongPressGesture(minimumDuration: .infinity)` 解决与 ScrollView 冲突
|
||
- **触控目标放大**：`ZXIconBtn` 36pt → 44pt
|
||
- **大文件拆分**：从 `DailyThinkingPage.swift` 拆出 4 个子页面，从 `SettingsView.swift` 拆出 3 个子页面
|
||
- **TabBar 胶囊指示器**：选中 Tab 上方紫色 Capsule 替代旧圆形指示器
|
||
- **ZXSTask 颜色模型**：`Color` → hex `String`，支持 Hashable 路由参数
|
||
- **ZXAIInputBar 重构**：提取为共享组件，padding 由调用方控制
|