# 🚀 EchoFlow 开发指南 - Harvey's Tech Site

📋 目录

分支策略
开发流程
提交规范
CI/CD 流程
环境说明
代码审查

🌳 分支策略

主要分支

分支名	用途	自动部署	保护级别
`main`	生产环境代码	✅ Production	🔒 高度保护
`develop`	开发环境代码	✅ Staging	🛡️ 基本保护
`feature/*`	功能开发分支	❌	📝 无保护
`hotfix/*`	紧急修复分支	❌	📝 无保护
`release/*`	发布准备分支	❌	📝 无保护

分支规则

gitgraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Dev Setup"

    branch feature/user-auth
    checkout feature/user-auth
    commit id: "Add login"
    commit id: "Add signup"

    checkout develop
    merge feature/user-auth
    commit id: "Merge auth"

    branch release/v1.0.0
    checkout release/v1.0.0
    commit id: "Version bump"
    commit id: "Update docs"

    checkout main
    merge release/v1.0.0
    commit id: "Release v1.0.0"

    checkout develop
    merge main

🔄 开发流程

1. 新功能开发

# 1. 从 develop 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/audio-enhancement

# 2. 开发功能
# ... 代码开发 ...

# 3. 提交代码（遵循提交规范）
git add .
git commit -m "feat(audio): add real-time audio enhancement

- Implement WebRTC audio processing
- Add noise cancellation algorithm
- Optimize for low-latency streaming

Closes #123"

# 4. 推送并创建 Pull Request
git push origin feature/audio-enhancement
# 在 GitHub 上创建 PR: feature/audio-enhancement → develop

2. 紧急修复（Hotfix）

# 1. 从 main 创建 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/critical-auth-bug

# 2. 修复问题
# ... 代码修复 ...

# 3. 提交修复
git add .
git commit -m "fix(auth): resolve critical login vulnerability

- Fix SQL injection in user authentication
- Add input validation for login parameters
- Update security tests

Fixes #456
BREAKING CHANGE: Updated authentication API requires new client integration"

# 4. 推送并创建 PR
git push origin hotfix/critical-auth-bug
# 创建两个 PR:
# - hotfix/critical-auth-bug → main (紧急生产修复)
# - hotfix/critical-auth-bug → develop (同步到开发分支)

3. 发布流程

# 1. 从 develop 创建 release 分支
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# 2. 准备发布
# - 更新版本号
# - 更新 CHANGELOG.md
# - 运行测试
# - 更新文档

# 3. 提交发布准备
git add .
git commit -m "chore(release): prepare v1.2.0

- Update version to 1.2.0
- Update CHANGELOG.md
- Update API documentation"

# 4. 合并到 main
# 创建 PR: release/v1.2.0 → main
# 合并后自动部署到生产环境

# 5. 同步回 develop
# 创建 PR: main → develop

📝 提交规范（Conventional Commits）

提交格式

<type>(<scope>): <subject>

<body>

<footer>

Type 类型

Type	说明	示例
`feat`	新功能	`feat(audio): add voice command support`
`fix`	Bug 修复	`fix(auth): resolve login timeout issue`
`docs`	文档更新	`docs(api): update authentication guide`
`style`	代码格式	`style(frontend): fix linting errors`
`refactor`	代码重构	`refactor(backend): simplify user service`
`perf`	性能优化	`perf(audio): optimize transcription speed`
`test`	测试相关	`test(auth): add unit tests for login flow`
`chore`	构建/工具	`chore(deps): update dependencies`
`ci`	CI/CD 配置	`ci(github): add staging deployment`
`revert`	代码回滚	`revert: feat(audio): remove broken feature`

Scope 范围

frontend - iOS 前端相关
backend - NestJS 后端相关
audio - 音频处理相关
auth - 认证授权相关
api - API 接口相关
db - 数据库相关
docs - 文档相关
deps - 依赖管理

特殊标记

# 破坏性变更
BREAKING CHANGE: API endpoint /auth/login now requires additional parameters

# 关联 Issue
Closes #123
Fixes #456
Refs #789

# 共同作者
Co-authored-by: John Doe <john@example.com>

🤖 CI/CD 流程

自动触发规则

事件	分支	执行动作
`push`	`develop`	🧪 测试 + 🚀 部署到 Staging
`push`	`main`	🧪 测试 + 🚀 部署到 Production
`pull_request`	any → `develop`	🧪 测试 + 🔍 代码检查
`pull_request`	any → `main`	🧪 测试 + 🔍 代码检查 + 📋 发布检查

Pipeline 阶段

graph LR
    A[Code Push] --> B[Lint & Format]
    B --> C[Unit Tests]
    C --> D[Integration Tests]
    D --> E[Build]
    E --> F[Security Scan]
    F --> G[Deploy]
    G --> H[Health Check]
    H --> I[Notification]

部署策略

Staging: 自动部署，快速迭代
Production: 自动部署，但需要 PR 审查通过
Rollback: 一键回滚到上一个稳定版本

🏗️ 环境说明

环境配置

环境	分支	用途	数据库	缓存	监控
Development	`feature/*`	本地开发	SQLite	本地 Redis	本地日志
Staging	`develop`	测试验证	PostgreSQL	Redis Cluster	Sentry + 日志
Production	`main`	生产服务	PostgreSQL HA	Redis HA	Sentry + APM

环境变量

# Staging (.env.staging)
NODE_ENV=staging
API_URL=https://api-staging.echoflow.com
SENTRY_ENVIRONMENT=staging
LOG_LEVEL=debug

# Production (.env.production)
NODE_ENV=production
API_URL=https://api.echoflow.com
SENTRY_ENVIRONMENT=production
LOG_LEVEL=info

👥 代码审查

PR 要求

目标分支	必需审查者	自动检查
`develop`	1 人	✅ Tests, ✅ Lint
`main`	2 人	✅ Tests, ✅ Lint, ✅ Security

审查清单

功能完整性: 功能是否按需求实现
代码质量: 代码是否清晰、可维护
测试覆盖: 是否有适当的测试用例
性能影响: 是否对性能有负面影响
安全检查: 是否存在安全隐患
文档更新: 是否需要更新文档

PR 模板示例

## 🎯 功能描述

简述此 PR 解决的问题和实现的功能

## 🔧 改动内容

- [ ] 新增音频处理API
- [ ] 优化缓存策略
- [ ] 更新相关文档

## 🧪 测试说明

- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试完成

## 📸 截图/演示

如果是UI相关改动，请提供截图或GIF

## 🔗 相关链接

- Closes #123
- Related to #456

🚀 快速开始

Clone 和设置

# 1. Clone 仓库
git clone https://github.com/your-org/EchoFlow.git
cd EchoFlow

# 2. 设置开发环境
git checkout develop
git pull origin develop

# 3. 安装依赖
# Backend
cd backend && yarn install

# Frontend
cd ../frontend/EchoFlowApp && open EchoFlowApp.xcodeproj

开始新功能

# 1. 从 develop 创建功能分支
git checkout -b feature/your-awesome-feature

# 2. 开发并提交
git add .
git commit -m "feat(scope): your feature description"

# 3. 推送并创建 PR
git push origin feature/your-awesome-feature

📞 支持

如有问题，请：

检查此文档
搜索已有 Issues
在团队频道询问
创建新的 Issue

Happy Coding! 🎉