# SaaS 项目文档总索引

> **最后更新**: 2026-06-19  
> **当前状态**: Phase 7 已完成，进入专项治理阶段

本文档是小虾 SaaS 项目的文档导航入口。

---

## 一、快速导航

### 🎯 我想快速了解项目

1. **[README.md](../README.md)** - 项目总览
2. **[API 主线清单](API-MAINLINE.md)** - 所有 API endpoints
3. **[代码状态标注](CODE-STATUS.md)** - 代码库导航
4. **[Phase 7 进度](PHASE7-PROGRESS.md)** - 当前进度

### 🛠️ 我想开始开发

1. **[Git 工作流](GIT-WORKFLOW.md)** - 分支规范
2. **[环境配置](ENVIRONMENT-CONFIG.md)** - 环境变量
3. **[API 使用指南](API-GUIDE.md)** - API 用法
4. **[代码状态标注](CODE-STATUS.md)** - 找到主线代码

### 📦 我想部署

1. **[Docker 部署指南](DOCKER-DEPLOYMENT.md)**
2. **[CI/CD 文档](CI-CD.md)**
3. **[生产检查清单](PRODUCTION-CHECKLIST.md)**
4. **[健康检查指南](HEALTH-CHECKS.md)**

---

## 二、核心文档清单

### 项目状态与进度

| 文档 | 说明 |
|------|------|
| [PHASE7-PROGRESS.md](PHASE7-PROGRESS.md) | Phase 7 完成总结 ✅ |
| [PHASE7-DESIGN.md](PHASE7-DESIGN.md) | Phase 7 设计文档 |
| [SaaS-后续专项整治清单-2026-06-18.md](SaaS-后续专项整治清单-2026-06-18.md) | 后续专项规划 |

### API 与代码

| 文档 | 说明 |
|------|------|
| [API-MAINLINE.md](API-MAINLINE.md) | ⭐ 当前所有 API 清单 |
| [CODE-STATUS.md](CODE-STATUS.md) | ⭐ 代码状态与导航 |
| [API-GUIDE.md](API-GUIDE.md) | API 使用指南 |
| [API-VERSIONING.md](API-VERSIONING.md) | API 版本管理 |

### 开发规范

| 文档 | 说明 |
|------|------|
| [GIT-WORKFLOW.md](GIT-WORKFLOW.md) | Git 分支规范 |
| [CI-CD.md](CI-CD.md) | CI/CD 流程 |
| [ENVIRONMENT-CONFIG.md](ENVIRONMENT-CONFIG.md) | 环境配置 |

### 部署与运维

| 文档 | 说明 |
|------|------|
| [DOCKER-DEPLOYMENT.md](DOCKER-DEPLOYMENT.md) | Docker 部署 |
| [PRODUCTION-CHECKLIST.md](PRODUCTION-CHECKLIST.md) | 生产检查清单 |
| [HEALTH-CHECKS.md](HEALTH-CHECKS.md) | 健康检查 |
| [PERFORMANCE-MONITORING.md](PERFORMANCE-MONITORING.md) | 性能监控 |

### 技术细节

| 文档 | 说明 |
|------|------|
| [DATABASE-SWITCH.md](DATABASE-SWITCH.md) | 数据库切换 |
| [CONNECTION-POOL.md](CONNECTION-POOL.md) | 连接池优化 |
| [PAGINATION.md](PAGINATION.md) | 分页实现 |

### 历史规划文档

| 文档 | 说明 | 状态 |
|------|------|------|
| [saas-rebuild-kickoff-plan.md](saas-rebuild-kickoff-plan.md) | 重建启动方案 | 📚 归档 |
| [saas-rebuild-inventory.md](saas-rebuild-inventory.md) | 重建盘点总表 | 📚 归档 |
| [saas-mvp-scope.md](saas-mvp-scope.md) | MVP 范围 | 📚 归档 |
| [saas-core-objects.md](saas-core-objects.md) | 核心对象 | 📚 归档 |
| [saas-core-flows.md](saas-core-flows.md) | 核心流程 | 📚 归档 |

---

## 三、当前项目状态

### Phase 状态

- ✅ **Phase 4**: SAAS 产品化（后端 API）- 82.4% 完成
- ✅ **Phase 6**: 前端开发（React UI）- 80% 完成
- ✅ **Phase 7**: 核心视频剪辑业务 - **已完成**

### 已交付能力

1. **素材管理**: 上传、分类、查询、标签
2. **视频生成**: 任务创建、worker 自动触发、结果管理
3. **成片下载**: 预签名 URL、规范化路径
4. **前端联调**: 生成页、结果页完整打通
5. **基础设施**: CI/CD 稳定、Git 工作流规范

### 进行中专项

当前正在执行：**专项 B：全仓主线路径澄清**

目标：消除旧文档/旧测试/当前主线并存的认知混乱。

---

## 四、技术栈总览

### 后端
- Python 3.12
- FastAPI 0.115.0
- PostgreSQL 16
- Redis 7
- Celery
- MinIO

### 前端
- React 18
- TypeScript
- Vite
- Ant Design

### 基础设施
- Docker
- Gitea (CI/CD)
- Nginx

---

## 五、快速定位代码

### 我想找素材上传流程
```
apps/api/app/api/routes/upload.py (API)
  ↓
apps/api/app/core/storage.py (MinIO)
  ↓
packages/domain/entities.py::Asset (领域模型)
  ↓
packages/adapters/sqlalchemy_impl/asset_repository.py (持久化)
```

### 我想找视频生成流程
```
apps/api/app/api/routes/generation_tasks.py (API)
  ↓
packages/application/generation_tasks.py (用例)
  ↓
apps/worker/tasks.py::generate_video (Worker)
  ↓
packages/adapters/sqlalchemy_impl/generation_task_repository.py (持久化)
```

### 我想找用户认证流程
```
apps/api/app/api/routes/auth.py (API)
  ↓
packages/application/auth/login_use_case.py (用例)
  ↓
packages/domain/auth/jwt_service.py (JWT)
  ↓
packages/domain/auth/session_store.py (会话)
```

完整导航请查看 **[CODE-STATUS.md](CODE-STATUS.md)**

---

## 六、文档维护原则

1. **文档优先于实现** - 重要变更先更新文档
2. **保持文档与代码同步** - 代码改了文档也要改
3. **废弃文档要标注** - 不要默默删除，要留归档标记
4. **新文档要加入索引** - 创建新文档后更新本文件

---

**维护人**: 小虾 🦐  
**最后更新**: 2026-06-19