# Collector Backend

数据采集后端服务 - Python FastAPI 实现

## 项目介绍

Collector Backend 是 IDE 数据采集系统的后端服务，负责接收、存储和分析来自各 IDE 插件的数据。

## 技术栈

- **框架**: FastAPI
- **数据库**: PostgreSQL + SQLAlchemy (async)
- **缓存**: Redis
- **数据库迁移**: Alembic
- **包管理**: Poetry

## 快速开始

### 环境要求

- Python 3.11+
- PostgreSQL 14+
- Redis 7+
- Poetry

### 安装

```bash
# 安装依赖
poetry install

# 复制环境配置
cp .env.example .env

# 编辑 .env 配置数据库等信息
```

### 数据库迁移

```bash
# 生成迁移
poetry run alembic revision --autogenerate -m "Initial migration"

# 执行迁移
poetry run alembic upgrade head
```

### 运行

```bash
# 开发模式
poetry run uvicorn src.main:app --reload --port 8000

# 生产模式
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000
```

### Docker 运行

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f app
```

## API 文档

启动服务后访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## API 端点

### 健康检查
- `GET /api/v1/health` - 健康检查
- `GET /api/v1/health/db` - 数据库健康检查

### 事件管理
- `POST /api/v1/events` - 创建单个事件
- `POST /api/v1/events/batch` - 批量创建事件
- `GET /api/v1/events` - 查询事件列表
- `GET /api/v1/events/{event_id}` - 获取单个事件

### 数据分析
- `GET /api/v1/analytics/overview` - 概览统计
- `GET /api/v1/analytics/acceptance-rate` - 采纳率统计
- `GET /api/v1/analytics/token-usage` - Token使用统计
- `GET /api/v1/analytics/user-activity` - 用户活动统计

### 配置管理
- `GET /api/v1/config` - 获取客户端配置

## 项目结构

```
collector-backend/
├── src/
│   ├── api/
│   │   └── v1/
│   │       ├── events.py      # 事件API
│   │       ├── analytics.py   # 分析API
│   │       ├── config.py      # 配置API
│   │       └── health.py      # 健康检查
│   ├── config/
│   │   ├── settings.py        # 配置管理
│   │   └── database.py        # 数据库配置
│   ├── models/
│   │   ├── event.py           # 事件模型
│   │   └── user.py            # 用户模型
│   ├── schemas/
│   │   ├── event.py           # 事件Schema
│   │   └── analytics.py       # 分析Schema
│   ├── services/
│   │   ├── event_processor.py # 事件处理
│   │   └── analytics_engine.py # 分析引擎
│   └── main.py                # 应用入口
├── migrations/                 # 数据库迁移
├── tests/                      # 测试
├── pyproject.toml             # 项目配置
├── docker-compose.yml         # Docker配置
└── README.md
```

## 开发

### 代码格式化

```bash
# 格式化代码
poetry run black src tests
poetry run isort src tests

# 代码检查
poetry run ruff check src tests
poetry run mypy src
```

### 运行测试

```bash
poetry run pytest
poetry run pytest --cov=src
```

## 相关仓库

- [ide-data-collector](../ide-data-collector) - IDE插件 Monorepo
- [collector-dashboard](../collector-dashboard) - 数据分析看板

## 许可证

MIT License