docs: add complete project roadmap and status documentation

2026-06-16 22:26:21 +08:00
parent 415b180c5d
commit 6049ecc9e3
1 changed files with 380 additions and 0 deletions
@@ -0,0 +1,380 @@
+# 小虾 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`
+
+---
+
+**以后每次新会话，先读这个文件快速恢复上下文。**