Xiaoxia AI
188 lines
4.9 KiB
Markdown
188 lines
4.9 KiB
Markdown
# 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
|