startup-plan/技术设计/ios-projects/功能需求清单.md

# 个人开发者创业 v0.1 — iOS 相关需求整理

> 来源：`startup-plan/个人开发者创业 v0.1/` 各文档
> 整理时间：2026-05-10 | 状态更新：2026-05-17
> 
> 已实现功能详见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md)
> 待补全项详见 [`缺失项与待补全方向.md`](./已完成/[已完成]-缺失项与待补全方向.md)

本文档从 v0.1 创业计划中提取所有与 iOS 客户端直接相关的内容，作为 iOS 开发的参考基线。

---

## 一、产品定位（来源：`0-项目总纲/项目总纲.md`）

- 产品长期方向：AI 驱动的系统化学习产品（知识库 + 笔记 + AI 学习教练 + 复习计划）
- 当前只做三件事：确定方向 → 做 14 天验证 Demo → 找第一批真实反馈
- 平台策略：**只做 iPhone**，不做 Android/iPad/Mac/Web 学习端
- 不做：完整平台、泛学习大而全、复杂后端、支付

### 三个候选方向

1. 公考申论 AI 学习教练
2. AI 工具学习知识库
3. 程序员/前端面试学习助手

---

## 二、第一版产品形态（来源：`2-Demo与MVP/Demo与MVP.md`）

```
iPhone App + 官网基础页面 + 最小后端 + AI API
```

### MVP 核心学习闭环

```
注册/登录 → 选择学习方向 → 进入学习路径 → 阅读知识内容
→ 主动回忆/写笔记/写答案 → AI 分析 → 生成学习状态
→ 给出复习和下一步建议 → 进入下一次学习
```

### 第一版页面列表（计划 14 页）

| 优先级 | 页面 | 当前 iOS 实现 |
|--------|------|---------------|
| **P0** | 登录页 | `LoginPage` ✅ |
| **P0** | 学习方向选择页 | `GoalSetupPage` ✅ (部分) |
| **P0** | 学习路径页 | `LibraryHomeView` + `LibraryDetailPage` ✅ |
| **P0** | 今日学习任务页 | `StudyHomeView` ✅ |
| **P0** | 内容阅读页 | `KnowledgeDetailPage` ✅ |
| **P0** | 主动回忆/笔记输入页 | `DailyThinkingPage` + `RecallTestPage` ✅ |
| **P0** | AI 分析结果页 | `AIFeedbackPage` ✅ |
| **P0** | AI 对话页 | `AIChatPage` ✅ |
| **P0** | 复习计划页 | `ReviewPlanView` ✅ |
| **P1** | 学习进度页 | `AnalysisHomeView` ✅ |
| **P1** | 设置页 | `ProfileView` ✅（含 5 个子页面 + 外观/语言切换） |
| **P1** | 反馈页 | `FeedbackView` + `FeedbackViewModel` ✅ |
| **P1** | 启动页/欢迎页 | `SplashPage` + `WelcomePage` ✅ |
| **P1** | 语言与基础偏好页 | 设置页内语言切换 ✅ |

### 底部 Tab 设计（计划）

```
学习 | 知识库 | AI助手 | 我的
```

当前 iOS 实现为 5 个 Tab：`AI | 知识库 | 学习 | 分析 | 我的`（多了"分析"Tab，将计划的 AI 助手拆分为独立的分析页）

---

## 三、账号体系（来源：`2-Demo与MVP/Demo与MVP.md`）

- **第一版登录方式**：Sign in with Apple
- **暂不做**：微信登录、手机号登录、邮箱密码登录、Google 登录

> ⚠️ 当前 iOS `LoginPage` 包含了手机号/邮箱登录 + 微信/Apple 登录 UI，与计划"A Sign in with Apple"的要求不完全一致。计划强调极简，实际 UI 做了更多登录方式入口。

### 用户身份模型（计划）

```
User
├── id
├── appleUserId
├── displayName
├── email
├── preferredLanguage
├── createdAt
├── lastLoginAt
└── status
```

---

## 四、知识库设计（来源：`2-Demo与MVP/Demo与MVP.md`）

### 数据结构

```
KnowledgeBase → LearningPath → Module → Lesson
                                      ├── 正文内容
                                      ├── 学习目标
                                      ├── 重点概念
                                      ├── 主动回忆问题
                                      ├── 练习输入
                                      └── AI 分析规则
```

### 第一版内容范围

只做一个小路径，例如"AI 工具入门 7 天路径"，而不是大而全的知识库市场。

---

## 五、AI 能力需求（来源：`2-Demo与MVP/Demo与MVP.md`）

### AI 三大核心职责

1. 分析用户输入
2. 判断用户当前学习状态
3. 给出下一步学习建议

### AI 分析维度

```
理解程度、要点覆盖、逻辑结构、表达清晰度、错误理解、遗漏内容、下一步建议
```

### AI 输出结构（计划 JSON Schema）

```json
{
  "masteryScore": 3,
  "understandingLevel": "基本理解",
  "summary": "用户能说出核心意思，但要点不够完整。",
  "strengths": ["能识别主要问题", "表达比较清楚"],
  "weakPoints": ["遗漏关键要点", "逻辑层次不够清晰"],
  "suggestions": ["补充材料中的第二个要点", "回答时先概括问题，再展开原因"],
  "reviewNeeded": true,
  "nextAction": "建议明天复习本节，并重新回答主动回忆问题。"
}
```

### 掌握度评分（0-5）

```
0 = 没有作答/无法判断
1 = 基本没理解
2 = 理解较弱
3 = 基本理解
4 = 理解较好
5 = 掌握很好
```

### AI 对话页定位

