# Xiaoxia SaaS - 项目状态

> 最后更新：2026-06-16  
> 这是项目当前状态的单页真相，每次新会话优先读这个文件。

---

## 当前阶段

**Phase 1 已完成** - 核心平台层已搭建完成并稳定化中  
**Phase 2 进行中** - 项目管理模块已落地

---

## 已完成

### 核心架构
- ✅ Clean Architecture 骨架（packages/domain + ports + application + adapters）
- ✅ 三层应用工程（apps/api + worker + web）
- ✅ 双持久化实现（In-Memory 测试 + PostgreSQL 生产）
- ✅ Alembic 数据库迁移
- ✅ Docker Compose 开发环境

### 核心业务对象
- ✅ User（用户）
- ✅ Workspace（工作空间）
- ✅ Project（项目）
- ✅ AssetLibrary（素材库：视频/音频）
- ✅ Asset（素材）
- ✅ IngestJob（入库任务：PENDING → PROCESSING → COMPLETED/FAILED）
- ✅ ClassificationJob（分类任务：含 9 种分类）
- ✅ **Task（任务：支持状态/进度/优先级/子任务/计划时间/实际时间）**
- ✅ **Milestone（里程碑）**
- ✅ **TaskIssue（任务问题/卡点）**

### 核心业务流程
- ✅ 上传 → 入库 → Asset 创建链路
- ✅ 分类任务链路
- ✅ 完整异步任务处理（Celery + Redis）
- ✅ **任务创建 → 状态更新 → 进度跟踪链路**
- ✅ **里程碑管理**
- ✅ **任务问题/卡点记录与解决**
- ✅ **完整的项目推进器前后端链路**

### 基础设施
- ✅ **MinIO 真实文件存储**（`apps/api/app/core/storage.py`）
- ✅ **Gitea CI/CD workflows**（`.gitea/workflows/tests.yml` + `deploy.yml`）
- ✅ 环境配置体系（`.env.staging` + `.env.production`）
- ✅ API 文档（Swagger）

### 测试与质量
- ✅ **17 个集成测试全绿**（素材管理 8 个 + 项目管理 9 个）
- ✅ 测试策略：集成测试优先，覆盖核心业务流程

---

## 进行中

### 部署与运行环境优化
- ✅ 服务器优先开发/部署策略明确
- ✅ 前端改为生产构建部署方案
- ✅ 仓库内部署脚本（staging / production）
- 🔄 等待服务器侧执行入口验证

### 后端优化
- 🔄 切换到 PostgreSQL 生产环境
- 🔄 补充更多 Use Case 测试
- 🔄 添加批量操作接口

### 前端优化
- 🔄 甘特图视图
- 🔄 数据导出功能
- 🔄 批量操作 UI

### 稳定化与部署打磨
- 🔄 Gitea workflows 持续优化
- 🔄 部署流程与环境隔离稳定化
- 🔄 Docker 构建优化（国内镜像源、多阶段构建）

---

## 下一步优先级

1. **项目推进器前端页面**
   - 任务列表与详情页
   - 里程碑管理页
   - 问题卡点面板
   - 甘特图/时间线视图

2. **更完整的 SAAS 产品化能力**
   - 多租户/组织/权限体系
   - 账号体系与认证
   - 订阅/计费体系

3. **业务能力扩展**
   - 真实视频分类模型接入
   - 更多素材处理能力（剪辑/合成/配音）
   - 批量任务调度

---

## 关键目录

**核心业务逻辑**
- `packages/domain/` - 核心实体与业务规则
- `packages/application/` - 用例层
- `packages/ports/` - 接口定义
- `packages/adapters/` - 接口实现

**应用层**
- `apps/api/` - FastAPI REST API
- `apps/worker/` - Celery 异步任务
- `apps/web/` - Next.js 前端

**基础设施**
- `infra/docker/` - Docker Compose 配置
- `.gitea/workflows/` - CI/CD 流水线

**测试**
- `tests/integration/` - 集成测试

**数据库**
- `alembic/` - 数据库迁移

**文档**
- `docs/` - 项目文档
- `README.md` - 项目总览与开发指南

---

## 关键决策记录

- 新 SaaS 与旧桌面版完全物理隔离
- 旧桌面版仅作为业务参考，不再作为未来主线
- 新系统从第一天起就遵循 Clean Architecture
- 持久化层提供双实现（in-memory + SQLAlchemy），方便测试
- 测试策略：集成测试优先，覆盖核心业务流程
- 数据库迁移从第一天起就版本化管理
- CI/CD 基于 Gitea Actions + 自建 runner
- **旧项目推进器（纯前端 HTML）已废弃，项目管理功能重新在 SAAS 里实现**

---

## 仓库信息

- **本地路径**: `F:\openclaw-saas`
- **远程仓库**: `xiaoxia-server:/var/lib/xiaoxia-ci/xiaoxia-saas.git`
- **分支**: `main`
- **最新提交**: `0217c8c feat: complete all backend endpoints and frontend features`

---

## 技术栈

**Backend**: Python 3.12 + FastAPI + Pydantic + SQLAlchemy + Alembic  
**Worker**: Celery + Redis  
**Database**: PostgreSQL + SQLite（测试）  
**Storage**: MinIO（S3-compatible）  
**Frontend**: Next.js 14 + TypeScript + React 18  
**CI/CD**: Gitea Actions  
**Architecture**: Clean Architecture + Ports/Adapters  
**Testing**: pytest + 集成测试优先

---

**以后每次新会话，先读这个文件 + `README.md`，快速对齐项目现状。**