## 一、文章标题

**GEO 品牌监测系统实战：Node.js + React 模块化架构设计与双引擎采集**

> 系统覆盖品牌管理、问题配置、多平台采集、重复采样、历史趋势和报告导出。随着功能增加，代码需要按职责组织：接口层负责接收请求，业务层协调任务，采集层操作浏览器，分析层计算指标，前端负责交互与展示。
> 
> 下面结合目录结构与关键代码，说明这些模块如何协作。

[**获取地址**](https://yming.xin/upload/docs/molizhishu-api.html "获取地址")

![](https://developer.qcloudimg.com/http-save/yehe-12807703/2def7fad0529ddd2b0aae745af9dcc25.png)

## 二、整体目录结构

```bash
geo-monitoring/
├── src/
│ ├── index.js # 服务启动入口
│ │
│ ├── api/
│ │ ├── server.js # Fastify 初始化与路由注册
│ │ ├── routes/
│ │ │ ├── brands.js # 品牌接口
│ │ │ ├── prompts.js # 问题接口
│ │ │ ├── runs.js # 创建、查询、取消任务
│ │ │ ├── platforms.js # 平台配置与连接检查
│ │ │ └── reports.js # 报告查询与下载
│ │ └── schemas/
│ │ └── run-schema.js # 任务参数校验
│ │
│ ├── services/
│ │ ├── run-service.js # 创建任务、协调调度
│ │ └── report-service.js # 获取报告及导出内容
│ │
│ ├── db/
│ │ ├── database.js # 数据库连接与迁移
│ │ └── repository.js # 数据访问
│ │
│ ├── worker/
│ │ └── run-worker.js # 并发、间隔、取消、状态流转
│ │
│ ├── infrastructure/
│ │ ├── collector-runner.js # 统一采集入口
│ │ ├── platform-runner.js # Playwright 执行器
│ │ ├── opencli-runner.js # OpenCLI 执行器
│ │ ├── node-process.js # 子进程生命周期管理
│ │ ├── bridge-lock.js # 浏览器桥接互斥控制
│ │ └── artifacts.js # 证据文件存储
│ │
│ ├── platforms/
│ │ ├── index.js # 平台适配器注册
│ │ ├── base.js # 公共约定
│ │ ├── deepseek/adapter.js
│ │ ├── doubao/adapter.js
│ │ ├── kimi/adapter.js
│ │ ├── qwen/adapter.js
│ │ └── yuanbao/adapter.js
│ │
│ ├── analysis/
│ │ ├── sample-metrics.js # 样本指标计算
│ │ └── sampling-report.js # 报告数据聚合
│ │
│ ├── exporters/
│ │ ├── html-report.js # HTML 报告渲染
│ │ └── yao-dataset.js # Yao 兼容数据导出
│ │
│ ├── config/
│ │ └── paths.js # 数据及证据目录配置
│ └── shared/
│ ├── errors.js # 统一错误类型
│ └── ids.js # ID 生成
│
├── web/src/
│ ├── main.jsx # React 挂载入口
│ ├── App.jsx # 应用布局与页面路由
│ ├── api/
│ │ ├── client.js # 公共 HTTP 请求封装
│ │ └── reports.js # 报告请求与下载地址
│ ├── pages/
│ │ ├── OverviewPage.jsx
│ │ ├── QuestionsPage.jsx
│ │ ├── RunsPage.jsx
│ │ ├── PlatformsPage.jsx
│ │ ├── TrendsPage.jsx
│ │ └── ReportsPage.jsx
│ ├── components/
│ │ ├── RateBar.jsx
│ │ ├── ReportSummary.jsx
│ │ └── ReportDownloads.jsx
│ ├── hooks/
│ │ └── useSamplingReport.js # 加载、轮询与清理
│ └── styles/
│ ├── base.css
│ └── reports.css
│
├── vendor/yao-geo-skills/ # 上游脚本及许可证
├── test/ # 自动化测试
└── docs/ # 部署、采集器与架构说明
```

拆分的依据是职责和变化频率。例如，调整统计口径只涉及分析模块；改变报告样式只涉及导出模块；平台页面变化主要修改对应适配器。

## 三、明确模块之间的调用关系

```bash
React 页面
 ↓ HTTP
API 路由
 ↓
业务服务
 ├── Repository → SQLite
 └── Worker
 ↓
 统一采集入口
 ├── Playwright → 平台适配器
 └── OpenCLI → 浏览器采集脚本
 ↓
 回答与证据入库

报告请求
 ↓
报告服务 → 样本分析 → JSON / HTML / Yao 数据
```

这里有几个关键边界：

| 模块 | 负责 | 约束 |
| --- | --- | --- |
| API 路由 | 参数校验、调用服务、返回响应 | 不直接操作浏览器 |
| 业务服务 | 协调数据库与任务执行 | 不依赖页面选择器 |
| Worker | 并发、取消、间隔和状态 | 不生成报告 HTML |
| 采集器 | 执行提问、标准化结果 | 不决定统计口径 |
| 分析模块 | 从样本计算指标 | 不访问数据库和网络 |
| 导出模块 | 将报告转换为输出格式 | 不重新计算指标 |

## 四、核心代码按文件展示

以下展示一条完整的“采集结果 → 统计 → 报告 → 前端显示”路径。采集入口对应现有实现，其余代码展示建议拆分方式。

### 1\. 统一采集入口

文件：`src/infrastructure/collector-runner.js`

```bash
import { executePlatformRun } from './platform-runner.js';
import { executeOpenCliRun } from './opencli-runner.js';

export function executeCollectorRun(options) {
 return options.platformRun.collector === 'opencli'
 ? executeOpenCliRun(options)
 : executePlatformRun(options);
}
```

Worker 只调用这个入口。采集方式在创建任务时校验并保存，因此后续修改平台默认设置不会影响已有任务。

### 2\. 独立计算样本指标

文件：`src/analysis/sample-metrics.js`

```bash
function percentage(count, total) {
 return total > 0
 ? Math.round((count / total) * 1000) / 10
 : null;
}

export function summarizeSamples(samples) {
 const valid = samples.filter(
 sample =>
 sample.status === 'completed' &&
 sample.answer?.content?.trim()
 );

 const mentioned = valid.filter(
 sample => sample.answer.brandMentioned
 ).length;

 return {
 planned: samples.length,
 valid: valid.length,
 mentioned,
 failed: samples.filter(s => s.status === 'failed').length,
 cancelled: samples.filter(s => s.status === 'cancelled').length,
 pending: samples.filter(
 s => ['queued', 'running'].includes(s.status)
 ).length,
 mentionRate: percentage(mentioned, valid.length),
 coverageRate: percentage(valid.length, samples.length),
 citationRate: percentage(
 valid.filter(s => s.answer.citations?.length > 0).length,
 valid.length
 ),
 };
}
```

这个模块是纯函数，相同输入产生相同统计结果，可以直接测试。

其中：

```bash
品牌提及率 = 提及品牌的有效回答数 ÷ 有效回答数
采样覆盖率 = 有效回答数 ÷ 计划采样数
```

采集失败不应直接算作“未提及品牌”。

### 3\. 聚合报告数据

文件：`src/analysis/sampling-report.js`

```bash
import { summarizeSamples } from './sample-metrics.js';

export function buildSamplingReport(run) {
 const samples = run.platformRuns;
 const groups = new Map();

 for (const sample of samples) {
 const key = JSON.stringify([
 sample.promptId,
 sample.platformId,
 ]);

 if (!groups.has(key)) {
 groups.set(key, []);
 }

 groups.get(key).push(sample);
 }

 return {
 schemaVersion: 'geo-monitoring/sampling-report/v1',
 runId: run.id,
 status: run.status,
 generatedAt: new Date().toISOString(),
 brand: run.brandSnapshot,
 repeatCount: run.repeatCount,
 intervalSeconds: run.intervalSeconds,
 summary: summarizeSamples(samples),
 groups: [...groups.values()].map(items => ({
 question: items[0].prompt.text,
 platformId: items[0].platformId,
 ...summarizeSamples(items),
 })),
 samples,
 };
}
```

这是精简示例。迁移实际代码时，要保留现有报告中的指标说明、历史快照缺失提示等字段，保持前端兼容。

HTML 渲染和 Yao 数据转换分别移动到 `exporters`，避免统计文件同时承担模板和格式转换职责。

### 4\. 报告业务服务

文件：`src/services/report-service.js`

```bash
import { buildSamplingReport } from '../analysis/sampling-report.js';

export function createReportService({ repository }) {
 return {
 getReport(runId) {
 const run = repository.getRun(runId);
 return buildSamplingReport(run);
 },
 };
}
```

这一层将数据读取和报告生成组合起来。数据库层的“任务不存在”等错误，交由 API 的统一错误处理器转换成 HTTP 响应。

### 5\. 独立注册报告路由

文件：`src/api/routes/reports.js`

```bash
export async function reportRoutes(app, { reportService }) {
 app.get('/api/runs/:runId/report', {
 schema: {
 params: {
 type: 'object',
 required: ['runId'],
 properties: {
 runId: { type: 'string', minLength: 1 },
 },
 },
 },
 }, async request => {
 return reportService.getReport(request.params.runId);
 });
}
```

这里仅展示 JSON 查询。现有 HTML 下载、完整 JSON 下载和 Yao 导出分支，在迁移时保留相同 URL 和参数。

路由模块负责 HTTP 交互，具体导出逻辑调用对应服务与导出器。

### 6\. 前端请求统一封装

文件：`web/src/api/client.js`

```bash
export async function requestJson(url, options = {}) {
 const response = await fetch(url, options);
 const data = await response.json();

 if (!response.ok) {
 throw new Error(data.message || `请求失败：${response.status}`);
 }

 return data;
}
```

文件：`web/src/api/reports.js`

```bash
import { requestJson } from './client.js';

export function getSamplingReport(runId, options = {}) {
 return requestJson(
 `/api/runs/${encodeURIComponent(runId)}/report`,
 options
 );
}

export function getHtmlReportUrl(runId) {
 return `/api/runs/${encodeURIComponent(runId)}/report?format=html`;
}
```

页面不再重复拼接地址和处理 HTTP 错误。

### 7\. 展示组件只负责渲染

文件：`web/src/components/ReportSummary.jsx`

```bash
export default function ReportSummary({ summary }) {
 const mentionRate = summary.mentionRate === null
 ? '—'
 : `${summary.mentionRate}%`;

 return (
 <div className="report-summary">
 计划样本：{summary.planned}
 有效样本：{summary.valid}
 失败样本：{summary.failed}
 待完成：{summary.pending}
 品牌提及率：{mentionRate}
 </div>
 );
}
```

数据加载和轮询放到 `useSamplingReport.js`。该 Hook 需要在切换任务、切换品牌或卸载页面时，取消请求并清理定时器，避免旧报告覆盖新选择。

一、文章标题 GEO 品牌监测系统实战：Node.js + React 模块化架构设计与双引擎采集 系统覆盖品牌管理、问题配置、多平台采集、重复采样、历史趋势和报告导出。随着功能增加，代码需要按职责组织：接口层负责接收请求，业务层协调任务，采集层操作浏览器，分析层计算指标，前端负责交互与展示。 下面结合目录结构与关键代码，说明这些模块如何协作。 获取地址 二、整体目录结构 geo-monitori

GEO 品牌监测系统实战：Node.js + React 模块化架构设计与双引擎采集

编程语言

后端

架构设计

基于Node.js与React的GEO品牌监测系统，采用模块化架构实现多平台采集、重复采样与历史趋势分析。系统分层设计清晰：API路由负责请求校验，业务服务协调调度，采集层支持Playwright与OpenCLI双引擎，分析模块独立计算品牌提及率等指标。前端通过React组件展示报告，支持HTML及Yao数据导出，便于SEO数据追踪与决策。

文件存储

数据转换

数据库

路由

SQLite

ReAct 

JSON

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

基于Node.js与React的GEO品牌监测系统，采用模块化架构实现多平台采集、重复采样与历史趋势分析。系统分层设计清晰：API路由负责请求校验，业务服务协调调度，采集层支持Playwright与OpenCLI双引擎，分析模块独立计算品牌提及率等指标。前端通过React组件展示报告，支持HTML及Yao数据导出，便于...

GEO 品牌监测系统实战：Node.js + React 模块化架构设计与双引擎采集-腾讯云开发者社区-腾讯云

GEO 品牌监测系统实战：Node.js + React 模块化架构设计与双引擎采集

GEO 品牌监测系统实战：Node.js + React 模块化架构设计与双引擎采集

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