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.
349 lines
14 KiB
Markdown
349 lines
14 KiB
Markdown
# 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 接口清单** — 至少给出每个路由组下的核心端点
|