400 lines
16 KiB
Markdown
400 lines
16 KiB
Markdown
# GEO 平台操作流程
|
||
|
||
## 一、环境准备
|
||
|
||
### 1.1 系统要求
|
||
- Node.js 18+
|
||
- Python 3.11+
|
||
- PostgreSQL 15
|
||
- Redis 7
|
||
- Docker & Docker Compose（推荐）
|
||
|
||
### 1.2 环境变量配置
|
||
|
||
在项目根目录 `.env` 文件中配置以下关键项：
|
||
|
||
| 变量名 | 示例值 | 说明 |
|
||
|--------|--------|------|
|
||
| `DATABASE_URL` | `postgresql+asyncpg://chiguyong@localhost:5432/geo_platform` | PostgreSQL 异步连接串 |
|
||
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接串 |
|
||
| `JWT_SECRET` | `a3f8c2e1d7b9...` | JWT 签名密钥，**必须 ≥ 32 字符**，否则启动失败 |
|
||
| `JWT_EXPIRE_HOURS` | `24` | JWT Access Token 过期时间（小时） |
|
||
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | 前端调用后端的 API 地址 |
|
||
| `CORS_ORIGINS` | `http://localhost:3000,http://localhost:3001` | 允许跨域的前端地址 |
|
||
| `ENABLE_LLM` | `true` | 启用真实 AI 引用检测（`false` 则使用 Mock） |
|
||
| `OPENAI_API_KEY` | `sk-sp-c76f198d...` | 百炼 DashScope API 密钥 |
|
||
| `OPENAI_BASE_URL` | `https://coding.dashscope.aliyuncs.com/v1` | 百炼 DashScope 端点（OpenAI 兼容格式） |
|
||
| `DEFAULT_LLM_PROVIDER` | `openai` | LLM 提供商（`openai` / `deepseek`） |
|
||
| `LLM_MODEL` | `qwen3-coder-plus` | 默认调用模型名 |
|
||
| `ZHIPU_API_KEY` | _(可选)_ | 智谱 AI API Key |
|
||
| `TONGYI_API_KEY` | _(可选)_ | 通义千问 API Key |
|
||
| `MOONSHOT_API_KEY` | _(可选)_ | Kimi（月之暗面）API Key |
|
||
| `BAIDU_QIANFAN_API_KEY` | _(可选)_ | 百度千帆 API Key |
|
||
| `DOUBAO_API_KEY` | _(可选)_ | 豆包（字节跳动）API Key |
|
||
| `API_RATE_LIMIT_RPM` | `10` | AI 平台 API 调用频率限制（每分钟请求数） |
|
||
|
||
> **提示**：`JWT_SECRET` 启动时会强制校验长度，不足 32 字符将直接退出进程。可用以下命令生成：
|
||
> ```bash
|
||
> python3 -c "import secrets; print(secrets.token_hex(32))"
|
||
> ```
|
||
|
||
---
|
||
|
||
## 二、系统启动
|
||
|
||
### 2.1 Docker 一键启动（推荐）
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
启动后访问：
|
||
- 前端：http://localhost:3000
|
||
- 后端 API：http://localhost:8000
|
||
- API 文档（Swagger）：http://localhost:8000/docs
|
||
|
||
Docker Compose 编排四个服务：
|
||
|
||
| 服务 | 镜像 | 端口 | 依赖 |
|
||
|------|------|------|------|
|
||
| `db` | postgres:15-alpine | 5432 | — |
|
||
| `redis` | redis:7-alpine | 6379 | — |
|
||
| `backend` | 自建（./backend） | 8000 | db + redis 健康检查 |
|
||
| `frontend` | 自建（./frontend） | 3000 | backend |
|
||
|
||
数据持久化卷：`postgres_data`、`redis_data`
|
||
|
||
### 2.2 本地开发启动
|
||
|
||
后端：
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
alembic upgrade head
|
||
uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
前端：
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
> **注意**：生产环境启动后端应使用 `--no-reload` 参数，避免文件监视导致的进程崩溃。
|
||
|
||
---
|
||
|
||
## 三、业务操作流程
|
||
|
||
### 3.1 用户注册与登录
|
||
- 测试账号：`admin@fischer.com` / `Admin@123`
|
||
- 注册流程：`POST /api/v1/auth/register` → 邮箱验证 → 登录
|
||
- 登录流程：`POST /api/v1/auth/login` → 获取 Access Token + Refresh Token
|
||
|
||
### 3.2 Onboarding 引导（新用户首次登录）
|
||
1. 创建品牌（填写品牌名称、行业）→ `POST /api/v1/onboarding/brand`
|
||
2. 选择竞品（系统自动推荐 + 手动添加）→ `GET /api/v1/onboarding/competitor-recommendations`
|
||
3. 查看品牌健康报告（AI 分析品牌在各平台的表现）→ `GET /api/v1/onboarding/health-report/{brand_id}`
|
||
4. 获取行动建议（基于数据的优化建议）→ `GET /api/v1/onboarding/action-suggestions/{brand_id}`
|
||
5. 完成引导 → `POST /api/v1/onboarding/complete/{brand_id}` → 进入仪表盘
|
||
|
||
### 3.3 品牌管理
|
||
- 创建/编辑/删除品牌（`/api/v1/brands/`）
|
||
- 管理品牌下的竞品（`/api/v1/brands/{brand_id}/competitors/`）
|
||
- 查看品牌评分（`/api/v1/brands/{brand_id}/score/`、`/api/v1/brands/{brand_id}/score/history/`）
|
||
- 配置品牌别名（用于多名称匹配）
|
||
|
||
### 3.4 查询管理
|
||
- 创建监测查询词（如"XXX品牌怎么样"）→ `POST /api/v1/queries/`
|
||
- 查看查询列表 → `GET /api/v1/queries/`
|
||
- 立即执行检测 → `POST /api/v1/queries/{query_id}/run-now`
|
||
- 设置查询频率（即时/每日/每周），由 APScheduler 定时调度自动执行
|
||
|
||
### 3.5 引用检测
|
||
- 系统自动调用 AI 平台检测品牌引用
|
||
- 使用百炼 `qwen3-coder-plus` 模型分析引用情况
|
||
- 记录：是否被引用、引用位置、情感倾向、置信度
|
||
- 查看引用列表 → `GET /api/v1/citations/`
|
||
- 查看引用统计 → `GET /api/v1/citations/stats`
|
||
|
||
### 3.6 数据分析与报告
|
||
- 仪表盘统计：`GET /api/v1/dashboard/stats`
|
||
- 综合评分(V2)、健康等级、较昨日变化
|
||
- 五维度评分详情（提及率、推荐排名、情感评分、引用质量、竞争地位）
|
||
- 各平台评分对比（含竞品）
|
||
- 报告导出：`GET /api/v1/reports/export/csv`、`GET /api/v1/reports/export/pdf`
|
||
- 引用详情查看与筛选
|
||
|
||
### 3.7 内容管理
|
||
- 内容 CRUD：`/api/v1/contents/`（列表、创建、查看、更新、删除、发布）
|
||
- AI 内容生成：`POST /api/v1/content/generate`
|
||
- 流程：内容生成 → 去AI化 → GEO优化（三阶段 Pipeline）
|
||
- 支持知识库 RAG 上下文增强
|
||
- AI 选题生成：`POST /api/v1/content/generate-topics`
|
||
- 品牌知识库条目：`/api/v1/contents/knowledge/`（CRUD）
|
||
|
||
### 3.8 知识库
|
||
- 创建/列出/查看/删除知识库 → `/api/v1/knowledge/bases`
|
||
- 上传文档到知识库 → `POST /api/v1/knowledge/bases/{kb_id}/documents`
|
||
- 支持 text / markdown / url 三种来源
|
||
- 自动分块 + 向量化（MockEmbedder / OpenAIEmbedder）
|
||
- 文档管理（列出/删除）→ `/api/v1/knowledge/bases/{kb_id}/documents`
|
||
- 查看文档分块 → `GET /api/v1/knowledge/bases/{kb_id}/documents/{doc_id}/chunks`
|
||
- RAG 检索 → `POST /api/v1/knowledge/search`
|
||
|
||
### 3.9 内容分发
|
||
- 获取支持平台列表 → `GET /api/v1/distribution/platforms`
|
||
- 内容合规校验 → `POST /api/v1/distribution/validate`
|
||
- 生成发布策略 → `POST /api/v1/distribution/strategy`
|
||
- 内容格式化 → `POST /api/v1/distribution/format`
|
||
- 创建发布排期 → `POST /api/v1/distribution/schedule`
|
||
|
||
### 3.10 监测优化（Analytics）
|
||
- 记录发布 → `POST /api/v1/analytics/publish`
|
||
- 更新效果指标 → `PUT /api/v1/analytics/metrics/{publish_id}`
|
||
- 全局概览 → `GET /api/v1/analytics/overview`
|
||
- 单内容详情 → `GET /api/v1/analytics/content/{publish_id}`
|
||
- 排行榜 → `GET /api/v1/analytics/top`
|
||
- 洞察列表 → `GET /api/v1/analytics/insights`
|
||
- AI 生成洞察 → `POST /api/v1/analytics/insights/generate`
|
||
- 标记洞察已应用 → `POST /api/v1/analytics/insights/{insight_id}/apply`
|
||
|
||
### 3.11 告警通知
|
||
- 查看告警列表 → `GET /api/v1/alerts/`
|
||
- 未读告警数 → `GET /api/v1/alerts/unread-count`
|
||
- 全部标为已读 → `PATCH /api/v1/alerts/read-all`
|
||
- 单条标为已读 → `PATCH /api/v1/alerts/{alert_id}/read`
|
||
- 告警设置管理 → `/api/v1/alerts/settings`
|
||
|
||
### 3.12 客户管理
|
||
- 客户（组织）CRUD → `/api/v1/clients/`
|
||
- 查看客户下项目 → `GET /api/v1/clients/{client_id}/projects`
|
||
|
||
### 3.13 生命周期项目管理
|
||
- 项目列表 → `GET /api/v1/lifecycle/projects/`
|
||
- 项目统计 → `GET /api/v1/lifecycle/projects/stats`
|
||
- 快速创建项目 → `POST /api/v1/lifecycle/projects/quick-start`
|
||
- 项目时间线 → `GET /api/v1/lifecycle/projects/{project_id}/timeline`
|
||
- 阶段管理 → `/api/v1/lifecycle/projects/{project_id}/stages`
|
||
|
||
### 3.14 Agent 管理
|
||
- 列出所有 Agent → `GET /api/v1/agents/`
|
||
- Agent 详情/配置 → `/api/v1/agents/{agent_name}`
|
||
- 任务管理 → `/api/v1/agents/tasks/`（创建、查询状态、取消、日志）
|
||
|
||
### 3.15 订阅管理
|
||
- 查看套餐 → `GET /api/v1/subscriptions/plans`
|
||
- 当前订阅 → `GET /api/v1/subscriptions/current`
|
||
- 订阅 → `POST /api/v1/subscriptions/subscribe`
|
||
- 取消订阅 → `POST /api/v1/subscriptions/cancel`
|
||
- 订阅历史 → `GET /api/v1/subscriptions/history`
|
||
|
||
---
|
||
|
||
## 四、API 接口总览
|
||
|
||
### 认证 `/api/v1/auth`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/register` | 用户注册 |
|
||
| POST | `/login` | 用户登录（返回 Access + Refresh Token） |
|
||
| POST | `/refresh` | 刷新 Token（滑动过期） |
|
||
| GET | `/me` | 获取当前用户信息 |
|
||
| POST | `/forgot-password` | 忘记密码（发送重置链接） |
|
||
| POST | `/reset-password` | 重置密码 |
|
||
| POST | `/verify-email` | 验证邮箱 |
|
||
| POST | `/resend-verification` | 重发验证码 |
|
||
| PUT | `/change-password` | 修改密码 |
|
||
| PUT | `/profile` | 更新个人资料 |
|
||
|
||
### 品牌管理 `/api/v1/brands`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 获取当前用户所有品牌 |
|
||
| POST | `/` | 创建品牌 |
|
||
| GET | `/{brand_id}/` | 获取品牌详情 |
|
||
| PUT | `/{brand_id}/` | 更新品牌 |
|
||
| DELETE | `/{brand_id}/` | 删除品牌 |
|
||
| GET | `/{brand_id}/score/` | 获取品牌评分 |
|
||
| GET | `/{brand_id}/score/history/` | 获取评分历史 |
|
||
| * | `/{brand_id}/competitors/...` | 竞品管理（子路由） |
|
||
|
||
### 查询词 `/api/v1/queries`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 查询词列表（分页） |
|
||
| POST | `/` | 创建查询词 |
|
||
| GET | `/{query_id}` | 查询词详情 |
|
||
| PUT | `/{query_id}` | 更新查询词 |
|
||
| DELETE | `/{query_id}` | 删除查询词 |
|
||
| POST | `/{query_id}/run-now` | 立即执行检测 |
|
||
|
||
### 引用数据 `/api/v1/citations`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 引用列表（支持按 query_id/platform/日期筛选） |
|
||
| GET | `/stats` | 引用统计 |
|
||
|
||
### 报告 `/api/v1/reports`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/export/csv` | 导出 CSV 报告 |
|
||
| GET | `/export/pdf` | 导出 PDF 报告 |
|
||
|
||
### Onboarding `/api/v1/onboarding`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/status` | 检查 Onboarding 状态 |
|
||
| POST | `/brand` | 创建品牌（简化版） |
|
||
| GET | `/competitor-recommendations` | 竞品推荐 |
|
||
| GET | `/health-report/{brand_id}` | 品牌健康报告 |
|
||
| GET | `/action-suggestions/{brand_id}` | 行动建议 |
|
||
| POST | `/complete/{brand_id}` | 完成 Onboarding |
|
||
|
||
### 内容生产 `/api/v1/content`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/generate` | 一键生成内容（Pipeline：生成→去AI化→GEO优化） |
|
||
| POST | `/generate-topics` | AI 选题生成 |
|
||
|
||
### 内容管理 `/api/v1/contents`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 内容列表（分页、筛选） |
|
||
| POST | `/` | 创建内容 |
|
||
| GET | `/{content_id}` | 内容详情 |
|
||
| PUT | `/{content_id}` | 更新内容 |
|
||
| DELETE | `/{content_id}` | 删除内容 |
|
||
| POST | `/{content_id}/publish` | 发布内容 |
|
||
| GET | `/knowledge/` | 品牌知识库条目列表 |
|
||
| POST | `/knowledge/` | 创建品牌知识库条目 |
|
||
| PUT | `/knowledge/{knowledge_id}` | 更新品牌知识库条目 |
|
||
| DELETE | `/knowledge/{knowledge_id}` | 删除品牌知识库条目 |
|
||
|
||
### 知识库 `/api/v1/knowledge`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/bases` | 创建知识库 |
|
||
| GET | `/bases` | 列出知识库 |
|
||
| GET | `/bases/{kb_id}` | 知识库详情 |
|
||
| DELETE | `/bases/{kb_id}` | 删除知识库 |
|
||
| POST | `/bases/{kb_id}/documents` | 上传文档 |
|
||
| GET | `/bases/{kb_id}/documents` | 列出文档 |
|
||
| DELETE | `/bases/{kb_id}/documents/{doc_id}` | 删除文档 |
|
||
| GET | `/bases/{kb_id}/documents/{doc_id}/chunks` | 查看文档分块 |
|
||
| POST | `/search` | RAG 语义检索 |
|
||
|
||
### 仪表盘 `/api/v1/dashboard`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/stats` | 仪表盘统计（综合评分、维度、平台、竞品对比） |
|
||
|
||
### 内容分发 `/api/v1/distribution`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/platforms` | 支持平台列表 |
|
||
| POST | `/validate` | 内容合规校验 |
|
||
| POST | `/strategy` | 生成发布策略 |
|
||
| POST | `/format` | 内容格式化 |
|
||
| POST | `/schedule` | 创建发布排期 |
|
||
|
||
### 监测优化 `/api/v1/analytics`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/publish` | 记录内容发布 |
|
||
| PUT | `/metrics/{publish_id}` | 更新效果指标 |
|
||
| GET | `/overview` | 全局效果概览 |
|
||
| GET | `/content/{publish_id}` | 单内容详细表现 |
|
||
| GET | `/top` | 表现最好内容排行 |
|
||
| GET | `/insights` | 洞察列表 |
|
||
| POST | `/insights/generate` | AI 生成洞察 |
|
||
| POST | `/insights/{insight_id}/apply` | 标记洞察已应用 |
|
||
|
||
### 告警通知 `/api/v1/alerts`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 告警列表（支持类型/严重程度/已读状态/品牌筛选） |
|
||
| GET | `/unread-count` | 未读告警数 |
|
||
| PATCH | `/read-all` | 全部标为已读 |
|
||
| PATCH | `/{alert_id}/read` | 单条标为已读 |
|
||
| GET | `/settings` | 告警设置列表 |
|
||
| PUT | `/settings` | 批量更新告警设置 |
|
||
| PUT | `/settings/{setting_id}` | 更新单条告警设置 |
|
||
|
||
### 客户管理 `/api/v1/clients`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 客户列表 |
|
||
| POST | `/` | 创建客户 |
|
||
| GET | `/{client_id}` | 客户详情 |
|
||
| PUT | `/{client_id}` | 更新客户 |
|
||
| DELETE | `/{client_id}` | 删除客户 |
|
||
| GET | `/{client_id}/projects` | 客户下的项目列表 |
|
||
|
||
### 生命周期 `/api/v1/lifecycle`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/projects/` | 项目列表 |
|
||
| GET | `/projects/stats` | 项目统计 |
|
||
| POST | `/projects/quick-start` | 快速创建项目 |
|
||
| GET | `/projects/{project_id}/timeline` | 项目时间线 |
|
||
| GET | `/projects/{project_id}/stages` | 项目阶段列表 |
|
||
| PUT | `/projects/{project_id}/stages/{stage_number}` | 更新阶段状态 |
|
||
|
||
### Agent 管理 `/api/v1/agents`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 列出所有 Agent |
|
||
| GET | `/{agent_name}` | Agent 详情 |
|
||
| GET | `/{agent_name}/config` | Agent 配置 |
|
||
| PUT | `/{agent_name}/config` | 更新 Agent 配置 |
|
||
| GET | `/tasks/` | 任务列表 |
|
||
| POST | `/tasks/` | 创建任务（分发给 Agent） |
|
||
| GET | `/tasks/{task_id}` | 任务状态 |
|
||
| POST | `/tasks/{task_id}/cancel` | 取消任务 |
|
||
| GET | `/tasks/{task_id}/logs` | 任务日志 |
|
||
|
||
### 订阅 `/api/v1/subscriptions`
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/plans` | 套餐列表 |
|
||
| GET | `/current` | 当前订阅 |
|
||
| POST | `/subscribe` | 订阅套餐 |
|
||
| POST | `/cancel` | 取消订阅 |
|
||
| GET | `/history` | 订阅历史 |
|
||
|
||
### 管理员 `/api/v1/admin`（需管理员权限）
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/stats` | 系统统计 |
|
||
| GET | `/users` | 用户列表（分页、搜索） |
|
||
| GET | `/users/{user_id}` | 用户详情 |
|
||
| POST | `/users/{user_id}/toggle-active` | 启用/禁用用户 |
|
||
| PUT | `/users/{user_id}/update-plan` | 更新用户套餐 |
|
||
|
||
---
|
||
|
||
## 五、监控与运维
|
||
|
||
### 5.1 健康检查
|
||
- `GET /health` — 基础存活检查（Liveness），不依赖外部服务
|
||
- `GET /ready` — 依赖就绪检查（Readiness），检测 DB + Redis 连通性
|
||
- 返回 `200` + `{"status": "ready"}` 表示全部就绪
|
||
- 返回 `503` + `{"status": "not_ready"}` 表示依赖异常
|
||
|
||
### 5.2 日志
|
||
- 结构化 JSON 日志（`setup_logging()` 在启动时初始化）
|
||
- 每个请求附带 `X-Request-ID`（由 `RequestIdMiddleware` 注入）
|
||
- 慢请求（>1s）自动告警
|
||
- 中间件执行链：RequestId → Metrics → RateLimit → RequestLogging → CORS → SecurityHeaders
|
||
|
||
### 5.3 安全特性
|
||
- JWT 认证 + 用户级数据隔离（所有查询均按 `current_user.id` 过滤）
|
||
- 用户+IP 组合限流（`RateLimitMiddleware`）
|
||
- Agent 并发控制（Semaphore）
|
||
- LLM 令牌桶限流（30 RPM）
|
||
- 安全响应头：`X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY`、`X-XSS-Protection: 1; mode=block`
|
||
- 统一异常处理（不泄漏内部错误详情）
|
||
- 密码重置/邮箱验证等敏感操作防止用户枚举
|