geo/docs/操作流程.md

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 字符将直接退出进程。可用以下命令生成：

python3 -c "import secrets; print(secrets.token_hex(32))"

---

二、系统启动

2.1 Docker 一键启动（推荐）

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 本地开发启动

后端：

cd backend
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

前端：

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