# 开发流程

<cite>
**本文引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/package.json](file://frontend/package.json)
- [tests/conftest.py](file://tests/conftest.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
- [frontend/README.md](file://frontend/README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向GEO项目的开发团队，提供一套完整的开发流程规范，涵盖Git分支策略与工作流、代码审查流程、版本发布管理、持续集成/持续部署（CI/CD）配置说明，以及开发环境搭建与团队协作最佳实践。内容基于仓库现有技术栈与容器化配置进行设计，确保前后端协同开发、数据库迁移与测试流程可追溯、可复现。

## 项目结构
GEO采用前后端分离与容器编排的组织方式：
- 前端：Next.js 14 应用，使用TypeScript与TailwindCSS，开发端口3000。
- 后端：FastAPI + Uvicorn，使用异步数据库驱动与Redis缓存，开发端口8000。
- 数据层：PostgreSQL 15 + Redis 7，通过Docker Compose统一编排。
- 迁移与版本管理：Alembic用于数据库迁移脚本生成与执行。
- 测试：pytest + pytest-asyncio，配合HTTP异步客户端与依赖注入覆盖。

```mermaid
graph TB
subgraph "本地开发环境"
FE["前端服务<br/>Next.js 3000"]
BE["后端服务<br/>FastAPI 8000"]
DB["数据库<br/>PostgreSQL 15"]
RC["缓存<br/>Redis 7"]
end
FE --> |"HTTP 请求"| BE
BE --> DB
BE --> RC
```

图表来源
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)

章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)

## 核心组件
- 前端工程
  - 使用Next.js应用路由与API路由，开发脚本与构建脚本在package.json中定义。
  - TypeScript与ESLint配置位于前端根目录，保证类型安全与代码风格一致。
- 后端工程
  - FastAPI应用入口与异步数据库连接，依赖通过requirements.txt集中管理。
  - Alembic迁移配置与初始迁移脚本存在，支持数据库演进。
- 测试工程
  - pytest会话级fixture用于屏蔽真实定时任务，提供模拟用户与认证头，便于快速集成测试。
- 容器化与编排
  - Dockerfile分别构建前后端镜像；docker-compose统一启动数据库、缓存、后端与前端服务，并设置健康检查与依赖顺序。

章节来源
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)
- [backend/alembic.ini:1-134](file://backend/alembic.ini#L1-L134)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)

## 架构总览
下图展示从浏览器到后端API再到数据库与缓存的整体调用链路，体现开发环境中的典型请求路径与数据流向。

```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant Frontend as "前端应用"
participant Backend as "后端API"
participant DB as "数据库"
participant Cache as "缓存"
Browser->>Frontend : "访问页面"
Frontend->>Backend : "发起HTTP请求"
Backend->>DB : "查询/写入数据"
DB-->>Backend : "返回结果"
Backend->>Cache : "读取/更新缓存"
Cache-->>Backend : "返回缓存命中/更新"
Backend-->>Frontend : "响应JSON"
Frontend-->>Browser : "渲染页面"
```

图表来源
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)

## 详细组件分析

### Git 分支策略与工作流
建议采用Git Flow变体，结合Feature分支与Release分支，确保开发与发布的可控性与可追溯性：

- 主分支
  - main：仅允许来自release或hotfix的合并，保持生产就绪状态。
  - develop：集成各功能特性，作为后续release的基线。
- 功能分支（feature）
  - 命名：feature/<issue-id>-短描述
  - 从develop切出，完成后合并回develop并删除分支。
- 预发布分支（release）
  - 从develop切出，进行最终修复与回归测试，完成后合并至main与develop并打标签。
- 热修复分支（hotfix）
  - 从main切出，紧急修复后同时合并回main与develop。

```mermaid
flowchart TD
A["开始"] --> B["创建功能分支 feature/<id>-desc"]
B --> C["提交到功能分支"]
C --> D{"完成开发？"}
D --> |否| C
D --> |是| E["推送并发起PR到 develop"]
E --> F["代码审查与测试通过"]
F --> G["合并到 develop 并删除分支"]
G --> H["准备 release 分支"]
H --> I["最终测试与修复"]
I --> J["合并到 main 与 develop 并打标签"]
```

说明
- PR需关联Issue，确保需求可追溯。
- 合并前必须通过本地与CI测试，且无冲突。

### 代码审查流程
- Pull Request 模板
  - 必填字段：标题（简述变更）、类型（修复/特性/重构/文档）、影响范围、变更摘要、测试要点、风险评估与回滚预案。
  - 关联信息：关联Issue编号、相关PR链接、模块负责人。
- 审查标准
  - 正确性：单元测试与集成测试覆盖率达标；边界条件与异常处理完备。
  - 可读性：命名规范、注释清晰、函数长度与复杂度合理。
  - 兼容性：接口变更需向后兼容或提供迁移方案；数据库变更需可逆。
  - 安全性：输入校验、权限控制、敏感信息脱敏。
- 合并要求
  - 至少一名审查者批准。
  - CI流水线通过。
  - 无未解决评论。
  - 合并后清理功能分支。

### 版本发布管理
- 语义化版本控制
  - 主版本号：破坏性变更
  - 次版本号：新增兼容功能
  - 修订号：修复兼容问题
- 变更日志维护
  - 按版本记录：新增、修复、改进、废弃与破坏性变更。
  - 引用相关PR与Issue，便于追溯。
