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

329 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 代码规范
<cite>
**本文档引用的文件**
- [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)
</cite>
## 目录
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<br/>应用入口与路由挂载"]
AUTH_API["app/api/auth.py<br/>认证路由"]
SCHEMA_AUTH["app/schemas/auth.py<br/>认证模式"]
MODEL_USER["app/models/user.py<br/>用户模型"]
WORKER["app/workers/citation_engine.py<br/>引用检测引擎"]
CONFIG["app/config.py<br/>配置读取"]
end
subgraph "前端"
LAYOUT["app/layout.tsx<br/>根布局与元数据"]
API_TS["lib/api.ts<br/>API 封装"]
BTN["components/ui/button.tsx<br/>按钮组件"]
TYPES["types/next-auth.d.ts<br/>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)
Reference in New Issue View Git Blame Copy Permalink