只能围绕当前知识库和学习内容，不能做泛聊天。快捷问题预设：
- 帮我解释这一节
- 用更简单的话讲
- 给我举个例子
- 我哪里理解错了
- 帮我总结重点
- 生成一个复习问题

---

## 六、学习状态模型（来源：`2-Demo与MVP/Demo与MVP.md`）

### 用户学习画像

```
UserLearningProfile
├── userId
├── currentKnowledgeBaseId
├── currentPathId
├── currentLessonId
├── overallLevel
├── weakPoints
├── strengths
├── recentMistakes
├── reviewQueue
├── learningStreak
└── updatedAt
```

### 单次学习记录

```
LearningSession
├── id
├── userId
├── lessonId
├── startedAt
├── endedAt
├── userInput
├── aiAnalysis
├── masteryScore
├── weakPoints
├── nextSuggestion
└── reviewAt
```

### 复习任务

```
ReviewTask
├── id
├── userId
├── lessonId
├── sourceSessionId
├── reviewType
├── scheduledAt
├── completedAt
└── status
```

---

## 七、UI 设计原则（来源：`2-Demo与MVP/Demo与MVP.md`）

```
安静、清晰、克制、学习感、低干扰、Apple原生感、卡片式结构、适合长时间阅读
```

- 不做花哨视觉
- 不做复杂动画
- 不做社交信息流
- 不做游戏化过重设计
- 优先保证阅读体验
- 优先保证学习任务清晰
- 优先保证 AI 分析结果可理解

---

## 八、技术选型（来源：`3-官网与技术基础/官网与技术基础.md`）

| 项目 | 计划选型 | 当前实现 |
|------|----------|----------|
| UI 框架 | SwiftUI | SwiftUI ✅ |
| 架构模式 | MVVM + Service + Repository | 无分层（View 内聚）⚠️ |
| 设计规范 | Apple HIG | 深色主题 + 自定义 DesignTokens ✅ |
| 动效策略 | 轻量、有意义、服务学习体验 | 最小动效（仅基础过渡）⚠️ |
| 多语言 | 预留架构，中文默认 | 未实现 ❌ |
| 部署 | 4 核 4G 轻量云 + Nginx + Docker | 未接入 ❌ |

### 目录结构（计划 vs 实际）

计划定义了完整的分层目录（App/Core/Features/Shared/Resources），当前实现仅有 Features 和 DesignSystem，缺少 Network、Auth、Storage、Localization、ViewModel、Model 等层。

### 第一版 iOS 不做（来自计划）

- 复杂动画系统
- iPad 专门布局 / Mac Catalyst / Watch App / Widget
- 离线完整知识库
- 复杂搜索
- 文件导入
- 推送通知
- 支付订阅
- 复杂自定义控件

---

## 九、数据实体汇总（来源：`2-Demo与MVP/Demo与MVP.md`）

```
User
KnowledgeBase
LearningPath
Lesson
LearningSession
AIAnalysis
ReviewTask
Feedback
WaitlistEntry
```

---

## 十、核心 API 接口（来源：`3-官网与技术基础/官网与技术基础.md`）

### POST /ai/analyze-learning-input

分析用户学习输入，返回掌握度评估。

### POST /ai/chat

AI 对话接口，限于当前知识库上下文。

### 后端模块（P0）

Auth → User → Knowledge → Learning → AI → Review → Feedback → Waitlist

---

## 十一、成功标准（来源：`2-Demo与MVP/Demo与MVP.md`）

### 产品可用标准

- 用户能登录
- 用户能选择学习路径
- 用户能完成一节学习
- 用户能输入内容
- AI 能返回分析
- 系统能生成复习建议
- 用户知道下一步该干什么

### 验证成功标准

- 至少 10 个用户愿意试用
- 至少 3 个用户完整走完学习闭环
- 至少 3 条有效反馈
- 至少 1 个用户表示愿意继续用
- 至少 1 个用户表示未来愿意付费

---

## 十二、暂缓事项（来源：`99-暂缓事项/暂缓事项.md`）

以下为 v0.1 明确不做、后续解冻的事项：

| 类别 | 暂缓内容 | 解冻条件 |
|------|----------|----------|
| 商业化 | Apple IAP、订阅、免费试用 | TestFlight 有真实用户 + 有人愿意付费 |
| 运营 | 社群、客服机器人、打卡活动 | 10+ 内测用户持续反馈 |
| 数据 | 完整埋点、留存分析、付费转化 | App Store MVP 准备上线 |
| 合规 | 公司注册、微信/支付宝、备案 | Apple 端稳定收入 |
| 多端 | iPad、Mac、Android、Web | iPhone 核心稳定 + 用户多端需求 |

---

## 十三、当前 iOS 实现与计划的差距

| 维度 | 计划要求 | 当前状态 | 差距 |
|------|----------|----------|------|
| 登录 | Sign in with Apple | Apple 登录 ✅ | 已实现 |
| 架构 | MVVM + Service | 部分 MVVM + Service 层 ✅ | ViewModel 迁移进行中 |
| 多语言 | 架构预留 | Localizable.strings + LanguageManager ✅ | 仅中文，英文待补 |
| 后端对接 | REST API | Auth 已对接 ✅ | 其他页面待接 |
| AI 集成 | 真实 AI 分析 | 静态 Mock | 待接后端 AI API |
| 数据持久化 | 本地缓存 + Keychain | Keychain ✅ | 本地缓存待建 |
| Tab 设计 | 4 个 Tab | 5 个 Tab | 待决策 |
| 反馈页 | P1 优先级 | ✅ | — |
| 复习计划页 | P0 优先级 | ✅ | — |