fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/docs/brainstorms/2026-05-31-geo-platform-acc...

8.4 KiB
Raw Permalink Blame History

date topic
2026-05-31 geo-platform-acceptance-audit

Summary

GEO 平台全项目验收审计方案，定义功能完整性、安全性、性能、代码质量四个维度的验收标准与检查清单，包含已发现 42 项问题的分级修复计划，以及四类项目文档的更新规范，确保平台达到可交付质量水平。

Problem Frame

GEO 平台经过多轮迭代开发，已实现 33 个 API 路由模块、8 个 Agent、35 个数据模型、25+ 前端页面。但快速迭代带来了技术债务：4 个新 Agent 的前端 API 客户端尚未创建、部分 API 存在认证绕过风险、N+1 查询影响性能、API 文档覆盖率仅 15%。在交付前需要系统性的验收审计，识别并修复阻塞问题，同步更新文档使项目状态与代码一致。

Key Decisions

审计维度覆盖全部四项而非选择性覆盖 — 功能完整性、安全性、性能、代码质量相互关联，部分安全漏洞隐藏在功能实现中，性能问题影响功能可用性，选择性覆盖会遗漏跨维度问题。

Critical/High 问题作为验收阻塞项 — 20 个 Critical + High 问题必须在验收通过前修复，Medium/Low 问题可记录为技术债务在后续迭代处理。

文档更新纳入验收流程 — 文档与代码不同步是当前最大运维风险（API 文档覆盖率仅 15%），文档更新不是附加任务而是验收的必要条件。

自审计而非第三方审计 — 本方案定位为交付前自审计，确保基本质量门槛；渗透测试等深度安全审计作为后续独立项目规划。

Requirements

功能完整性

R1. 所有 33 个 API 路由模块必须有对应的前端 API 客户端模块，且接口签名与后端一致

R2. 8 个 Agent 均可通过 standalone 模式独立启动并执行其声明的 supported_tasks

R3. 用户注册→登录→Onboarding→品牌创建→诊断→方案生成→内容生成→效果追踪的完整业务闭环可端到端走通

R4. 4 个新 Agent（MonitorAgent、SchemaAdvisor、CompetitorAnalyzer、TrendAgent）的前端 API 客户端模块必须创建，覆盖其全部 API 端点

R5. 前端所有页面的 API 调用参数（字段名、类型、顺序）与后端路由定义一致，无运行时 400/500 错误

R6. GEO 方案自动生成流程（诊断→策略→方案→行动）完整可用，竞品为可选输入

R7. 品牌评分（5 维度 V2 评分体系）在品牌详情页和仪表盘均可正确展示

安全性

R8. 所有业务 API 端点（除 /health、/ready、/auth/login、/auth/register 外）必须要求认证，不存在认证绕过路径

R9. analytics 路由的认证检查必须与业务路由一致，不能因中间件顺序或装饰器缺失而跳过

R10. API Key 通过加密存储（key_encryption.py），密钥不在日志、响应体、前端代码中明文暴露

R11. CORS 配置在生产环境必须限制 allow_origins 为具体域名，不能使用通配符 *

R12. 用户输入必须经过 Pydantic Schema 校验，不存在未校验的请求参数直接进入数据库查询

R13. SQL 查询使用 SQLAlchemy ORM 参数化查询，不存在字符串拼接 SQL

性能

R14. 品牌评分数据获取逻辑提取为共享服务（BrandScoringDataService），消除 dashboard.py 和 strategy.py 中的重复查询

R15. 消除 N+1 查询模式：品牌列表页、仪表盘、策略页等高频访问路径不得出现循环内单条查询

R16. AI 引擎批量查询使用 queryBatch 端点而非逐条查询

R17. Redis 缓存层对热点数据（品牌评分、仪表盘统计）生效，缓存命中率作为可观测指标

代码质量

R18. 前端 agentsApi.enable/agentsApi.disable 死代码必须移除或替换为实际可用的实现

R19. 前端 onboardingApi.getCompetitorRecommendations 参数签名必须与后端一致

R20. models/__init__.py 中标注为"重构后遗留"的模型导入必须验证其与数据库迁移的一致性

R21. SEOOptimizer 命名与实际功能（GEO 优化）不一致的问题必须在代码或文档中明确标注

R22. content.py（内容生产）与 contents.py（内容管理）的命名混淆必须在 API 文档中明确区分

R23. 前端 lib/api/index.ts 聚合导出必须覆盖所有 API 客户端模块，消除遗漏

