root
de30497f59
- Implemented tenant and user management features including: - Tenant creation and management with associated migrations. - User creation and management with associated migrations. - Tenant membership management with associated migrations. - Platform user roles management with associated migrations. - Quota management with associated migrations. - Article and template management with associated migrations. - Added HTTP handlers for templates and workspaces. - Created tests for protected and public routes. - Introduced a script to check tenant scope in SQL queries. - Documented task plan for backend completion and frontend foundation.
14 KiB
14 KiB
GEO 平台技术架构严格审查报告
基于 geo-platform-ops-admin-tech-architecture-v1.md 对照
docs/refer中 8 个功能截图及两份 PRD 文档进行逐功能审查。
审查总结
| 评估维度 | 结果 |
|---|---|
| 功能覆盖度 | ⚠️ 存在多处缺口 |
| 后端模块划分 | ✅ 基本合理，部分缺失 |
| API 路由设计 | ⚠️ 多条功能链路缺少对应路由 |
| 数据模型覆盖 | ❌ 未提供数据库 Schema |
| 异步链路设计 | ⚠️ 部分 Worker 职责不完整 |
| 前端路由覆盖 | ⚠️ 缺少部分关键页面路由 |
一、逐功能审查
1. 工作台 (工作台.png)
截图功能点：
- 模板类型卡片入口（Top X / 产品评测 / 研究报告 / 持续扩展中）
- 右侧数据总览（生成数、发布数、品牌数、媒体平台数）
- 最近生成列表（标题、模板类型、生成状态、发布状态、字数、操作按钮）
- 左下角套餐额度区（免费版、升级入口、额度进度条、重置时间）
- 操作能力：发布、优化、预览、复制、删除
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
前端路由 /workspace |
✅ | 已定义 |
API /api/tenant/workspace/* |
✅ | 已定义 |
| 数据总览统计接口 | ⚠️ | 未在 API 中明确统计聚合端点 |
| 套餐额度展示接口 | ⚠️ | /api/tenant/account/* 未明确额度查询子接口 |
| 模板类型配置管理 | ❌ | 技术架构中未定义模板类型配置的存储与下发接口 |
Warning
工作台首屏需聚合多个数据源（文章统计、品牌数、媒体数、额度），架构中未设计聚合 BFF 层或专用 Dashboard API，可能导致首屏请求过多。
2. 模板创作 (模板创作.png)
截图功能点：
- 筛选区：模板类型、发布状态、生成时间、生成状态、搜索文章
- 操作按钮：批量生成文章、选择模板创作
- 列表：文章标题、模板类型、生成状态、发布状态、字数、操作
- 单次生成、批量任务
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
| 前端路由 | ⚠️ | admin-web 路由中有 /articles 但缺少模板创作专属路由 |
API /api/tenant/articles/* |
✅ | 已定义 |
| 模板定义管理 | ❌ | 后端缺少 tenant/template 模块定义 |
| 批量生成任务 | ✅ | worker-generate 已定义 |
| 模板输入字段配置 | ❌ | 未定义模板 schema 的存储与解析 |
Important
模板创作是核心链路之一，但技术架构中对"模板"概念的后端支撑严重不足。
internal/tenant下未见template子模块；后端模块职责 §5.5.4 仅列出article / brand / knowledge，完全未提及模板管理。
3. 自定义生成 (自定义生成.png)
截图功能点：
- 快捷入口：即时生成内容、定时计划生成
- Tabs：生成文章、即时任务、定时任务、Prompt 规则
- 筛选区：Prompt、定时任务、发布状态、标题、生成状态、生成时间
- 列表：文章标题、规则名称、Prompt、发布平台、生成状态、发布状态、字数
- Prompt 规则管理
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
| 前端路由（自定义生成） | ⚠️ | /articles 覆盖但未区分模板创作与自定义生成的路由 |
| Prompt 规则 CRUD | ❌ | 后端完全未定义 tenant/prompt-rule 模块 |
| 定时任务管理 | ❌ | 后端未定义定时调度器（Scheduler）组件 |
| 即时任务与定时任务差异化 | ❌ | worker-generate 仅定义"处理文章生成任务"，未区分即时/定时 |
| 定时任务表 | ❌ | 数据库设计中未提及 schedule_task 表 |
Caution
定时任务是自定义生成的核心子功能，但技术架构中完全缺少：
- 定时调度组件（如 cron scheduler 或 delayed message）
- 定时任务 CRUD 接口
- Prompt 规则管理接口
这是重大架构缺失。
4. 文章优化 (文章优化.png)
截图功能点：
- 操作入口：导入已生成文章、新建文章优化、未完成优化任务
- 筛选区：发布状态、生成时间、生成状态、搜索文章
- 列表：作品标题/来源、字数、发布状态、最后修改时间、操作
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
| 前端路由 | ⚠️ | /articles 中未区分文章优化页 |
| 优化任务管理模块 | ❌ | 后端未定义 tenant/optimization 子模块 |
| 优化任务 Worker | ❌ | worker-generate 未声明支持优化任务类型 |
| 优化版本管理 | ❌ | 未定义 article_version 的存储与接口 |
Warning
文章优化涉及"导入 → 优化 → 版本保存"链路，架构中完全未涉及。PRD 中定义了
OptimizationTask数据对象，但技术架构未对应出后端模块和接口。
5. 媒体管理 (媒体管理.png)
截图功能点：
- 绑定流程引导（安装插件 → 登录 → 授权同步）
- 平台分类 Tabs：UGC 媒体平台、企业自建站点、第三方新闻源
- 搜索与筛选（全部/已连接/未连接）
- 平台卡片：名称、类型、绑定状态、账号昵称、ID、运行状态
- 操作：去绑定、发布内容
- 支持 13+ 平台（知乎、头条号、百家号、搜狐号、企鹅号、网易号、简书、bilibili、稀土掘金、什么值得买、公众号、中关村在线等）
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
前端路由 /media |
✅ | 已定义 |
API /api/tenant/media/* |
✅ | 已定义 |
| 浏览器插件交互接口 | ⚠️ | 仅有 /api/callback/publish/*，缺少绑定回调接口 |
| 平台 Adapter 管理 | ✅ | platform-api 中有平台接入管理 |
| 平台分类模型 | ❌ | 未定义 UGC / 自建站 / 新闻源的分类架构 |
| 发布链路中的插件通信协议 | ❌ | 架构中未定义插件 ↔ 后端的通信协议和数据格式 |
Warning
媒体管理涉及浏览器插件的深度交互，但技术架构中未定义：
- 绑定回调接口（
/api/callback/bind/*）- 插件与后端的 WebSocket 或轮询通信机制
- 13+ 平台的 Adapter 注册与路由分发策略
6. 品牌词库 (品牌词库.png)
截图功能点：
- 品牌卡片区（品牌名称、新建品牌）
- Tab：关键词、竞品库
- 左侧关键词列表（关键词名称、数量、新建）
- 右侧问题集列表（问题内容、创建时间、操作：数据/删除）
- 新建问题集
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
前端路由 /brands |
✅ | 已定义 |
API /api/tenant/brands/* |
✅ | 已定义 |
| 品牌-关键词-问题集层级关系 | ⚠️ | 后端模块 §5.5.4 只笼统提到"品牌资料"，未展开数据层级 |
| 竞品库管理 | ❌ | 后端未定义 competitor 子模块 |
| 问题集"数据"操作（跳转数据详情） | ❌ | 架构中未定义品牌词→数据追踪的关联查询接口 |
7. 知识库 (知识库.png)
截图功能点：
- 新建内容按钮
- 左侧分组树（默认分组、新建分组）
- 右侧列表：名称、类型、大小、AI 学习状态、上传时间、操作
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
前端路由 /knowledge |
✅ | 已定义 |
API /api/tenant/knowledge/* |
✅ | 已定义 |
worker-knowledge |
✅ | 已定义，负责解析、Embedding、Qdrant 写入 |
| 分组管理接口 | ⚠️ | 未明确分组 CRUD 的子路由 |
| 多来源类型（文档/链接/文本） | ❌ | 架构中未定义不同来源类型的解析策略差异 |
| 对象存储集成 | ✅ | 已定义用于存储原始文档 |
知识库是架构覆盖度最高的模块。
8. 数据管理 (数据管理.png)
截图功能点：
- 数据概览卡片：总发文数、总引用数、文章引用率、品牌可见率
- 品牌排名数据区（品牌选择、关键词选择、模型选择）
- 指标 Tabs：提及率、首位提及率、首选推荐率、正面提及率
- 趋势图（按日期折线）
- 右侧高频问题列表
- 引用排行榜
架构覆盖情况：
| 检查项 | 状态 | 说明 |
|---|---|---|
前端路由 /tracking |
✅ | 已定义 |
API /api/tenant/tracking/* |
✅ | 已定义 |
worker-analytics |
✅ | 已定义，负责统计聚合 |
| 数据采集机制 | ❌ | 架构中未定义 GEO 指标（提及率、引用率等）的采集方式 |
| 品牌×关键词×模型 三维筛选 | ❌ | 后端未定义这种复合维度的查询接口设计 |
| 高频问题聚合逻辑 | ❌ | 未定义高频问题的来源和聚合策略 |
| 引用排行榜数据来源 | ❌ | 未定义引用数据的采集或模拟机制 |
Caution
数据管理/追踪是 UI 复杂度最高的功能之一，但技术架构中几乎仅有一行提到
worker-analytics负责"统计聚合、分析快照、缓存刷新"。缺少：
- GEO 指标采集服务或爬虫组件的架构定义
AnalyticsSnapshot、MentionRecord、CitationRecord的存储方案- 品牌×关键词×模型的多维查询 API 设计
- 高频问题的采集与聚合方案
二、跨功能架构问题
问题 1：数据库 Schema 完全缺失
Caution
技术架构文档 774 行，没有任何一张数据库表定义。PRD 中定义了 20+ 数据对象（User、Brand、Article、GenerationTask、ScheduleTask、PlatformAccount、KnowledgeItem 等），但技术架构中仅在 §7.1 笼统列出 PostgreSQL 负责的类别，未给出任何表结构、索引策略或分区方案。
问题 2：定时调度器缺失
技术架构定义了 4 类 Worker：
worker-generateworker-knowledgeworker-analyticsworker-publish-callback
但没有定义定时调度器。自定义生成中的"定时计划生成"功能需要 cron 调度能力，但架构中既没有独立的 cmd/scheduler 二进制，也没有说明使用 RabbitMQ Delayed Message 或其他延迟队列机制。
问题 3：Prompt 规则管理无后端支撑
自定义生成截图中有独立的 "Prompt 规则" Tab，PRD 中也明确定义了 Prompt 规则的 CRUD。但技术架构中：
internal/tenant下无prompt子模块- API 路由
/api/tenant/articles/*中未体现规则管理 - 平台侧
platform/content提到了"Prompt 规则管理"，但租户侧的 Prompt 规则管理被忽略
问题 4：浏览器插件通信架构缺失
媒体管理的核心链路依赖浏览器插件，但架构中：
- 未定义插件架构（虽然提到了
apps/browser-extension，但标记为"可选"） - 未定义绑定回调接口
- 未定义插件 ↔ 后端的消息协议
- 未定义发布过程中的状态同步（SSE vs WebSocket vs 轮询）
问题 5：文章版本管理与优化链路缺失
PRD 中定义了 ArticleVersion 和 OptimizationTask 数据对象，但技术架构中：
- 未出现"版本"概念
- 未设计优化任务的 Worker 或处理流程
- 文章模块仅支持 CRUD，缺少版本历史能力
问题 6：SSE 实现细节不足
架构中多次提到 SSE（Server-Sent Events），但：
- 仅在
internal/shared/sse中有一行提及 - 未定义 SSE 连接管理、heartbeat、reconnect 策略
- 未说明哪些场景走 SSE vs 轮询
- 未定义 SSE 事件类型与负载格式
问题 7：前端路由粒度不足
admin-web 路由仅 9 条，但参考截图中的功能至少需要：
/login
/workspace
-/articles
-/articles/:id
+/articles/template # 模板创作
+/articles/template/create # 模板创建表单
+/articles/custom # 自定义生成
+/articles/custom/instant # 即时任务
+/articles/custom/scheduled # 定时任务
+/articles/custom/prompts # Prompt 规则
+/articles/optimize # 文章优化
+/articles/:id # 文章详情
/brands
+/brands/:id # 品牌详情
/knowledge
/media
-/tracking
+/tracking/overview # 数据概览
+/tracking/detail # 数据详情
/account
三、按模块严重级别排列
🔴 严重缺失（阻塞开发）
| # | 问题 | 影响模块 |
|---|---|---|
| 1 | 定时调度器完全未设计 | 自定义生成 |
| 2 | Prompt 规则管理无后端模块 | 自定义生成 |
| 3 | 模板管理后端模块缺失 | 模板创作、工作台 |
| 4 | 数据库 Schema 缺失 | 全部模块 |
| 5 | GEO 指标采集方案未定义 | 数据管理 |
🟡 重要缺失（影响功能完整性）
| # | 问题 | 影响模块 |
|---|---|---|
| 6 | 文章优化/版本管理后端缺失 | 文章优化 |
| 7 | 浏览器插件通信协议未定义 | 媒体管理 |
| 8 | 绑定回调接口缺失 | 媒体管理 |
| 9 | 竞品库管理后端缺失 | 品牌词库 |
| 10 | 品牌×关键词×模型 复合查询设计缺失 | 数据管理 |
🟢 轻微不足（可迭代补充）
| # | 问题 | 影响模块 |
|---|---|---|
| 11 | 前端路由粒度不足 | 全部前端 |
| 12 | SSE 实现细节不足 | 长任务反馈 |
| 13 | 知识库多来源解析策略未定义 | 知识库 |
| 14 | 工作台 Dashboard 聚合 API 未设计 | 工作台 |
| 15 | 平台分类模型未定义 | 媒体管理 |
四、审查结论
Important
总体评估：技术架构文档覆盖了系统的宏观层面（服务拆分、技术选型、部署方案），但在对照 PRD 和参考截图进行逐功能审查时，发现多处核心业务链路缺少对应的后端模块定义、API 设计和数据模型。
建议补充项（按优先级排序）：
- 补充完整数据库 Schema 设计 — 至少覆盖 PRD 中定义的 20+ 数据对象
- 补充模板管理模块 —
internal/tenant/template，含模板 CRUD、schema 解析 - 补充定时调度器设计 —
cmd/scheduler或基于 RabbitMQ Delayed Message - 补充 Prompt 规则管理 —
internal/tenant/prompt-rule，含 CRUD + 关联生成 - 补充 GEO 数据采集架构 — 明确数据来源、采集频率、存储方案
- 补充文章优化模块 —
internal/tenant/optimization，含版本管理 - 补充浏览器插件通信协议 — 绑定/发布回调、状态同步机制
- 细化前端路由表 — 按实际页面层级展开
- 补充 SSE 事件定义 — 事件类型、负载格式、连接管理
- 补充 API 接口清单 — 至少给出每个路由组下的核心端点