958 lines
21 KiB
Markdown
958 lines
21 KiB
Markdown
|
---
|
|||
|
|
version: v0.1
|
|||
|
|
status: draft
|
|||
|
|
updated: 2026-05-03
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 官网与技术基础
|
|||
|
|
|
|||
|
|
## 1. 当前技术目标
|
|||
|
|
|
|||
|
|
v0.1 阶段的技术目标不是做完整大系统，而是搭建一个可持续迭代的最小技术底座。
|
|||
|
|
|
|||
|
|
**当前需要支持：**
|
|||
|
|
|
|||
|
|
1. iPhone App Demo / MVP
|
|||
|
|
2. Sign in with Apple 登录
|
|||
|
|
3. AI API 调用
|
|||
|
|
4. 用户学习记录保存
|
|||
|
|
5. AI 分析结果保存
|
|||
|
|
6. 学习状态模型
|
|||
|
|
7. 官网基础页面
|
|||
|
|
8. 等待名单和反馈入口
|
|||
|
|
9. 后续可扩展到 TestFlight、App Store、iPad、Mac、Android
|
|||
|
|
|
|||
|
|
**当前不追求：**
|
|||
|
|
|
|||
|
|
- 高并发
|
|||
|
|
- 完整后台管理系统
|
|||
|
|
- 完整支付系统
|
|||
|
|
- 完整内容管理系统
|
|||
|
|
- 复杂微服务
|
|||
|
|
- 复杂云原生架构
|
|||
|
|
- 多端同步
|
|||
|
|
- 企业级权限系统
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 技术总原则
|
|||
|
|
|
|||
|
|
### 2.1 用熟悉技术优先
|
|||
|
|
|
|||
|
|
当前是个人开发者阶段，技术选型优先考虑：
|
|||
|
|
|
|||
|
|
- 自己能理解
|
|||
|
|
- AI Agent 容易生成
|
|||
|
|
- 出问题容易排查
|
|||
|
|
- 部署简单
|
|||
|
|
- 成本低
|
|||
|
|
- 后续能扩展
|
|||
|
|
|
|||
|
|
### 2.2 架构要清晰，但不能过度设计
|
|||
|
|
|
|||
|
|
原则：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
代码结构清晰 > 技术炫技
|
|||
|
|
可维护 > 复杂
|
|||
|
|
能上线 > 完美
|
|||
|
|
能验证 > 大而全
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.3 前后端职责分离
|
|||
|
|
|
|||
|
|
| 端 | 职责 |
|
|||
|
|
|---|------|
|
|||
|
|
| iOS 客户端 | 页面展示、用户交互、本地状态、登录入口、学习流程体验 |
|
|||
|
|
| 后端 | 用户身份记录、AI API 代理、学习记录保存、AI 分析结果保存、学习画像更新、反馈收集、等待名单 |
|
|||
|
|
| AI 模型 | 分析用户输入、生成学习反馈、识别薄弱点、生成复习建议、辅助学习对话 |
|
|||
|
|
| 官网 | 产品介绍、SEO、隐私政策、用户协议、支持页面、等待名单、TestFlight 招募、未来 Mac DMG 下载 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 当前推荐最终选型
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
iOS：SwiftUI
|
|||
|
|
iOS 架构：MVVM + Service + Repository
|
|||
|
|
设计规范：Apple Human Interface Guidelines
|
|||
|
|
UI 风格：Apple 原生感、安静、克制、学习感
|
|||
|
|
动效策略：轻量、有意义、服务学习体验
|
|||
|
|
官网：Astro
|
|||
|
|
官网域名：longde.cloud
|
|||
|
|
后端：NestJS + TypeScript
|
|||
|
|
数据库：MySQL
|
|||
|
|
缓存：Redis，先预留，可延后
|
|||
|
|
AI：Provider 抽象 + 一个真实模型 + MockProvider
|
|||
|
|
AI 记忆：结构化学习画像，不急着做复杂 Agent Memory
|
|||
|
|
部署：现有 4 核 4G 轻量云
|
|||
|
|
反向代理：Nginx
|
|||
|
|
进程/容器：Docker Compose 或 PM2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
当前不买新服务器，不做复杂架构，先把最小闭环跑通。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 整体技术架构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
iPhone App
|
|||
|
|
├── SwiftUI
|
|||
|
|
├── Sign in with Apple
|
|||
|
|
├── 本地缓存
|
|||
|
|
└── API Client
|
|||
|
|
↓
|
|||
|
|
后端 API
|
|||
|
|
├── 用户模块
|
|||
|
|
├── 学习记录模块
|
|||
|
|
├── AI 代理模块
|
|||
|
|
├── 学习画像模块
|
|||
|
|
├── 反馈模块
|
|||
|
|
└── 等待名单模块
|
|||
|
|
↓
|
|||
|
|
数据库
|
|||
|
|
├── MySQL
|
|||
|
|
└── Redis（可选）
|
|||
|
|
↓
|
|||
|
|
AI 服务
|
|||
|
|
├── MiniMax / DeepSeek / 通义 / OpenAI / Claude / Gemini
|
|||
|
|
└── 后续可替换
|
|||
|
|
↓
|
|||
|
|
官网
|
|||
|
|
├── Astro
|
|||
|
|
├── SEO 页面
|
|||
|
|
├── 隐私政策
|
|||
|
|
├── 用户协议
|
|||
|
|
└── 等待名单
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. iOS 客户端技术选型
|
|||
|
|
|
|||
|
|
### 5.1 技术选择
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
Swift
|
|||
|
|
SwiftUI
|
|||
|
|
Xcode
|
|||
|
|
MVVM
|
|||
|
|
Service 层
|
|||
|
|
Repository 层
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**选择原因：**
|
|||
|
|
|
|||
|
|
1. 当前第一阶段只做 Apple 平台
|
|||
|
|
2. SwiftUI 适合快速做原型和 MVP
|
|||
|
|
3. 原生体验更适合长期做 iPhone、iPad、Mac
|
|||
|
|
4. Apple 生态的动画、交互、系统组件体验好
|
|||
|
|
5. 后续可以逐步学习和沉淀原生开发能力
|
|||
|
|
|
|||
|
|
### 5.2 SwiftUI 学习策略
|
|||
|
|
|
|||
|
|
学习顺序：
|
|||
|
|
|
|||
|
|
1. Swift 基础语法
|
|||
|
|
2. SwiftUI 页面布局
|
|||
|
|
3. NavigationStack 页面跳转
|
|||
|
|
4. TabView 底部导航
|
|||
|
|
5. Form / List / ScrollView
|
|||
|
|
6. ObservableObject / State / Binding
|
|||
|
|
7. 网络请求
|
|||
|
|
8. 本地存储
|
|||
|
|
9. Sign in with Apple
|
|||
|
|
10. 简单动画和转场
|
|||
|
|
|
|||
|
|
第一版 UI 优先使用系统组件，尽量做出 Apple 原生感。
|
|||
|
|
|
|||
|
|
### 5.3 iOS 目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
AIStudyApp/
|
|||
|
|
├── App/
|
|||
|
|
│ ├── AIStudyApp.swift
|
|||
|
|
│ ├── AppConfig.swift
|
|||
|
|
│ └── AppRouter.swift
|
|||
|
|
│
|
|||
|
|
├── Core/
|
|||
|
|
│ ├── Network/
|
|||
|
|
│ │ ├── APIClient.swift
|
|||
|
|
│ │ ├── APIEndpoint.swift
|
|||
|
|
│ │ └── APIError.swift
|
|||
|
|
│ │
|
|||
|
|
│ ├── Auth/
|
|||
|
|
│ │ ├── AppleSignInService.swift
|
|||
|
|
│ │ └── AuthSession.swift
|
|||
|
|
│ │
|
|||
|
|
│ ├── Storage/
|
|||
|
|
│ │ ├── LocalStorage.swift
|
|||
|
|
│ │ └── KeychainService.swift
|
|||
|
|
│ │
|
|||
|
|
│ ├── Localization/
|
|||
|
|
│ │ └── LocalizationManager.swift
|
|||
|
|
│ │
|
|||
|
|
│ └── DesignSystem/
|
|||
|
|
│ ├── AppColors.swift
|
|||
|
|
│ ├── AppTypography.swift
|
|||
|
|
│ ├── AppSpacing.swift
|
|||
|
|
│ └── Components/
|
|||
|
|
│
|
|||
|
|
├── Features/
|
|||
|
|
│ ├── Onboarding/
|
|||
|
|
│ │ ├── Views/
|
|||
|
|
│ │ ├── ViewModels/
|
|||
|
|
│ │ └── Models/
|
|||
|
|
│ │
|
|||
|
|
│ ├── Auth/
|
|||
|
|
│ │ ├── Views/
|
|||
|
|
│ │ └── ViewModels/
|
|||
|
|
│ │
|
|||
|
|
│ ├── Learning/
|
|||
|
|
│ │ ├── Views/
|
|||
|
|
│ │ ├── ViewModels/
|
|||
|
|
│ │ └── Models/
|
|||
|
|
│ │
|
|||
|
|
│ ├── KnowledgeBase/
|
|||
|
|
│ │ ├── Views/
|
|||
|
|
│ │ ├── ViewModels/
|
|||
|
|
│ │ └── Models/
|
|||
|
|
│ │
|
|||
|
|
│ ├── AIAssistant/
|
|||
|
|
│ │ ├── Views/
|
|||
|
|
│ │ ├── ViewModels/
|
|||
|
|
│ │ └── Models/
|
|||
|
|
│ │
|
|||
|
|
│ ├── Review/
|
|||
|
|
│ │ ├── Views/
|
|||
|
|
│ │ ├── ViewModels/
|
|||
|
|
│ │ └── Models/
|
|||
|
|
│ │
|
|||
|
|
│ └── Profile/
|
|||
|
|
│ ├── Views/
|
|||
|
|
│ ├── ViewModels/
|
|||
|
|
│ └── Models/
|
|||
|
|
│
|
|||
|
|
├── Shared/
|
|||
|
|
│ ├── Components/
|
|||
|
|
│ ├── Extensions/
|
|||
|
|
│ ├── Utils/
|
|||
|
|
│ └── Constants/
|
|||
|
|
│
|
|||
|
|
└── Resources/
|
|||
|
|
├── Localizable.xcstrings
|
|||
|
|
├── Assets.xcassets
|
|||
|
|
└── PreviewData/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.4 iOS 模块说明
|
|||
|
|
|
|||
|
|
| 模块 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| App | 负责 App 入口、全局配置、路由 |
|
|||
|
|
| Core | 负责底层能力：网络请求、登录、本地存储、Keychain、多语言、设计系统 |
|
|||
|
|
| Features | 按业务模块拆分：Onboarding、Auth、Learning、KnowledgeBase、AIAssistant、Review、Profile |
|
|||
|
|
| Shared | 存放通用组件、工具函数、扩展 |
|
|||
|
|
| Resources | 存放资源文件、多语言、图片、测试数据 |
|
|||
|
|
|
|||
|
|
### 5.5 iOS 第一版不做
|
|||
|
|
|
|||
|
|
- 复杂动画系统
|
|||
|
|
- 自定义复杂控件
|
|||
|
|
- iPad 专门布局
|
|||
|
|
- Mac Catalyst
|
|||
|
|
- Watch App
|
|||
|
|
- Widget
|
|||
|
|
- 离线完整知识库
|
|||
|
|
- 复杂搜索
|
|||
|
|
- 文件导入
|
|||
|
|
- 推送通知
|
|||
|
|
- 支付订阅
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Apple 设计规范与动效原则
|
|||
|
|
|
|||
|
|
### 6.1 设计基准
|
|||
|
|
|
|||
|
|
本产品第一阶段优先做 Apple 平台，因此 UI/UX 设计需要参考 Apple Human Interface Guidelines。
|
|||
|
|
|
|||
|
|
第一版设计目标不是做复杂视觉，而是做出：
|
|||
|
|
|
|||
|
|
- 原生感
|
|||
|
|
- 安静感
|
|||
|
|
- 学习感
|
|||
|
|
- 清晰的层级
|
|||
|
|
- 流畅的交互
|
|||
|
|
- 适度高级感
|
|||
|
|
- 符合 Apple 用户习惯的体验
|
|||
|
|
|
|||
|
|
### 6.2 HIG 设计原则
|
|||
|
|
|
|||
|
|
1. **内容优先** — 学习内容、任务和 AI 分析结果应该是页面中心
|
|||
|
|
2. **层级清晰** — 用户应该很清楚当前在哪、今天要做什么、下一步做什么
|
|||
|
|
3. **交互克制** — 不做过多按钮，不堆功能，不制造干扰
|
|||
|
|
4. **系统一致** — 尽量使用 Apple 原生组件、系统字体、系统导航、系统交互
|
|||
|
|
5. **可访问性** — 字体大小、颜色对比、动态效果都要考虑不同用户
|
|||
|
|
6. **动效有意义** — 动效用于反馈、状态变化、页面过渡和学习进度表达，不做无意义炫技
|
|||
|
|
|
|||
|
|
### 6.3 动效优先级
|
|||
|
|
|
|||
|
|
**P0 必须做：**
|
|||
|
|
- 页面进入 / 返回的自然过渡
|
|||
|
|
- 按钮点击反馈
|
|||
|
|
- 加载状态
|
|||
|
|
- AI 分析中状态
|
|||
|
|
- 学习完成反馈
|
|||
|
|
|
|||
|
|
**P1 建议做：**
|
|||
|
|
- 今日任务卡片动效
|
|||
|
|
- 进度条更新动效
|
|||
|
|
- AI 分析结果分块出现
|
|||
|
|
- 复习建议卡片出现
|
|||
|
|
|
|||
|
|
**P2 延后做：**
|
|||
|
|
- 启动页品牌动画
|
|||
|
|
- 高级图表动效
|
|||
|
|
- 大范围转场动画
|
|||
|
|
- 自定义复杂动画
|
|||
|
|
|
|||
|
|
### 6.4 SwiftUI 动效实现策略
|
|||
|
|
|
|||
|
|
第一版优先使用 SwiftUI 原生能力：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
withAnimation
|
|||
|
|
transition
|
|||
|
|
opacity
|
|||
|
|
scaleEffect
|
|||
|
|
ProgressView
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
谨慎使用：
|
|||
|
|
```text
|
|||
|
|
matchedGeometryEffect
|
|||
|
|
PhaseAnimator
|
|||
|
|
SymbolEffect
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
第一版不追求复杂自定义动画系统。目标是让 App 看起来顺滑、有质感，而不是炫技。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. SwiftUI + AI Agent 开发策略
|
|||
|
|
|
|||
|
|
### 7.1 基本判断
|
|||
|
|
|
|||
|
|
创始人当前没有 SwiftUI 实战经验，但可以借助 AI Agent 完成开发。
|
|||
|
|
|
|||
|
|
这不影响第一版使用 SwiftUI。原因：
|
|||
|
|
|
|||
|
|
1. SwiftUI 适合快速构建 Apple 原生界面
|
|||
|
|
2. AI Agent 对 SwiftUI 页面、组件、ViewModel 的生成能力较强
|
|||
|
|
3. 只要目录结构清晰、任务拆分明确，AI 可以辅助完成大量开发
|
|||
|
|
4. 创始人需要掌握的是架构、产品逻辑、代码审查和调试能力
|
|||
|
|
|
|||
|
|
### 7.2 AI 开发原则
|
|||
|
|
|
|||
|
|
使用 AI 开发 SwiftUI 时，必须遵守：
|
|||
|
|
|
|||
|
|
1. 每次只让 AI 修改一个模块
|
|||
|
|
2. 每次生成前先说明目录和目标文件
|
|||
|
|
3. 不允许 AI 随意改全局架构
|
|||
|
|
4. 不允许 AI 把所有代码写进一个 View
|
|||
|
|
5. 页面、ViewModel、Model、Service 分开
|
|||
|
|
6. 复杂逻辑放到 Service，不堆在 View 里
|
|||
|
|
7. UI 组件尽量复用
|
|||
|
|
8. 每完成一个页面就真机预览或模拟器运行
|
|||
|
|
|
|||
|
|
### 7.3 推荐开发顺序
|
|||
|
|
|
|||
|
|
1. 创建项目骨架
|
|||
|
|
2. 建立 DesignSystem
|
|||
|
|
3. 建立 Tab 结构
|
|||
|
|
4. 建立 Onboarding 页面
|
|||
|
|
5. 建立 Apple 登录页面
|
|||
|
|
6. 建立学习路径页面
|
|||
|
|
7. 建立今日任务页面
|
|||
|
|
8. 建立内容阅读页面
|
|||
|
|
9. 建立主动回忆输入页面
|
|||
|
|
10. 建立 AI 分析结果页面
|
|||
|
|
11. 建立 AI 助手页面
|
|||
|
|
12. 建立我的 / 设置 / 反馈页面
|
|||
|
|
|
|||
|
|
### 7.4 AI 生成代码时的提示原则
|
|||
|
|
|
|||
|
|
每次让 AI 写代码时，要明确：
|
|||
|
|
|
|||
|
|
- 当前模块
|
|||
|
|
- 目标文件
|
|||
|
|
- 不要修改哪些文件
|
|||
|
|
- 使用 SwiftUI
|
|||
|
|
- 使用 MVVM
|
|||
|
|
- 使用已有 DesignSystem
|
|||
|
|
- 不写死颜色和字体
|
|||
|
|
- 支持多语言 key
|
|||
|
|
- 页面要支持深色模式
|
|||
|
|
- 页面要适配不同 iPhone 尺寸
|
|||
|
|
|
|||
|
|
### 7.5 第一版代码质量底线
|
|||
|
|
|
|||
|
|
底线：
|
|||
|
|
|
|||
|
|
- 不把业务逻辑写在 View 里
|
|||
|
|
- 不把 API Key 写在客户端
|
|||
|
|
- 不写大量重复 UI
|
|||
|
|
- 不写死所有文案
|
|||
|
|
- 不把 AI Prompt 写死在 iOS 端
|
|||
|
|
- 不让一个文件超过过大规模
|
|||
|
|
- 不做无法维护的一次性 Demo
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 官网技术选型
|
|||
|
|
|
|||
|
|
### 8.1 官网定位
|
|||
|
|
|
|||
|
|
官网不是 Web 学习系统，而是产品基础设施。
|
|||
|
|
|
|||
|
|
官网第一阶段承担：
|
|||
|
|
|
|||
|
|
- 产品介绍
|
|||
|
|
- SEO 收录
|
|||
|
|
- 等待名单
|
|||
|
|
- TestFlight 招募
|
|||
|
|
- 隐私政策
|
|||
|
|
- 用户协议
|
|||
|
|
- 支持页面
|
|||
|
|
- 更新日志
|
|||
|
|
- 未来 Mac DMG 下载
|
|||
|
|
|
|||
|
|
### 8.2 框架选择
|
|||
|
|
|
|||
|
|
| 框架 | 优点 | 缺点 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| Astro | 适合内容型网站、SEO 友好、静态页面性能好、适合官网博客文档、比 Nuxt/Next 更轻 | 未来做 Web App 需要另起项目 |
|
|||
|
|
| Nuxt | Vue 生态、适合 SSR/SSG | 对纯官网来说稍重 |
|
|||
|
|
| Next.js | React 生态强、SSR/SSG 成熟 | 对当前阶段偏重 |
|
|||
|
|
| VitePress | 文档站很快 | 视觉自由度不如 Astro |
|
|||
|
|
|
|||
|
|
**推荐：Astro**
|
|||
|
|
|
|||
|
|
### 8.3 官网页面结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
website/
|
|||
|
|
├── src/
|
|||
|
|
│ ├── pages/
|
|||
|
|
│ │ ├── index.astro
|
|||
|
|
│ │ ├── privacy.astro
|
|||
|
|
│ │ ├── terms.astro
|
|||
|
|
│ │ ├── support.astro
|
|||
|
|
│ │ ├── waitlist.astro
|
|||
|
|
│ │ ├── download.astro
|
|||
|
|
│ │ └── changelog.astro
|
|||
|
|
│ │
|
|||
|
|
│ ├── layouts/
|
|||
|
|
│ │ └── BaseLayout.astro
|
|||
|
|
│ │
|
|||
|
|
│ ├── components/
|
|||
|
|
│ │ ├── Hero.astro
|
|||
|
|
│ │ ├── FeatureCard.astro
|
|||
|
|
│ │ ├── CTA.astro
|
|||
|
|
│ │ └── Footer.astro
|
|||
|
|
│ │
|
|||
|
|
│ ├── content/
|
|||
|
|
│ │ └── posts/
|
|||
|
|
│ │
|
|||
|
|
│ └── styles/
|
|||
|
|
│ └── global.css
|
|||
|
|
│
|
|||
|
|
├── public/
|
|||
|
|
│ ├── images/
|
|||
|
|
│ └── favicon.svg
|
|||
|
|
│
|
|||
|
|
└── package.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 8.4 SEO 规划
|
|||
|
|
|
|||
|
|
**第一版 SEO 重点：**
|
|||
|
|
|
|||
|
|
- 首页标题、描述、关键词
|
|||
|
|
- Open Graph 分享图
|
|||
|
|
- sitemap.xml
|
|||
|
|
- robots.txt
|
|||
|
|
- 清晰 URL 结构
|
|||
|
|
- 更新日志内容
|
|||
|
|
- 长尾关键词页面
|
|||
|
|
|
|||
|
|
**当前不做：**
|
|||
|
|
- 复杂 SEO 工具链
|
|||
|
|
- 大量采集文章
|
|||
|
|
- 自动生成垃圾内容
|
|||
|
|
- 过度关键词堆砌
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 后端技术选型
|
|||
|
|
|
|||
|
|
### 9.1 是否需要后端
|
|||
|
|
|
|||
|
|
v0.1 需要最小后端，原因：
|
|||
|
|
|
|||
|
|
1. AI API Key 不能放在 iOS 客户端
|
|||
|
|
2. 用户登录后需要保存用户身份
|
|||
|
|
3. 学习记录需要保存
|
|||
|
|
4. AI 分析结果需要保存
|
|||
|
|
5. 学习状态模型需要后端维护
|
|||
|
|
6. 等待名单和反馈需要收集
|
|||
|
|
7. 后续订阅权益需要后端基础
|
|||
|
|
|
|||
|
|
### 9.2 技术对比
|
|||
|
|
|
|||
|
|
| 技术 | 优点 | 缺点 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| NestJS | 模块清晰、适合长期、TypeScript 生态好、AI Agent 容易按模块生成代码 | 学习成本稍高 |
|
|||
|
|
| Express | 简单、学习成本低、快速启动 | 大项目容易混乱、AI Agent 写多了容易堆代码 |
|
|||
|
|
| FastAPI | Python 生态适合 AI、写 API 很快、后续接 AI/RAG 方便 | 两个语言栈分散注意力 |
|
|||
|
|
| Spring Boot | 企业级成熟 | 太重、不擅长 |
|
|||
|
|
|
|||
|
|
**推荐：Node.js + NestJS + TypeScript**
|
|||
|
|
|
|||
|
|
### 9.3 后端目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
server/
|
|||
|
|
├── src/
|
|||
|
|
│ ├── main.ts
|
|||
|
|
│ ├── app.module.ts
|
|||
|
|
│ │
|
|||
|
|
│ ├── common/
|
|||
|
|
│ │ ├── filters/
|
|||
|
|
│ │ ├── guards/
|
|||
|
|
│ │ ├── interceptors/
|
|||
|
|
│ │ ├── decorators/
|
|||
|
|
│ │ └── utils/
|
|||
|
|
│ │
|
|||
|
|
│ ├── config/
|
|||
|
|
│ │ ├── app.config.ts
|
|||
|
|
│ │ ├── database.config.ts
|
|||
|
|
│ │ └── ai.config.ts
|
|||
|
|
│ │
|
|||
|
|
│ ├── modules/
|
|||
|
|
│ │ ├── auth/
|
|||
|
|
│ │ ├── users/
|
|||
|
|
│ │ ├── knowledge/
|
|||
|
|
│ │ ├── learning/
|
|||
|
|
│ │ ├── ai/
|
|||
|
|
│ │ │ ├── prompts/
|
|||
|
|
│ │ │ └── providers/
|
|||
|
|
│ │ ├── review/
|
|||
|
|
│ │ ├── feedback/
|
|||
|
|
│ │ └── waitlist/
|
|||
|
|
│ │
|
|||
|
|
│ └── database/
|
|||
|
|
│ ├── migrations/
|
|||
|
|
│ └── seeds/
|
|||
|
|
│
|
|||
|
|
├── .env
|
|||
|
|
├── package.json
|
|||
|
|
└── docker-compose.yml
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 9.4 后端第一版模块
|
|||
|
|
|
|||
|
|
**P0 模块：**
|
|||
|
|
- Auth 模块
|
|||
|
|
- User 模块
|
|||
|
|
- Knowledge 模块
|
|||
|
|
- Learning 模块
|
|||
|
|
- AI 模块
|
|||
|
|
- Review 模块
|
|||
|
|
- Feedback 模块
|
|||
|
|
- Waitlist 模块
|
|||
|
|
|
|||
|
|
**P1 模块：**
|
|||
|
|
- Admin 简单管理
|
|||
|
|
- Analytics 简单日志
|
|||
|
|
- Subscription 订阅预留
|
|||
|
|
|
|||
|
|
**P2 暂不做：**
|
|||
|
|
- 支付、完整后台、多租户、企业账号、复杂权限
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. 数据库设计
|
|||
|
|
|
|||
|
|
### 10.1 数据库选型
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
v0.1：MySQL + Redis（预留）
|
|||
|
|
后续：向量数据库（PostgreSQL pgvector / Milvus / Qdrant）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 10.2 为什么用 MySQL
|
|||
|
|
|
|||
|
|
MySQL 适合保存结构化业务数据：
|
|||
|
|
- 用户、登录信息
|
|||
|
|
- 知识库、学习路径
|
|||
|
|
- 学习记录、AI 分析结果
|
|||
|
|
- 复习任务、反馈、等待名单
|
|||
|
|
|
|||
|
|
### 10.3 为什么用 Redis
|
|||
|
|
|
|||
|
|
Redis 第一版可以先不急着重度使用，但可以预留：
|
|||
|
|
|
|||
|
|
- 缓存
|
|||
|
|
- 限流
|
|||
|
|
- AI 请求频控
|
|||
|
|
- 短期会话
|
|||
|
|
- 验证码（未来如果有）
|
|||
|
|
- 队列（后续如果需要）
|
|||
|
|
|
|||
|
|
### 10.4 是否需要向量数据库
|
|||
|
|
|
|||
|
|
**第一版暂不急着上向量数据库。**
|
|||
|
|
|
|||
|
|
原因：
|
|||
|
|
1. 第一版知识库内容很小
|
|||
|
|
2. 可以先用结构化课程上下文传给 AI
|
|||
|
|
3. RAG 系统会增加复杂度
|
|||
|
|
4. 当前重点是验证学习闭环，而不是做大规模知识检索
|
|||
|
|
|
|||
|
|
**后续再考虑：** PostgreSQL + pgvector、Qdrant、Milvus
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. AI 长期记忆与知识库能力
|
|||
|
|
|
|||
|
|
### 11.1 名词澄清
|
|||
|
|
|
|||
|
|
| 概念 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| 长期记忆 Long-term Memory | 记录用户长期偏好、历史行为、薄弱点 |
|
|||
|
|
| 学习画像 Learning Profile | 记录用户在具体学习领域里的状态 |
|
|||
|
|
| 知识库 Knowledge Base | 产品提供的结构化内容（课程小节、知识点、示例、练习、复习问题） |
|
|||
|
|
| RAG | 当知识库内容变多后，通过检索相关内容，再交给 AI 回答 |
|
|||
|
|
| 向量数据库 | 用于存储文本向量，实现语义检索 |
|
|||
|
|
| Agent Memory | Agent 为了长期协作，保存用户目标、偏好、任务历史等 |
|
|||
|
|
|
|||
|
|
### 11.2 v0.1 推荐做法
|
|||
|
|
|
|||
|
|
第一版不要急着做复杂 Agent Memory。
|
|||
|
|
|
|||
|
|
v0.1 只做：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
结构化学习画像
|
|||
|
|
+
|
|||
|
|
学习记录
|
|||
|
|
+
|
|||
|
|
AI 分析结果
|
|||
|
|
+
|
|||
|
|
复习队列
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
也就是：
|
|||
|
|
- UserLearningProfile
|
|||
|
|
- LearningSession
|
|||
|
|
- AIAnalysis
|
|||
|
|
- ReviewTask
|
|||
|
|
|
|||
|
|
### 11.3 AI 对话上下文
|
|||
|
|
|
|||
|
|
第一版 AI 对话上下文包括：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
当前用户
|
|||
|
|
当前知识库
|
|||
|
|
当前学习路径
|
|||
|
|
当前小节
|
|||
|
|
用户最近一次输入
|
|||
|
|
最近一次 AI 分析
|
|||
|
|
用户薄弱点
|
|||
|
|
当前复习任务
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
暂不做全局长期聊天记忆。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12. AI 模型与 API 选型
|
|||
|
|
|
|||
|
|
### 12.1 模型选择原则
|
|||
|
|
|
|||
|
|
1. 中文能力好
|
|||
|
|
2. 成本可控
|
|||
|
|
3. API 稳定
|
|||
|
|
4. 支持结构化输出
|
|||
|
|
5. 速度可以接受
|
|||
|
|
6. 容易接入
|
|||
|
|
7. 可替换
|
|||
|
|
|
|||
|
|
### 12.2 候选模型
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
MiniMax
|
|||
|
|
DeepSeek
|
|||
|
|
通义千问
|
|||
|
|
OpenAI
|
|||
|
|
Claude
|
|||
|
|
Gemini
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 12.3 AI Provider 层设计
|
|||
|
|
|
|||
|
|
后端需要设计 AI Provider 层：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
AIService
|
|||
|
|
├── MiniMaxProvider
|
|||
|
|
├── DeepSeekProvider
|
|||
|
|
├── OpenAIProvider
|
|||
|
|
└── MockProvider
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 12.4 MockProvider
|
|||
|
|
|
|||
|
|
v0.1 强烈建议做一个 MockProvider。
|
|||
|
|
|
|||
|
|
作用：
|
|||
|
|
- 没有 API Key 时也能开发
|
|||
|
|
- AI 服务出问题时能测试流程
|
|||
|
|
- 降低开发成本
|
|||
|
|
- 方便录 Demo
|
|||
|
|
|
|||
|
|
### 12.5 核心 AI 接口
|
|||
|
|
|
|||
|
|
**POST /ai/analyze-learning-input**
|
|||
|
|
|
|||
|
|
输入：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"userId": "user_001",
|
|||
|
|
"lessonId": "lesson_001",
|
|||
|
|
"userInput": "用户写下的答案或笔记",
|
|||
|
|
"context": {
|
|||
|
|
"lessonTitle": "材料阅读方法",
|
|||
|
|
"objectives": ["理解材料结构", "提取关键要点"],
|
|||
|
|
"keyPoints": ["问题", "原因", "影响", "对策"]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
输出：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"masteryScore": 3,
|
|||
|
|
"understandingLevel": "基本理解",
|
|||
|
|
"summary": "用户能理解主要内容，但要点不完整。",
|
|||
|
|
"strengths": ["表达清楚"],
|
|||
|
|
"weakPoints": ["遗漏关键要点", "逻辑层次不足"],
|
|||
|
|
"suggestions": ["补充第二个要点", "先概括再展开"],
|
|||
|
|
"reviewNeeded": true,
|
|||
|
|
"nextAction": "明天重新回答本节主动回忆问题。"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**POST /ai/chat**
|
|||
|
|
|
|||
|
|
输入：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"userId": "user_001",
|
|||
|
|
"lessonId": "lesson_001",
|
|||
|
|
"message": "这节内容能不能举个例子？"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
输出：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"reply": "可以。你可以这样理解……",
|
|||
|
|
"suggestedActions": ["生成复习问题", "重新解释", "给我一个例子"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 13. 域名规划
|
|||
|
|
|
|||
|
|
### 13.1 当前已有域名
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
longde.cloud
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
v0.1 阶段使用该域名作为产品基础设施域名。
|
|||
|
|
|
|||
|
|
### 13.2 子域名规划
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
longde.cloud 官网首页
|
|||
|
|
www.longde.cloud 官网首页（可跳转）
|
|||
|
|
api.longde.cloud 后端 API
|
|||
|
|
git.longde.cloud Gitea 代码仓库
|
|||
|
|
download.longde.cloud 未来 Mac DMG 下载（可选）
|
|||
|
|
status.longde.cloud 未来服务状态页（可选）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 13.3 官网 URL 规划
|
|||
|
|
|
|||
|
|
| 路径 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| / | 首页 |
|
|||
|
|
| /privacy | 隐私政策 |
|
|||
|
|
| /terms | 用户协议 |
|
|||
|
|
| /support | 支持与反馈 |
|
|||
|
|
| /waitlist | 等待名单 / 内测申请 |
|
|||
|
|
| /changelog | 更新日志 |
|
|||
|
|
| /download | 未来 Mac DMG 下载页 |
|
|||
|
|
| /blog | 后续 SEO 内容文章 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 14. 部署方案
|
|||
|
|
|
|||
|
|
### 14.1 当前服务器情况
|
|||
|
|
|
|||
|
|
- 4 核 4G 轻量云服务器
|
|||
|
|
- 当前运行 Gitea
|
|||
|
|
|
|||
|
|
### 14.2 是否需要新买服务器
|
|||
|
|
|
|||
|
|
**v0.1 阶段不建议立刻买新 ECS。**
|
|||
|
|
|
|||
|
|
原因：
|
|||
|
|
1. 当前没有真实用户
|
|||
|
|
2. v0.1 请求量很低
|
|||
|
|
3. 官网、后端、数据库可以先小规模部署
|
|||
|
|
4. 先验证产品，不增加固定成本
|
|||
|
|
|
|||
|
|
### 14.3 当前推荐部署方式
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
Nginx
|
|||
|
|
Docker Compose 或 PM2
|
|||
|
|
MySQL
|
|||
|
|
Redis（可选）
|
|||
|
|
NestJS 后端
|
|||
|
|
Astro 静态官网
|
|||
|
|
Gitea 继续保留
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 14.4 什么时候买新服务器
|
|||
|
|
|
|||
|
|
满足以下情况再考虑新服务器：
|
|||
|
|
|
|||
|
|
1. Gitea 和产品服务互相影响
|
|||
|
|
2. 官网访问开始明显增加
|
|||
|
|
3. 后端 AI 请求明显增多
|
|||
|
|
4. MySQL 占用资源明显
|
|||
|
|
5. 需要更稳定的生产环境
|
|||
|
|
6. App Store 正式上线前想隔离开发服务
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 15. 开发环境与仓库规划
|
|||
|
|
|
|||
|
|
### 15.1 仓库策略
|
|||
|
|
|
|||
|
|
**推荐 monorepo：**
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
ai-study-product/
|
|||
|
|
├── apps/
|
|||
|
|
│ ├── ios/
|
|||
|
|
│ └── website/
|
|||
|
|
│
|
|||
|
|
├── services/
|
|||
|
|
│ └── api/
|
|||
|
|
│
|
|||
|
|
├── packages/
|
|||
|
|
│ ├── shared-types/
|
|||
|
|
│ └── prompts/
|
|||
|
|
│
|
|||
|
|
├── docs/
|
|||
|
|
│ └── planning/
|
|||
|
|
│
|
|||
|
|
└── README.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**原因：**
|
|||
|
|
1. 早期项目小，放一起方便管理
|
|||
|
|
2. AI Agent 更容易读取完整上下文
|
|||
|
|
3. Prompt、类型定义、文档可以共享
|
|||
|
|
4. 后续大了再拆仓库
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 16. 技术里程碑
|
|||
|
|
|
|||
|
|
### 技术里程碑 1：可点击 iOS Demo
|
|||
|
|
|
|||
|
|
- SwiftUI 项目
|
|||
|
|
- 基础页面
|
|||
|
|
- Tab 导航
|
|||
|
|
- 学习路径页面
|
|||
|
|
- 内容阅读页面
|
|||
|
|
- AI 分析结果假数据
|
|||
|
|
|
|||
|
|
### 技术里程碑 2：最小后端
|
|||
|
|
|
|||
|
|
- NestJS 项目
|
|||
|
|
- MySQL 连接
|
|||
|
|
- 用户表
|
|||
|
|
- 学习记录表
|
|||
|
|
- AI MockProvider
|
|||
|
|
- 反馈接口
|
|||
|
|
|
|||
|
|
### 技术里程碑 3：真实 AI 接入
|
|||
|
|
|
|||
|
|
- AI Provider 抽象
|
|||
|
|
- 接入一个真实模型
|
|||
|
|
- AI 分析接口
|
|||
|
|
- AI 对话接口
|
|||
|
|
- 结构化输出保存
|
|||
|
|
|
|||
|
|
### 技术里程碑 4：官网上线
|
|||
|
|
|
|||
|
|
- Astro 官网
|
|||
|
|
- 首页
|
|||
|
|
- 隐私政策
|
|||
|
|
- 用户协议
|
|||
|
|
- 支持页
|
|||
|
|
- 等待名单
|
|||
|
|
- SEO 基础配置
|
|||
|
|
|
|||
|
|
### 技术里程碑 5：TestFlight 前准备
|
|||
|
|
|
|||
|
|
- Sign in with Apple
|
|||
|
|
- 后端用户身份记录
|
|||
|
|
- 基础错误处理
|
|||
|
|
- 数据隐私检查
|
|||
|
|
- 反馈入口
|
|||
|
|
- 内测版本构建
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 17. 当前技术不做清单
|
|||
|
|
|
|||
|
|
- Spring Boot
|
|||
|
|
- 微服务
|
|||
|
|
- Kubernetes
|
|||
|
|
- 多云部署
|
|||
|
|
- 完整后台管理系统
|
|||
|
|
- 完整 CMS
|
|||
|
|
- 完整 RAG
|
|||
|
|
- 向量数据库
|
|||
|
|
- 多模型自动路由
|
|||
|
|
- AI Agent 工具调用系统
|
|||
|
|
- 文件上传解析
|
|||
|
|
- Web 学习端
|
|||
|
|
- Android
|
|||
|
|
- Mac 正式版
|
|||
|
|
- 支付系统
|
|||
|
|
- 复杂数据分析平台
|