Key Flows

  • F1. 验收审计执行流程

    • Trigger: 审计方案文档确认后启动
    • Actors: 开发者、审计执行者
    • Steps: (1) 按维度执行检查清单 (2) 记录每项的通过/不通过状态 (3) Critical/High 不通过项进入修复流程 (4) 修复后回归验证 (5) 全部阻塞项通过后进入文档更新阶段 (6) 文档更新完成后签发验收报告
    • Outcome: 验收通过/不通过判定 + 问题修复记录 + 更新后的文档

  • F2. 问题修复流程

    • Trigger: 审计检查发现 Critical 或 High 问题
    • Actors: 开发者
    • Steps: (1) 问题分级确认 (2) 按优先级排序（Critical > High > Medium > Low）(3) 修复实现 (4) 回归验证（确认修复未引入新问题）(5) 更新审计检查清单状态
    • Outcome: 问题状态从"不通过"变为"通过"

  • F3. 文档更新流程

    • Trigger: 代码修复完成后
    • Actors: 开发者
    • Steps: (1) 更新项目文档（README、架构图、API 文档）(2) 更新 AI 上下文文件（CLAUDE.md、AGENTS.md）(3) 更新设计文档（模块说明、流程图）(4) 更新部署文档（环境变量、Docker 配置）(5) 交叉验证文档与代码一致性
    • Outcome: 四类文档与代码实现完全一致

Acceptance Examples

  • AE1. 认证绕过验证 — Covers R8, R9

    • Given: 未认证的 HTTP 请求
    • When: 请求 /api/v1/analytics 端点
    • Then: 返回 401 Unauthorized，不返回业务数据

  • AE2. 新 Agent 前端可用性 — Covers R4

    • Given: 前端 API 客户端模块 monitoring.ts、competitor-analysis.ts、schema-advisor.ts、trends.ts 已创建
    • When: 前端页面调用这些模块的方法
    • Then: 请求正确到达后端对应端点，参数类型和顺序匹配，无 400/500 错误

  • AE3. N+1 查询消除 — Covers R14, R15

    • Given: 仪表盘页面加载
    • When: 后端处理 /api/v1/dashboard 请求
    • Then: 品牌评分数据通过共享服务一次查询获取，SQL 日志中不出现循环内单条查询模式

  • AE4. CORS 生产配置 — Covers R11

    • Given: 生产环境部署
    • When: CORS 中间件初始化
    • Then: allow_origins 不包含通配符 *，仅允许配置的域名

  • AE5. 业务闭环端到端 — Covers R3

    • Given: 新注册用户完成 Onboarding
    • When: 依次执行诊断→查看诊断报告→生成 GEO 方案→执行内容生成→查看效果追踪
    • Then: 每一步均可成功完成，数据在步骤间正确传递

Success Criteria

  • 全部 6 个 Critical 问题修复并通过回归验证
  • 全部 14 个 High 问题修复并通过回归验证
  • API 文档覆盖率从 15% 提升至 80% 以上（至少覆盖 27/33 个路由模块）
  • AI 上下文文件（CLAUDE.md / AGENTS.md）创建完成，准确反映项目当前架构
  • 四类文档更新完成且与代码实现一致
  • 端到端业务闭环无阻塞错误

Scope Boundaries

Deferred for later:

  • 自动化 E2E 测试框架搭建
  • 性能压测与负载测试方案
  • 第三方安全审计（渗透测试）
  • CI/CD 流水线完善
  • 前端单元测试和集成测试覆盖

Outside this product's identity:

  • 基础设施级别的安全审计（网络层、K8s 配置）
  • 用户体验走查和可用性测试
  • 多语言/国际化验证

Dependencies / Assumptions

  • 后端服务可正常启动（PostgreSQL + Redis 可用）
  • 前端开发服务器可正常启动
  • 至少一个 LLM Provider 的 API Key 可用（用于验证 Agent 功能）
  • 当前审计基于代码静态分析 + 架构审查，不包含运行时动态分析
  • 数据库迁移状态与 models 定义一致（需在验收时验证）

Sources / Research

  • 审计扫描结果：Critical 6、High 14、Medium 14、Low 8 共 42 项问题
  • 项目架构文档：docs/01-项目概览/architecture.md
  • Agent 框架协议：docs/02-模块说明/agent-protocol.md
  • GEO 工作流分析：docs/02-模块说明/geo-workflow-analysis.md
  • 新 Agent 实现计划：docs/plans/2026-05-28-001-feat-geo-platform-new-agents-plan.md
  • 环境变量模板：.env.example
  • Docker 部署配置：docker-compose.yml