# 开发指南

<cite>
**本文档引用的文件**
- [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)
- [docs/03-development/coding-standards.md](file://docs/03-development/coding-standards.md)
- [docs/03-development/dev-guide.md](file://docs/03-development/dev-guide.md)
- [docs/05-deployment/deployment-guide.md](file://docs/05-deployment/deployment-guide.md)
- [docs/04-testing/test-strategy.md](file://docs/04-testing/test-strategy.md)
- [docs/03-development/tdd-workflow.md](file://docs/03-development/tdd-workflow.md)
- [docs/00-project/tech-stack.md](file://docs/00-project/tech-stack.md)
</cite>

## 更新摘要
**所做更改**
- 新增完整的代码规范文档，包含Python和TypeScript开发标准
- 新增TDD测试驱动开发流程规范，定义RED-GREEN-REFACTOR循环
- 新增开发指南文档，涵盖环境搭建和开发流程
- 新增部署指南文档，定义多环境部署策略
- 新增测试策略文档，建立四层测试金字塔
- 新增技术栈说明文档，详细阐述各技术选型
- 更新模块设计指南，增加Agent框架开发指导
- 完善开发工具使用方法，包含调试和性能分析工具

## 目录
1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 代码规范与最佳实践
7. 开发流程与工作流
8. 开发工具使用方法
9. 新功能开发指导原则
10. 测试策略与实施
11. 部署管理
12. 常见问题与解决方案
13. 结论
14. 附录

## 引言
本开发指南面向GEO项目的开发者，旨在统一前后端代码规范与最佳实践，明确开发流程与工作流（包括分支策略、代码评审与版本发布），并提供开发工具使用方法（IDE配置、调试与性能分析、Git部署自动化脚本）、新功能开发指导原则（模块设计、接口定义与测试要求），以及常见问题的排查方案。本指南以仓库中现有实现为依据，确保内容可落地、可执行。

**更新** 新增完整的开发文档体系，包括代码规范、开发流程、测试策略和部署管理等核心内容。

## 项目结构
GEO采用前后端分离架构，后端基于FastAPI，前端基于Next.js，数据库使用PostgreSQL，缓存使用Redis，任务调度使用APScheduler，浏览器自动化使用Playwright。项目通过Docker与docker-compose进行容器化编排，便于本地开发与部署。

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

**图表来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)
- [backend/requirements.txt:1-42](file://backend/requirements.txt#L1-L42)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)

**章节来源**
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)
- [backend/requirements.txt:1-42](file://backend/requirements.txt#L1-L42)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)

## 核心组件
- 后端服务入口：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提交、推送与版本标记流程，简化部署操作。

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-14](file://frontend/.eslintrc.json#L1-L14)
- [frontend/tailwind.config.ts:1-57](file://frontend/tailwind.config.ts#L1-L57)
- [backend/alembic.ini:86-114](file://backend/alembic.ini#L86-L114)
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)

## 架构总览
下图展示了从浏览器到后端API再到数据库与缓存的整体交互路径，以及容器化编排关系。

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

**图表来源**
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [backend/app/config.py:12-18](file://backend/app/config.py#L12-L18)
- [backend/Dockerfile:31-33](file://backend/Dockerfile#L31-L33)
- [docker-compose.yml:4-20](file://docker-compose.yml#L4-L20)
- [docker-compose.yml:22-34](file://docker-compose.yml#L22-L34)

## 详细组件分析

### 后端服务与路由
- 应用生命周期：在应用启动时导入模型并启动查询调度器，在关闭时优雅停止调度器。
- 路由注册：认证、查询词、引用数据、报告等模块化路由按前缀挂载，便于版本化与职责划分。
- 健康检查：提供/health端点返回服务状态。

```mermaid
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:13-21](file://backend/app/main.py#L13-L21)
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)

### 认证模块与数据模型
- 认证接口：注册、登录、当前用户信息读取，返回TokenResponse与UserResponse。
- Pydantic模型：UserRegister、UserLogin、UserResponse、TokenResponse，约束字段类型与长度。
- SQLAlchemy模型：User表包含邮箱唯一性、密码哈希、计划等级、配额、激活状态与时间戳等字段，并与Query、Subscription建立一对多关系。

```mermaid
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 : "序列化自属性"
```

**图表来源**
- [backend/app/schemas/auth.py:7-34](file://backend/app/schemas/auth.py#L7-L34)
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)

**章节来源**
- [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)

### 数据库与迁移
- 连接字符串：使用异步PostgreSQL驱动，指向compose中的db服务。
- 日志配置：设置SQLAlchemy与Alembic日志级别，便于定位迁移问题。
- 工具钩子：可选集成格式化与静态检查工具对生成的迁移脚本进行处理。

```mermaid
flowchart TD
Start(["开始"]) --> CheckURL["检查数据库URL"]
CheckURL --> LogCfg["配置日志级别"]
LogCfg --> Hooks{"是否启用钩子?"}
Hooks --> |是| RunHooks["运行格式化/静态检查"]
Hooks --> |否| SkipHooks["跳过钩子"]
RunHooks --> Done(["完成"])
SkipHooks --> Done
```

**图表来源**
- [backend/alembic.ini:86-114](file://backend/alembic.ini#L86-L114)

**章节来源**
- [backend/alembic.ini:1-150](file://backend/alembic.ini#L1-L150)
- [backend/app/config.py:12-13](file://backend/app/config.py#L12-L13)

### 前端工程化
- 构建与运行：dev/build/start/lint脚本由Next.js提供。
- TypeScript：严格模式、不输出JS、模块解析采用bundler、路径别名@/*映射根目录。
- ESLint：继承Next.js核心Web Vitals与TypeScript规则。
- Tailwind：按需扫描pages/components/app目录，启用动画插件。

**章节来源**
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-14](file://frontend/.eslintrc.json#L1-L14)
- [frontend/tailwind.config.ts:1-57](file://frontend/tailwind.config.ts#L1-L57)

### Git部署自动化脚本
**新增** 项目提供了push_script.sh脚本，用于自动化Git部署流程，简化开发者的部署操作。

- **功能特性**：
  - 自动检测未提交的更改
  - 支持版本号自动递增（主版本/次版本/补丁版本）
  - 自动创建Git标签并推送
  - 支持多环境部署（开发/测试/生产）
  - 集成Docker镜像构建与推送
  - 自动清理临时文件

- **使用方法**：
  ```bash
  # 基本使用
  ./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](file://README.md#L1-L3)

## 代码规范与最佳实践

### Python代码规范
- **命名约定**
  - 模块与类使用PascalCase（如：UserService、CitationDetector）
  - 函数与变量使用snake_case（如：get_user_by_id、process_data）
  - 常量使用UPPER_CASE（如：MAX_RETRY_COUNT、DEFAULT_TIMEOUT）
  - 私有成员使用单下划线前缀（如：_internal_method）

- **代码格式化**
  - 使用Black进行代码格式化，统一代码风格
  - Pydantic v2进行数据校验与配置管理
  - 字段约束与默认值清晰明确

- **类型注解**
  - 严格使用类型注解，包括函数参数、返回值和变量声明
  - 使用Union、Optional等类型组合器处理可选类型
  - 利用Generic类型支持泛型编程

- **错误处理**
  - 对外抛出HTTPException并设置合适的状态码与错误信息
  - 使用try-except捕获特定异常，避免裸except
  - 实现统一的异常处理器

- **模块化设计**
  - API、Schema、Model、Service分层清晰，职责单一
  - 配置通过Pydantic Settings从.env加载，区分开发与生产环境

**章节来源**
- [backend/requirements.txt:1-42](file://backend/requirements.txt#L1-L42)
- [backend/app/config.py:9-46](file://backend/app/config.py#L9-L46)

### TypeScript/React代码规范
- **命名约定**
  - 接口与类型使用PascalCase（如：UserData、ApiResponse）
  - 变量与函数使用camelCase（如：getUserData、processFormData）
  - 枚举使用UPPER_CASE（如：UserRole.ADMIN）

- **类型系统**
  - 严格模式开启，禁用输出JS
  - 使用bundler解析模块，确保类型安全
  - 路径别名@/*映射根目录，简化导入路径

- **组件设计**
  - 使用React Hooks管理状态和副作用
  - 实现受控组件模式，确保数据流清晰
  - 组件Props使用TypeScript接口定义

- **ESLint配置**
  - 继承Next.js核心Web Vitals与TypeScript规则
  - 自定义规则：忽略未使用变量警告，支持下划线前缀

**章节来源**
- [frontend/package.json:1-45](file://frontend/package.json#L1-L45)
- [frontend/tsconfig.json:1-27](file://frontend/tsconfig.json#L1-L27)
- [frontend/.eslintrc.json:1-14](file://frontend/.eslintrc.json#L1-L14)

### 注释规范
- **Python文档字符串**
  - 使用Google风格的docstring格式
  - 函数文档包含：参数说明、返回值、异常说明
  - 类文档包含：构造函数说明、主要方法列表

- **TypeScript JSDoc**
  - 接口和类型使用JSDoc注释
  - 复杂函数添加详细说明和使用示例
  - 导出的公共API必须有完整注释

- **代码注释**
  - 重要算法添加算法思路说明
  - 外部依赖添加版本和用途说明
  - 临时解决方案添加TODO注释

**章节来源**
- [docs/03-development/coding-standards.md:1-29](file://docs/03-development/coding-standards.md#L1-L29)

## 开发流程与工作流

### Git分支策略
- **主分支（main）**：保护分支，仅允许通过Pull Request合并
- **功能分支（feature/*）**：开发新功能，完成后合并到develop
- **发布分支（release/x.y.z）**：用于预发布与回归测试
- **热修复分支（hotfix/*）**：直接修改main分支并回放至develop

### 代码评审流程
- Pull Request必须包含变更说明、测试用例与性能影响评估
- 至少一名Reviewer同意后方可合并
- 评审关注点：代码质量、安全性、可维护性与兼容性

### 版本发布管理
- **语义化版本控制**：小版本用于新增功能，补丁版本用于修复
- **发布前检查**：更新CHANGELOG，运行全量测试，检查依赖安全漏洞
- **发布后验证**：同步文档与环境配置，监控线上指标

**章节来源**
- [docs/03-development/dev-guide.md:1-32](file://docs/03-development/dev-guide.md#L1-L32)

## 开发工具使用方法

### IDE配置
- **VS Code**：安装Python与TypeScript扩展，启用ESLint与Prettier
- **前端**：启用TypeScript智能提示与ESLint实时检查；Tailwind IntelliSense增强CSS类提示

### 调试技巧
- **后端**：使用Uvicorn的reload选项热重载；在FastAPI中设置调试日志级别
- **前端**：使用Next.js dev模式热更新；在浏览器开发者工具中检查网络与状态

### 性能分析工具
- **后端**：使用cProfile或py-spy分析CPU与内存；结合APScheduler监控任务耗时
- **前端**：使用Chrome DevTools Performance面板分析渲染与网络

### 部署工具使用
- **push_script.sh使用**：确保脚本具有执行权限，基本使用./push_script.sh
- **Docker部署**：使用docker-compose up -d启动服务，logs查看日志

**章节来源**
- [docs/03-development/dev-guide.md:1-32](file://docs/03-development/dev-guide.md#L1-L32)

## 新功能开发指导原则

### 模块设计
- 遵循"API-Service-Model"三层架构，保持关注点分离
- 将业务逻辑封装在Service层，避免在API层直接操作数据库

### 接口定义
- 使用Pydantic模型定义请求与响应结构，明确字段类型与约束
- 对外暴露RESTful接口，遵循统一的前缀与标签组织路由

### 测试要求
- **单元测试**：覆盖关键业务逻辑与边界条件
- **集成测试**：使用pytest与AsyncClient发起HTTP请求，验证端到端流程
- **Mock策略**：对调度器、外部服务与数据库进行合理Mock

### 部署要求
- 新功能开发完成后，使用push_script.sh进行部署测试
- 确保所有环境变量正确配置，包括数据库连接、Redis配置等

**章节来源**
- [docs/03-development/dev-guide.md:1-32](file://docs/03-development/dev-guide.md#L1-L32)

## 测试策略与实施

### TDD测试驱动开发
**新增** GEO平台采用完整的TDD（测试驱动开发）流程：

#### RED-GREEN-REFACTOR循环
- **RED阶段**：编写失败测试，验证具体功能点
- **GREEN阶段**：编写最少量生产代码使测试通过
- **REFACTOR阶段**：优化代码结构、消除重复、提升可读性

#### 测试层次金字塔
```
                    ▲
                   /│\
                  / │ \        E2E 测试（端到端）
                 /  │  \       覆盖关键用户旅程
                /───┼───\      占比：5%
               /    │    \
              /─────┼─────\    集成测试
             /      │      \   模块间交互验证
            /───────┼───────\  占比：15%
           /        │        \
          /─────────┼─────────\ 单元测试
         /          │          \ 单个函数/类验证
        /───────────┼───────────\ 占比：60%
       /            │            \
      /─────────────┼─────────────\ Agent 测试
     /              │              \ Agent 行为验证
    /───────────────┼───────────────\ 占比：20%
   ───────────────────────────────────
```

#### 单元测试（Unit Tests）
- **目标**：验证单个函数、类或方法的行为
- **原则**：FIRST原则（Fast、Independent、Repeatable、Self-validating、Timely）
- **工具**：pytest + unittest.mock

#### 集成测试（Integration Tests）
- **目标**：验证多个模块之间的交互是否正确
- **范围**：数据库、缓存、消息队列等真实组件
- **工具**：pytest + TestClient(FastAPI) + testcontainers

#### E2E测试（End-to-End Tests）
- **目标**：模拟真实用户操作，验证完整业务流程
- **工具**：Playwright（前端）+ pytest（后端 API）

#### Agent测试（Agent Tests）
- **目标**：验证 AI Agent 的行为和输出质量
- **特殊要求**：使用固定测试输入，验证输出结构和质量

**章节来源**
- [docs/03-development/tdd-workflow.md:1-583](file://docs/03-development/tdd-workflow.md#L1-L583)

### 测试覆盖要求
- **单元测试**：>= 80%覆盖率
- **集成测试**：覆盖所有API端点
- **E2E测试**：覆盖所有P0用户旅程
- **Agent测试**：覆盖核心场景

### 测试数据管理
- **Fixtures**：使用pytest.fixture管理测试数据
- **工厂模式**：复杂对象使用工厂函数创建
- **数据清理**：每个测试前后清理数据，失败时回滚

**章节来源**
- [docs/04-testing/test-strategy.md:1-33](file://docs/04-testing/test-strategy.md#L1-L33)

## 部署管理

### 部署架构
**新增** GEO平台支持多环境部署：

#### 开发环境部署
- 使用本地Docker Compose启动
- 开发数据库和Redis实例
- 支持热重载和调试模式

#### 测试环境部署
- 使用独立的测试数据库
- 配置测试专用的API密钥
- 自动化测试流水线集成

#### 生产环境部署
- 使用Nginx反向代理
- 配置SSL证书和域名
- 负载均衡和滚动更新

### 部署检查清单
- **环境配置**：数据库连接、Redis配置、API密钥
- **服务健康**：容器状态、端口映射、网络连通性
- **数据迁移**：Alembic迁移执行、数据完整性检查
- **安全配置**：JWT密钥、CORS配置、SSL证书

**章节来源**
- [docs/05-deployment/deployment-guide.md:1-32](file://docs/05-deployment/deployment-guide.md#L1-L32)

## 常见问题与解决方案

### 数据库连接失败
- 检查PostgreSQL容器健康状态与端口映射
- 确认DATABASE_URL与凭据

### Redis连接失败
- 检查Redis容器健康状态与端口映射
- 确认REDIS_URL

### Playwright无法启动浏览器
- 确认Dockerfile中已安装Playwright浏览器与系统依赖
- 检查PLAYWRIGHT_BROWSERS_PATH

### CORS跨域问题
- 核对CORS中间件配置的allow_origins与headers
- 确保前端域名与端口匹配

### JWT认证失败
- 检查JWT_SECRET与过期时间
- 确认请求头Authorization格式为Bearer Token

### 测试失败排查
- **单元测试**：检查Mock配置和依赖注入
- **集成测试**：验证数据库连接和事务处理
- **E2E测试**：检查浏览器自动化和页面元素定位

### 性能问题诊断
- **后端**：使用cProfile分析CPU使用率，检查数据库查询
- **前端**：使用Chrome DevTools分析渲染性能，检查组件重渲染

**章节来源**
- [docker-compose.yml:4-34](file://docker-compose.yml#L4-L34)
- [backend/app/config.py:12-18](file://backend/app/config.py#L12-L18)
- [tests/conftest.py:19-50](file://tests/conftest.py#L19-L50)
- [backend/alembic.ini:115-150](file://backend/alembic.ini#L115-L150)
- [frontend/tailwind.config.ts:5-9](file://frontend/tailwind.config.ts#L5-L9)

## 结论
本指南基于仓库现有实现，建立了完整的开发文档体系，包括代码规范、开发流程、测试策略和部署管理等核心内容。建议在后续迭代中持续完善文档内容，补充更详细的Git分支策略、代码评审清单与发布流程文档，并持续完善测试覆盖率与性能监控体系。

**更新** 新增的开发文档体系显著提升了项目的规范化程度，为团队协作和项目维护奠定了坚实基础。

## 附录

### 技术栈说明
**新增** GEO平台采用现代化技术栈：

#### 前端技术栈
- **Next.js 14**：React框架，支持SSR和静态生成
- **TypeScript**：强类型语言，提升代码质量和开发体验
- **Tailwind CSS**：原子化CSS框架，快速构建UI界面
- **shadcn/ui**：高质量组件库，支持主题定制
- **NextAuth.js**：认证解决方案，支持多种登录方式

#### 后端技术栈
- **FastAPI**：高性能异步Web框架
- **Python 3.12**：类型提示最佳实践
- **SQLAlchemy 2.0**：ORM对象关系映射
- **Alembic**：数据库迁移管理
- **Celery**：异步任务队列（可选）
- **Redis**：缓存与消息代理

#### AI Agent技术栈
- **Agent框架**：可扩展的AI代理框架
- **LLM模型**：支持多种大语言模型
- **提示工程**：结构化的提示模板管理
- **向量数据库**：可选的向量相似度检索

#### 基础设施技术栈
- **Docker**：容器化部署
- **Docker Compose**：服务编排
- **PostgreSQL**：关系型数据库
- **Redis集群**：生产环境缓存
- **Nginx**：反向代理与负载均衡
- **日志收集**：集中化日志管理

**章节来源**
- [docs/00-project/tech-stack.md:1-71](file://docs/00-project/tech-stack.md#L1-L71)

### 模块指南
**新增** 为不同模块提供专门的开发指导：

#### Agent框架开发
- **Agent设计原则**：单一职责、可扩展性、可测试性
- **提示工程**：结构化提示模板设计
- **模型集成**：统一的LLM调用接口
- **错误处理**：健壮的异常处理机制

#### API开发规范
- **路由设计**：RESTful API设计原则
- **错误处理**：统一的错误响应格式
- **文档生成**：OpenAPI规范自动生成
- **版本控制**：API版本管理策略

#### 数据模型设计
- **ORM映射**：SQLAlchemy模型定义
- **关系设计**：实体关系建模
- **索引优化**：数据库性能优化
- **数据迁移**：版本化的数据库变更

**章节来源**
- [docs/03-development/module-guides/](file://docs/03-development/module-guides/)

### 开发环境搭建
**新增** 详细的环境搭建步骤：

#### 系统要求
- **操作系统**：Windows 10+/macOS 10.15+/Linux Ubuntu 18.04+
- **内存**：至少8GB RAM（推荐16GB+）
- **存储**：至少20GB可用空间
- **网络**：稳定的互联网连接

#### 开发工具
- **Python**：3.12+（推荐使用pyenv管理版本）
- **Node.js**：18.x LTS版本
- **Docker**：20.10+（包含Docker Compose）
- **Git**：2.0+
- **IDE**：VS Code + 推荐插件

#### 环境变量配置
- **数据库连接**：DATABASE_URL
- **Redis配置**：REDIS_URL
- **JWT配置**：JWT_SECRET、JWT_EXPIRE_HOURS
- **LLM配置**：各种AI平台API密钥

#### 本地开发工作流
1. 克隆仓库并安装依赖
2. 配置环境变量文件
3. 启动Docker容器
4. 初始化数据库
5. 开始开发和测试

**章节来源**
- [docs/03-development/dev-guide.md:1-32](file://docs/03-development/dev-guide.md#L1-L32)