fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/开发指南/开发指南.md

26 KiB
Raw Permalink Blame History

开发指南

**本文档引用的文件** - [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) - [docs/03-development/coding-standards.md](file://docs/03-development/coding-standards.md) - [docs/03-development/dev-guide.md](file://docs/03-development/dev-guide.md) - [docs/05-deployment/deployment-guide.md](file://docs/05-deployment/deployment-guide.md) - [docs/04-testing/test-strategy.md](file://docs/04-testing/test-strategy.md) - [docs/03-development/tdd-workflow.md](file://docs/03-development/tdd-workflow.md) - [docs/00-project/tech-stack.md](file://docs/00-project/tech-stack.md)

更新摘要

所做更改

  • 新增完整的代码规范文档，包含Python和TypeScript开发标准
  • 新增TDD测试驱动开发流程规范，定义RED-GREEN-REFACTOR循环
  • 新增开发指南文档，涵盖环境搭建和开发流程
  • 新增部署指南文档，定义多环境部署策略
  • 新增测试策略文档，建立四层测试金字塔
  • 新增技术栈说明文档，详细阐述各技术选型
  • 更新模块设计指南，增加Agent框架开发指导
  • 完善开发工具使用方法，包含调试和性能分析工具

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 代码规范与最佳实践
  7. 开发流程与工作流
  8. 开发工具使用方法
  9. 新功能开发指导原则
  10. 测试策略与实施
  11. 部署管理
  12. 常见问题与解决方案
  13. 结论
  14. 附录

引言

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

更新 新增完整的开发文档体系，包括代码规范、开发流程、测试策略和部署管理等核心内容。

项目结构

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

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

图表来源

章节来源

核心组件

  • 后端服务入口：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提交、推送与版本标记流程，简化部署操作。

章节来源

架构总览

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

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

图表来源

详细组件分析

后端服务与路由

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

图表来源

章节来源

认证模块与数据模型

  • 认证接口：注册、登录、当前用户信息读取，返回TokenResponse与UserResponse。
  • Pydantic模型：UserRegister、UserLogin、UserResponse、TokenResponse，约束字段类型与长度。
  • SQLAlchemy模型：User表包含邮箱唯一性、密码哈希、计划等级、配额、激活状态与时间戳等字段，并与Query、Subscription建立一对多关系。
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 : "序列化自属性"

图表来源

章节来源

数据库与迁移

  • 连接字符串：使用异步PostgreSQL驱动，指向compose中的db服务。
  • 日志配置：设置SQLAlchemy与Alembic日志级别，便于定位迁移问题。
  • 工具钩子：可选集成格式化与静态检查工具对生成的迁移脚本进行处理。
flowchart TD
Start(["开始"]) --> CheckURL["检查数据库URL"]
CheckURL --> LogCfg["配置日志级别"]
LogCfg --> Hooks{"是否启用钩子?"}
Hooks --> |是| RunHooks["运行格式化/静态检查"]
Hooks --> |否| SkipHooks["跳过钩子"]
RunHooks --> Done(["完成"])
SkipHooks --> Done

图表来源

章节来源

前端工程化

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

章节来源

Git部署自动化脚本

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

  • 功能特性：

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

  • 使用方法：

    # 基本使用
./push_script.sh

# 指定版本类型
./push_script.sh patch    # 补丁版本
./push_script.sh minor    # 次版本
./push_script.sh major    # 主版本

# 指定环境
./push_script.sh -e production

  • 配置选项：

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

章节来源

代码规范与最佳实践

Python代码规范

  • 命名约定

    • 模块与类使用PascalCase（如：UserService、CitationDetector）
    • 函数与变量使用snake_case（如：get_user_by_id、process_data）
    • 常量使用UPPER_CASE（如：MAX_RETRY_COUNT、DEFAULT_TIMEOUT）
    • 私有成员使用单下划线前缀（如：_internal_method）

  • 代码格式化

    • 使用Black进行代码格式化，统一代码风格
    • Pydantic v2进行数据校验与配置管理
    • 字段约束与默认值清晰明确

  • 类型注解

    • 严格使用类型注解，包括函数参数、返回值和变量声明
    • 使用Union、Optional等类型组合器处理可选类型
    • 利用Generic类型支持泛型编程

  • 错误处理

    • 对外抛出HTTPException并设置合适的状态码与错误信息
    • 使用try-except捕获特定异常，避免裸except
    • 实现统一的异常处理器

  • 模块化设计

    • API、Schema、Model、Service分层清晰，职责单一
    • 配置通过Pydantic Settings从.env加载，区分开发与生产环境

章节来源

TypeScript/React代码规范

  • 命名约定

    • 接口与类型使用PascalCase（如：UserData、ApiResponse）
    • 变量与函数使用camelCase（如：getUserData、processFormData）
    • 枚举使用UPPER_CASE（如：UserRole.ADMIN）

  • 类型系统

    • 严格模式开启，禁用输出JS
    • 使用bundler解析模块，确保类型安全
    • 路径别名@/*映射根目录，简化导入路径

  • 组件设计

    • 使用React Hooks管理状态和副作用
    • 实现受控组件模式，确保数据流清晰
    • 组件Props使用TypeScript接口定义

  • ESLint配置

    • 继承Next.js核心Web Vitals与TypeScript规则
    • 自定义规则：忽略未使用变量警告，支持下划线前缀

章节来源

注释规范

  • Python文档字符串

    • 使用Google风格的docstring格式
    • 函数文档包含：参数说明、返回值、异常说明
    • 类文档包含：构造函数说明、主要方法列表

  • TypeScript JSDoc

    • 接口和类型使用JSDoc注释
    • 复杂函数添加详细说明和使用示例
    • 导出的公共API必须有完整注释

  • 代码注释

    • 重要算法添加算法思路说明
    • 外部依赖添加版本和用途说明
    • 临时解决方案添加TODO注释

章节来源

开发流程与工作流

Git分支策略

  • 主分支（main）：保护分支，仅允许通过Pull Request合并
  • 功能分支（feature/*）：开发新功能，完成后合并到develop
  • 发布分支（release/x.y.z）：用于预发布与回归测试
  • 热修复分支（hotfix/*）：直接修改main分支并回放至develop

代码评审流程

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

版本发布管理

  • 语义化版本控制：小版本用于新增功能，补丁版本用于修复
  • 发布前检查：更新CHANGELOG，运行全量测试，检查依赖安全漏洞
  • 发布后验证：同步文档与环境配置，监控线上指标

章节来源

开发工具使用方法

IDE配置

  • VS Code：安装Python与TypeScript扩展，启用ESLint与Prettier
  • 前端：启用TypeScript智能提示与ESLint实时检查；Tailwind IntelliSense增强CSS类提示

调试技巧

  • 后端：使用Uvicorn的reload选项热重载；在FastAPI中设置调试日志级别
  • 前端：使用Next.js dev模式热更新；在浏览器开发者工具中检查网络与状态

性能分析工具

  • 后端：使用cProfile或py-spy分析CPU与内存；结合APScheduler监控任务耗时
  • 前端：使用Chrome DevTools Performance面板分析渲染与网络

部署工具使用

  • push_script.sh使用：确保脚本具有执行权限，基本使用./push_script.sh
  • Docker部署：使用docker-compose up -d启动服务，logs查看日志

章节来源

新功能开发指导原则

模块设计

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

接口定义

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

测试要求

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

部署要求

  • 新功能开发完成后，使用push_script.sh进行部署测试
  • 确保所有环境变量正确配置，包括数据库连接、Redis配置等

章节来源

测试策略与实施

TDD测试驱动开发

新增 GEO平台采用完整的TDD（测试驱动开发）流程：

RED-GREEN-REFACTOR循环

  • RED阶段：编写失败测试，验证具体功能点
  • GREEN阶段：编写最少量生产代码使测试通过
  • REFACTOR阶段：优化代码结构、消除重复、提升可读性

测试层次金字塔

                    ▲
                   /│\
                  / │ \        E2E 测试（端到端）
                 /  │  \       覆盖关键用户旅程
                /───┼───\      占比：5%
               /    │    \
              /─────┼─────\    集成测试
             /      │      \   模块间交互验证
            /───────┼───────\  占比：15%
           /        │        \
          /─────────┼─────────\ 单元测试
         /          │          \ 单个函数/类验证
        /───────────┼───────────\ 占比：60%
       /            │            \
      /─────────────┼─────────────\ Agent 测试
     /              │              \ Agent 行为验证
    /───────────────┼───────────────\ 占比：20%
   ───────────────────────────────────

单元测试（Unit Tests）

  • 目标：验证单个函数、类或方法的行为
  • 原则：FIRST原则（Fast、Independent、Repeatable、Self-validating、Timely）
  • 工具：pytest + unittest.mock

集成测试（Integration Tests）

  • 目标：验证多个模块之间的交互是否正确
  • 范围：数据库、缓存、消息队列等真实组件
  • 工具：pytest + TestClient(FastAPI) + testcontainers

E2E测试（End-to-End Tests）

  • 目标：模拟真实用户操作，验证完整业务流程
  • 工具：Playwright（前端）+ pytest（后端 API）

Agent测试（Agent Tests）

  • 目标：验证 AI Agent 的行为和输出质量
  • 特殊要求：使用固定测试输入，验证输出结构和质量

章节来源

测试覆盖要求

  • 单元测试：>= 80%覆盖率
  • 集成测试：覆盖所有API端点
  • E2E测试：覆盖所有P0用户旅程
  • Agent测试：覆盖核心场景

测试数据管理

  • Fixtures：使用pytest.fixture管理测试数据
  • 工厂模式：复杂对象使用工厂函数创建
  • 数据清理：每个测试前后清理数据，失败时回滚

章节来源

部署管理

部署架构

新增 GEO平台支持多环境部署：

开发环境部署

  • 使用本地Docker Compose启动
  • 开发数据库和Redis实例
  • 支持热重载和调试模式

测试环境部署

  • 使用独立的测试数据库
  • 配置测试专用的API密钥
  • 自动化测试流水线集成

生产环境部署

  • 使用Nginx反向代理
  • 配置SSL证书和域名
  • 负载均衡和滚动更新

部署检查清单

  • 环境配置：数据库连接、Redis配置、API密钥
  • 服务健康：容器状态、端口映射、网络连通性
  • 数据迁移：Alembic迁移执行、数据完整性检查
  • 安全配置：JWT密钥、CORS配置、SSL证书

章节来源

常见问题与解决方案

数据库连接失败

  • 检查PostgreSQL容器健康状态与端口映射
  • 确认DATABASE_URL与凭据

Redis连接失败

  • 检查Redis容器健康状态与端口映射
  • 确认REDIS_URL

Playwright无法启动浏览器

  • 确认Dockerfile中已安装Playwright浏览器与系统依赖
  • 检查PLAYWRIGHT_BROWSERS_PATH

CORS跨域问题

  • 核对CORS中间件配置的allow_origins与headers
  • 确保前端域名与端口匹配

JWT认证失败

  • 检查JWT_SECRET与过期时间
  • 确认请求头Authorization格式为Bearer Token

测试失败排查

  • 单元测试：检查Mock配置和依赖注入
  • 集成测试：验证数据库连接和事务处理
  • E2E测试：检查浏览器自动化和页面元素定位

性能问题诊断

  • 后端：使用cProfile分析CPU使用率，检查数据库查询
  • 前端：使用Chrome DevTools分析渲染性能，检查组件重渲染

章节来源

结论

本指南基于仓库现有实现，建立了完整的开发文档体系，包括代码规范、开发流程、测试策略和部署管理等核心内容。建议在后续迭代中持续完善文档内容，补充更详细的Git分支策略、代码评审清单与发布流程文档，并持续完善测试覆盖率与性能监控体系。

更新 新增的开发文档体系显著提升了项目的规范化程度，为团队协作和项目维护奠定了坚实基础。

附录

技术栈说明

新增 GEO平台采用现代化技术栈：

前端技术栈

  • Next.js 14：React框架，支持SSR和静态生成
  • TypeScript：强类型语言，提升代码质量和开发体验
  • Tailwind CSS：原子化CSS框架，快速构建UI界面
  • shadcn/ui：高质量组件库，支持主题定制
  • NextAuth.js：认证解决方案，支持多种登录方式

后端技术栈

  • FastAPI：高性能异步Web框架
  • Python 3.12：类型提示最佳实践
  • SQLAlchemy 2.0：ORM对象关系映射
  • Alembic：数据库迁移管理
  • Celery：异步任务队列（可选）
  • Redis：缓存与消息代理

AI Agent技术栈

  • Agent框架：可扩展的AI代理框架
  • LLM模型：支持多种大语言模型
  • 提示工程：结构化的提示模板管理
  • 向量数据库：可选的向量相似度检索

基础设施技术栈

  • Docker：容器化部署
  • Docker Compose：服务编排
  • PostgreSQL：关系型数据库
  • Redis集群：生产环境缓存
  • Nginx：反向代理与负载均衡
  • 日志收集：集中化日志管理

章节来源

模块指南

新增 为不同模块提供专门的开发指导：

Agent框架开发

  • Agent设计原则：单一职责、可扩展性、可测试性
  • 提示工程：结构化提示模板设计
  • 模型集成：统一的LLM调用接口
  • 错误处理：健壮的异常处理机制

API开发规范

  • 路由设计：RESTful API设计原则
  • 错误处理：统一的错误响应格式
  • 文档生成：OpenAPI规范自动生成
  • 版本控制：API版本管理策略

数据模型设计

  • ORM映射：SQLAlchemy模型定义
  • 关系设计：实体关系建模
  • 索引优化：数据库性能优化
  • 数据迁移：版本化的数据库变更

章节来源

开发环境搭建

新增 详细的环境搭建步骤：

系统要求

  • 操作系统：Windows 10+/macOS 10.15+/Linux Ubuntu 18.04+
  • 内存：至少8GB RAM（推荐16GB+）
  • 存储：至少20GB可用空间
  • 网络：稳定的互联网连接

开发工具

  • Python：3.12+（推荐使用pyenv管理版本）
  • Node.js：18.x LTS版本
  • Docker：20.10+（包含Docker Compose）
  • Git：2.0+
  • IDE：VS Code + 推荐插件

环境变量配置

  • 数据库连接：DATABASE_URL
  • Redis配置：REDIS_URL
  • JWT配置：JWT_SECRET、JWT_EXPIRE_HOURS
  • LLM配置：各种AI平台API密钥

本地开发工作流

  1. 克隆仓库并安装依赖
  2. 配置环境变量文件
  3. 启动Docker容器
  4. 初始化数据库
  5. 开始开发和测试

章节来源