- 发布标签
  - 在release分支合并后于main打标签，格式：vMAJOR.MINOR.REVISION。
  - 为每个版本生成对应Docker镜像并推送到制品库。

### 持续集成/持续部署（CI/CD）
当前仓库未包含CI配置文件，建议在CI系统中实现以下流程：
- 触发条件
  - push到develop/release/main/hotfix或打开PR时触发。
- 步骤
  - 安装依赖：后端pip、前端npm ci。
  - 代码质量：后端使用ruff/black，前端使用ESLint。
  - 单元测试：pytest与pytest-asyncio，生成覆盖率报告。
  - 容器构建：分别构建后端与前端镜像。
  - 健康检查：启动docker-compose并在数据库/缓存健康后运行端到端测试。
  - 制品归档：上传测试报告与镜像。
- 部署
  - develop：自动部署到预发布环境。
  - release：手动审批后部署到生产环境。
  - hotfix：自动部署到生产并回补到develop。

```mermaid
flowchart TD
S["提交/PR触发"] --> L["安装依赖与代码质量检查"]
L --> T["运行单元测试与覆盖率"]
T --> B["构建后端/前端镜像"]
B --> D["启动容器并健康检查"]
D --> E["端到端测试"]
E --> R{"是否发布？"}
R --> |否| P["归档制品与报告"]
R --> |是| DEP["部署到目标环境"]
DEP --> TAG["打标签并发布"]
```

说明
- 以上为通用CI/CD流程建议，具体实现需在CI平台配置相应作业与工件。

### 开发环境搭建与团队协作最佳实践
- 环境准备
  - 安装Docker与Docker Compose，确保端口未被占用。
  - 复制示例环境变量文件并按需调整数据库与缓存参数。
- 启动步骤
  - 后端：进入backend目录，安装依赖并启动服务；或使用docker-compose一键启动。
  - 前端：进入frontend目录，安装依赖并启动开发服务器。
- 团队协作
  - 统一代码风格：后端使用ruff/black，前端使用ESLint/TailwindCSS。
  - 提交信息规范：type(scope): subject，如feat(api): 新增用户认证接口。
  - 冲突解决：优先rebase保持线性历史，必要时使用merge并保留解决记录。
  - 文档同步：变更涉及用户界面或API时同步更新README与变更日志。

章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/README.md:1-37](file://frontend/README.md#L1-L37)

## 依赖关系分析
- 技术栈依赖
  - 前端：Next.js、React、TypeScript、TailwindCSS、Radix UI等。
  - 后端：FastAPI、SQLAlchemy、AsyncPG、Alembic、Redis、APScheduler、Playwright等。
- 容器与编排
  - docker-compose定义了数据库、缓存、后端与前端服务的依赖关系与健康检查。
- 测试依赖
  - pytest与pytest-asyncio用于异步测试；ASGI传输用于HTTP客户端测试；依赖注入覆盖用于模拟认证上下文。

```mermaid
graph LR
FE["前端应用"] --> |HTTP| BE["后端API"]
BE --> DB["PostgreSQL"]
BE --> RC["Redis"]
BE --> AL["Alembic 迁移"]
TEST["pytest 测试"] --> BE
```

图表来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)

章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)
- [backend/alembic.ini:1-134](file://backend/alembic.ini#L1-L134)

## 性能考虑
- 数据库
  - 使用异步驱动与连接池，避免阻塞；迁移脚本应最小化DDL变更，避免长事务锁表。
- 缓存
  - 合理设置TTL与键空间，热点数据优先缓存；定期清理过期键。
- API
  - 控制响应大小与分页；对高频接口启用缓存；限制并发与速率。
- 前端
  - 图片与静态资源优化；按需加载；TailwindCSS类名避免冗余。
- 容器
  - 使用多阶段构建减少镜像体积；健康检查降低重启时间；资源限制防止资源争用。

## 故障排查指南
- 本地服务无法启动
  - 检查端口占用与防火墙；确认数据库与缓存服务已健康运行。
- 数据库迁移失败
  - 查看Alembic配置与URL；确认迁移脚本语法正确；必要时回滚至上一版本。
- 测试异常
  - 确认pytest会话级fixture已正确屏蔽定时任务；检查依赖注入覆盖是否生效。
- 前后端联调失败
  - 核对CORS与代理配置；确认API路由与鉴权头正确传递。

章节来源
- [docker-compose.yml:16-20](file://docker-compose.yml#L16-L20)
- [docker-compose.yml:30-34](file://docker-compose.yml#L30-L34)
- [backend/alembic.ini:86-89](file://backend/alembic.ini#L86-L89)
- [tests/conftest.py:19-25](file://tests/conftest.py#L19-L25)

## 结论
通过明确的分支策略、严格的代码审查流程、规范的版本发布管理与可落地的CI/CD实践，GEO项目能够在保障交付质量的同时提升团队协作效率。建议尽快在CI平台落地上述流程，并根据实际运行情况迭代优化。

## 附录
- 快速启动命令
  - docker-compose：启动所有服务并进入交互模式。
  - 前端：进入frontend目录，安装依赖后启动开发服务器。
  - 后端：进入backend目录，安装依赖后启动Uvicorn服务。
- 参考文档
  - Next.js官方文档与部署指南。
  - FastAPI与SQLAlchemy异步数据库实践。
  - Alembic迁移最佳实践。