17 KiB

Raw Permalink Blame History

新功能开发

**本文档引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/api/auth.py](file://backend/app/api/auth.py) - [backend/app/api/queries.py](file://backend/app/api/queries.py) - [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py) - [backend/app/schemas/query.py](file://backend/app/schemas/query.py) - [backend/app/models/user.py](file://backend/app/models/user.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/services/auth.py](file://backend/app/services/auth.py) - [backend/app/services/query.py](file://backend/app/services/query.py) - [frontend/app/layout.tsx](file://frontend/app/layout.tsx) - [frontend/components/providers.tsx](file://frontend/components/providers.tsx) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [tests/test_auth.py](file://tests/test_auth.py)

简介

本指导文档面向在 GEO 平台进行新功能开发的工程师，系统阐述后端 API 模块设计原则、接口定义与依赖管理；前端页面开发规范（页面组织、组件设计、状态管理）；数据库模型设计指导（表结构、关系映射、索引策略）；以及测试驱动开发（TDD）最佳实践与单元测试编写指南。文档以现有代码库为依据，结合可扩展性与一致性原则，帮助团队高效、安全地交付高质量功能。

项目结构

后端采用 FastAPI + SQLAlchemy 异步 ORM 架构，按领域分层组织：API 路由、服务层、模型层、模式层（Pydantic）、依赖注入与工具。
前端采用 Next.js App Router，使用 TypeScript、TailwindCSS 与 NextAuth 管理会话状态，通过统一的 API 客户端封装调用。
测试覆盖后端 API 与服务逻辑，使用 pytest 异步客户端与依赖覆盖机制。

graph TB
subgraph "前端"
FE_App["Next.js 应用<br/>根布局与全局样式"]
FE_Providers["会话提供者<br/>NextAuth Provider"]
FE_API["API 客户端<br/>统一请求封装"]
end
subgraph "后端"
BE_Main["FastAPI 应用<br/>生命周期与中间件"]
BE_Routers["API 路由<br/>认证/查询/引用/报告"]
BE_Services["服务层<br/>业务逻辑"]
BE_Models["模型层<br/>SQLAlchemy ORM"]
BE_Schemas["模式层<br/>Pydantic 校验"]
end
FE_App --> FE_Providers
FE_API --> BE_Routers
BE_Main --> BE_Routers
BE_Routers --> BE_Services
BE_Services --> BE_Models
BE_Services --> BE_Schemas

图表来源

章节来源

核心组件

后端应用与生命周期：定义 CORS、路由注册、健康检查与任务调度器启动/关闭。
认证模块：注册、登录、当前用户信息，配合 JWT 令牌与密码哈希。
查询模块：CRUD、分页、权限校验（用户配额限制）、频率变更触发下次执行时间重算。
数据模型：用户、查询、引用记录、查询任务、订阅等，定义字段、外键与索引。
前端布局与会话：根布局、全局样式、NextAuth Provider 包裹。
前端 API 客户端：统一封装鉴权头、错误处理与各模块接口。

章节来源

架构总览

后端通过 FastAPI 聚合多个领域路由，每个路由对应一个服务层函数，服务层通过 SQLAlchemy 异步会话访问数据库模型，并使用 Pydantic 模式进行输入输出校验。前端通过统一 API 客户端发起请求，自动附加鉴权头，错误时统一解析并抛出。

sequenceDiagram
participant FE as "前端页面"
participant API as "API 客户端"
participant Router as "FastAPI 路由"
participant Service as "服务层"
participant Model as "模型层(SQLAlchemy)"
participant DB as "数据库"
FE->>API : "调用接口(带鉴权头)"
API->>Router : "HTTP 请求"
Router->>Service : "调用业务方法"
Service->>Model : "ORM 查询/更新"
Model->>DB : "异步 SQL 执行"
DB-->>Model : "结果集"
Model-->>Service : "领域对象"
Service-->>Router : "返回结果"
Router-->>API : "JSON 响应"
API-->>FE : "解析并渲染"

图表来源

详细组件分析

后端模块设计原则与依赖管理

模块划分
- API 层：定义路由、参数校验、异常映射与响应模型。
- 服务层：封装业务规则、权限控制与跨模型操作。
- 模型层：定义表结构、关系与索引。
- 模式层：Pydantic 模型用于请求/响应序列化与校验。
接口定义
- 统一前缀与标签：如 /api/v1/auth、/api/v1/queries 等。
- 参数校验：Query 分页参数、Pydantic 字段长度与枚举校验。
- 错误处理：HTTP 状态码与错误详情映射。
依赖管理
- 依赖注入：数据库会话、当前用户通过 Depends 获取。
- 生命周期：应用启动时初始化模型与调度器，关闭时优雅退出。

章节来源

认证模块（API/服务/模式）

路由设计
- 注册：接收注册体，返回用户信息（201）。
- 登录：校验凭据，签发 JWT，返回令牌与用户信息。
- 当前用户：基于依赖注入获取已认证用户。
处理逻辑
- 密码哈希与校验、JWT 过期时间配置、邮箱唯一性检查。
错误处理
- 注册重复邮箱、登录凭据无效、未授权访问。

sequenceDiagram
participant C as "客户端"
participant R as "认证路由"
participant S as "认证服务"
participant U as "用户模型"
participant T as "JWT/密码库"
C->>R : "POST /api/v1/auth/register"
R->>S : "register_user()"
S->>U : "查询邮箱是否已存在"
U-->>S : "不存在"
S->>T : "hash_password()"
S->>U : "创建用户并持久化"
U-->>S : "返回用户"
S-->>R : "用户信息"
R-->>C : "201 + 用户"
C->>R : "POST /api/v1/auth/login"
R->>S : "authenticate_user()"
S->>U : "查找用户"
U-->>S : "用户对象"
S->>T : "verify_password()"
T-->>S : "匹配成功"
S-->>R : "用户+令牌"
R-->>C : "200 + 令牌"

图表来源

章节来源

查询模块（API/服务/模式/模型）

路由设计
- 列表：支持 skip/limit 分页，返回 items 与 total。
- 创建：校验平台与频率，检查用户配额，计算 next_query_at。
- 读取/更新/删除：基于 query_id 与 user_id 的权限校验。
处理逻辑
- 频率变更时重算下次执行时间。
- 删除级联清理关联任务与引用记录。
错误处理
- 403 配额超限、404 未找到、401 未授权。

flowchart TD
Start(["创建查询"]) --> Count["统计用户查询数量"]
Count --> CheckLimit{"是否超过配额?"}
CheckLimit --> |是| Raise403["抛出权限错误(403)"]
CheckLimit --> |否| CalcNext["根据频率计算 next_query_at"]
CalcNext --> Persist["持久化查询记录"]
Persist --> Done(["完成"])
Raise403 --> End(["结束"])
Done --> End

图表来源

backend/app/services/query.py:45-81

章节来源

前端页面开发规范

页面组织
- 使用 Next.js App Router 的分组路由与布局，根布局统一注入 Provider。
组件设计
- UI 组件库化，遵循语义化与可复用性；页面组件负责数据获取与展示。
状态管理
- 使用 NextAuth 提供的会话状态，通过 Provider 在应用根部注入。
API 调用
- 统一的 api.ts 封装：自动添加 Content-Type 与 Authorization 头，统一错误处理与 JSON 解析。

graph LR
Root["根布局<br/>layout.tsx"] --> Providers["会话提供者<br/>providers.tsx"]
Providers --> Pages["页面与组件"]
Pages --> API["API 客户端<br/>api.ts"]
API --> Backend["后端 API"]

图表来源

章节来源

数据库模型设计指导

表结构设计
- 使用 UUID 主键，字符串长度约束，布尔与整数字段合理设置默认值。
- JSONB 字段用于存储动态列表（品牌别名、平台列表）。
关系映射
- 外键约束与级联删除（如用户删除时级联删除其查询与订阅）。
- 双向关系与回溯属性（back_populates）。
索引策略
- 对高频过滤字段建立复合或单列索引（如 user_id、status、next_query_at）。

章节来源

测试驱动开发（TDD）最佳实践与单元测试编写指南

设计原则
- 先写失败的测试，再实现最小逻辑使其通过；关注边界条件与错误路径。
- 使用依赖覆盖（dependency override）隔离外部依赖，确保测试可重复。
单元测试编写
- 使用 pytest 异步客户端发起请求，断言状态码与响应结构。
- Mock 服务层或模型层行为，验证路由层的参数传递与异常映射。
示例参考
- 认证模块测试覆盖注册成功/重复邮箱、登录成功/凭据错误、当前用户接口的鉴权场景。

章节来源

tests/test_auth.py:1-104

依赖分析

后端模块耦合
- API 路由依赖服务层；服务层依赖模型层与配置；模式层独立于业务逻辑。
- 依赖注入降低耦合，便于替换与测试。
前后端交互
- 前端通过统一 API 客户端与后端路由通信，鉴权头由 NextAuth 管理。

graph TB
API_Auth["认证路由"] --> Svc_Auth["认证服务"]
API_Queries["查询路由"] --> Svc_Query["查询服务"]
Svc_Auth --> Model_User["用户模型"]
Svc_Query --> Model_Query["查询模型"]
FE_API["前端 API 客户端"] --> API_Auth
FE_API --> API_Queries

图表来源

章节来源

性能考虑

数据库层面
- 为高频查询字段建立索引，避免全表扫描；对分页与排序字段保持索引覆盖。
- 使用批量查询与延迟加载策略，减少 N+1 查询风险。
服务层层面
- 合理拆分查询与计数，避免不必要的 COUNT 开销；缓存热点数据（如平台白名单）。
API 层面
- 控制分页大小上限，防止过大数据量返回；对敏感字段进行选择性序列化。
前端层面
- 使用虚拟列表与懒加载优化长列表渲染；统一错误提示与加载态，提升用户体验。

故障排查指南

常见问题定位
- 401 未授权：确认鉴权头是否正确传递与令牌是否过期。
- 403 权限错误：检查用户配额与资源归属（user_id）。
- 404 未找到：核对主键与所属用户 ID 是否匹配。
- 400 参数错误：检查 Pydantic 校验规则与枚举值。
日志与监控
- 后端开启路由级日志与异常捕获；前端统一错误上报与用户提示。
回滚与恢复
- 数据库迁移版本化管理；关键变更需配套回滚脚本与数据备份。

章节来源

结论

通过清晰的模块划分、严格的依赖注入、完善的模式校验与统一的前后端交互规范，GEO 平台具备良好的扩展性与可维护性。建议在新增功能时遵循本文档的设计原则与测试实践，确保功能快速落地且质量可控。

附录

新增功能开发清单
- 明确领域边界与模块职责，避免跨模块耦合。
- 编写路由与模式定义，确保参数与响应结构清晰。
- 实现服务层业务逻辑，覆盖边界条件与异常路径。
- 设计数据库模型与索引，评估性能影响。
- 编写单元测试与集成测试，保证功能正确性。
- 前端页面与组件开发，统一状态管理与错误处理。
- 文档与回归测试同步推进，保障发布质量。

17 KiB Raw Permalink Blame History Unescape Escape

新功能开发

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端模块设计原则与依赖管理

认证模块（API/服务/模式）

查询模块（API/服务/模式/模型）

前端页面开发规范

数据库模型设计指导

测试驱动开发（TDD）最佳实践与单元测试编写指南

依赖分析

性能考虑

故障排查指南

结论

附录

17 KiB

Raw Permalink Blame History