From 6049ecc9e39824dc6798bdb6ac8c932176c2d091 Mon Sep 17 00:00:00 2001 From: Xiaoxia AI Date: Tue, 16 Jun 2026 22:26:21 +0800 Subject: [PATCH] docs: add complete project roadmap and status documentation --- PROJECT_ROADMAP.md | 380 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 380 insertions(+) create mode 100644 PROJECT_ROADMAP.md diff --git a/PROJECT_ROADMAP.md b/PROJECT_ROADMAP.md new file mode 100644 index 000000000..65c498c30 --- /dev/null +++ b/PROJECT_ROADMAP.md @@ -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` + +--- + +**以后每次新会话，先读这个文件快速恢复上下文。**