xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases 7 Wiki Activity
Files
main
xiaoxia-saas/PROJECT_ROADMAP.md
T

381 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 小虾 SaaS 项目全景 - 完整状态记录
> 最后更新：2026-06-16 22:16
> 这是项目的完整状态、规则、进度记录，确保不会遗忘任何事情
---
## 🎯 项目定位
新一代 SaaS 版小虾自动化剪辑系统，采用 Clean Architecture 重新设计。
**核心目标**：
- AI 视频自动化剪辑
- 多租户 SaaS 平台
- 项目推进管理系统
---
## ✅ 已完成（Phase 1 & 2）
### 核心架构
- ✅ Clean Architecture 分层（Domain → Ports → Application → Adapters）
- ✅ 双持久化实现（In-Memory 测试 + PostgreSQL 生产）
- ✅ Docker Compose 完整开发环境
- ✅ Alembic 数据库迁移
- ✅ Gitea CI/CD workflows（测试 + 部署）
### 核心业务对象
- ✅ User（用户）
- ✅ Workspace（工作空间）
- ✅ Project（项目）
- ✅ AssetLibrary（素材库：视频/音频）
- ✅ Asset（素材）
- ✅ IngestJob（入库任务）
- ✅ ClassificationJob（分类任务）
- ✅ **Task（任务管理）**
- ✅ **Milestone（里程碑）**
- ✅ **TaskIssue（任务问题/卡点）**
### 核心业务流程
- ✅ 上传 → 入库 → Asset 创建链路
- ✅ 分类任务链路
- ✅ 完整异步任务处理（Celery + Redis）
- ✅ **任务创建 → 状态更新 → 进度跟踪链路**
- ✅ **里程碑管理**
- ✅ **问题/卡点记录与解决**
### 基础设施
- ✅ MinIO 真实文件存储
- ✅ PostgreSQL 数据库
- ✅ Redis 消息队列
- ✅ Celery 异步任务
- ✅ Docker Compose 部署配置
- ✅ Nginx 反向代理（8088/8089 临时端口）
### 前端
- ✅ Next.js 14 + TypeScript + React 18
- ✅ 项目推进器前端页面（5 个页面）
- 首页
- 项目列表
- 任务详情
- 里程碑管理
- 问题卡点面板
- ✅ 3 个表单组件（创建任务/编辑任务/创建问题）
### 测试
- ✅ 17 个集成测试全绿
- 素材管理 8 个
- 项目管理 9 个
### 部署
- ✅ 服务器部署（47.98.113.167）
- ✅ 5 个容器运行（postgres/redis/api/worker/web）
- ✅ Nginx 配置完成（绕过备案限制）
- ✅ 临时访问地址：
- 前端：http://47.98.113.167:8088
- API 文档：http://47.98.113.167:8089/docs
---
## 🔄 进行中（Phase 3）
### 部署相关
- 🔄 **域名备案审核**（阻塞中）
- saas.xiaoxiajianji.com
- saas-api.xiaoxiajianji.com
- 等待工信部审核通过
- 🔄 **HTTPS 证书申请**（依赖备案）
- Let's Encrypt 证书
- 备案通过后申请
- 🔄 **推进器 API 路由问题**（技术问题）
- 症状：`/api/v1/project-management/tasks` 返回 404
- 根因：Docker 构建缓存导致旧代码进入容器
- 已诊断：`project_management.py` 的 router prefix 重复
- 修复方案：移除 `/api/v1` 前缀，只保留 `/project-management`
- 状态：代码已修改，但容器内未生效（缓存问题）
---
## 📋 待办任务（按优先级）
### Phase 3：部署与备案完成（目标：2026-06-30）
**URGENT - 阻塞项**
1. ⚠️ **修复推进器 API 路由**
- 方案：直接进入容器手动修改测试
- 或者：彻底清理 Docker 镜像重建
2. ⚠️ **等待备案通过**
- 无法加速，只能等待
**HIGH - 备案后立即执行**
3. 📝 切换到正式域名和 HTTPS
- 改回 80/443 端口
- 申请 Let's Encrypt 证书
- nginx 配置 HTTPS
4. 📝 PostgreSQL 生产环境切换
- 当前用 In-Memory
- 需切换到 PostgreSQL + 数据持久化验证
5. 📝 前端环境变量配置
- API 地址从临时端口改为 https://saas-api.xiaoxiajianji.com
### Phase 4：SAAS 产品化完成（目标：2026-07-15）
**URGENT - 商业化基础**
6. 🔐 认证与账号体系
- JWT 登录
- 注册 + 密码重置
- Session 管理
7. 🔐 多租户权限体系
- Workspace 级别权限控制
- 用户角色管理（Admin/Member/Viewer）
- 数据隔离
**HIGH - 商业化能力**
8. 💰 订阅与计费体系
- SaaS 订阅套餐（基础版/专业版/企业版）
- 支付接入（微信/支付宝）
- 账单管理
### Phase 5：AI 剪辑能力接入（目标：2026-08-01）
**URGENT - 核心价值**
9. 🤖 视频分类模型接入
- 替换占位分类逻辑
- 真实 AI 模型
**HIGH - 增值功能**
10. 🎬 自动剪辑能力
- 视频自动剪辑
- 转场特效
- 字幕生成
11. 🎙️ 配音合成能力
- AI 配音
- 音频混音
### Phase 2 收尾（低优先级）
**MEDIUM**
12. 📊 甘特图视图开发
- 项目推进器增加甘特图/时间线视图
13. 📤 数据导出功能
- 导出任务列表为 Excel/CSV
**LOW**
14. 🔧 批量操作 API
- 任务批量更新状态/优先级/删除接口
---
## 🎯 里程碑
| 里程碑 | 目标日期 | 状态 | 说明 |
|--------|----------|------|------|
| Phase 1: 核心平台层完成 | 2026-06-15 | ✅ 完成 | Clean Architecture + 核心业务对象 |
| Phase 2: 项目管理模块落地 | 2026-06-16 | ✅ 完成 | 任务/里程碑/问题管理 + 前后端 |
| Phase 3: 部署与备案完成 | 2026-06-30 | 🔄 进行中 | 生产部署 + HTTPS + 域名备案 |
| Phase 4: SAAS 产品化完成 | 2026-07-15 | 📋 待开始 | 多租户 + 权限 + 订阅计费 |
| Phase 5: AI 剪辑能力接入 | 2026-08-01 | 📋 待开始 | 视频分类 + 自动剪辑 + 配音 |
---
## 📐 技术架构
### 后端
- **语言**：Python 3.12
- **框架**：FastAPI
- **数据库**：PostgreSQL（生产）+ SQLite（测试）
- **缓存/队列**：Redis
- **异步任务**：Celery
- **ORM**：SQLAlchemy
- **迁移**：Alembic
- **存储**：MinIO（S3-compatible）
### 前端
- **框架**：Next.js 14
- **语言**：TypeScript
- **UI 库**：React 18
### 架构模式
- Clean Architecture
- Ports & Adapters (Hexagonal)
- Repository Pattern
- Use Case Pattern
### 基础设施
- **容器**：Docker + Docker Compose
- **Web 服务器**：Nginx
- **CI/CD**：Gitea Actions
- **部署**：自建服务器（阿里云 ECS）
---
## 🗂️ 关键目录
```
xiaoxia-saas/
├── packages/ # 共享业务逻辑包
│ ├── domain/ # 核心实体与规则
│ ├── application/ # 用例层
│ ├── ports/ # 接口定义
│ └── adapters/ # 接口实现
│ ├── in_memory/ # 内存实现（测试）
│ └── sqlalchemy_impl/ # PostgreSQL 实现
├── apps/ # 应用层
│ ├── api/ # FastAPI REST API
│ ├── worker/ # Celery 异步任务
│ └── web/ # Next.js 前端
├── infra/ # 基础设施配置
│ ├── docker/ # Docker Compose
│ ├── scripts/ # 部署脚本
│ ├── systemd/ # systemd 服务
│ └── nginx/ # Nginx 配置（待添加）
├── tests/ # 测试
│ ├── integration/ # 集成测试
│ └── e2e/ # 端到端测试（待添加）
├── alembic/ # 数据库迁移
├── scripts/ # 工具脚本
│ ├── init_tracker_data.py # 推进器数据初始化（Python）
│ └── init_tracker_data.ps1 # 推进器数据初始化（PowerShell）
└── docs/ # 文档
```
---
## 🔑 关键决策记录
### 架构决策
- ✅ 新 SaaS 与旧桌面版完全物理隔离
- ✅ 旧桌面版仅作为业务参考，不再作为未来主线
- ✅ 从第一天起就遵循 Clean Architecture
- ✅ 持久化层提供双实现（便于测试）
- ✅ 测试策略：集成测试优先，覆盖核心业务流程
- ✅ 数据库迁移从第一天起就版本化管理
### 部署决策
- ✅ CI/CD 基于 Gitea Actions + 自建 runner
- ✅ 服务器优先开发/部署策略
- ✅ 前端改为生产构建部署方案（非开发模式）
- ✅ 临时用 8088/8089 端口绕过备案限制
- ✅ 等备案通过后切换到 80/443 + HTTPS
### 工具链决策
- ✅ 缺工具直接装，不找替代方案（避免出错）
- ✅ Python 依赖装到 F 盘项目虚拟环境里
- ✅ 旧项目推进器（纯前端 HTML）已废弃
- ✅ 项目管理功能重新在 SAAS 里实现（后端 API + 前端 UI）
---
## 🔗 仓库信息
- **本地路径**：`F:\openclaw-saas`
- **远程仓库**：`xiaoxia-server:/var/lib/xiaoxia-ci/xiaoxia-saas.git`
- **服务器路径**：`/var/lib/xiaoxia-saas-staging/repo`
- **分支**：`main`
- **最新提交**：`c6f21d2 fix: remove duplicate api/v1 prefix in project-management routes`
---
## 📊 当前访问地址
### 临时地址（HTTP，绕过备案）
- **前端**：http://47.98.113.167:8088
- **API 文档**：http://47.98.113.167:8089/docs
- **API 端点**：http://47.98.113.167:8089/api/v1/
### 正式域名（备案通过后）
- **前端**：https://saas.xiaoxiajianji.com
- **API**：https://saas-api.xiaoxiajianji.com
---
## 🐛 已知问题
### 1. 推进器 API 路由 404（高优先级）
**症状**：
- 访问 `http://localhost:8000/api/v1/project-management/tasks` 返回 404
- OpenAPI 文档显示路由为 `/api/v1/api/v1/project-management/tasks`（重复前缀）
**根因**：
- `project_management.py` 里的 router 有 prefix `/api/v1/project-management`
- 主应用 `main.py` 又把 `api_router` 挂载到 `/api/v1`
- 导致前缀重复：`/api/v1` + `/api/v1/project-management`
**修复**：
- 已修改 `project_management.py` 的 prefix 为 `/project-management`
- 代码已提交：`c6f21d2`
- 服务器仓库已拉取最新代码
- **问题**：Docker 构建缓存顽固，容器内还是旧代码
**下一步**：
- 方案 A：直接进入容器修改文件测试
- 方案 B：完全清理 Docker 镜像层缓存再重建
- 方案 C：临时跳过，先完成其他任务
---
## 📝 开发规则
### Git 工作流
- ✅ 新功能开发在 `main` 分支（单人项目）
- ✅ 每个功能完成后及时提交
- ✅ 提交信息格式：`feat/fix/docs/refactor: 简短描述`
- ✅ 推送前确保本地测试通过
### 测试策略
- ✅ 集成测试优先（覆盖业务流程）
- ✅ 每个 Use Case 至少 1 个测试
- ✅ 新功能必须有测试
- ✅ 修复 bug 先写测试重现
### 部署流程
1. 本地开发 + 测试
2. 提交到 Git
3. 推送到服务器
4. 服务器自动触发 CI/CD（或手动）
5. Docker 重新构建
6. 容器重启
---
## 🔐 敏感信息（不要泄露）
- **服务器 IP**：47.98.113.167
- **SSH 别名**：xiaoxia-server
- **数据库密码**：（存储在 `.env` 文件，不提交到 Git）
- **MinIO 密钥**：（存储在 `.env` 文件）
---
## 🎓 技术债务
1. **In-Memory 持久化**：当前 API 用的还是 In-Memory，需切换到 PostgreSQL
2. **认证缺失**：当前无认证，所有接口公开
3. **错误处理**：部分接口错误处理不完善
4. **日志**：缺少结构化日志
5. **监控**：缺少性能监控和告警
6. **备份**：缺少数据库备份策略
---
## 📚 参考文档
- **项目总览**：`README.md`
- **当前状态**：`STATUS.md`（简化版）
- **部署指南**：`infra/docker/SERVER-DEPLOY.md`
- **CI/CD 说明**：`docs/CI-CD.md`
---
**以后每次新会话，先读这个文件快速恢复上下文。**
Reference in New Issue View Git Blame Copy Permalink