wangdl/startup-plan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
startup-plan/个人开发者创业 v0.1/3-官网与技术基础/官网与技术基础.md

21 KiB
Raw Blame History

version, status, updated
version status updated
v0.1 draft 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 架构要清晰，但不能过度设计

原则：

代码结构清晰 > 技术炫技
可维护 > 复杂
能上线 > 完美
能验证 > 大而全

2.3 前后端职责分离

端 职责
iOS 客户端 页面展示、用户交互、本地状态、登录入口、学习流程体验
后端 用户身份记录、AI API 代理、学习记录保存、AI 分析结果保存、学习画像更新、反馈收集、等待名单
AI 模型 分析用户输入、生成学习反馈、识别薄弱点、生成复习建议、辅助学习对话
官网 产品介绍、SEO、隐私政策、用户协议、支持页面、等待名单、TestFlight 招募、未来 Mac DMG 下载

3. 当前推荐最终选型

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. 整体技术架构

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 技术选择

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 目录结构

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 原生能力：

withAnimation
transition
opacity
scaleEffect
ProgressView

谨慎使用：

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 官网页面结构

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 后端目录结构

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 数据库选型

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 只做：

结构化学习画像
+
学习记录
+
AI 分析结果
+
复习队列

也就是：

  • UserLearningProfile
  • LearningSession
  • AIAnalysis
  • ReviewTask

11.3 AI 对话上下文

第一版 AI 对话上下文包括：

当前用户
当前知识库
当前学习路径
当前小节
用户最近一次输入
最近一次 AI 分析
用户薄弱点
当前复习任务

暂不做全局长期聊天记忆。

12. AI 模型与 API 选型

12.1 模型选择原则

  1. 中文能力好
  2. 成本可控
  3. API 稳定
  4. 支持结构化输出
  5. 速度可以接受
  6. 容易接入
  7. 可替换

12.2 候选模型

MiniMax
DeepSeek
通义千问
OpenAI
Claude
Gemini

12.3 AI Provider 层设计

后端需要设计 AI Provider 层：

AIService
  ├── MiniMaxProvider
  ├── DeepSeekProvider
  ├── OpenAIProvider
  └── MockProvider

12.4 MockProvider

v0.1 强烈建议做一个 MockProvider。

作用：

  • 没有 API Key 时也能开发
  • AI 服务出问题时能测试流程
  • 降低开发成本
  • 方便录 Demo

12.5 核心 AI 接口

POST /ai/analyze-learning-input

输入：

{
  "userId": "user_001",
  "lessonId": "lesson_001",
  "userInput": "用户写下的答案或笔记",
  "context": {
    "lessonTitle": "材料阅读方法",
    "objectives": ["理解材料结构", "提取关键要点"],
    "keyPoints": ["问题", "原因", "影响", "对策"]
  }
}

输出：

{
  "masteryScore": 3,
  "understandingLevel": "基本理解",
  "summary": "用户能理解主要内容，但要点不完整。",
  "strengths": ["表达清楚"],
  "weakPoints": ["遗漏关键要点", "逻辑层次不足"],
  "suggestions": ["补充第二个要点", "先概括再展开"],
  "reviewNeeded": true,
  "nextAction": "明天重新回答本节主动回忆问题。"
}

POST /ai/chat

输入：

{
  "userId": "user_001",
  "lessonId": "lesson_001",
  "message": "这节内容能不能举个例子？"
}

输出：

{
  "reply": "可以。你可以这样理解……",
  "suggestedActions": ["生成复习问题", "重新解释", "给我一个例子"]
}

13. 域名规划

13.1 当前已有域名

longde.cloud

v0.1 阶段使用该域名作为产品基础设施域名。

13.2 子域名规划

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 当前推荐部署方式

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：

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 正式版
  • 支付系统
  • 复杂数据分析平台