xiaoxia-saas/docs/saas-index.md

SaaS 项目文档总索引

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

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

---

一、快速导航

🎯 我想快速了解项目

1. README.md - 项目总览
2. API 主线清单 - 所有 API endpoints
3. 代码状态标注 - 代码库导航
4. Phase 7 进度 - 当前进度

🛠️ 我想开始开发

1. Git 工作流 - 分支规范
2. 环境配置 - 环境变量
3. API 使用指南 - API 用法
4. 代码状态标注 - 找到主线代码

📦 我想部署

1. Docker 部署指南
2. CI/CD 文档
3. 生产检查清单
4. 健康检查指南

---

二、核心文档清单

项目状态与进度

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

API 与代码

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

开发规范

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

部署与运维

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

技术细节

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

历史规划文档

文档	说明	状态
saas-rebuild-kickoff-plan.md	重建启动方案	📚 归档
saas-rebuild-inventory.md	重建盘点总表	📚 归档
saas-mvp-scope.md	MVP 范围	📚 归档
saas-core-objects.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

---

六、文档维护原则

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

---

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