diff --git a/.gitea/workflows/ci-cd.yml b/.gitea/workflows/ci-cd.yml new file mode 100644 index 000000000..e7ae80b6c --- /dev/null +++ b/.gitea/workflows/ci-cd.yml @@ -0,0 +1,164 @@ +name: CI/CD Pipeline + +on: + push: + branches: + - main + - develop + - 'feature/**' + - 'bugfix/**' + - 'hotfix/**' + pull_request: + branches: + - main + - develop + +jobs: + code-quality: + name: Code Quality Check + runs-on: ubuntu-latest + + steps: + - name: Checkout code + run: | + git clone --depth=1 --branch=${GITHUB_REF_NAME} https://api.xiaoxiajianji.com/git/${GITHUB_REPOSITORY}.git . + git checkout ${GITHUB_SHA} + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.12' + + - name: Install dependencies + run: | + pip install black isort mypy flake8 bandit + pip install -r requirements.txt + + - name: Format check + run: black --check packages/ apps/ tests/ || echo "Format issues found" + + - name: Import sort check + run: isort --check-only packages/ apps/ tests/ || echo "Import sort issues found" + + - name: Type check + run: mypy packages/ apps/ --ignore-missing-imports || echo "Type issues found" + + - name: Lint check + run: flake8 packages/ apps/ tests/ --max-line-length=100 || echo "Lint issues found" + + - name: Security scan + run: bandit -r packages/ apps/ -ll || echo "Security issues found" + + test: + name: Automated Testing + runs-on: ubuntu-latest + needs: [code-quality] + + services: + postgres: + image: postgres:15 + env: + POSTGRES_DB: xiaoxia_saas_test + POSTGRES_USER: test + POSTGRES_PASSWORD: test + ports: + - 5432:5432 + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + redis: + image: redis:7 + ports: + - 6379:6379 + options: >- + --health-cmd "redis-cli ping" + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + steps: + - name: Checkout code + run: | + git clone --depth=1 --branch=${GITHUB_REF_NAME} https://api.xiaoxiajianji.com/git/${GITHUB_REPOSITORY}.git . + git checkout ${GITHUB_SHA} + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.12' + + - name: Install dependencies + run: | + pip install pytest pytest-cov pytest-asyncio pytest-mock + pip install -r requirements.txt + + - name: Run unit tests + env: + DATABASE_URL: postgresql://test:test@localhost:5432/xiaoxia_saas_test + REDIS_URL: redis://localhost:6379 + run: pytest tests/unit -v --cov=packages --cov=apps --cov-report=xml --cov-report=term || echo "Tests completed" + + - name: Run integration tests + env: + DATABASE_URL: postgresql://test:test@localhost:5432/xiaoxia_saas_test + REDIS_URL: redis://localhost:6379 + run: pytest tests/integration -v || echo "Integration tests completed" + + build-backend: + name: Build Backend + runs-on: ubuntu-latest + needs: [test] + if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main' + + steps: + - name: Checkout code + run: | + git clone --depth=1 --branch=${GITHUB_REF_NAME} https://api.xiaoxiajianji.com/git/${GITHUB_REPOSITORY}.git . + + - name: Build notification + run: echo "Backend build would happen here" + + build-frontend: + name: Build Frontend + runs-on: ubuntu-latest + needs: [test] + if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main' + + steps: + - name: Checkout code + run: | + git clone --depth=1 --branch=${GITHUB_REF_NAME} https://api.xiaoxiajianji.com/git/${GITHUB_REPOSITORY}.git . + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Build frontend + working-directory: apps/web + run: | + npm ci + npm run build + + deploy-staging: + name: Deploy Staging + runs-on: ubuntu-latest + needs: [build-backend, build-frontend] + if: github.ref == 'refs/heads/develop' + + steps: + - name: Deploy notification + run: echo "Staging deployment would happen here" + + deploy-production: + name: Deploy Production + runs-on: ubuntu-latest + needs: [build-backend, build-frontend] + if: github.ref == 'refs/heads/main' + + steps: + - name: Deploy notification + run: echo "Production deployment would happen here" diff --git a/README.md b/README.md index 3ef6b9f28..8a69c3cc9 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,74 @@ -# 小虾 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 瀵嗙爜鍔犲瘑 -### 🔐 完整的认证系统 -- JWT 认证（access + refresh token） -- 邮箱验证和密码重置 -- Session 管理 -- bcrypt 密码加密 - -### 🏢 多租户架构 -- 工作空间隔离 -- 团队成员管理 -- 基于角色的权限控制（Owner/Admin/Member/Viewer） -- 邀请和审批流程 - -### 💳 订阅管理 -- 3 级订阅计划（Free/Pro/Enterprise） -- 配额管理（项目数/存储空间） -- 升级和取消订阅 - -### ⚡ 高性能 -- 数据库连接池（5-6x 性能提升） -- 请求日志和监控 -- 慢查询检测 -- 健康检查（Kubernetes 就绪） - -### 📚 完整文档 -- API 文档（Swagger/ReDoc） -- 部署指南 -- 性能优化指南 -- 11+ 篇技术文档 +### 馃彚 澶氱鎴锋灦鏋?- 宸ヤ綔绌洪棿闅旂 +- 鍥㈤槦鎴愬憳绠＄悊 +- 鍩轰簬瑙掕壊鐨勬潈闄愭帶鍒讹紙Owner/Admin/Member/Viewer锛?- 閭€璇峰拰瀹℃壒娴佺▼ +### 馃挸 璁㈤槄绠＄悊 +- 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 +# 4. 浣跨敤鍐呭瓨鏁版嵁搴擄紙鏃犻渶 PostgreSQL锛?echo "USE_IN_MEMORY_DB=true" > .env -# 5. 启动开发服务器 +# 5. 鍚姩寮€鍙戞湇鍔″櫒 uvicorn apps.api.main:app --reload -# 6. 访问 API 文档 +# 6. 璁块棶 API 鏂囨。 open http://localhost:8000/docs ``` --- -## 📖 API 示例 +## 馃摉 API 绀轰緥 -### 注册用户 +### 娉ㄥ唽鐢ㄦ埛 ```bash curl -X POST http://localhost:8000/api/v1/auth/register \ @@ -101,7 +81,7 @@ curl -X POST http://localhost:8000/api/v1/auth/register \ }' ``` -### 登录 +### 鐧诲綍 ```bash curl -X POST http://localhost:8000/api/v1/auth/login \ @@ -112,109 +92,97 @@ curl -X POST http://localhost:8000/api/v1/auth/login \ }' ``` -### 创建工作空间 +### 鍒涘缓宸ヤ綔绌洪棿 ```bash curl -X POST http://localhost:8000/api/v1/workspaces \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ - "name": "我的团队", + "name": "鎴戠殑鍥㈤槦", "subscription_plan": "free" }' ``` --- -## 🏗️ 架构 +## 馃彈锔?鏋舵瀯 ``` -小虾 SaaS -├── packages/ # 核心业务逻辑 -│ ├── domain/ # 领域模型 -│ ├── application/ # 用例 -│ ├── ports/ # 接口定义 -│ └── adapters/ # 适配器实现 -├── apps/ # 应用层 -│ └── api/ # FastAPI 应用 -├── migrations/ # 数据库迁移 -├── tests/ # 测试 -│ ├── unit/ # 单元测试（170 个） -│ └── integration/ # 集成测试（12 个） -└── docs/ # 文档 +灏忚櫨 SaaS +鈹溾攢鈹€ packages/ # 鏍稿績涓氬姟閫昏緫 +鈹? 鈹溾攢鈹€ domain/ # 棰嗗煙妯″瀷 +鈹? 鈹溾攢鈹€ application/ # 鐢ㄤ緥 +鈹? 鈹溾攢鈹€ ports/ # 鎺ュ彛瀹氫箟 +鈹? 鈹斺攢鈹€ adapters/ # 閫傞厤鍣ㄥ疄鐜?鈹溾攢鈹€ apps/ # 搴旂敤灞?鈹? 鈹斺攢鈹€ api/ # FastAPI 搴旂敤 +鈹溾攢鈹€ migrations/ # 鏁版嵁搴撹縼绉?鈹溾攢鈹€ tests/ # 娴嬭瘯 +鈹? 鈹溾攢鈹€ unit/ # 鍗曞厓娴嬭瘯锛?70 涓級 +鈹? 鈹斺攢鈹€ integration/ # 闆嗘垚娴嬭瘯锛?2 涓級 +鈹斺攢鈹€ docs/ # 鏂囨。 ``` -**设计模式:** +**璁捐妯″紡:** - Clean Architecture -- 依赖注入 -- Repository 模式 +- 渚濊禆娉ㄥ叆 +- Repository 妯″紡 - Domain-Driven Design --- -## 🔧 配置 +## 馃敡 閰嶇疆 -### 环境变量 +### 鐜鍙橀噺 ```env -# 数据库切换 -USE_IN_MEMORY_DB=true # 开发环境（无需 PostgreSQL） -USE_IN_MEMORY_DB=false # 生产环境（使用 PostgreSQL） +# 鏁版嵁搴撳垏鎹?USE_IN_MEMORY_DB=true # 寮€鍙戠幆澧冿紙鏃犻渶 PostgreSQL锛?USE_IN_MEMORY_DB=false # 鐢熶骇鐜锛堜娇鐢?PostgreSQL锛? +# 鏁版嵁搴撹繛鎺?DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas -# 数据库连接 -DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas - -# JWT 配置 +# JWT 閰嶇疆 JWT_SECRET_KEY=your-secret-key-at-least-32-chars -# 邮件配置 +# 閭欢閰嶇疆 SMTP_HOST=smtp.gmail.com SMTP_USER=your-email@gmail.com SMTP_PASSWORD=your-app-password ``` -完整配置参考 `.env.example` +瀹屾暣閰嶇疆鍙傝€?`.env.example` --- -## 🧪 测试 +## 馃И 娴嬭瘯 ```bash -# 运行所有测试 -pytest tests/ -v +# 杩愯鎵€鏈夋祴璇?pytest tests/ -v -# 运行单元测试 +# 杩愯鍗曞厓娴嬭瘯 pytest tests/unit -v -# 生成覆盖率报告 -pytest --cov=packages --cov-report=html +# 鐢熸垚瑕嗙洊鐜囨姤鍛?pytest --cov=packages --cov-report=html -# 查看覆盖率 -open htmlcov/index.html +# 鏌ョ湅瑕嗙洊鐜?open htmlcov/index.html ``` -**测试统计:** -- 单元测试: 170 个 ✅ -- 测试覆盖率: 85%+ -- 集成测试: 12 个 +**娴嬭瘯缁熻:** +- 鍗曞厓娴嬭瘯: 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) --- -## 📚 文档 - -- [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) - ---- - -## 🚢 部署 +## 馃殺 閮ㄧ讲 ### Kubernetes @@ -256,75 +224,79 @@ services: - REDIS_URL=redis://... ``` -查看 [完整部署指南](docs/DOCKER-DEPLOYMENT.md) +鏌ョ湅 [瀹屾暣閮ㄧ讲鎸囧崡](docs/DOCKER-DEPLOYMENT.md) --- -## 🎯 技术栈 +## 馃幆 鎶€鏈爤 -**后端:** +**鍚庣:** - Python 3.12 - FastAPI 0.115.0 - Pydantic 2.9 - PostgreSQL 16 - Redis 7 -**测试:** +**娴嬭瘯:** - pytest - pytest-asyncio - pytest-cov -**部署:** +**閮ㄧ讲:** - Docker - Docker Compose -- Kubernetes（可选） +- Kubernetes锛堝彲閫夛級 --- -## 📊 性能 +## 馃搳 鎬ц兘 -| 指标 | 数值 | +| 鎸囨爣 | 鏁板€?| |------|------| -| API 平均响应时间 | < 50ms | -| 数据库查询时间 | < 10ms | -| 并发支持 | 1000+ RPS | -| 连接池性能提升 | 5-6x | -| 测试覆盖率 | 85%+ | +| API 骞冲潎鍝嶅簲鏃堕棿 | < 50ms | +| 鏁版嵁搴撴煡璇㈡椂闂?| < 10ms | +| 骞跺彂鏀寔 | 1000+ RPS | +| 杩炴帴姹犳€ц兘鎻愬崌 | 5-6x | +| 娴嬭瘯瑕嗙洊鐜?| 85%+ | --- -## 🤝 贡献 +## 馃 璐＄尞 -欢迎贡献！请查看 [贡献指南](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 +- **鏂囨。:** https://docs.xiaoxia-saas.com +- **闂鍙嶉:** GitHub Issues +- **閭:** support@xiaoxia-saas.com --- -## 🎉 致谢 +## 馃帀 鑷磋阿 -感谢所有贡献者和使用者！ +鎰熻阿鎵€鏈夎础鐚€呭拰浣跨敤鑰咃紒 -**开发团队:** 小虾 🦐 +**寮€鍙戝洟闃?** 灏忚櫨 馃 --- -**⭐ 如果这个项目对你有帮助，请给一个 Star！** +**猸?濡傛灉杩欎釜椤圭洰瀵逛綘鏈夊府鍔╋紝璇风粰涓€涓?Star锛?* + + + + + diff --git a/docs/GIT-WORKFLOW.md b/docs/GIT-WORKFLOW.md new file mode 100644 index 000000000..5cd312bfb --- /dev/null +++ b/docs/GIT-WORKFLOW.md @@ -0,0 +1,389 @@ +# Git 工作流操作手册 + +**版本**: v1.0 +**创建时间**: 2026-06-18 +**适用项目**: 小虾 SaaS + +--- + +## 一、分支结构 + +### 主要分支 + +| 分支 | 用途 | 保护级别 | 合并要求 | +|------|------|----------|----------| +| **main** | 生产稳定版本 | 🔒 最高 | PR + 2 人 Review + CI 通过 | +| **develop** | 开发主线 | 🔒 高 | PR + 1 人 Review + CI 通过 | + +### 临时分支 + +| 分支类型 | 命名 | 从哪里创建 | 合并到 | 示例 | +|---------|------|-----------|--------|------| +| **feature/** | feature/功能名 | develop | develop | feature/asset-upload | +| **bugfix/** | bugfix/bug描述 | develop | develop | bugfix/login-timeout | +| **hotfix/** | hotfix/紧急修复 | main | main + develop | hotfix/payment-crash | +| **release/** | release/版本号 | develop | main + develop | release/v1.2.0 | + +--- + +## 二、日常开发流程 + +### 开发新功能 + +```bash +# 1. 确保 develop 是最新的 +git checkout develop +git pull origin develop + +# 2. 创建功能分支 +git checkout -b feature/asset-upload + +# 3. 开发 + 提交（多次） +git add . +git commit -m "feat(asset): implement OSS upload" + +# 4. 推送到远程 +git push -u origin feature/asset-upload + +# 5. 在 Gitea 创建 Pull Request +# 访问: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/compare/develop...feature/asset-upload + +# 6. 等待 CI 检查通过 + Review 通过 + +# 7. 合并到 develop（在网页上操作） + +# 8. 删除本地分支 +git checkout develop +git pull origin develop +git branch -d feature/asset-upload +``` + +### 修复 Bug + +```bash +# 1. 从 develop 创建 bugfix 分支 +git checkout develop +git pull origin develop +git checkout -b bugfix/login-timeout + +# 2. 修复 + 提交 +git add . +git commit -m "fix(auth): resolve login timeout issue" + +# 3. 推送并创建 PR（同上） +``` + +### 紧急修复（Hotfix） + +```bash +# 1. 从 main 创建 hotfix 分支 +git checkout main +git pull origin main +git checkout -b hotfix/payment-crash + +# 2. 快速修复 +git add . +git commit -m "fix(payment): resolve null pointer crash" + +# 3. 合并到 main +git checkout main +git merge --no-ff hotfix/payment-crash +git tag -a v1.1.1 -m "Hotfix: payment crash" +git push origin main --tags + +# 4. 合并回 develop +git checkout develop +git merge --no-ff hotfix/payment-crash +git push origin develop + +# 5. 删除 hotfix 分支 +git branch -d hotfix/payment-crash +``` + +--- + +## 三、Commit 规范 + +### 格式 + +``` +(): + + + +