Xiaoxia AI
11 KiB
11 KiB
小虾 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 配置完成（绕过备案限制）
- ✅ 临时访问地址：
🔄 进行中（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 - 阻塞项
-
⚠️ 修复推进器 API 路由
- 方案：直接进入容器手动修改测试
- 或者：彻底清理 Docker 镜像重建
-
⚠️ 等待备案通过
- 无法加速，只能等待
HIGH - 备案后立即执行 3. 📝 切换到正式域名和 HTTPS
- 改回 80/443 端口
- 申请 Let's Encrypt 证书
- nginx 配置 HTTPS
-
📝 PostgreSQL 生产环境切换
- 当前用 In-Memory
- 需切换到 PostgreSQL + 数据持久化验证
-
📝 前端环境变量配置
- API 地址从临时端口改为 https://saas-api.xiaoxiajianji.com
Phase 4：SAAS 产品化完成（目标：2026-07-15）
URGENT - 商业化基础 6. 🔐 认证与账号体系
- JWT 登录
- 注册 + 密码重置
- Session 管理
- 🔐 多租户权限体系
- Workspace 级别权限控制
- 用户角色管理（Admin/Member/Viewer）
- 数据隔离
HIGH - 商业化能力 8. 💰 订阅与计费体系
- SaaS 订阅套餐（基础版/专业版/企业版）
- 支付接入（微信/支付宝）
- 账单管理
Phase 5：AI 剪辑能力接入（目标：2026-08-01）
URGENT - 核心价值 9. 🤖 视频分类模型接入
- 替换占位分类逻辑
- 真实 AI 模型
HIGH - 增值功能 10. 🎬 自动剪辑能力 - 视频自动剪辑 - 转场特效 - 字幕生成
- 🎙️ 配音合成能力
- AI 配音
- 音频混音
Phase 2 收尾（低优先级）
MEDIUM 12. 📊 甘特图视图开发 - 项目推进器增加甘特图/时间线视图
- 📤 数据导出功能
- 导出任务列表为 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/
正式域名（备案通过后）
🐛 已知问题
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 先写测试重现
部署流程
- 本地开发 + 测试
- 提交到 Git
- 推送到服务器
- 服务器自动触发 CI/CD（或手动）
- Docker 重新构建
- 容器重启
🔐 敏感信息（不要泄露）
- 服务器 IP：47.98.113.167
- SSH 别名：xiaoxia-server
- 数据库密码：（存储在
.env文件，不提交到 Git） - MinIO 密钥：（存储在
.env文件）
🎓 技术债务
- In-Memory 持久化：当前 API 用的还是 In-Memory，需切换到 PostgreSQL
- 认证缺失：当前无认证，所有接口公开
- 错误处理：部分接口错误处理不完善
- 日志：缺少结构化日志
- 监控：缺少性能监控和告警
- 备份：缺少数据库备份策略
📚 参考文档
- 项目总览：
README.md - 当前状态：
STATUS.md（简化版） - 部署指南：
infra/docker/SERVER-DEPLOY.md - CI/CD 说明：
docs/CI-CD.md
以后每次新会话，先读这个文件快速恢复上下文。