# 代码规范
**本文档引用的文件**
- [backend/requirements.txt](file://backend/requirements.txt)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.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)
- [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py)
- [tests/test_auth.py](file://tests/test_auth.py)
- [frontend/package.json](file://frontend/package.json)
- [.eslintrc.json](file://frontend/.eslintrc.json)
- [frontend/tsconfig.json](file://frontend/tsconfig.json)
- [frontend/app/layout.tsx](file://frontend/app/layout.tsx)
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
- [frontend/components/ui/button.tsx](file://frontend/components/ui/button.tsx)
- [frontend/types/next-auth.d.ts](file://frontend/types/next-auth.d.ts)
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 引言
本文件为 GEO 项目的统一代码规范文档，覆盖后端 Python 与前端 TypeScript/Next.js 的风格与实践，明确命名约定、导入顺序、注释规范、类型与接口设计、模块组织、错误处理模式以及前后端一致性要求，并提供可操作的自动化检查工具配置与使用方法。文档同时给出“正确/错误”示例的路径指引，便于团队在开发过程中快速对照与改进。
## 项目结构
- 后端采用 FastAPI + SQLAlchemy 2.x + Pydantic v2，使用异步数据库会话与依赖注入，模块按功能分层：API 路由、服务层、模型与模式（schemas）、工作流与调度。
- 前端采用 Next.js App Router + TypeScript + TailwindCSS，UI 组件基于 Radix UI 与 class-variance-authority，类型扩展用于 NextAuth。
```mermaid
graph TB
subgraph "后端"
MAIN["app/main.py
应用入口与路由挂载"]
AUTH_API["app/api/auth.py
认证路由"]
SCHEMA_AUTH["app/schemas/auth.py
认证模式"]
MODEL_USER["app/models/user.py
用户模型"]
WORKER["app/workers/citation_engine.py
引用检测引擎"]
CONFIG["app/config.py
配置读取"]
end
subgraph "前端"
LAYOUT["app/layout.tsx
根布局与元数据"]
API_TS["lib/api.ts
API 封装"]
BTN["components/ui/button.tsx
按钮组件"]
TYPES["types/next-auth.d.ts
NextAuth 类型扩展"]
end
MAIN --> AUTH_API
AUTH_API --> SCHEMA_AUTH
AUTH_API --> MODEL_USER
MAIN --> WORKER
MAIN --> CONFIG
LAYOUT --> API_TS
API_TS --> AUTH_API
BTN --> LAYOUT
TYPES --> LAYOUT
```
图示来源
- [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/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/ui/button.tsx:1-57](file://frontend/components/ui/button.tsx#L1-L57)
- [frontend/types/next-auth.d.ts:1-26](file://frontend/types/next-auth.d.ts#L1-L26)
章节来源
- [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)
## 核心组件
- 应用入口与中间件：统一设置 CORS、健康检查端点、路由挂载与生命周期管理。
- 认证模块：注册、登录、当前用户信息获取，配合 Pydantic 模式与数据库模型。
- 引擎与工作流：引用检测引擎封装品牌匹配、竞争品牌识别与多平台适配器调用。
- 前端 API 封装：统一鉴权头、错误处理与资源访问；UI 组件通过变体系统实现一致风格。
- 类型与扩展：NextAuth 类型扩展确保会话与 JWT 字段的类型安全。
章节来源
- [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/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/types/next-auth.d.ts:1-26](file://frontend/types/next-auth.d.ts#L1-L26)
## 架构总览
后端通过 FastAPI 提供 REST 接口，前端通过 Next.js App Router 渲染页面并通过封装的 API 客户端访问后端。测试覆盖认证流程与错误场景，确保行为符合预期。
```mermaid
sequenceDiagram
participant FE as "前端页面"
participant API as "lib/api.ts"
participant BE as "FastAPI 路由"
participant SVC as "服务/模型"
FE->>API : "调用认证/查询/报告接口"
API->>BE : "携带 Authorization 头发起请求"
BE->>SVC : "依赖注入与业务处理"
SVC-->>BE : "返回响应或异常"
BE-->>API : "标准化响应"
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/main.py:1-48](file://backend/app/main.py#L1-L48)
## 详细组件分析
### Python 后端代码规范
- 语言与版本：使用 Python 3.x，推荐 3.10+。
- 依赖管理：通过 requirements.txt 管理生产与测试依赖。
- 代码风格与静态检查：Alembic 配置中预留了格式化与检查钩子（如 black/ruff），建议在本地与 CI 中启用以保持一致性。
- 命名约定
- 模块与包：小写、下划线分隔（如 app/api/auth.py）。
- 类：大驼峰（如 User、CitationEngine）。
- 函数与变量：小写加下划线（如 register_user、execute_query）。
- 常量：全大写加下划线（如 DATABASE_URL）。
- 导入顺序
- 标准库 → 第三方库 → 项目内相对导入（遵循相对导入与绝对导入的一致性）。
- FastAPI 路由模块中，先导入标准库与第三方，再导入项目内模块。
- 注释规范
- 模块级 docstring：简述模块职责。
- 类与函数：使用三引号 docstring，描述参数、返回值与异常。
- 关键逻辑处添加行内注释，解释复杂算法或边界条件。
- 错误处理
- 使用 HTTPException 抛出语义化错误，避免泄露内部细节。
- 服务层捕获业务异常并转换为 HTTP 状态码。
- 类型与数据模型
- 使用 Pydantic v2 BaseModel 定义输入输出模式，配合 EmailStr、Field 等约束。
- SQLAlchemy ORM 模型使用 mapped_column、mapped_alias 等现代语法。
- 并发与异步
- 使用 AsyncSession 与 async/await，避免阻塞操作。
- 示例路径
- 正确：[认证路由与异常处理:1-43](file://backend/app/api/auth.py#L1-L43)
- 正确：[Pydantic 模式定义:1-34](file://backend/app/schemas/auth.py#L1-L34)
- 正确：[SQLAlchemy 模型字段与关系:1-41](file://backend/app/models/user.py#L1-L41)
- 正确：[引擎类与方法注释:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
章节来源
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [backend/alembic.ini:92-114](file://backend/alembic.ini#L92-L114)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
### TypeScript/JavaScript 前端代码规范
- 语言与编译选项：严格模式、ESNext 模块解析、Bundler 解析、JSX 保留。
- 命名约定
- 文件：小写加连字符（如 api.ts），组件使用 PascalCase（如 Button）。
- 变量与函数：小驼峰（如 fetchWithAuth）。
- 类型：接口与类型别名使用大驼峰（如 ButtonProps）。
- 导入顺序
- 先标准库与第三方，再内部路径别名（如 @/*）。
- 注释规范
- 函数与接口：使用 JSDoc 风格注释，说明参数、返回值与异常。
- 复杂逻辑处补充行内注释。
- 类型定义与接口设计
- 使用 TypeScript 接口与联合类型表达数据结构。
- NextAuth 类型扩展确保会话与 JWT 字段类型安全。
- 模块组织
- API 客户端集中于 lib/api.ts，按领域拆分子模块。
- UI 组件位于 components/ui，通过变体系统统一风格。
- 错误处理模式
- 统一的 fetchWithAuth 封装：校验响应状态、提取错误详情并抛出错误。
- 页面侧通过 try/catch 或 Promise.catch 捕获并提示。
- 示例路径
- 正确：[TS 编译配置:1-27](file://frontend/tsconfig.json#L1-L27)
- 正确：[ESLint 扩展:1-4](file://frontend/.eslintrc.json#L1-L4)
- 正确：[API 客户端封装与错误处理:1-58](file://frontend/lib/api.ts#L1-58)
- 正确：[UI 组件变体系统:1-57](file://frontend/components/ui/button.tsx#L1-57)
- 正确：[NextAuth 类型扩展:1-26](file://frontend/types/next-auth.d.ts#L1-26)
章节来源
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/ui/button.tsx:1-57](file://frontend/components/ui/button.tsx#L1-L57)
- [frontend/types/next-auth.d.ts:1-26](file://frontend/types/next-auth.d.ts#L1-L26)
### 前后端一致性要求
- 接口契约
- 请求与响应字段命名保持一致（如 email、password、access_token）。
- 错误响应结构统一（包含 detail 字段）。
- 鉴权与头部
- 前端统一在 Authorization 头中携带 Bearer Token。
- 后端路由对未认证请求返回 401。
- 资源路径
- 前端 API 基础地址通过环境变量控制，与后端路由前缀保持一致。
- 示例路径
- 正确：[后端路由前缀与标签:38-42](file://backend/app/main.py#L38-L42)
- 正确：[前端 API 基础地址与鉴权头:1-21](file://frontend/lib/api.ts#L1-L21)
章节来源
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [frontend/lib/api.ts:1-21](file://frontend/lib/api.ts#L1-L21)
### 自动化代码检查工具配置与使用
- 后端
- Alembic 配置预留了 post_write_hooks，可集成 black 与 ruff 进行格式化与检查。
- 建议在本地与 CI 中启用：格式化（black）与静态检查（ruff/flake8/pylint）。
- 依赖声明参考 requirements.txt，确保工具链可用。
- 前端
- ESLint 通过 .eslintrc.json 扩展 next/core-web-vitals 与 next/typescript。
- 建议在本地与 CI 中运行 lint 脚本，修复问题后再提交。
- TS 编译配置启用 strict 模式，提升类型安全性。
- 示例路径
- 正确：[Alembic hooks 配置:92-114](file://backend/alembic.ini#L92-L114)
- 正确：[ESLint 扩展:1-4](file://frontend/.eslintrc.json#L1-L4)
- 正确：[TS 严格模式与模块解析:6-12](file://frontend/tsconfig.json#L6-L12)
- 正确：[依赖声明:1-35](file://backend/requirements.txt#L1-L35)
章节来源
- [backend/alembic.ini:92-114](file://backend/alembic.ini#L92-L114)
- [frontend/.eslintrc.json:1-4](file://frontend/.eslintrc.json#L1-L4)
- [frontend/tsconfig.json:6-12](file://frontend/tsconfig.json#L6-L12)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
## 依赖分析
- 后端依赖
- Web 框架：FastAPI、Uvicorn
- 数据库：SQLAlchemy 2.x、Asyncpg、Alembic
- 数据验证与配置：Pydantic v2、Pydantic-Settings、email-validator
- 认证与安全：python-jose、passlib、multipart
- 缓存与任务调度：Redis、APScheduler
- 浏览器自动化：Playwright
- HTTP 客户端与工具：HTTPX、python-dotenv
- 测试：pytest、pytest-asyncio、aiosqlite
- 前端依赖
- 运行时：Next.js、React、NextAuth
- UI：Radix UI、Recharts、TailwindCSS
- 开发工具：ESLint、TypeScript、PostCSS、TailwindCSS
```mermaid
graph LR
subgraph "后端"
FASTAPI["FastAPI"]
SQLA["SQLAlchemy 2.x"]
PYD["Pydantic v2"]
REDIS["Redis"]
APS["APScheduler"]
PW["Playwright"]
HTTPX["HTTPX"]
PYTEST["pytest"]
end
subgraph "前端"
NEXT["Next.js"]
REACT["React"]
NA["NextAuth"]
RUI["Radix UI"]
REC["Recharts"]
TSC["TypeScript"]
ESL["ESLint"]
end
FASTAPI --> SQLA
FASTAPI --> PYD
FASTAPI --> REDIS
FASTAPI --> APS
FASTAPI --> HTTPX
NEXT --> REACT
NEXT --> NA
NEXT --> RUI
NEXT --> REC
NEXT --> TSC
NEXT --> ESL
```
图示来源
- [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)
## 性能考虑
- 异步优先：后端使用 AsyncSession 与异步 I/O，避免阻塞事件循环。
- 任务调度：APScheduler 合理设置频率与并发，避免重复任务与资源争用。
- 缓存策略：Redis 用于热点数据缓存与会话存储，减少数据库压力。
- 前端渲染：Next.js App Router 与静态生成/预渲染结合，降低首屏延迟。
- 网络请求：统一的 API 客户端封装，避免重复请求与无谓重试。
## 故障排查指南
- 认证失败
- 检查前端是否正确传递 Authorization 头。
- 检查后端路由是否正确处理 401 场景。
- 参考测试用例断言与错误消息。
- 数据库连接
- 确认 DATABASE_URL 与容器网络可达。
- 检查 Alembic 迁移是否成功。
- 任务执行异常
- 查看日志与 QueryTask 状态更新，定位具体平台适配器问题。
- 前端类型错误
- 启用 TS 严格模式，修复类型不匹配。
- 使用 ESLint 规则约束代码质量。
章节来源
- [tests/test_auth.py:1-104](file://tests/test_auth.py#L1-L104)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/workers/citation_engine.py:211-228](file://backend/app/workers/citation_engine.py#L211-L228)
- [frontend/lib/api.ts:16-21](file://frontend/lib/api.ts#L16-L21)
## 结论
本规范明确了 GEO 项目在 Python 与 TypeScript 生态下的风格与实践，强调一致性、可维护性与可测试性。建议在本地与 CI 中强制执行格式化与静态检查，持续完善测试覆盖，确保前后端契约稳定与类型安全。
## 附录
- 快速检查清单
- 后端：使用 Alembic hooks 格式化与检查；Pydantic 字段约束完整；HTTP 异常语义化；异步会话正确使用。
- 前端：ESLint 通过；TS 严格模式开启；UI 组件统一变体；API 客户端统一错误处理；NextAuth 类型扩展齐全。
- 示例路径（正确/错误对照）
- 正确：[认证路由与异常处理:1-43](file://backend/app/api/auth.py#L1-L43)
- 正确：[API 客户端封装与错误处理:1-58](file://frontend/lib/api.ts#L1-58)
- 正确：[NextAuth 类型扩展:1-26](file://frontend/types/next-auth.d.ts#L1-26)