# SaaS 技术栈选型表（第一版）

本文档用于明确新 SaaS 项目应该采用什么技术栈，以及为什么这样选。

当前阶段的原则不是追求“最新最炫”，而是追求：

- 稳定
- 清晰
- 好维护
- 适合两人 + AI 协作
- 便于长期迭代

---

## 1. 选型原则

### 必须满足

- 简单清晰
- 社区成熟
- 适合视频/任务型系统
- 适合长期演进
- 对 AI 编码工具友好
- 前后端边界明确

### 尽量避免

- 过重的企业级复杂框架组合
- 需要大量人力维护的微服务架构
- 前期就引入过多中间件
- 因“先进”而牺牲可维护性

---

## 2. 前端建议

### 推荐方向

- **React + TypeScript + Next.js（管理台 / Web 前端）**

### 原因

- 生态成熟
- AI 工具支持好
- 组件化能力强
- 适合后台系统和 SaaS 管理界面
- 后续做 SSR / 管理台 / 仪表盘都顺手

### UI 组件建议

- `shadcn/ui` 或同类现代组件体系
- 配合 Tailwind CSS

### 结论建议

前端推荐：

- `Next.js + TypeScript + Tailwind + shadcn/ui`

---

## 3. 后端建议

### 推荐方向

- **Python + FastAPI**

### 原因

- 和现有业务逻辑语言认知一致
- 适合 AI 工具协作
- 非常适合 API + 后台任务系统
- 类型标注、文档、异步支持都成熟
- 对视频处理、脚本、任务调度的生态友好

### 不建议前期改成 Node 作为主后端的原因

- 现有业务规则和视频处理经验都更接近 Python 生态
- 后续 worker、ffmpeg、诊断逻辑、脚本集成都更自然

### 结论建议

后端推荐：

- `FastAPI + Python`

---

## 4. 数据库建议

### 推荐方向

- **PostgreSQL**

### 原因

- 稳定成熟
- 非常适合 SaaS 主业务数据
- 对 JSON 字段、索引、事务支持好
- 生态完整

### 结论建议

主数据库：

- `PostgreSQL`

---

## 5. 异步任务 / 队列建议

### 推荐方向

- **Celery + Redis**

### 原因

- 视频生成、素材分类、同步、诊断都属于典型长任务
- 需要 worker、状态、重试、任务分离
- Python 生态成熟

### 可替代方向

- RQ / Dramatiq / 自建轻量任务层

### 当前建议

如果追求成熟和可扩展，优先：

- `Celery + Redis`

---

## 6. 对象存储建议

### 推荐方向

- **S3 兼容对象存储 / OSS**

### 原因

- SaaS 素材和结果文件不适合长期直接绑本地磁盘
- 对象存储天然适合大文件、归档、分发
- 便于后续多 worker / 多环境扩展

### 当前建议

抽象成统一存储接口，底层可接：

- 阿里云 OSS
- MinIO
- S3 兼容存储

---

## 7. 鉴权建议

### 推荐方向

- **JWT + Session/Refresh Token 组合**

### 原因

- 适合 Web SaaS
- 前后端分离支持好
- 后续权限系统扩展方便

### 当前建议

一期先做：

- 登录
- 用户身份校验
- 工作空间边界

高级权限后续再扩。

---

## 8. 部署建议

### 推荐方向

- **Docker Compose 起步，后续再升级**

### 原因

- 我们当前团队规模不适合一开始上 Kubernetes
- Compose 足够支撑首版和测试环境
- 后续如果规模上来，再考虑更复杂调度

### 初期部署对象

- Web 前端
- FastAPI 后端
- PostgreSQL
- Redis
- Worker
- Nginx / 反向代理

---

## 9. 日志与监控建议

### 一期最小配置

- 应用日志
- 任务日志
- 错误追踪
- 健康检查
- 巡检机器人

### 后续建议

- Sentry（错误追踪）
- Prometheus + Grafana（指标）
- Loki / ELK（日志检索，按需要）

---

## 10. 开发规范建议

### 前端

- TypeScript 强制
- ESLint / Prettier
- 组件边界清晰
- 页面逻辑与数据逻辑分离

### 后端

- 类型标注
- Pydantic / schema 明确
- 分层结构清晰
- 用例层和适配器层分开

### 测试

- 单元测试
- API 测试
- 任务流关键路径测试
- CI 自动执行

---

## 11. 当前推荐组合（第一版）

### 推荐首选方案

- **前端**：Next.js + TypeScript + Tailwind + shadcn/ui
- **后端**：FastAPI + Python
- **数据库**：PostgreSQL
- **队列**：Redis + Celery
- **存储**：S3/OSS 兼容对象存储
- **部署**：Docker Compose
- **监控**：巡检机器人 + 基础日志 + 后续接 Sentry

这是我现在最推荐的首版 SaaS 技术栈。

---

## 12. 当前阶段结论

对于我们这种“两个人 + AI 工具”的实际情况，最重要的不是用最潮的栈，而是：

- 选成熟的
- 选 AI 容易协作的
- 选长期不容易后悔的
- 选和视频任务系统天然契合的

当前推荐方向已经足够支撑下一步：

- 正式定义 SaaS 项目目录结构
- 开始搭第一版工程骨架