# geo-saas

**Repository Path**: vicoproplus/geo-saas

## Basic Information

- **Project Name**: geo-saas
- **Description**: GEO系统
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GEO SaaS — 面向中国 AI 搜索引擎的 SEO 优化工具

> 针对 **豆包（Doubao）** 和 **通义（Tongyi）** 等中国主流 AI 搜索入口，
> 为线下商家提供关键词可见度监测、品牌提及分析、内容生成与周报能力的 SaaS 平台。

---

## 项目结构

```
geo-saas/
├── backend/                    # FastAPI + SQLAlchemy + Celery 后端
│   ├── app/
│   │   ├── main.py             # FastAPI 入口
│   │   ├── config.py           # 环境变量配置
│   │   ├── auth/               # JWT 认证
│   │   ├── core/               # LLM 客户端、数据质量门、成本控制
│   │   ├── models/             # 20+ ORM 模型
│   │   ├── modules/
│   │   │   ├── admin/          # 系统配置管理（LLM 中转站热配置）
│   │   │   ├── collector/      # 双通道采集（豆包 Playwright + 通义 SDK）
│   │   │   ├── sources/        # 线下数据源
│   │   │   ├── scoring/        # 可见度/提及率/竞品差距 三维评分
│   │   │   ├── content/        # AI 内容生成
│   │   │   └── reports/        # 周报聚合 + PDF
│   │   └── schemas/            # Pydantic v2 API 模型
│   ├── alembic/                # 数据库迁移
│   ├── scripts/seed_demo.py    # 演示种子数据脚本
│   └── tests/
├── frontend/                   # Vue 3 + Vite + TypeScript + Pinia 前端
├── docker-compose.yml
├── docs/                       # 设计规格、实施计划
└── plans/                      # 阶段开发计划
```

---

## 快速开始（Demo 环境）

### 前置要求

只需装 **Docker Desktop**（Windows/macOS）或 Docker Engine（Linux）—— Python / Node 都**不用**装，全部跑在容器里。

### 四条命令启动（首次约 3–5 分钟）

```bash
# 1. 克隆仓库
git clone <repo-url> geo-saas && cd geo-saas

# 2. 准备环境变量（默认值已经能跑，不改也行）
cp .env.example .env

# 3. 一键起全套服务（backend/frontend/celery/postgres/redis 共 6 个容器）
docker-compose up -d

# 4. 初始化数据库 + 种子数据
docker-compose exec backend alembic upgrade head
docker-compose exec backend python -m scripts.seed_demo
```

> **Windows PowerShell** 用 `Copy-Item .env.example .env` 替代 `cp`；后面几条命令都一样。

### 更便捷：Makefile 一键操作（可选）

```bash
make up      # = docker-compose up -d + migrate + seed
make down    # 停止并清理数据卷（重置数据库）
make logs    # 跟看后端日志
make reset   # 全清重来
```

启动完成后：

| 服务       | 地址                               | 默认账号             |
|-----------|-----------------------------------|---------------------|
| 前端 UI    | http://localhost:5173             | admin / admin123    |
| 后端 API   | http://localhost:8000             | —                   |
| API 文档   | http://localhost:8000/docs        | （仅开发环境）        |
| Postgres   | localhost:5432                    | geo_user / geo_password |
| Redis      | localhost:6379                    | —                   |

登录后，访问 **管理 → 系统配置 → LLM 中转站**，填入 `base_url` 和 `api_key`
（留空 `api_key` 时表示保留原值），勾选 **启用**，点击 **测试连接**，看到 `pong` 即表示配置生效。
**LLM 配置热生效，无需重启服务。**

---

## 主要功能

1. **双通道采集**：豆包使用 Playwright 异步浏览器自动化，通义使用 OpenAI 兼容 SDK；
   五级降级策略（正常 → 降频 → 代理 IP → 切换账号 → 人工介入）自动应对反爬。
2. **三维评分**：可见度（visibility）、品牌提及率（mention_rate）、竞品差距（competitor_gap）
   每日自动计算，并沉淀到 `score_history` 供趋势分析。
3. **AI 内容生成**：基于关键词意图层级（T1/T2/T3）生成不同形式的优化内容，
   写回 `generated_content`，供运营人员审核使用。
4. **周报 PDF**：WeasyPrint + Jinja2 渲染，包含排名变化、竞品对比、优化建议。
5. **LLM 中转站热配置**：所有 LLM 调用通过 `system_configs` 表驱动，admin UI 可视化改 key/base_url/模型，
   30 秒 TTL 缓存自动失效，**永远不需要重启**。
6. **多租户隔离**：PostgreSQL RLS（`app.current_client_id` / `app.is_admin`）保证数据硬隔离。

---

## 开发指南

### 后端本地开发

不想用 Docker 跑整套、只想在宿主机直接起后端和 Celery 时，推荐**基础设施用容器、业务进程跑本机**：
Postgres / Redis 仍由 `docker-compose` 起（免去装库麻烦），`uvicorn` 与 `celery` 在本地虚拟环境里跑，改代码即时生效、断点友好。

