geo/docs/Claude_architecture_review.md

# GEO 平台技术架构严格审查报告

> 基于 [geo-platform-ops-admin-tech-architecture-v1.md](file:///d:/project/geo/docs/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]
> **定时任务是自定义生成的核心子功能**，但技术架构中完全缺少：
> 1. 定时调度组件（如 cron scheduler 或 delayed message）
> 2. 定时任务 CRUD 接口
> 3. 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` 负责"统计聚合、分析快照、缓存刷新"。缺少：
> 1. GEO 指标采集服务或爬虫组件的架构定义
> 2. `AnalyticsSnapshot`、`MentionRecord`、`CitationRecord` 的存储方案
> 3. 品牌×关键词×模型的多维查询 API 设计
> 4. 高频问题的采集与聚合方案

---

## 二、跨功能架构问题

### 问题 1：数据库 Schema 完全缺失

> [!CAUTION]
> 技术架构文档 774 行，**没有任何一张数据库表定义**。PRD 中定义了 20+ 数据对象（User、Brand、Article、GenerationTask、ScheduleTask、PlatformAccount、KnowledgeItem 等），但技术架构中仅在 §7.1 笼统列出 PostgreSQL 负责的类别，未给出任何表结构、索引策略或分区方案。

### 问题 2：定时调度器缺失

技术架构定义了 4 类 Worker：
- `worker-generate`
- `worker-knowledge`
- `worker-analytics`
- `worker-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 条，但参考截图中的功能至少需要：

```diff
 /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 设计和数据模型。**

### 建议补充项（按优先级排序）：

1. **补充完整数据库 Schema 设计** — 至少覆盖 PRD 中定义的 20+ 数据对象
2. **补充模板管理模块** — `internal/tenant/template`，含模板 CRUD、schema 解析
3. **补充定时调度器设计** — `cmd/scheduler` 或基于 RabbitMQ Delayed Message
4. **补充 Prompt 规则管理** — `internal/tenant/prompt-rule`，含 CRUD + 关联生成
5. **补充 GEO 数据采集架构** — 明确数据来源、采集频率、存储方案
6. **补充文章优化模块** — `internal/tenant/optimization`，含版本管理
7. **补充浏览器插件通信协议** — 绑定/发布回调、状态同步机制
8. **细化前端路由表** — 按实际页面层级展开
9. **补充 SSE 事件定义** — 事件类型、负载格式、连接管理
10. **补充 API 接口清单** — 至少给出每个路由组下的核心端点