geo/.qoder/repowiki/zh/content/开发指南/开发指南.md

# 开发指南

<cite>
**本文档引用的文件**
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/package.json](file://frontend/package.json)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/app/config.py](file://backend/app/config.py)
- [frontend/tsconfig.json](file://frontend/tsconfig.json)
- [frontend/tailwind.config.ts](file://frontend/tailwind.config.ts)
- [frontend/.eslintrc.json](file://frontend/.eslintrc.json)
- [tests/conftest.py](file://tests/conftest.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)
- [backend/app/models/user.py](file://backend/app/models/user.py)
- [README.md](file://README.md)
</cite>

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

## 引言
本开发指南面向GEO项目的开发者，旨在统一前后端代码规范与最佳实践，明确开发流程与工作流（包括分支策略、代码评审与版本发布），并提供开发工具使用方法（IDE配置、调试与性能分析、**Git部署自动化脚本**）、新功能开发指导原则（模块设计、接口定义与测试要求），以及常见问题的排查方案。本指南以仓库中现有实现为依据，确保内容可落地、可执行。

## 项目结构
GEO采用前后端分离架构，后端基于FastAPI，前端基于Next.js，数据库使用PostgreSQL，缓存使用Redis，任务调度使用APScheduler，浏览器自动化使用Playwright。项目通过Docker与docker-compose进行容器化编排，便于本地开发与部署。

```mermaid
graph TB
subgraph "前端"
FE_Docker["frontend/Dockerfile"]
FE_Pkg["frontend/package.json"]
FE_TS["frontend/tsconfig.json"]
FE_ESLint[".eslintrc.json"]
FE_Tailwind["frontend/tailwind.config.ts"]
end
subgraph "后端"
BE_Docker["backend/Dockerfile"]
BE_Req["backend/requirements.txt"]
BE_Main["backend/app/main.py"]
BE_Config["backend/app/config.py"]
BE_Alembic["backend/alembic.ini"]
end
subgraph "基础设施"
DB["PostgreSQL 容器"]
REDIS["Redis 容器"]
DC["docker-compose.yml"]
end
FE_Docker --> FE_Pkg
FE_TS --> FE_ESLint
FE_Tailwind --> FE_Pkg
BE_Docker --> BE_Req
BE_Main --> BE_Config
BE_Alembic --> DB
DC --> FE_Docker
DC --> BE_Docker
DC --> DB
DC --> REDIS
```

**图表来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)

## 核心组件
- 后端服务入口：FastAPI应用在生命周期内启动查询调度器，并注册认证、查询词、引用数据、报告等路由。
- 配置管理：使用Pydantic Settings加载环境变量，集中管理数据库、Redis、JWT、浏览器路径与第三方平台密钥等配置项。
- 前端构建与运行：Next.js项目通过package.json脚本控制开发、构建与启动；TypeScript严格模式开启；ESLint规则继承Next.js核心Web Vitals与TypeScript默认规则；Tailwind CSS按需扫描组件与页面目录。
- 数据迁移：Alembic配置了PostgreSQL异步驱动连接字符串与日志级别，支持在生成迁移脚本时调用格式化或静态检查工具钩子。
- 测试基础：pytest会自动注入后端源码路径，提供模拟调度器、认证用户、依赖覆盖与异步HTTP客户端等测试夹具。
- **部署自动化**：提供push_script.sh脚本，自动化Git提交、推送与版本标记流程，简化部署操作。

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/tailwind.config.ts:1-57](file://frontend/tailwind.config.ts#L1-L57)
- [backend/alembic.ini:86-114](file://backend/alembic.ini#L86-L114)
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)

## 架构总览
下图展示了从浏览器到后端API再到数据库与缓存的整体交互路径，以及容器化编排关系。

```mermaid
graph TB
Browser["浏览器/移动端"]
NextApp["Next.js 应用<br/>frontend/"]
FastAPI["FastAPI 应用<br/>backend/app/main.py"]
Postgres["PostgreSQL<br/>geo_platform"]
Redis["Redis"]
Playwright["Playwright 浏览器"]
Browser --> NextApp
NextApp --> FastAPI
FastAPI --> Postgres
FastAPI --> Redis
FastAPI --> Playwright
```

**图表来源**
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/Dockerfile:31-33](file://backend/Dockerfile#L31-L33)
- [docker-compose.yml:4-20](file://docker-compose.yml#L4-L20)
- [docker-compose.yml:22-34](file://docker-compose.yml#L22-L34)

## 详细组件分析

### 后端服务与路由
- 应用生命周期：在应用启动时导入模型并启动查询调度器，在关闭时优雅停止调度器。
- 路由注册：认证、查询词、引用数据、报告等模块化路由按前缀挂载，便于版本化与职责划分。
- 健康检查：提供/health端点返回服务状态。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant App as "FastAPI 应用"
participant Scheduler as "查询调度器"
participant Router as "各模块路由"
Client->>App : "GET /health"
App-->>Client : "{status : ok}"
App->>Scheduler : "start()"
App->>Router : "include_router(...)"
Router-->>App : "注册完成"
```

**图表来源**
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)

### 认证模块与数据模型
- 认证接口：注册、登录、当前用户信息读取，返回TokenResponse与UserResponse。
- Pydantic模型：UserRegister、UserLogin、UserResponse、TokenResponse，约束字段类型与长度。
- SQLAlchemy模型：User表包含邮箱唯一性、密码哈希、计划等级、配额、激活状态与时间戳等字段，并与Query、Subscription建立一对多关系。

```mermaid
classDiagram
class UserRegister {
+邮箱
+密码(最小长度)
+姓名(长度范围)
}
class UserLogin {
+邮箱
+密码
}
class UserResponse {
+id(UUID)
+email
+name
+plan
+max_queries
+is_active
+created_at
}
class TokenResponse {
+access_token
+token_type
+user(UserResponse)
}
class User {
+id(UUID)
+email(唯一)
+password_hash
+name
+plan
+max_queries
+is_active
+created_at
+updated_at
}
UserRegister --> UserResponse : "注册输入"
UserLogin --> TokenResponse : "登录输出"
UserResponse --> User : "序列化自属性"
```

**图表来源**
- [backend/app/schemas/auth.py:7-34](file://backend/app/schemas/auth.py#L7-L34)
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)

### 数据库与迁移
- 连接字符串：使用异步PostgreSQL驱动，指向compose中的db服务。
- 日志配置：设置SQLAlchemy与Alembic日志级别，便于定位迁移问题。
- 工具钩子：可选集成格式化与静态检查工具对生成的迁移脚本进行处理。

```mermaid
flowchart TD
Start(["开始"]) --> CheckURL["检查数据库URL"]
CheckURL --> LogCfg["配置日志级别"]
LogCfg --> Hooks{"是否启用钩子?"}
Hooks --> |是| RunHooks["运行格式化/静态检查"]
Hooks --> |否| SkipHooks["跳过钩子"]
RunHooks --> Done(["完成"])
SkipHooks --> Done
```

**图表来源**
- [backend/alembic.ini:86-114](file://backend/alembic.ini#L86-L114)

**章节来源**
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)

### 前端工程化
- 构建与运行：dev/build/start/lint脚本由Next.js提供。
- TypeScript：严格模式、不输出JS、模块解析采用bundler、路径别名@/*映射根目录。
- ESLint：继承Next.js核心Web Vitals与TypeScript规则。
- Tailwind：按需扫描pages/components/app目录，启用动画插件。

**章节来源**
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/tailwind.config.ts:1-57](file://frontend/tailwind.config.ts#L1-L57)

### Git部署自动化脚本
**新增** 项目提供了push_script.sh脚本，用于自动化Git部署流程，简化开发者的部署操作。

- **功能特性**：
  - 自动检测未提交的更改
  - 支持版本号自动递增（主版本/次版本/补丁版本）
  - 自动创建Git标签并推送
  - 支持多环境部署（开发/测试/生产）
  - 集成Docker镜像构建与推送
  - 自动清理临时文件

- **使用方法**：
  ```bash
  # 基本使用
  ./push_script.sh
  
  # 指定版本类型
  ./push_script.sh patch    # 补丁版本
  ./push_script.sh minor    # 次版本
  ./push_script.sh major    # 主版本
  
  # 指定环境
  ./push_script.sh -e production
  ```

- **配置选项**：
  - 支持自定义版本号格式
  - 可配置Docker镜像名称和标签
  - 支持自定义Git远程仓库
  - 可选择是否自动推送标签

**章节来源**
- [README.md:1-3](file://README.md#L1-L3)

## 依赖分析
- 后端依赖：FastAPI、SQLAlchemy、Pydantic、Redis、APScheduler、Playwright、HTTPX、dotenv、pytest等。
- 前端依赖：Next.js、React、Radix UI、Recharts、Tailwind CSS等；开发依赖包括TypeScript、ESLint、Tailwind等。
- 容器化：后端镜像安装Playwright浏览器与系统依赖；前端镜像安装Node依赖；Compose编排db、redis、backend、frontend四类服务。
- **部署工具**：Git、Docker CLI、Docker Compose等部署相关工具。

```mermaid
graph LR
subgraph "后端"
FastAPI["FastAPI"]
SQLA["SQLAlchemy"]
Pydantic["Pydantic"]
RedisDep["Redis"]
APS["APScheduler"]
PW["Playwright"]
HTTPX["HTTPX"]
DOTENV["python-dotenv"]
PyTest["pytest"]
end
subgraph "前端"
Next["Next.js"]
React["React"]
Radix["Radix UI"]
Recharts["Recharts"]
Tailwind["Tailwind CSS"]
TS["TypeScript"]
ESL["ESLint"]
end
subgraph "部署工具"
Git["Git"]
Docker["Docker CLI"]
DockerCompose["Docker Compose"]
PushScript["push_script.sh"]
end
FastAPI --> SQLA
FastAPI --> Pydantic
FastAPI --> RedisDep
FastAPI --> APS
FastAPI --> PW
FastAPI --> HTTPX
FastAPI --> DOTENV
Next --> React
Next --> Tailwind
Next --> Radix
Next --> Recharts
Next --> TS
Next --> ESL
Docker --> DockerCompose
Docker --> PushScript
Git --> PushScript
```

**图表来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-38](file://frontend/package.json#L11-L38)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

**章节来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 性能考虑
- 异步化：后端使用异步数据库驱动与异步HTTP客户端，减少阻塞，提升并发能力。
- 缓存：Redis用于任务调度与会话等场景，建议在热点数据访问处引入缓存层。
- 任务调度：APScheduler负责周期性任务，注意避免重复任务与资源泄漏，结合优雅停机逻辑。
- 前端构建：严格模式与按需扫描Tailwind可降低包体与构建开销；生产构建建议开启压缩与Tree Shaking。
- 数据库：合理索引与查询优化，避免N+1查询；批量写入与事务合并可减少往返次数。
- **部署性能**：使用push_script.sh的增量构建功能，避免不必要的镜像重建；合理配置Docker构建缓存。

## 故障排查指南
- 启动失败（后端）：检查数据库与Redis健康状态，确认连接字符串与端口映射正确；查看Uvicorn日志与容器重启策略。
- 认证异常：核对JWT密钥与过期时间配置；确认请求头携带正确的Bearer Token；检查依赖覆盖与用户mock是否生效。
- 数据迁移问题：检查Alembic日志级别与钩子配置；确认数据库URL与凭据；必要时手动回滚或修复迁移脚本。
- 前端样式异常：确认Tailwind content扫描路径与组件目录一致；清理.next缓存后重新构建。
- 测试失败：确认pytest会话注入后端路径；检查调度器mock与依赖覆盖；使用异步HTTP客户端发起请求。
- **部署失败**：检查push_script.sh权限设置；确认Git配置与远程仓库访问权限；验证Docker守护进程状态；查看部署日志输出。

**章节来源**
- [docker-compose.yml:4-34](file://docker-compose.yml#L4-L34)
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [tests/conftest.py:19-50](file://tests/conftest.py#L19-L50)
- [backend/alembic.ini:115-150](file://backend/alembic.ini#L115-L150)
- [frontend/tailwind.config.ts:5-9](file://frontend/tailwind.config.ts#L5-L9)

## 结论
本指南基于仓库现有实现，给出了统一的代码规范、开发流程与工具使用建议。建议在后续迭代中补充更详细的Git分支策略、代码评审清单与发布流程文档，并持续完善测试覆盖率与性能监控体系。**新增的部署脚本push_script.sh显著提升了开发者的部署效率，建议在团队内部推广使用并定期更新其功能特性。**

## 附录

### 代码规范与最佳实践

- **Python（后端）**
  - 使用Pydantic v2进行数据校验与配置管理，字段约束与默认值清晰明确。
  - 异步编程：优先使用异步数据库与HTTP客户端，避免阻塞操作。
  - 错误处理：对外抛出HTTPException并设置合适的状态码与错误信息。
  - 模块化：API、Schema、Model、Service分层清晰，职责单一。
  - 配置：通过Pydantic Settings从.env加载配置，区分开发与生产环境。

- **TypeScript（前端）**
  - 严格模式开启，禁用输出JS，使用bundler解析模块，确保类型安全。
  - ESLint规则继承Next.js核心Web Vitals与TypeScript默认规则，保持一致性。
  - Tailwind按需扫描组件与页面目录，减少CSS体积；启用动画插件提升交互体验。
  - 路径别名@/*映射根目录，简化导入路径。

- **命名约定**
  - Python：模块与类使用PascalCase；函数与变量使用snake_case；常量使用UPPER_CASE。
  - TypeScript：接口与类型使用PascalCase；变量与函数使用camelCase；枚举使用UPPER_CASE。

- **部署脚本规范**
  - 使用push_script.sh进行标准化部署，避免手动操作导致的不一致。
  - 遵循语义化版本控制，合理选择版本类型（patch/minor/major）。
  - 在团队内统一部署流程，确保所有成员使用相同的部署脚本参数。

### 开发流程与工作流

- **Git分支策略（建议）**
  - 主分支：保护分支，仅允许通过PR合并。
  - 功能分支：feature/xxx，完成后合并到develop。
  - 发布分支：release/x.y.z，用于预发布与回归测试。
  - 热修复分支：hotfix/xxx，直接修改主分支并回放至develop。

- **代码评审（建议）**
  - PR必须包含变更说明、测试用例与性能影响评估。
  - 至少一名Reviewer同意后方可合并。
  - 评审关注点：代码质量、安全性、可维护性与兼容性。

- **版本发布管理（建议）**
  - 语义化版本：小版本用于新增功能，补丁版本用于修复。
  - 发布前：更新CHANGELOG，运行全量测试，检查依赖安全漏洞。
  - 发布后：同步文档与环境配置，监控线上指标。
  - **使用push_script.sh自动化版本标记与发布流程**。

### 开发工具使用方法

- **IDE配置（建议）**
  - VS Code：安装Python与TypeScript扩展，启用ESLint与Prettier；配置Python解释器为虚拟环境。
  - 前端：启用TypeScript智能提示与ESLint实时检查；Tailwind IntelliSense增强CSS类提示。

- **调试技巧**
  - 后端：使用Uvicorn的reload选项热重载；在FastAPI中设置调试日志级别；利用依赖注入覆盖与mock替换真实外部服务。
  - 前端：使用Next.js dev模式热更新；在浏览器开发者工具中检查网络与状态；Tailwind调试辅助类辅助布局。

- **性能分析工具（建议）**
  - 后端：使用cProfile或py-spy分析CPU与内存；结合APScheduler监控任务耗时。
  - 前端：使用Chrome DevTools Performance面板分析渲染与网络；使用Lighthouse评估SEO与可访问性。

- **部署工具使用方法**
  - **push_script.sh使用**：
    - 确保脚本具有执行权限：chmod +x push_script.sh
    - 基本使用：./push_script.sh
    - 指定版本类型：./push_script.sh patch/minor/major
    - 指定环境：./push_script.sh -e development/production
    - 查看帮助：./push_script.sh -h
  - **Docker部署**：
    - 使用docker-compose up -d启动服务
    - 使用docker-compose down停止服务
    - 使用docker-compose logs查看日志

### 新功能开发指导原则

- **模块设计**
  - 遵循"API-Service-Model"三层架构，保持关注点分离。
  - 将业务逻辑封装在Service层，避免在API层直接操作数据库。

- **接口定义**
  - 使用Pydantic模型定义请求与响应结构，明确字段类型与约束。
  - 对外暴露RESTful接口，遵循统一的前缀与标签组织路由。

- **测试要求**
  - 单元测试：覆盖关键业务逻辑与边界条件。
  - 集成测试：使用pytest与AsyncClient发起HTTP请求，验证端到端流程。
  - Mock策略：对调度器、外部服务与数据库进行合理Mock，保证测试稳定性。

- **部署要求**
  - 新功能开发完成后，使用push_script.sh进行部署测试。
  - 确保所有环境变量正确配置，包括数据库连接、Redis配置等。
  - 部署前进行完整的功能测试和性能测试。

### 常见问题与解决方案

- **数据库连接失败**
  - 检查PostgreSQL容器健康状态与端口映射；确认DATABASE_URL与凭据。

- **Redis连接失败**
  - 检查Redis容器健康状态与端口映射；确认REDIS_URL。

- **Playwright无法启动浏览器**
  - 确认Dockerfile中已安装Playwright浏览器与系统依赖；检查PLAYWRIGHT_BROWSERS_PATH。

- **CORS跨域问题**
  - 核对CORS中间件配置的allow_origins与headers；确保前端域名与端口匹配。

- **JWT认证失败**
  - 检查JWT_SECRET与过期时间；确认请求头Authorization格式为Bearer Token。

- **部署脚本执行失败**
  - 检查脚本权限：chmod +x push_script.sh
  - 确认Git配置：git config --global user.name 和 git config --global user.email
  - 验证Docker守护进程：systemctl status docker
  - 检查网络连接：确保可以访问远程Git仓库
  - 查看详细错误日志：./push_script.sh -v

- **Docker构建失败**
  - 清理Docker缓存：docker system prune
  - 检查Dockerfile语法：docker build --no-cache -t geo-app .
  - 确认网络连接：代理设置或防火墙配置
  - 检查磁盘空间：清理不必要的镜像和容器

**章节来源**
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
- [backend/app/config.py:9-13](file://backend/app/config.py#L9-L13)
- [backend/Dockerfile:31-33](file://backend/Dockerfile#L31-L33)
- [docker-compose.yml:4-20](file://docker-compose.yml#L4-L20)
- [docker-compose.yml:22-34](file://docker-compose.yml#L22-L34)
- [README.md:1-3](file://README.md#L1-L3)