2026合肥域明科技有限责任公司：智叟云集系统扩展架构设计

（平台提示：本文可能是商业推广软文）

2026合肥域明科技有限责任公司：智叟云集系统扩展架构设计

摘要

智叟云集系统由合肥域明科技开发。系统面向品牌 AI 可见度监测，提供客户端业务入口和服务商接口接入能力。本文说明如何在现有前后端结构上扩展舆情监控与数据分析，并统一身份、权限、任务、事件、计费和可观测性。

文中涉及的事件发件箱、独立分析 Worker、新接口和预留结算流程属于后续实施方案，不代表已全部上线。代码展示采用脱敏的业务契约，实际接入时需补齐数据库、认证、错误处理和测试实现。

一 新模块如何融入现有系统

智叟云集已有 React/Vite 前端、Node.js/Fastify 后端，以及品牌、问题、监控任务、采集适配和服务商 API 等能力。增加舆情与数据分析时，适合沿用模块化结构：

客户端 / 服务商 API
          ↓
身份认证与权限校验
          ↓
品牌 任务 舆情 分析业务服务
          ↓
持久化任务与事件
          ↓
采集 Worker / 分析 Worker
          ↓
结果数据库与证据存储

当前可以继续采用模块化单体。只有在任务量和部署需求明确后，再逐步拆分独立 Worker 和多个服务实例。多进程不能替代跨主机冗余，多副本也不能替代备份与恢复演练。

二 第一步 划分业务模块与依赖关系

建议结构如下：

src/
  modules/
    identity/          用户 租户 角色
    brands/            品牌与问题
    monitoring/        监控任务
    opinion/           舆情内容与预警
    analytics/         指标与汇总
    billing/           价格与流水
    provider-api/      服务商接口
  infrastructure/
    database/
    queue/
    storage/
    notifications/
  workers/
    collector-worker.ts
    opinion-worker.ts
    analytics-worker.ts
  shared/
    errors/
    contracts/

模块之间通过服务接口或明确的数据事件连接。例如，舆情模块可以读取已授权的采集结果，但不应该直接修改采集器内部状态；分析模块可以生成汇总数据，但不应该自己调整客户余额。这样能减少一个功能修改影响多个业务的情况。

三 第二步 统一身份与权限上下文

客户端会话和服务商密钥的认证方式不同，但进入业务服务后，可以统一为访问上下文：

// shared/contracts/access-context.ts
export interface AccessContext {
  actorId: string;
  actorType: "user" | "api_key";
  tenantId: string;
  customerId?: string;
  permissions: string[];
  requestId: string;
}

权限可以按动作定义为 opinion.read、opinion.review、opinion.rules.manage、analytics.read、analytics.export、monitoring.create。这些新增权限需要与现有角色和 API scope 映射。

路由处理应依次验证会话或 Key、构建可信访问上下文、检查动作权限、验证品牌或任务归属、执行业务，并记录必要审计信息。租户信息必须由服务器确定，不能仅依据请求体里的 tenantId。

如果以后迁移 PostgreSQL，可增加行级安全作为纵深防御。应用运行账号不应拥有绕过策略的权限，也需要注意表所有者通常具有特殊行为。连接池中的租户上下文应限定在当前事务内，避免串用其他请求的上下文。

四 第三步 用持久化事件连接采集与分析

采集完成后，系统需要继续触发内容分析和指标更新。如果直接在内存里发送事件，进程可能在保存结果后、发送事件前崩溃，导致后续处理遗漏。

可以引入事务发件箱：在同一个数据库事务中保存采集结果和待处理事件，再由后台分发器读取事件，触发舆情分析或指标更新。

// modules/monitoring/services/complete-sample.ts
export async function completeSample(
  db,
  sampleId: string,
  result
) {
  await db.transaction(async tx => {
    const sample = await tx.samples.getForUpdate(sampleId);

    if (sample.status === "completed") return;

    await tx.samples.complete(sampleId, result);

    await tx.outbox.insertUnique({
      eventKey:
        `sample.completed:${sampleId}:${result.version}`,
      type: "sample.completed",
      tenantId: sample.tenantId,
      payload: { sampleId, resultVersion: result.version }
    });
  });
}

getForUpdate 等方法代表数据访问层契约，需要按实际数据库实现；SQLite 不可直接照搬 PostgreSQL 的行锁语法。调用前还需完成资源存在性、归属和结果版本校验。

事件通常按至少一次方式投递，因此消费者也要幂等。分析结果可通过“样本编号与分析版本”的唯一约束防止重复写入；人工修订和重新分析应使用新的结果版本及独立更新流程。

五 第四步 实现 Worker 的领取 执行与恢复

Worker 需要处理的不只是循环读取任务，还包括原子领取、保存领取者与租约到期时间、执行期间更新心跳、超时恢复、错误与重试记录，以及防止旧 Worker 覆盖新结果。

建议状态包括 queued、running、succeeded、retry_wait、waiting_review、reconciling 和 failed。正常路径为 queued → running → succeeded；可重试错误进入 retry_wait，等待后重新排队；需要人工处理则进入 waiting_review。

reconciling 用于“上游是否成功尚不确定”的情况。例如上游提交请求超时，但可能已经创建任务，此时应优先查询上游任务状态，而不是立即再次提交。

对浏览器采集，还需要按租户和平台控制并发，避免同一浏览器目录同时被多个任务操作。

六 第五步 向服务商开放新增能力

服务商 API 应复用业务服务，不再单独实现另一套舆情或分析逻辑。建议接口分组如下：

GET /api/v1/opinion/documents查询授权范围内的内容

GET /api/v1/opinion/alerts 查询预警

GET /api/v1/analytics/summary 获取指标摘要

