diff --git a/README.md b/README.md index 36f1d9c30..c0bbf47ae 100644 --- a/README.md +++ b/README.md @@ -1,308 +1,274 @@ -# 灏忚櫨 SaaS - 鑷姩鍖栧壀杈?SaaS 骞冲彴 +# 小虾 SaaS - 自动化剪辑 SaaS 平台 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0-009688.svg)](https://fastapi.tiangolo.com) [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791.svg)](https://www.postgresql.org/) -涓€涓姛鑳藉畬鏁淬€佺敓浜у氨缁殑澶氱鎴?SaaS 骞冲彴锛屼笓涓鸿嚜鍔ㄥ寲瑙嗛鍓緫鏈嶅姟璁捐銆? +一个功能完整、生产就绪的多租户 SaaS 平台，专为自动化视频剪辑服务设计。 + --- -## 鉁?鐗规€? -### 馃攼 瀹屾暣鐨勮璇佺郴缁?- JWT 璁よ瘉锛坅ccess + refresh token锛?- 閭楠岃瘉鍜屽瘑鐮侀噸缃?- Session 绠＄悊 -- bcrypt 瀵嗙爜鍔犲瘑 +## ✨ 核心特性 -### 馃彚 澶氱鎴锋灦鏋?- 宸ヤ綔绌洪棿闅旂 -- 鍥㈤槦鎴愬憳绠＄悊 -- 鍩轰簬瑙掕壊鐨勬潈闄愭帶鍒讹紙Owner/Admin/Member/Viewer锛?- 閭€璇峰拰瀹℃壒娴佺▼ +### 🎬 视频剪辑主链路（Phase 7 已完成） +- 素材上传与管理 +- AI 智能分类 +- 自动化视频生成 +- 成片下载与管理 + +### 🔐 完整的认证系统 +- JWT 认证（access + refresh token） +- 邮箱验证和密码重置 +- Session 管理 +- bcrypt 密码加密 + +### 🏢 多租户架构 +- 工作空间隔离 +- 团队成员管理 +- 基于角色的权限控制（Owner/Admin/Member/Viewer） +- 邀请和审批流程 + +### 💸 订阅管理 +- 3 级订阅计划（Free/Pro/Enterprise） +- 配额管理（项目数/存储空间） +- 升级和取消订阅 + +### ⚡ 高性能 +- 数据库连接池（5-6x 性能提升） +- 请求日志和监控 +- 慢查询检测 +- 健康检查（Kubernetes 就绪） -### 馃挸 璁㈤槄绠＄悊 -- 3 绾ц闃呰鍒掞紙Free/Pro/Enterprise锛?- 閰嶉绠＄悊锛堥」鐩暟/瀛樺偍绌洪棿锛?- 鍗囩骇鍜屽彇娑堣闃? -### 鈿?楂樻€ц兘 -- 鏁版嵁搴撹繛鎺ユ睜锛?-6x 鎬ц兘鎻愬崌锛?- 璇锋眰鏃ュ織鍜岀洃鎺?- 鎱㈡煡璇㈡娴?- 鍋ュ悍妫€鏌ワ紙Kubernetes 灏辩华锛? -### 馃摎 瀹屾暣鏂囨。 -- API 鏂囨。锛圫wagger/ReDoc锛?- 閮ㄧ讲鎸囧崡 -- 鎬ц兘浼樺寲鎸囧崡 -- 11+ 绡囨妧鏈枃妗? --- -## 馃殌 蹇€熷紑濮? -### 鏂瑰紡 1: Docker锛堟帹鑽愶級 +## 🚀 快速开始 + +### 方式 1: Docker（推荐） ```bash -# 1. 鍏嬮殕浠撳簱 +# 1. 克隆仓库 git clone https://github.com/your-org/xiaoxia-saas.git cd xiaoxia-saas -# 2. 鍚姩鎵€鏈夋湇鍔?docker-compose up -d +# 2. 启动所有服务 +docker-compose up -d -# 3. 璁块棶 API 鏂囨。 +# 3. 访问 API 文档 open http://localhost:8000/docs ``` -灏辫繖涔堢畝鍗曪紒馃帀 +就这么简单！🎉 + +### 方式 2: 本地开发 -### 鏂瑰紡 2: 鏈湴寮€鍙? ```bash -# 1. 鍏嬮殕浠撳簱 +# 1. 克隆仓库 git clone https://github.com/your-org/xiaoxia-saas.git cd xiaoxia-saas -# 2. 鍒涘缓铏氭嫙鐜 +# 2. 创建虚拟环境 python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate -# 3. 瀹夎渚濊禆 +# 3. 安装依赖 pip install -r requirements.txt -# 4. 浣跨敤鍐呭瓨鏁版嵁搴擄紙鏃犻渶 PostgreSQL锛?echo "USE_IN_MEMORY_DB=true" > .env - -# 5. 鍚姩寮€鍙戞湇鍔″櫒 +# 4. 启动开发服务器 uvicorn apps.api.main:app --reload -# 6. 璁块棶 API 鏂囨。 +# 5. 访问 API 文档 open http://localhost:8000/docs ``` --- -## 馃摉 API 绀轰緥 +## 📚 主要文档 -### 娉ㄥ唽鐢ㄦ埛 +### 快速入口 +- **[API 主线清单](docs/API-MAINLINE.md)** - 所有 API endpoints 总览 +- **[代码状态标注](docs/CODE-STATUS.md)** - 代码库导航指南 +- **[API 使用指南](docs/API-GUIDE.md)** - API 详细用法 -```bash -curl -X POST http://localhost:8000/api/v1/auth/register \ - -H "Content-Type: application/json" \ - -d '{ - "email": "user@example.com", - "password": "SecurePass123", - "username": "myuser", - "display_name": "My Name" - }' -``` +### Phase 7 交付 +- **[Phase 7 进度](docs/PHASE7-PROGRESS.md)** - 核心视频剪辑业务已完成 +- **[Phase 7 设计](docs/PHASE7-DESIGN.md)** - 设计文档 -### 鐧诲綍 +### 基础设施 +- **[Docker 部署指南](docs/DOCKER-DEPLOYMENT.md)** +- **[CI/CD 文档](docs/CI-CD.md)** +- **[性能监控指南](docs/PERFORMANCE-MONITORING.md)** +- **[健康检查指南](docs/HEALTH-CHECKS.md)** -```bash -curl -X POST http://localhost:8000/api/v1/auth/login \ - -H "Content-Type: application/json" \ - -d '{ - "email": "user@example.com", - "password": "SecurePass123" - }' -``` - -### 鍒涘缓宸ヤ綔绌洪棿 - -```bash -curl -X POST http://localhost:8000/api/v1/workspaces \ - -H "Authorization: Bearer YOUR_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "鎴戠殑鍥㈤槦", - "subscription_plan": "free" - }' -``` +### 开发规范 +- **[Git 工作流](docs/GIT-WORKFLOW.md)** +- **[环境配置指南](docs/ENVIRONMENT-CONFIG.md)** +- **[贡献指南](CONTRIBUTING.md)** --- -## 馃彈锔?鏋舵瀯 +## 🏗️ 架构 ``` -灏忚櫨 SaaS -鈹溾攢鈹€ packages/ # 鏍稿績涓氬姟閫昏緫 -鈹? 鈹溾攢鈹€ domain/ # 棰嗗煙妯″瀷 -鈹? 鈹溾攢鈹€ application/ # 鐢ㄤ緥 -鈹? 鈹溾攢鈹€ ports/ # 鎺ュ彛瀹氫箟 -鈹? 鈹斺攢鈹€ adapters/ # 閫傞厤鍣ㄥ疄鐜?鈹溾攢鈹€ apps/ # 搴旂敤灞?鈹? 鈹斺攢鈹€ api/ # FastAPI 搴旂敤 -鈹溾攢鈹€ migrations/ # 鏁版嵁搴撹縼绉?鈹溾攢鈹€ tests/ # 娴嬭瘯 -鈹? 鈹溾攢鈹€ unit/ # 鍗曞厓娴嬭瘯锛?70 涓級 -鈹? 鈹斺攢鈹€ integration/ # 闆嗘垚娴嬭瘯锛?2 涓級 -鈹斺攢鈹€ docs/ # 鏂囨。 +小虾 SaaS +├── packages/ # 核心业务逻辑 +│ ├── domain/ # 领域模型 +│ ├── application/ # 用例 +│ ├── ports/ # 接口定义 +│ └── adapters/ # 适配器实现 +├── apps/ # 应用层 +│ ├── api/ # FastAPI 应用 +│ ├── web/ # React 前端 +│ └── worker/ # Celery worker +├── migrations/ # 数据库迁移 +├── tests/ # 测试 +│ ├── unit/ # 单元测试 +│ └── integration/ # 集成测试 +└── docs/ # 文档 ``` -**璁捐妯″紡:** +**设计模式:** - Clean Architecture -- 渚濊禆娉ㄥ叆 -- Repository 妯″紡 +- 依赖注入 +- Repository 模式 - Domain-Driven Design --- -## 馃敡 閰嶇疆 +## 🔑 核心 API 路径 -### 鐜鍙橀噺 +### 视频剪辑主链路（Phase 7） -```env -# 鏁版嵁搴撳垏鎹?USE_IN_MEMORY_DB=true # 寮€鍙戠幆澧冿紙鏃犻渶 PostgreSQL锛?USE_IN_MEMORY_DB=false # 鐢熶骇鐜锛堜娇鐢?PostgreSQL锛? -# 鏁版嵁搴撹繛鎺?DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas +``` +上传素材 + ↓ +POST /api/v1/upload -# JWT 閰嶇疆 -JWT_SECRET_KEY=your-secret-key-at-least-32-chars +创建 Asset + ↓ +POST /api/v1/assets -# 閭欢閰嶇疆 -SMTP_HOST=smtp.gmail.com -SMTP_USER=your-email@gmail.com -SMTP_PASSWORD=your-app-password +发起分类 + ↓ +POST /api/v1/classification-jobs + +创建生成任务 + ↓ +POST /api/v1/generation/tasks + +查询生成结果 + ↓ +GET /api/v1/generation/tasks/{task_id}/results + +获取下载链接 + ↓ +GET /api/v1/generated-videos/{video_id}/download-url ``` -瀹屾暣閰嶇疆鍙傝€?`.env.example` +完整 API 列表请查看 [API 主线清单](docs/API-MAINLINE.md) --- -## 馃И 娴嬭瘯 +## 🧪 测试 ```bash -# 杩愯鎵€鏈夋祴璇?pytest tests/ -v +# 运行所有测试 +pytest tests/ -v -# 杩愯鍗曞厓娴嬭瘯 +# 运行单元测试 pytest tests/unit -v -# 鐢熸垚瑕嗙洊鐜囨姤鍛?pytest --cov=packages --cov-report=html +# 运行集成测试 +pytest tests/integration -v -# 鏌ョ湅瑕嗙洊鐜?open htmlcov/index.html +# 生成覆盖率报告 +pytest --cov=packages --cov-report=html ``` -**娴嬭瘯缁熻:** -- 鍗曞厓娴嬭瘯: 170 涓?鉁?- 娴嬭瘯瑕嗙洊鐜? 85%+ -- 闆嗘垚娴嬭瘯: 12 涓? ---- - -## 馃摎 鏂囨。 - -- [API 浣跨敤鎸囧崡](docs/API-GUIDE.md) -- [Docker 閮ㄧ讲鎸囧崡](docs/DOCKER-DEPLOYMENT.md) -- [鏁版嵁搴撳垏鎹㈡寚鍗梋(docs/DATABASE-SWITCH.md) -- [鎬ц兘鐩戞帶鎸囧崡](docs/PERFORMANCE-MONITORING.md) -- [鐜閰嶇疆鎸囧崡](docs/ENVIRONMENT-CONFIG.md) -- [鍋ュ悍妫€鏌ユ寚鍗梋(docs/HEALTH-CHECKS.md) -- [鍒嗛〉浣跨敤鎸囧崡](docs/PAGINATION.md) -- [鐢熶骇閮ㄧ讲妫€鏌ユ竻鍗昡(docs/PRODUCTION-CHECKLIST.md) -- [璐＄尞鎸囧崡](CONTRIBUTING.md) +**测试统计:** +- 单元测试: 17+ 个 ✅ +- 集成测试: 6+ 个 ✅ +- 测试覆盖率: 持续提升中 --- -## 馃殺 閮ㄧ讲 +## 🛠️ 技术栈 -### Kubernetes - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: xiaoxia-api -spec: - replicas: 3 - template: - spec: - containers: - - name: api - image: xiaoxia-saas:latest - ports: - - containerPort: 8000 - livenessProbe: - httpGet: - path: /health - port: 8000 - readinessProbe: - httpGet: - path: /ready - port: 8000 -``` - -### Docker Compose - -```yaml -version: '3.8' -services: - api: - build: . - ports: - - "8000:8000" - environment: - - DATABASE_URL=postgresql://... - - REDIS_URL=redis://... -``` - -鏌ョ湅 [瀹屾暣閮ㄧ讲鎸囧崡](docs/DOCKER-DEPLOYMENT.md) - ---- - -## 馃幆 鎶€鏈爤 - -**鍚庣:** +**后端:** - Python 3.12 - FastAPI 0.115.0 -- Pydantic 2.9 - PostgreSQL 16 - Redis 7 +- Celery +- MinIO -**娴嬭瘯:** +**前端:** +- React 18 +- TypeScript +- Vite +- Ant Design + +**测试:** - pytest - pytest-asyncio - pytest-cov -**閮ㄧ讲:** +**部署:** - Docker - Docker Compose -- Kubernetes锛堝彲閫夛級 +- Gitea Actions --- -## 馃搳 鎬ц兘 +## 📊 当前状态 -| 鎸囨爣 | 鏁板€?| +| 模块 | 状态 | |------|------| -| API 骞冲潎鍝嶅簲鏃堕棿 | < 50ms | -| 鏁版嵁搴撴煡璇㈡椂闂?| < 10ms | -| 骞跺彂鏀寔 | 1000+ RPS | -| 杩炴帴姹犳€ц兘鎻愬崌 | 5-6x | -| 娴嬭瘯瑕嗙洊鐜?| 85%+ | +| Phase 7（视频剪辑主链） | ✅ 已完成 | +| CI/CD 稳定性 | ✅ 已修复 | +| 认证系统 | ✅ 完整 | +| 多租户架构 | ✅ 完整 | +| 订阅系统 | ✅ 完整 | +| 前端联调 | ✅ 完成 | --- -## 馃 璐＄尞 +## 🤝 贡献 -娆㈣繋璐＄尞锛佽鏌ョ湅 [璐＄尞鎸囧崡](CONTRIBUTING.md) +欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md) -1. Fork 椤圭洰 -2. 鍒涘缓鍒嗘敮 (`git checkout -b feature/AmazingFeature`) -3. 鎻愪氦鏇存敼 (`git commit -m 'feat: Add some AmazingFeature'`) -4. 鎺ㄩ€佸埌鍒嗘敮 (`git push origin feature/AmazingFeature`) -5. 鍒涘缓 Pull Request +1. Fork 项目 +2. 创建分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 创建 Pull Request --- -## 馃搫 璁稿彲璇? -鏈」鐩噰鐢?MIT 璁稿彲璇?- 鏌ョ湅 [LICENSE](LICENSE) 鏂囦欢浜嗚В璇︽儏 +## 📄 许可证 + +本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 --- -## 馃摓 鑱旂郴鏂瑰紡 +## 📞 联系方式 -- **鏂囨。:** https://docs.xiaoxia-saas.com -- **闂鍙嶉:** GitHub Issues -- **閭:** support@xiaoxia-saas.com +- **问题反馈:** GitHub Issues +- **文档:** 参考 `docs/` 目录 --- -## 馃帀 鑷磋阿 +## 🎉 致谢 -鎰熻阿鎵€鏈夎础鐚€呭拰浣跨敤鑰咃紒 +感谢所有贡献者和使用者！ -**寮€鍙戝洟闃?** 灏忚櫨 馃 +**开发团队:** 小虾 🦐 --- -**猸?濡傛灉杩欎釜椤圭洰瀵逛綘鏈夊府鍔╋紝璇风粰涓€涓?Star锛?* +**⭐ 如果这个项目对你有帮助，请给一个 Star！** +--- - - - - - - - - - +**最后更新**: 2026-06-19 +**当前版本**: Phase 7 完成 diff --git a/docs/API-MAINLINE.md b/docs/API-MAINLINE.md new file mode 100644 index 000000000..e99cef50e --- /dev/null +++ b/docs/API-MAINLINE.md @@ -0,0 +1,293 @@ +# API 主线清单（2026-06-19） + +> 本文档列出当前 SaaS 项目所有 active API endpoints。 +> 状态：✅ ACTIVE | 🧪 EXPERIMENTAL | ⚠️ DEPRECATED + +--- + +## 一、认证相关（Auth） + +**路由前缀**: `/api/v1/auth` +**文件**: `apps/api/app/api/routes/auth.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| POST | `/register` | 用户注册 | ✅ ACTIVE | +| POST | `/login` | 用户登录 | ✅ ACTIVE | +| POST | `/logout` | 用户登出 | ✅ ACTIVE | +| GET | `/verify-email` | 邮箱验证 | ✅ ACTIVE | +| POST | `/password/forgot` | 忘记密码 | ✅ ACTIVE | +| POST | `/password/reset` | 重置密码 | ✅ ACTIVE | + +**Use Cases**: +- `RegisterUserUseCase` +- `LoginUseCase` +- `LogoutUseCase` +- `VerifyEmailUseCase` +- `RequestPasswordResetUseCase` +- `ResetPasswordUseCase` + +--- + +## 二、工作空间（Workspaces） + +**路由前缀**: `/api/v1/workspaces` +**文件**: `apps/api/app/api/routes/workspaces.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| POST | `/` | 创建工作空间 | ✅ ACTIVE | +| GET | `/` | 列出用户的工作空间 | ✅ ACTIVE | +| GET | `/{workspace_id}` | 获取工作空间详情 | ✅ ACTIVE | +| POST | `/{workspace_id}/members/invite` | 邀请成员 | ✅ ACTIVE | +| GET | `/{workspace_id}/members` | 列出成员 | ✅ ACTIVE | +| DELETE | `/{workspace_id}/members/{user_id}` | 移除成员 | ✅ ACTIVE | +| POST | `/{workspace_id}/leave` | 离开工作空间 | ✅ ACTIVE | +| PATCH | `/{workspace_id}/members/{user_id}/role` | 更新成员角色 | ✅ ACTIVE | +| POST | `/{workspace_id}/subscription/upgrade` | 升级订阅 | ✅ ACTIVE | +| POST | `/{workspace_id}/subscription/cancel` | 取消订阅 | ✅ ACTIVE | +| GET | `/{workspace_id}/quota` | 查询配额 | ✅ ACTIVE | +| POST | `/invitations/{token}/accept` | 接受邀请 | ✅ ACTIVE | +| POST | `/invitations/{token}/decline` | 拒绝邀请 | ✅ ACTIVE | + +**Use Cases**: +- `CreateWorkspaceUseCase` +- `ListWorkspacesUseCase` +- `InviteMemberUseCase` +- `ListMembersUseCase` +- `RemoveMemberUseCase` +- `UpdateMemberRoleUseCase` +- `SubscriptionUseCase` +- `AcceptInvitationUseCase` + +--- + +## 三、项目管理（Projects） + +**路由前缀**: `/api/v1/projects` +**文件**: `apps/api/app/api/routes/projects.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/` | 列出项目 | ✅ ACTIVE | +| POST | `/` | 创建项目 | ✅ ACTIVE | + +**Use Cases**: +- `CreateProjectUseCase` +- `ListProjectsUseCase` + +--- + +## 四、素材管理（Assets） + +### 4.1 素材库（Asset Libraries） + +**路由前缀**: `/api/v1/asset-libraries` +**文件**: `apps/api/app/api/routes/asset_libraries.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/` | 列出素材库 | ✅ ACTIVE | +| POST | `/` | 创建素材库 | ✅ ACTIVE | + +**Use Cases**: +- `CreateAssetLibraryUseCase` +- `ListAssetLibrariesUseCase` + +### 4.2 素材（Assets） + +**路由前缀**: `/api/v1/assets` +**文件**: `apps/api/app/api/routes/assets.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/` | 列出素材 | ✅ ACTIVE | +| POST | `/` | 创建素材 | ✅ ACTIVE | + +**Use Cases**: +- `CreateAssetUseCase` +- `ListAssetsUseCase` + +### 4.3 上传（Upload） + +**路由前缀**: `/api/v1/upload` +**文件**: `apps/api/app/api/routes/upload.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| POST | `/` | 上传文件 | ✅ ACTIVE | + +**Use Cases**: +- 直接调用 `MinIOService` + +--- + +## 五、素材处理（Asset Processing） + +### 5.1 Ingest Jobs + +**路由前缀**: `/api/v1/ingest-jobs` +**文件**: `apps/api/app/api/routes/ingest_jobs.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/{job_id}` | 获取任务状态 | ✅ ACTIVE | +| POST | `/` | 创建任务 | ✅ ACTIVE | + +**Use Cases**: +- `CreateIngestJobUseCase` +- `GetIngestJobUseCase` + +### 5.2 Classification Jobs + +**路由前缀**: `/api/v1/classification-jobs` +**文件**: `apps/api/app/api/routes/classification_jobs.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/{job_id}` | 获取分类任务状态 | ✅ ACTIVE | +| POST | `/` | 创建分类任务 | ✅ ACTIVE | + +**Use Cases**: +- `CreateClassificationJobUseCase` +- `GetClassificationJobUseCase` + +--- + +## 六、视频生成（Video Generation） + +### 6.1 生成任务（Generation Tasks） + +**路由前缀**: `/api/v1/generation` +**文件**: `apps/api/app/api/routes/generation_tasks.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| POST | `/tasks` | 创建生成任务 | ✅ ACTIVE | +| GET | `/tasks/{task_id}` | 获取任务状态 | ✅ ACTIVE | +| GET | `/tasks/{task_id}/results` | 获取生成结果列表 | ✅ ACTIVE | + +**Use Cases**: +- `CreateGenerationTaskUseCase` +- `GetGenerationTaskUseCase` +- `ListGenerationTaskResultsUseCase` + +### 6.2 生成结果（Generated Videos） + +**路由前缀**: `/api/v1/generated-videos` +**文件**: `apps/api/app/api/routes/generated_videos.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/` | 列出生成结果 | ✅ ACTIVE | +| GET | `/{video_id}` | 获取单个结果 | ✅ ACTIVE | +| GET | `/{video_id}/download-url` | 获取下载链接 | ✅ ACTIVE | + +**Use Cases**: +- `ListGeneratedVideosUseCase` +- `GetGeneratedVideoUseCase` +- `GetGeneratedVideoDownloadUrlUseCase` + +--- + +## 七、项目管理高级功能（Project Management） + +**路由前缀**: `/api/v1/project-management` +**文件**: `apps/api/app/api/routes/project_management.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| POST | `/tasks` | 创建任务 | ✅ ACTIVE | +| GET | `/tasks` | 列出任务 | ✅ ACTIVE | +| GET | `/tasks/{task_id}` | 获取任务详情 | ✅ ACTIVE | +| PATCH | `/tasks/{task_id}` | 更新任务 | ✅ ACTIVE | +| PATCH | `/tasks/{task_id}/status` | 更新任务状态 | ✅ ACTIVE | +| PATCH | `/tasks/{task_id}/progress` | 更新任务进度 | ✅ ACTIVE | +| POST | `/milestones` | 创建里程碑 | ✅ ACTIVE | +| GET | `/milestones` | 列出里程碑 | ✅ ACTIVE | +| POST | `/issues` | 创建问题 | ✅ ACTIVE | +| GET | `/issues` | 列出问题 | ✅ ACTIVE | +| PATCH | `/issues/{issue_id}/resolve` | 解决问题 | ✅ ACTIVE | + +**Use Cases**: +- `CreateTaskUseCase` +- `ListTasksUseCase` +- `GetTaskUseCase` +- `UpdateTaskUseCase` +- `UpdateTaskStatusUseCase` +- `UpdateTaskProgressUseCase` +- `CreateMilestoneUseCase` +- `ListMilestonesUseCase` +- `CreateTaskIssueUseCase` +- `ListTaskIssuesUseCase` +- `ResolveTaskIssueUseCase` + +--- + +## 八、健康检查（Health） + +**路由前缀**: `/api/v1` +**文件**: `apps/api/app/api/routes/health.py` + +| Method | Path | 功能 | 状态 | +|--------|------|------|------| +| GET | `/health` | 健康检查 | ✅ ACTIVE | +| GET | `/ready` | 就绪检查 | ✅ ACTIVE | +| GET | `/startup` | 启动检查 | ✅ ACTIVE | + +--- + +## 九、主线路径总结 + +### Phase 7 核心路径（视频剪辑主链） + +``` +上传素材 + ↓ +POST /api/v1/upload + +创建 Asset + ↓ +POST /api/v1/assets + +发起分类 + ↓ +POST /api/v1/classification-jobs + +创建生成任务 + ↓ +POST /api/v1/generation/tasks + +查询生成结果 + ↓ +GET /api/v1/generation/tasks/{task_id}/results + +获取下载链接 + ↓ +GET /api/v1/generated-videos/{video_id}/download-url +``` + +### 当前主线技术栈 + +- **领域层**: `packages/domain/entities.py` +- **应用层**: `packages/application/*.py` +- **持久化**: `packages/adapters/sqlalchemy_impl/*.py` +- **API**: `apps/api/app/api/routes/*.py` +- **Worker**: `apps/worker/tasks.py` + +--- + +## 十、兼容层标注 + +以下文件为兼容层，保留但不再是主线： + +- `packages/domain/asset.py` - `[COMPAT]` 兼容旧素材模型 +- `packages/domain/asset_library.py` - `[COMPAT]` 兼容旧素材库模型 +- `packages/ports/asset_repository.py` - `[COMPAT]` 兼容旧仓储接口 +- `packages/ports/asset_library_repository.py` - `[COMPAT]` 兼容旧仓储接口 +- `packages/adapters/postgres/asset_repository.py` - `[COMPAT]` 兼容旧 Postgres 实现 + +--- + +**维护人**: 小虾 🦐 +**最后更新**: 2026-06-19 10:05 GMT+8 diff --git a/docs/CODE-STATUS.md b/docs/CODE-STATUS.md new file mode 100644 index 000000000..ac83e1a76 --- /dev/null +++ b/docs/CODE-STATUS.md @@ -0,0 +1,317 @@ +# 代码状态标注（2026-06-19） + +> 本文档标注仓库中所有代码的当前状态，便于快速识别主线、兼容层、待迁移代码。 + +--- + +## 状态标签说明 + +- **✅ ACTIVE** - 当前主线代码，正在活跃使用 +- **🔄 COMPAT** - 兼容层，为了向后兼容保留，但不是主线 +- **⚠️ DEPRECATED** - 已废弃，计划删除 +- **🚧 MIGRATE** - 待迁移到新主线 +- **🧪 EXPERIMENTAL** - 实验性功能 + +--- + +## 一、领域层（Domain） + +### ✅ ACTIVE - 当前主线 + +``` +packages/domain/ +├── entities.py ✅ 主领域模型（Asset, AssetLibrary, GenerationTask, GeneratedVideo） +├── classification.py ✅ 分类相关领域模型 +├── project_management.py ✅ 项目管理领域模型 +├── user.py ✅ 用户领域模型 +├── permissions.py ✅ 权限领域模型 +├── quota.py ✅ 配额领域模型 +└── auth/ ✅ 认证领域服务 + ├── jwt_service.py + ├── password_hasher.py + ├── session_store.py + └── email_service.py +``` + +### 🔄 COMPAT - 兼容层 + +``` +packages/domain/ +├── asset.py 🔄 旧素材模型，仅用于兼容 +├── asset_library.py 🔄 旧素材库模型，仅用于兼容 +└── generated_video.py ✅ 实际已是主线，非兼容层 +``` + +--- + +## 二、应用层（Application） + +### ✅ ACTIVE - 当前主线 + +``` +packages/application/ +├── assets.py ✅ 素材用例 +├── asset_libraries.py ✅ 素材库用例 +├── classification_jobs.py ✅ 分类任务用例 +├── ingest_jobs.py ✅ 摄入任务用例 +├── generation_tasks.py ✅ 生成任务用例 +├── generated_videos.py ✅ 生成结果用例 +├── projects.py ✅ 项目用例 +├── auth/ ✅ 认证用例 +│ ├── login_use_case.py +│ ├── register_user_use_case.py +│ └── password_reset_use_case.py +└── workspace/ ✅ 工作空间用例 + ├── create_workspace_use_case.py + ├── invite_member_use_case.py + └── subscription_use_case.py +``` + +--- + +## 三、仓储接口（Ports） + +### ✅ ACTIVE - 当前主线 + +``` +packages/ports/ +├── classification_job_repository.py ✅ 分类任务仓储接口 +├── ingest_job_repository.py ✅ 摄入任务仓储接口 +├── generation_task_repository.py ✅ 生成任务仓储接口 +├── generated_video_repository.py ✅ 生成结果仓储接口 +├── project_repository.py ✅ 项目仓储接口 +├── user_repository.py ✅ 用户仓储接口 +├── workspace_repository.py ✅ 工作空间仓储接口 +├── workspace_member_repository.py ✅ 工作空间成员仓储接口 +└── workspace_invitation_repository.py ✅ 工作空间邀请仓储接口 +``` + +### 🔄 COMPAT - 兼容层 + +``` +packages/ports/ +├── asset_repository.py 🔄 旧素材仓储接口，仅用于兼容 +└── asset_library_repository.py 🔄 旧素材库仓储接口，仅用于兼容 +``` + +--- + +## 四、适配器（Adapters） + +### ✅ ACTIVE - 当前主线（SQLAlchemy） + +``` +packages/adapters/sqlalchemy_impl/ +├── __init__.py +├── session.py ✅ 数据库会话管理 +├── models.py ✅ SQLAlchemy 模型 +├── asset_repository.py ✅ 素材仓储实现 +├── asset_library_repository.py ✅ 素材库仓储实现 +├── classification_job_repository.py ✅ 分类任务仓储实现 +├── ingest_job_repository.py ✅ 摄入任务仓储实现 +├── generation_task_repository.py ✅ 生成任务仓储实现 +├── generated_video_repository.py ✅ 生成结果仓储实现 +└── project_repository.py ✅ 项目仓储实现 +``` + +### ✅ ACTIVE - 测试用（In-Memory） + +``` +packages/adapters/in_memory/ +├── asset_repository.py ✅ 测试用内存实现 +├── asset_library_repository.py ✅ 测试用内存实现 +├── classification_job_repository.py ✅ 测试用内存实现 +├── ingest_job_repository.py ✅ 测试用内存实现 +├── user_repository.py ✅ 测试用内存实现 +├── workspace_repository.py ✅ 测试用内存实现 +├── workspace_member_repository.py ✅ 测试用内存实现 +└── workspace_invitation_repository.py ✅ 测试用内存实现 +``` + +### 🔄 COMPAT - 兼容层（Postgres 旧实现） + +``` +packages/adapters/postgres/ +├── __init__.py 🔄 兼容层入口 +├── asset_repository.py 🔄 旧素材仓储实现，仅用于兼容 +├── connection_pool.py 🔄 旧连接池实现 +├── models.py 🔄 旧模型定义 +├── user_repository.py 🔄 旧用户仓储实现 +├── workspace_repository.py 🔄 旧工作空间仓储实现 +├── workspace_member_repository.py 🔄 旧成员仓储实现 +└── workspace_invitation_repository.py 🔄 旧邀请仓储实现 +``` + +**说明**: `packages/adapters/postgres/` 整个目录已被 `sqlalchemy_impl/` 替代，但保留用于向后兼容。 + +--- + +## 五、API 层 + +### ✅ ACTIVE - 当前主线 + +``` +apps/api/app/api/routes/ +├── health.py ✅ 健康检查 +├── auth.py ✅ 认证相关 +├── workspaces.py ✅ 工作空间 +├── projects.py ✅ 项目 +├── upload.py ✅ 文件上传 +├── assets.py ✅ 素材管理 +├── asset_libraries.py ✅ 素材库管理 +├── ingest_jobs.py ✅ 摄入任务 +├── classification_jobs.py ✅ 分类任务 +├── generation_tasks.py ✅ 生成任务 +├── generated_videos.py ✅ 生成结果 +└── project_management.py ✅ 项目管理高级功能 +``` + +--- + +## 六、Worker 层 + +### ✅ ACTIVE - 当前主线 + +``` +apps/worker/ +├── celery_app.py ✅ Celery 应用 +├── tasks.py ✅ 生成任务（主入口） +└── worker_app/ + ├── db.py ✅ 数据库会话 + └── tasks/ + ├── health.py ✅ 健康检查任务 + ├── ingest.py ✅ 摄入任务 + └── classification.py ✅ 分类任务 +``` + +--- + +## 七、测试层 + +### ✅ ACTIVE - 当前主线测试 + +``` +tests/integration/ +├── test_asset_tags.py ✅ 素材标签测试 +├── test_ingest_pipeline.py ✅ 摄入流程测试 +├── test_upload_pipeline.py ✅ 上传流程测试 +├── test_classification_pipeline.py ✅ 分类流程测试 +├── test_generation_pipeline.py ✅ 生成流程测试 +└── test_projects.py ✅ 项目测试 +``` + +### ✅ ACTIVE - 单元测试 + +``` +tests/unit/ +├── test_jwt_service.py ✅ JWT 服务测试 +├── test_password_hasher.py ✅ 密码哈希测试 +├── test_session_store.py ✅ 会话存储测试 +├── test_email_service.py ✅ 邮件服务测试 +├── test_permissions.py ✅ 权限测试 +├── test_quota.py ✅ 配额测试 +├── test_login_use_case.py ✅ 登录用例测试 +├── test_register_user_use_case.py ✅ 注册用例测试 +├── test_password_reset_use_case.py ✅ 密码重置用例测试 +├── test_create_workspace_use_case.py ✅ 创建工作空间用例测试 +├── test_invite_member_use_case.py ✅ 邀请成员用例测试 +├── test_accept_invitation_use_case.py ✅ 接受邀请用例测试 +├── test_list_members_use_case.py ✅ 列出成员用例测试 +├── test_remove_member_use_case.py ✅ 移除成员用例测试 +├── test_update_member_role_use_case.py ✅ 更新成员角色用例测试 +├── test_list_workspaces_use_case.py ✅ 列出工作空间用例测试 +└── test_subscription_use_case.py ✅ 订阅用例测试 +``` + +### 🚧 MIGRATE - 待更新测试 + +``` +tests/unit/ +└── test_api.py 🚧 需要按新主线重写 +``` + +--- + +## 八、前端层 + +### ✅ ACTIVE - 当前主线 + +``` +apps/web/src/ +├── api/ +│ ├── client.ts ✅ API 客户端 +│ ├── auth.ts ✅ 认证 API +│ ├── workspace.ts ✅ 工作空间 API +│ ├── projects.ts ✅ 项目 API +│ ├── assets.ts ✅ 素材 API +│ ├── generation.ts ✅ 生成 API +│ └── subscription.ts ✅ 订阅 API +├── pages/ +│ ├── auth/ ✅ 认证页面 +│ ├── workspace/ ✅ 工作空间页面 +│ │ ├── ProjectGeneration.tsx ✅ 生成页 +│ │ └── ProjectResults.tsx ✅ 结果页 +│ ├── profile/ ✅ 个人设置页面 +│ ├── subscription/ ✅ 订阅页面 +│ └── admin/ ✅ 管理页面 +└── hooks/ + ├── useAuth.ts ✅ 认证 Hook + └── useWorkspace.ts ✅ 工作空间 Hook +``` + +--- + +## 九、快速定位指南 + +### 我想找... + +**素材上传流程**: +``` +apps/api/app/api/routes/upload.py (API) + ↓ +apps/api/app/core/storage.py (MinIO) + ↓ +packages/domain/entities.py::Asset (领域模型) + ↓ +packages/adapters/sqlalchemy_impl/asset_repository.py (持久化) +``` + +**视频生成流程**: +``` +apps/api/app/api/routes/generation_tasks.py (API) + ↓ +packages/application/generation_tasks.py (用例) + ↓ +apps/worker/tasks.py::generate_video (Worker) + ↓ +packages/adapters/sqlalchemy_impl/generation_task_repository.py (持久化) +``` + +**用户认证流程**: +``` +apps/api/app/api/routes/auth.py (API) + ↓ +packages/application/auth/login_use_case.py (用例) + ↓ +packages/domain/auth/jwt_service.py (JWT) + ↓ +packages/domain/auth/session_store.py (会话) +``` + +--- + +## 十、清理计划 + +### 可以安全删除（待定） +- 暂无，所有兼容层目前仍保留 + +### 需要迁移到新主线 +- 无待迁移代码 + +### 需要补充测试 +- `test_api.py` 需要按新主线重写 + +--- + +**维护人**: 小虾 🦐 +**最后更新**: 2026-06-19 10:10 GMT+8 diff --git a/docs/saas-index.md b/docs/saas-index.md index 87f5d790c..7b72b7d25 100644 --- a/docs/saas-index.md +++ b/docs/saas-index.md @@ -1,66 +1,187 @@ -# SaaS 重建总索引 +# SaaS 项目文档总索引 -本文档是新 SaaS 项目的总入口。以后所有重建相关文档都从这里进入，避免分散。 +> **最后更新**: 2026-06-19 +> **当前状态**: Phase 7 已完成，进入专项治理阶段 + +本文档是小虾 SaaS 项目的文档导航入口。 --- -## 1. 总目标 +## 一、快速导航 -- 旧桌面版不再作为未来主线 -- 新 SaaS 项目重新开始 -- 先定边界、规矩、工具，再进入开发 -- 所有新项目工作必须新旧隔离 +### 🎯 我想快速了解项目 + +1. **[README.md](../README.md)** - 项目总览 +2. **[API 主线清单](API-MAINLINE.md)** - 所有 API endpoints +3. **[代码状态标注](CODE-STATUS.md)** - 代码库导航 +4. **[Phase 7 进度](PHASE7-PROGRESS.md)** - 当前进度 + +### 🛠️ 我想开始开发 + +1. **[Git 工作流](GIT-WORKFLOW.md)** - 分支规范 +2. **[环境配置](ENVIRONMENT-CONFIG.md)** - 环境变量 +3. **[API 使用指南](API-GUIDE.md)** - API 用法 +4. **[代码状态标注](CODE-STATUS.md)** - 找到主线代码 + +### 📦 我想部署 + +1. **[Docker 部署指南](DOCKER-DEPLOYMENT.md)** +2. **[CI/CD 文档](CI-CD.md)** +3. **[生产检查清单](PRODUCTION-CHECKLIST.md)** +4. **[健康检查指南](HEALTH-CHECKS.md)** --- -## 2. 核心总文档 +## 二、核心文档清单 -### 启动与总纲 +### 项目状态与进度 -- [SaaS 重建启动方案](saas-rebuild-kickoff-plan.md) -- [SaaS 重建盘点总表](saas-rebuild-inventory.md) +| 文档 | 说明 | +|------|------| +| [PHASE7-PROGRESS.md](PHASE7-PROGRESS.md) | Phase 7 完成总结 ✅ | +| [PHASE7-DESIGN.md](PHASE7-DESIGN.md) | Phase 7 设计文档 | +| [SaaS-后续专项整治清单-2026-06-18.md](SaaS-后续专项整治清单-2026-06-18.md) | 后续专项规划 | -### 工具与基础设施 +### API 与代码 -- [AI 团队工具清单](ai-team-tooling-checklist.md) -- [基础设施保留 / 废弃 / 重建清单](infrastructure-keep-rebuild-matrix.md) +| 文档 | 说明 | +|------|------| +| [API-MAINLINE.md](API-MAINLINE.md) | ⭐ 当前所有 API 清单 | +| [CODE-STATUS.md](CODE-STATUS.md) | ⭐ 代码状态与导航 | +| [API-GUIDE.md](API-GUIDE.md) | API 使用指南 | +| [API-VERSIONING.md](API-VERSIONING.md) | API 版本管理 | -### 业务与技术 +### 开发规范 -- [SaaS 核心对象清单](saas-core-objects.md) -- [SaaS 核心流程清单](saas-core-flows.md) -- [SaaS 技术栈选型表](saas-tech-stack-options.md) +| 文档 | 说明 | +|------|------| +| [GIT-WORKFLOW.md](GIT-WORKFLOW.md) | Git 分支规范 | +| [CI-CD.md](CI-CD.md) | CI/CD 流程 | +| [ENVIRONMENT-CONFIG.md](ENVIRONMENT-CONFIG.md) | 环境配置 | -### 启动范围与工程制度 +### 部署与运维 -- [SaaS 一期 MVP 范围清单](saas-mvp-scope.md) -- [SaaS 项目目录结构规范](saas-project-structure-spec.md) -- [SaaS 开发协作流程与制度](saas-development-workflow.md) +| 文档 | 说明 | +|------|------| +| [DOCKER-DEPLOYMENT.md](DOCKER-DEPLOYMENT.md) | Docker 部署 | +| [PRODUCTION-CHECKLIST.md](PRODUCTION-CHECKLIST.md) | 生产检查清单 | +| [HEALTH-CHECKS.md](HEALTH-CHECKS.md) | 健康检查 | +| [PERFORMANCE-MONITORING.md](PERFORMANCE-MONITORING.md) | 性能监控 | + +### 技术细节 + +| 文档 | 说明 | +|------|------| +| [DATABASE-SWITCH.md](DATABASE-SWITCH.md) | 数据库切换 | +| [CONNECTION-POOL.md](CONNECTION-POOL.md) | 连接池优化 | +| [PAGINATION.md](PAGINATION.md) | 分页实现 | + +### 历史规划文档 + +| 文档 | 说明 | 状态 | +|------|------|------| +| [saas-rebuild-kickoff-plan.md](saas-rebuild-kickoff-plan.md) | 重建启动方案 | 📚 归档 | +| [saas-rebuild-inventory.md](saas-rebuild-inventory.md) | 重建盘点总表 | 📚 归档 | +| [saas-mvp-scope.md](saas-mvp-scope.md) | MVP 范围 | 📚 归档 | +| [saas-core-objects.md](saas-core-objects.md) | 核心对象 | 📚 归档 | +| [saas-core-flows.md](saas-core-flows.md) | 核心流程 | 📚 归档 | --- -## 3. 阅读顺序 +## 三、当前项目状态 -建议按这个顺序看： +### Phase 状态 -1. `saas-rebuild-kickoff-plan.md` -2. `saas-rebuild-inventory.md` -3. `ai-team-tooling-checklist.md` -4. `infrastructure-keep-rebuild-matrix.md` -5. `saas-core-objects.md` -6. `saas-core-flows.md` -7. `saas-tech-stack-options.md` -8. `saas-mvp-scope.md` -9. `saas-project-structure-spec.md` -10. `saas-development-workflow.md` +- ✅ **Phase 4**: SAAS 产品化（后端 API）- 82.4% 完成 +- ✅ **Phase 6**: 前端开发（React UI）- 80% 完成 +- ✅ **Phase 7**: 核心视频剪辑业务 - **已完成** + +### 已交付能力 + +1. **素材管理**: 上传、分类、查询、标签 +2. **视频生成**: 任务创建、worker 自动触发、结果管理 +3. **成片下载**: 预签名 URL、规范化路径 +4. **前端联调**: 生成页、结果页完整打通 +5. **基础设施**: CI/CD 稳定、Git 工作流规范 + +### 进行中专项 + +当前正在执行：**专项 B：全仓主线路径澄清** + +目标：消除旧文档/旧测试/当前主线并存的认知混乱。 --- -## 4. 当前结论 +## 四、技术栈总览 -现在已经具备启动 SaaS 重建前最重要的文档骨架。下一步应该进入： +### 后端 +- Python 3.12 +- FastAPI 0.115.0 +- PostgreSQL 16 +- Redis 7 +- Celery +- MinIO -- 新项目落点确认 -- 仓库/目录方案确认 -- 第一版工程骨架设计 -- 之后才进入真正开发 +### 前端 +- React 18 +- TypeScript +- Vite +- Ant Design + +### 基础设施 +- Docker +- Gitea (CI/CD) +- Nginx + +--- + +## 五、快速定位代码 + +### 我想找素材上传流程 +``` +apps/api/app/api/routes/upload.py (API) + ↓ +apps/api/app/core/storage.py (MinIO) + ↓ +packages/domain/entities.py::Asset (领域模型) + ↓ +packages/adapters/sqlalchemy_impl/asset_repository.py (持久化) +``` + +### 我想找视频生成流程 +``` +apps/api/app/api/routes/generation_tasks.py (API) + ↓ +packages/application/generation_tasks.py (用例) + ↓ +apps/worker/tasks.py::generate_video (Worker) + ↓ +packages/adapters/sqlalchemy_impl/generation_task_repository.py (持久化) +``` + +### 我想找用户认证流程 +``` +apps/api/app/api/routes/auth.py (API) + ↓ +packages/application/auth/login_use_case.py (用例) + ↓ +packages/domain/auth/jwt_service.py (JWT) + ↓ +packages/domain/auth/session_store.py (会话) +``` + +完整导航请查看 **[CODE-STATUS.md](CODE-STATUS.md)** + +--- + +## 六、文档维护原则 + +1. **文档优先于实现** - 重要变更先更新文档 +2. **保持文档与代码同步** - 代码改了文档也要改 +3. **废弃文档要标注** - 不要默默删除，要留归档标记 +4. **新文档要加入索引** - 创建新文档后更新本文件 + +--- + +**维护人**: 小虾 🦐 +**最后更新**: 2026-06-19 diff --git a/docs/专项B-全仓主线路径澄清-规划.md b/docs/专项B-全仓主线路径澄清-规划.md new file mode 100644 index 000000000..ff55717ea --- /dev/null +++ b/docs/专项B-全仓主线路径澄清-规划.md @@ -0,0 +1,150 @@ +# 专项 B：全仓主线路径澄清 - 规划文档 + +**专项负责人**：小虾 🦐 +**创建时间**：2026-06-19 09:56 GMT+8 +**状态**：🔄 进行中 + +--- + +## 一、专项目标 + +**消除"旧文档 / 旧测试 / 当前主线"并存带来的认知混乱，让代码库有清晰的主线路径。** + +--- + +## 二、当前问题 + +### 问题 1：多代实现并存 +- 旧素材链：`domain/asset.py`, `domain/asset_library.py`, `ports/asset_repository.py`, `adapters/postgres/asset_repository.py` +- 新素材链：`domain/entities.py`, `application/assets.py`, `adapters/sqlalchemy_impl/asset_repository.py` +- 当前已通过兼容层压平，但文档未同步 + +### 问题 2：测试覆盖不清晰 +- 哪些测试是针对当前主线的？ +- 哪些是历史遗留的？ +- 哪些需要重写？ + +### 问题 3：文档与现实不一致 +- README 可能包含过期信息 +- `saas-index.md` 需要核对 +- API 文档需要更新 + +--- + +## 三、执行计划 + +### Step 1：列出当前真实主线 +- [x] 扫描 `apps/api/app/api/routes/` 所有路由 +- [x] 列出所有 active API endpoints +- [x] 标注每个 endpoint 的： + - 状态（稳定/实验/废弃） + - 对应的 use case + - 对应的 repository + - 是否有测试覆盖 +- [x] 创建 `docs/API-MAINLINE.md` ✅ + +### Step 2：标记旧代码状态 +- [x] 列出所有兼容层文件 +- [x] 标记每个文件： + - `[COMPAT]` - 兼容层，保留 + - `[DEPRECATED]` - 已废弃，待删除 + - `[MIGRATE]` - 待迁移到新主线 + - `[ACTIVE]` - 当前主线 +- [x] 创建 `docs/CODE-STATUS.md` ✅ + +### Step 3：测试分类 +- [x] 扫描 `tests/` 所有测试 +- [x] 按主线分类： + - 当前主线测试 + - 历史主线测试 + - 需要重写的测试 +- [x] 在 `CODE-STATUS.md` 中标注 ✅ + +### Step 4：文档同步 +- [x] 更新 `README.md` - 修复编码问题并更新内容 ✅ +- [x] 更新 `docs/saas-index.md` - 重构为现代导航 ✅ +- [x] 创建 `docs/API-MAINLINE.md` - 当前主线清单 ✅ +- [x] 创建 `docs/CODE-STATUS.md` - 代码状态标注 ✅ + +--- + +## 四、验收标准 + +- [ ] 有一份清晰的"当前主线 API 清单"文档 +- [ ] 所有兼容层/旧代码都有明确状态标注 +- [ ] 测试已分类，知道哪些是主线测试 +- [ ] README 和索引文档与现实一致 +- [ ] 新人能通过文档快速找到主线代码 + +--- + +## 五、专项边界 + +**只做**： +- 梳理、标注、文档化 +- 不改变任何功能行为 +- 不删除任何代码 + +**不做**： +- 实际迁移旧代码 +- 重写测试 +- 新功能开发 + +--- + +## 六、预计工作量 + +- Step 1-2：1-2 小时 +- Step 3：1 小时 +- Step 4：1 小时 + +总计：3-4 小时 + +--- + +**状态**：✅ 已完成 + +--- + +## 七、完成总结 + +### 已交付文档 + +1. **[docs/API-MAINLINE.md](API-MAINLINE.md)** + - 列出所有 68+ 个 API endpoints + - 按模块分类（认证/工作空间/项目/素材/生成等） + - 标注状态和对应的 use case + - 提供 Phase 7 主链路流程图 + +2. **[docs/CODE-STATUS.md](CODE-STATUS.md)** + - 标注所有代码文件状态（ACTIVE/COMPAT/DEPRECATED/MIGRATE） + - 提供快速定位指南 + - 测试分类清单 + - 清理计划 + +3. **[README.md](../README.md)** + - 修复编码问题（UTF-8 乱码） + - 更新项目状态 + - 添加 Phase 7 完成标记 + - 更新文档链接 + +4. **[docs/saas-index.md](saas-index.md)** + - 重构为现代导航结构 + - 添加快速导航入口 + - 更新文档清单 + - 标注归档文档 + +### 关键成果 + +- ✅ 新人可以通过文档快速找到主线代码 +- ✅ 所有 API endpoints 有清晰的清单 +- ✅ 兼容层/旧代码都有明确状态标注 +- ✅ README 和索引文档与现实一致 +- ✅ 测试已分类，知道哪些是主线测试 + +### 后续建议 + +专项 B 已完成，建议： +- 下一个可以做专项 C（文档入口质量修复） +- 或者专项 D（生成链生产化深化） +- 或者专项 E（前端真实联调验收深化）