# GEO - AI搜索引擎品牌曝光度优化平台

[![CI Pipeline](https://github.com/YOUR_USERNAME/GEO/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/GEO/actions/workflows/ci.yml)
[![PR Check](https://github.com/YOUR_USERNAME/GEO/actions/workflows/pr-check.yml/badge.svg)](https://github.com/YOUR_USERNAME/GEO/actions/workflows/pr-check.yml)

## 项目简介

GEO（Generative Engine Optimization）是一个SaaS平台，帮助品牌监测其在各大AI搜索引擎中的曝光度和引用情况。支持文心一言、Kimi、通义千问、豆包、讯飞星火、天工、清言等主流国内AI平台，以及通用搜索引擎。

## 核心功能

- **多平台品牌引用监测**：同时覆盖8个主流AI搜索平台
- **定时自动查询与即时查询**：支持按日/周频率自动执行，也可手动触发
- **品牌匹配分析**：精确匹配、别名匹配、模糊匹配三级策略
- **竞品引用检测**：监测竞争对手在同一查询中的引用情况
- **数据可视化**：引用趋势图、平台对比图等多维度图表
- **CSV/PDF报告导出**：一键生成专业数据报告
- **用户管理与权限控制**：JWT认证、邮箱验证、密码管理
- **订阅套餐管理**：基于套餐的查询词数量限制
- **管理后台**：系统级用户与数据管理

## 技术栈

| 组件 | 技术 |
|------|------|
| 前端 | Next.js 14, React 18, TailwindCSS, shadcn/ui, Recharts |
| 后端 | Python FastAPI, SQLAlchemy 2.0 (async), Pydantic v2 |
| 数据库 | PostgreSQL 15, Redis 7 |
| 认证 | JWT + NextAuth.js |
| 任务调度 | APScheduler |
| 浏览器自动化 | Playwright |
| 容器化 | Docker Compose |

## 快速开始

### Docker 方式（推荐）

```bash
# 1. 克隆仓库
git clone <repository-url>
cd GEO

# 2. 复制环境变量
cp .env.example .env

# 3. 启动所有服务
docker-compose up -d

# 4. 访问应用
# 前端: http://localhost:3000
# 后端 API: http://localhost:8000
# API 文档: http://localhost:8000/docs
```

### 本地开发

#### 后端

```bash
cd backend
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000
```

#### 前端

```bash
cd frontend
npm install
npm run dev
```

## 项目结构

```
GEO/
├── backend/                    # FastAPI 后端服务
│   ├── alembic/                # 数据库迁移脚本
│   ├── app/
│   │   ├── api/                # API 路由层
│   │   │   ├── auth.py         # 认证接口
│   │   │   ├── queries.py      # 查询词管理接口
│   │   │   ├── citations.py    # 引用数据接口
│   │   │   ├── reports.py      # 报告导出接口
│   │   │   └── deps.py         # 依赖注入
│   │   ├── middleware/         # 中间件
│   │   │   ├── rate_limit.py   # 限流中间件
│   │   │   └── logging_middleware.py
│   │   ├── models/             # SQLAlchemy 数据模型
│   │   │   ├── user.py
│   │   │   ├── query.py
│   │   │   ├── citation_record.py
│   │   │   ├── query_task.py
│   │   │   └── subscription.py
│   │   ├── schemas/            # Pydantic 数据校验
│   │   ├── services/           # 业务逻辑层
│   │   ├── workers/            # 任务调度与引擎
│   │   │   ├── scheduler.py    # APScheduler 定时任务
│   │   │   ├── citation_engine.py
│   │   │   └── platforms/      # 各平台适配器
│   │   ├── config.py           # 应用配置
│   │   ├── database.py         # 数据库连接
│   │   └── main.py             # 应用入口
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/                   # Next.js 前端应用
│   ├── app/
│   │   ├── (auth)/             # 认证相关页面
│   │   │   ├── login/
│   │   │   ├── register/
│   │   │   ├── forgot-password/
│   │   │   └── reset-password/
│   │   ├── (dashboard)/        # 仪表盘页面
│   │   │   └── dashboard/
│   │   │       ├── queries/
│   │   │       ├── citations/
│   │   │       ├── reports/
│   │   │       └── settings/
│   │   ├── api/auth/[...nextauth]/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── ui/                 # shadcn/ui 组件
│   │   ├── charts/             # Recharts 图表组件
│   │   └── layout/             # 布局组件
│   ├── lib/                    # 工具函数与API客户端
│   └── package.json
├── tests/                      # 后端测试
├── docker-compose.yml
├── .env.example
└── README.md
```

## API 概览

| 模块 | 路径前缀 | 说明 |
|------|---------|------|
| 认证 | /api/v1/auth | 注册、登录、密码管理、邮箱验证、用户资料 |
| 查询管理 | /api/v1/queries | 查询词CRUD、立即查询 |
| 引用数据 | /api/v1/citations | 引用记录查询、统计分析 |
| 报告导出 | /api/v1/reports | CSV报告生成与下载 |

完整的 API 端点列表请参阅 [backend/README.md](backend/README.md)。

## 环境变量

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql+asyncpg://postgres:postgres123@db:5432/geo_platform` |
| `REDIS_URL` | Redis 连接地址 | `redis://redis:6379/0` |
| `JWT_SECRET` | JWT 签名密钥 | `your-secret-key-change-in-production` |
| `JWT_EXPIRE_HOURS` | JWT 过期时间（小时） | `24` |
| `NEXT_PUBLIC_API_URL` | 前端调用后端 API 地址 | `http://localhost:8000` |
| `PLAYWRIGHT_BROWSERS_PATH` | Playwright 浏览器路径 | `/ms-playwright` |
| `ZHIPU_API_KEY` | 智谱AI API 密钥（可选） | - |
| `TONGYI_API_KEY` | 通义千问 API 密钥（可选） | - |
| `CORS_ORIGINS` | 允许的跨域来源 | `http://localhost:3000` |

## 许可证

MIT