GET /api/v1/analytics/trends 获取时间趋势

POST /api/v1/report-jobs 创建异步报告任务

这些接口属于扩展设计，实际发布时需要同步 OpenAPI 文档、错误码、分页规则和权限说明。

大批量报告建议异步生成：创建任务后返回任务编号，生成完成再提供受控下载链接，避免一个 HTTP 请求长时间占用资源。

对于回调通知，需要增加签名、时间戳、事件编号和投递记录。服务商收到重复事件时，按事件编号幂等处理。回调地址也应进行外部地址检查，避免被利用访问内部资源。

七 第六步 明确费用与重试的关系

采集、情绪分析和报告生成可能使用不同资源，因此需要先定义收费对象，例如按有效采集样本、分析文档或报告任务收费，也可以在套餐额度中包含部分操作。

同一个逻辑操作的内部重试，不应未经规则约定就重复向客户收费。推荐结算流程为：校验价格与余额、预留额度、执行业务、根据最终结果结算、释放未使用额度。

任务状态不明确时进入对账流程，避免一边退款、一边继续产生上游费用。订单还应保存价格版本和费用明细，管理员后续改价不影响历史订单的结算依据。

这一流程属于后续完善方向，不能只因为存在余额页面就认为完整结算已经实现。

八 第七步 建立日志 指标与链路追踪

一个请求可能经过 API、队列、采集器、分析器和报告服务。排查问题需要把这些环节关联起来，建议统一携带 requestId、traceId、tenantId、jobId、sampleId、eventId 和 upstreamTaskId。

敏感内容应按权限保存，Token、Cookie 和密码不得写入日志。需要观察的指标包括队列等待时长、各平台成功率、采集与分析耗时、待人工处理数量、上游错误分布、报告生成失败数，以及对账中的任务数量。

OpenTelemetry 的 trace 可以将不同组件中的处理步骤关联成一条请求路径，适合定位耗时发生在哪个阶段。

存活检查 进程是否仍在运行

就绪检查 是否具备接受业务请求的条件

业务检查 最近是否能够完成关键流程

仅返回 HTTP 200 的健康接口，不能证明采集和分析链路正常。

九 第八步 按阶段发布与验收

阶段一 增加结构而不改变原业务

新增表、权限和后台处理模块，保留原有监控功能。迁移前完成数据库备份，并在测试环境验证恢复。

阶段二 只读验证

对授权样本执行情绪分析和指标计算，与人工结果对比。暂不开启自动外部通知，避免误报影响客户。

阶段三 小范围启用

通过功能开关为指定租户开放新页面、规则和接口，观察任务延迟、误报比例和资源消耗。

阶段四 扩大使用

在权限、费用、恢复和性能测试通过后，逐步扩大范围，并保留关闭新模块的能力。

Worker 执行中重启 任务可恢复，不重复落账

同一事件重复投递 分析结果不重复

租户 A 查询租户 B 数据 请求被拒绝

上游返回未知状态 进入对账，不盲目重复提交

模型输出格式错误 校验失败并记录原因

汇总任务重复执行 统计结果保持一致

页面快速切换品牌 旧响应不覆盖新数据

新模块关闭 原监控业务仍可使用

通过这种方式，舆情监控、数据分析与服务商 API 可以共享同一套身份、任务和证据体系，同时保持各模块职责清晰。后续增加平台、分析模型或报告模板时，也能在明确的边界内迭代。

常见问题（FAQ）

Q1｜舆情和分析新增 API 是否已开放给全部服务商？

答：尚不能这样描述。文中列出的 opinion、analytics、report-jobs 等接口属于扩展设计，发布时还需完善 OpenAPI 契约、授权范围、错误码、分页和测试。

Q2｜Web 客户端与服务商 API 是否共用同一种登录方式？

答：不共用认证凭据。浏览器使用客户端会话，服务商使用经授权的 API Key；进入业务服务后可以使用统一的可信访问上下文，并对每次资源访问核验租户与品牌归属。

Q3｜为什么建议将采集结果和待处理事件一起持久化？

答：如果只靠进程内事件，可能出现结果已保存、事件尚未发出时进程中断。事务发件箱设计旨在把两者纳入同一持久化事务，并通过消费者幂等应对重复投递。

Q4｜上游提交超时，Worker 应立即再次创建任务吗？

答：不宜直接重提。超时可能发生在上游已受理之后，方案建议先进入 reconciling 状态，查询上游实际结果，确认不存在原任务后再按规则处理。

Q5｜新模块内部重试会不会重复计费？

答：收费规则需要在实施前明确。文中提出内部重试不应在未经约定的情况下重复向客户收费，并规划预留、结算、释放及对账流程；这属于后续完善方向，不等于当前已上线完整结算。

Q6｜系统现在使用 PostgreSQL 行级安全了吗？

答：文档将 PostgreSQL 行级安全作为未来迁移时的可选纵深防御，并非现有部署事实。当前描述的基础架构采用 SQLite 和模块化单体方式，扩展需结合实际规模评估。

Q7｜健康接口返回 HTTP 200 就说明采集和分析完全正常吗？

答：不能。存活检查只说明进程运行；就绪检查关注是否能接受请求；业务检查还要验证关键采集、分析或报告链路是否实际可用。

Q8｜扩展架构应该怎样逐步发布？

答：建议先增加结构与备份机制，再进行只读验证；随后通过功能开关向少量租户启用，观察误报、任务延迟与资源消耗，通过权限、恢复、费用和性能验收后再扩大使用。

参考资料

PostgreSQL Row Security Policies

https://www.postgresql.org/docs/17/ddl-rowsecurity.html

OpenTelemetry Traces

https://opentelemetry.io/docs/concepts/signals/traces/