#### 前置要求

- **Python 3.12**（项目要求 `requires-python >= 3.12`，3.11 及其以下无法安装依赖）
- **只装 Docker 跑 Postgres / Redis**（可选）；或本机已装好 Postgres 18 + Redis 8
- **Playwright 浏览器**：采集豆包通道依赖 Chromium，`pip` 装完依赖后需单独下载
- **WeasyPrint 系统库**（仅周报 PDF 功能需要）：Linux 需 `libcairo2 / libpango / libgdk-pixbuf-2.0-0 / fonts-noto-cjk`；Windows 需 GTK 运行时。仅做 API 开发可暂时跳过

#### 1. 准备虚拟环境与依赖

```bash
cd backend
python -m venv .venv
source .venv/Scripts/activate      # Windows PowerShell/Git Bash；Linux/macOS 用 source .venv/bin/activate

pip install -r requirements.txt --timeout 120 --retries 10 --no-cache-dir

# 下载 Playwright Chromium（仅首次需要，约 100MB+）
playwright install chromium         # Windows 加 --with-deps 需先装 MSYS2，通常不需要
```

#### 2. 准备环境变量

根目录 `.env` 会**覆盖** `backend/.env`（`app/config.py` 按此优先级加载），本地开发直接改根目录 `.env`：

```bash
cp .env.example .env
```

把其中指向容器内服务名的连接改为宿主机 `localhost`：

```dotenv
DATABASE_URL=postgresql+asyncpg://geo_user:change_me_postgres_password@localhost:5432/geo_saas
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
```

> `JWT_SECRET_KEY` 等其余项保持模板默认值即可；`LLM_API_KEY` 留空时由 admin UI 热配置到 `system_configs` 表兜底。

#### 3. 只起基础设施（Postgres + Redis）

```bash
# 只拉起数据库与缓存，不启 backend / frontend / celery 容器
docker-compose up -d postgres redis

# 等待 Postgres 就绪
docker-compose exec -T postgres pg_isready -U geo_user
```

若本机已装好 Postgres 18 / Redis 8，可跳过这步，只要上面 `.env` 的连接能通即可。

#### 4. 初始化数据库与种子数据

```bash
cd backend
alembic upgrade head                 # 应用迁移
python -m scripts.seed_demo          # 写入演示数据（账号 admin / admin123）
```

#### 5. 启动业务进程（本机）

开三个终端，都在 `backend` 目录、且已 `activate` 虚拟环境：

```bash
# 终端 A — API（热重载，默认 http://localhost:8000，文档 /docs）
uvicorn app.main:app --reload --port 8000

# 终端 B — Celery Worker（gevent pool，Windows 兼容 async def 任务）
celery -A celery_app worker --pool gevent -c 4 --loglevel=info

# 终端 C — Celery Beat（定时任务调度器，必须常驻）
celery -A celery_app beat --loglevel=info
```

#### 6. 运行测试

业务进程跑着时，另开一个终端跑测试：

```bash
cd backend
pytest --no-cov -q                  # 快速跑一遍
# 或带覆盖率（项目要求 ≥ 80%）
pytest -v --cov=app --cov-report=term-missing
```

> 集成测试用 `testcontainers[postgres]` 在容器内临时拉起 Postgres，需要宿主机 Docker 可用。
> 单元测试用 `fakeredis` 模拟，无需真实 Redis。

---

### 后端单元测试

```bash
cd backend
pip install -r requirements.txt --timeout 120 --retries 10 --no-cache-dir
pytest --no-cov -q
```

### 前端本地开发

```bash
cd frontend
bun install
bun run dev          # 启动 Vite dev server，默认 http://localhost:5173
bun run build        # 生产构建
bun run type-check   # vue-tsc 类型检查
```

### 数据库迁移

```bash
# 生成新的迁移
docker-compose exec backend alembic revision --autogenerate -m "描述"

# 应用迁移
docker-compose exec backend alembic upgrade head

# 回滚最近一次
docker-compose exec backend alembic downgrade -1
```

---

## 技术栈要点

- **后端**：FastAPI 0.115 + SQLAlchemy 2.0 async + asyncpg + Pydantic v2 + Celery 5.4（gevent pool）
- **前端**：Vue 3 + Vite 8 + TypeScript + Pinia + TailwindCSS + shadcn-vue + vue-echarts
- **基础设施**：PostgreSQL 18（RLS 多租户）+ Redis 8（缓存 + Celery broker）
- **AI 层**：OpenAI 兼容客户端（支持任意中转站）+ Playwright 1.49（浏览器自动化）
- **PDF 渲染**：WeasyPrint + Jinja2

---

## 约定

- 全部代码注释、commit message、任务列表用中文；代码标识符保留英文。
- 不可变性优先：对象更新走"创建新副本"而非 in-place mutation。
- 文件尽量保持 200–400 行，单文件上限 800 行；函数上限 50 行。
- 任何改动：先写测试 → 跑 reviewer agent → 再合并。

---

## License

本项目处于内部开发阶段，暂未设置开源许可。如需合作请联系项目负责人。