185 lines
8.4 KiB
Markdown
185 lines
8.4 KiB
Markdown
---
|
||
date: "2026-05-31"
|
||
topic: "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`
|