# 开发工具

<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)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
- [frontend/tsconfig.json](file://frontend/tsconfig.json)
- [frontend/.eslintrc.json](file://frontend/.eslintrc.json)
- [frontend/next.config.mjs](file://frontend/next.config.mjs)
</cite>

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

## 简介
本文件面向GEO项目的开发者，提供从IDE配置、调试工具、开发辅助工具到命令行与脚本使用的完整指南。内容覆盖：
- VS Code配置与推荐插件（Python、TypeScript/Next.js）
- 断点调试、日志分析与性能分析方法
- API测试、数据库管理与Docker容器管理
- 命令行工具与脚本使用
- 开发环境优化与常见问题排查

## 项目结构
GEO采用前后端分离的多容器架构，通过Docker Compose编排数据库、缓存、后端服务与前端开发服务器。后端基于FastAPI，前端基于Next.js（App Router），数据库迁移使用Alembic。

```mermaid
graph TB
subgraph "本地开发环境"
VSCode["VS Code 开发环境"]
Postman["API 测试工具"]
DBTools["数据库管理工具"]
DockerCLI["Docker CLI"]
end
subgraph "容器编排"
DC["docker-compose.yml"]
DB["Postgres 容器"]
Redis["Redis 容器"]
BE["后端容器"]
FE["前端容器"]
end
VSCode --> DC
Postman --> BE
DBTools --> DB
DockerCLI --> DC
DC --> DB
DC --> Redis
DC --> BE
DC --> FE
```

图表来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

章节来源
- [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)

## 核心组件
- 后端服务（FastAPI）
  - 应用入口与生命周期管理、CORS配置、路由注册与健康检查接口
  - 配置加载与外部服务密钥（数据库、Redis、JWT、浏览器路径等）
- 数据库迁移（Alembic）
  - 异步迁移环境、日志级别与SQLAlchemy连接配置
- 前端应用（Next.js App Router）
  - API封装、类型配置、ESLint规则与构建配置
- 定时任务调度器（APScheduler + Playwright）
  - 异步调度、周期性查询检查与执行

章节来源
- [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/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

## 架构总览
下图展示本地开发与容器化运行时的交互关系，以及各组件在容器内的端口映射与依赖顺序。

```mermaid
graph TB
Dev["开发者主机"]
subgraph "Docker Compose 编排"
subgraph "服务"
DB["db:5432 → POSTGRES"]
RD["redis:6379 → 缓存"]
BE["backend:8000 → FastAPI"]
FE["frontend:3000 → Next.js dev"]
end
end
Dev --> |"浏览器访问"| FE
Dev --> |"API 请求"| BE
BE --> |"数据库/缓存"| DB
BE --> |"缓存/队列"| RD
FE --> |"调用后端 API"| BE
```

图表来源
- [docker-compose.yml:3-66](file://docker-compose.yml#L3-L66)

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

## 详细组件分析

### 后端服务（FastAPI）调试与配置
- 应用入口与生命周期
  - 使用生命周期钩子初始化模型与启动调度器，并在关闭时优雅停机
  - 注册认证、查询、引用、报告等路由前缀与标签
- CORS策略
  - 允许来自前端开发地址的跨域请求
- 健康检查
  - 提供基础健康检查端点用于容器健康探测

```mermaid
sequenceDiagram
participant Client as "客户端"
participant FE as "前端(3000)"
participant API as "后端(8000)"
participant DB as "数据库"
participant Cache as "缓存"
Client->>FE : "打开应用"
FE->>API : "发起登录/查询/报告等请求"
API->>DB : "读写数据(异步ORM)"
API->>Cache : "读写缓存(可选)"
API-->>FE : "返回JSON响应"
FE-->>Client : "渲染界面"
```

图表来源
- [backend/app/main.py:13-47](file://backend/app/main.py#L13-L47)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

### 数据库迁移（Alembic）流程
- 运行模式
  - 支持离线与在线两种迁移模式，使用异步引擎连接数据库
- 日志配置
  - 控制根日志、SQLAlchemy引擎与Alembic的日志级别
- 数据库URL
  - 默认指向本地或容器内Postgres服务

```mermaid
flowchart TD
Start(["启动迁移"]) --> Mode{"选择模式"}
Mode --> |离线| Offline["使用配置URL直接迁移"]
Mode --> |在线| Online["创建异步引擎并连接"]
Offline --> Tx["开启事务并执行迁移"]
Online --> Tx
Tx --> Done(["完成"])
```

图表来源
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
- [backend/alembic.ini:115-150](file://backend/alembic.ini#L115-L150)

章节来源
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)

### 前端（Next.js App Router）配置要点
- TypeScript与路径别名
  - 严格类型检查、Bundler模块解析、路径别名配置
- ESLint规则
  - 继承Next.js核心Web Vitals与TypeScript规则
- 构建与开发
  - 开发服务器端口、构建产物与类型生成

```mermaid
flowchart TD
TS["tsconfig.json<br/>严格类型/路径别名"] --> ESL[".eslintrc.json<br/>继承Next规则"]
ESL --> Build["next.config.mjs<br/>默认配置"]
Build --> Dev["npm run dev<br/>3000端口"]
```

图表来源
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)

章节来源
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)

### 定时任务调度器（APScheduler + Playwright）
- 调度策略
  - 每小时触发一次检查，筛选到期的活跃查询并交由引文引擎执行
- 异常处理
  - 单条任务失败不影响整体调度；关闭时优雅停止调度器与浏览器资源

```mermaid
classDiagram
class QueryScheduler {
+start()
+check_and_execute_queries()
+shutdown()
-_run_check()
-_execute_single_query(query, db)
}
class CitationEngine {
+execute_query(query, db)
+close()
}
QueryScheduler --> CitationEngine : "执行查询"
```

图表来源
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)

章节来源
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

## 依赖分析
- 后端依赖
  - Web框架、异步数据库、序列化、认证、缓存、任务调度、浏览器自动化、HTTP客户端、环境变量、测试工具
- 前端依赖
  - Next.js、React、UI库、Tailwind、TypeScript与开发工具链

```mermaid
graph LR
BE["后端应用"] --> Req["requirements.txt"]
FE["前端应用"] --> Pkg["package.json"]
Req --> FastAPI["FastAPI"]
Req --> SQLA["SQLAlchemy/AsyncPG/Alembic"]
Req --> RedisDep["Redis/APScheduler"]
Req --> PW["Playwright"]
Req --> HTTPX["HTTPX/HTTPX"]
Req --> Test["pytest/pytest-asyncio/aiosqlite"]
Pkg --> Next["Next.js"]
Pkg --> UI["@radix-ui/*"]
Pkg --> Tail["Tailwind/Recharts"]
Pkg --> TSDev["TypeScript/ESLint"]
```

图表来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

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

## 性能考虑
- 后端
  - 使用异步ORM与连接池，避免阻塞；合理设置任务调度间隔，避免频繁扫描
  - 浏览器自动化（Playwright）需预装浏览器二进制，减少重复下载开销
- 前端
  - 开发模式启用快速刷新；生产构建建议启用最小化与Tree-shaking
- 数据库
  - 迁移日志级别按需调整，避免过度输出影响性能

## 故障排查指南
- 容器健康与端口
  - 确认数据库与缓存容器健康检查通过，端口映射正确
  - 后端与前端容器分别监听8000与3000端口
- 数据库连接
  - 检查数据库URL与凭据；确认Alembic配置与容器网络可达
- 调试与日志
  - 后端生命周期钩子负责启动/关闭调度器；查看容器日志定位异常
  - 前端API封装统一处理错误响应，便于定位后端返回的错误详情
- 定时任务
  - 若查询未按时执行，检查调度器状态与异常日志；确认UTC时间与时区一致性

章节来源
- [docker-compose.yml:16-34](file://docker-compose.yml#L16-L34)
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
- [frontend/lib/api.ts:16-21](file://frontend/lib/api.ts#L16-L21)
- [backend/app/workers/scheduler.py:42-90](file://backend/app/workers/scheduler.py#L42-L90)

## 结论
通过容器化编排与严格的前后端配置，GEO提供了可复现的开发环境。配合本文档提供的IDE配置、调试与运维工具清单，开发者可以高效地进行功能迭代与问题定位。

## 附录

### IDE配置与推荐插件（VS Code）
- Python相关
  - 扩展：Python、Pylance、Black、isort、pytest
  - 设置：启用Pylance类型检查、自动格式化、导入排序
- TypeScript/Next.js相关
  - 扩展：ESLint、TypeScript Importer、Tailwind CSS IntelliSense
  - 设置：启用严格模式、路径别名、TS/TSX语法高亮
- Docker
  - 扩展：Docker、Kubernetes（可选）
  - 用途：可视化容器状态、日志查看、镜像构建与部署

[本节为通用实践建议，不直接分析具体源码文件]

### 调试工具使用方法
- 断点调试
  - 后端：在FastAPI路由或业务逻辑处设置断点，结合容器调试或本地调试
  - 前端：在API封装函数与页面逻辑处设置断点，观察请求/响应
- 日志分析
  - 后端：关注调度器与API层日志；容器日志中过滤关键字定位异常
  - 数据库：调整Alembic日志级别以获取更详细的迁移信息
- 性能分析
  - 后端：对慢查询与任务执行耗时进行采样；评估浏览器自动化并发
  - 前端：利用Next.js开发服务器热重载与性能面板

[本节为通用实践建议，不直接分析具体源码文件]

### 开发辅助工具
- API测试
  - 工具：Postman、Insomnia、curl
  - 建议：使用环境变量管理不同环境的API基础URL与令牌
- 数据库管理
  - 工具：pgAdmin、DBeaver、DataGrip
  - 建议：使用Alembic进行版本化迁移，避免手写DDL
- Docker容器管理
  - 工具：Docker Desktop、Lens（可选）
  - 建议：使用Compose一键拉起所有服务，查看容器日志与健康状态

[本节为通用实践建议，不直接分析具体源码文件]

### 命令行工具与脚本使用
- 后端
  - 安装依赖：pip install -r requirements.txt
  - 运行开发服务器：uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
  - 数据库迁移：alembic revision --autogenerate，alembic upgrade head
- 前端
  - 安装依赖：npm ci
  - 开发：npm run dev（3000端口）
  - 构建：npm run build（14.x）
- Docker
  - 构建与启动：docker-compose up --build
  - 查看日志：docker-compose logs -f 服务名
  - 进入容器：docker-compose exec 服务名 sh

章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/Dockerfile:28-33](file://backend/Dockerfile#L28-L33)
- [frontend/Dockerfile:6-7](file://frontend/Dockerfile#L6-L7)
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)