# 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`
- 统一异常处理（不泄漏内部错误详情）
- 密码重置/邮箱验证等敏感操作防止用户枚举