21 KiB

Raw 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)

引言

本开发指南面向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 : "注册完成"

图表来源

章节来源

backend/app/main.py:1-48

认证模块与数据模型

认证接口：注册、登录、当前用户信息读取，返回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

图表来源

backend/alembic.ini:86-114

章节来源

前端工程化

构建与运行：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远程仓库
- 可选择是否自动推送标签

章节来源

README.md:1-3

依赖分析

后端依赖：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等部署相关工具。

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

图表来源

章节来源

性能考虑

异步化：后端使用异步数据库驱动与异步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守护进程状态；查看部署日志输出。

章节来源

结论

本指南基于仓库现有实现，给出了统一的代码规范、开发流程与工具使用建议。建议在后续迭代中补充更详细的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 .
- 确认网络连接：代理设置或防火墙配置
- 检查磁盘空间：清理不必要的镜像和容器

章节来源

21 KiB Raw Blame History Unescape Escape

开发指南

目录

引言

项目结构

核心组件

架构总览

详细组件分析

后端服务与路由

认证模块与数据模型

数据库与迁移

前端工程化

Git部署自动化脚本

依赖分析

性能考虑

故障排查指南

结论

附录

代码规范与最佳实践

开发流程与工作流

开发工具使用方法

新功能开发指导原则

常见问题与解决方案

21 KiB

Raw Blame History