# 小虾 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`

---

**以后每次新会话，先读这个文件快速恢复上下文。**