# 新功能开发

<cite>
**本文档引用的文件**
- [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)
</cite>

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

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

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

```mermaid
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
```

图表来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [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)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

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

章节来源
- [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)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

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

```mermaid
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 : "解析并渲染"
```

图表来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)

## 详细组件分析

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

章节来源
- [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)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/schemas/query.py:1-94](file://backend/app/schemas/query.py#L1-L94)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)

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

```mermaid
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 + 令牌"
```

图表来源
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)

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

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

```mermaid
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](file://backend/app/services/query.py#L45-L81)

章节来源
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/schemas/query.py:1-94](file://backend/app/schemas/query.py#L1-L94)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)

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

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

图表来源
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

章节来源
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

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

章节来源
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)

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

章节来源
- [tests/test_auth.py:1-104](file://tests/test_auth.py#L1-L104)

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

```mermaid
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
```

图表来源
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

章节来源
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

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

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

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

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

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