已生成的报告

—
报告名称 类型 监测周期 生成时间 操作
监测报告 · 产品需求文档(PRD for 研发) 面向研发的完整规格:功能 · 交互 · 数据模型 · 接口 · 生成逻辑 · 异常 · 非功能 · 验收 收起展开查看
版本v1.7.12
最后更新2026-05-29
文档状态Stable · 待评审
维护人产品 · 张明 / 研发 · TBD
相关方后端 · 前端 · 数据 · QA · 运维

§1概述 / Overview

定位:to B 多租户 GEO 监控平台中的报告中心,自动聚合六大监控页数据,按订阅周期或手动触发生成结构化报告(PDF),支持查看 / 下载 / 删除。
目标:让客户在无人值守的情况下定期获得品牌 AI 表现的完整快照与归因分析,支撑日 / 周 / 月 / 季运营节奏。
边界:本页不包含报告投递(邮件 / IM)功能,已剥离;订阅仅管理「周期 + 内容范围」,不绑定收件人。
上游:六大监控页(品牌提及与排名 / 口碑追踪 / AI 引用来源 / AI 对话记录 / 作品引用追踪 / 品牌监测管理)。
下游:报告预览、PDF 下载;后续可扩展导出 API。

§2名词术语 / Glossary

术语英文 / 标识定义
租户tenant付费客户主体,资源 / 权限 / 计费 / 配额隔离的最小单元。
品牌brand租户下的监测对象,报告生成、列表展示均以品牌为维度。
报告Report一次生成的成品,含元数据 + PDF 文件,状态见 §7 状态机。
订阅Subscription「品牌 + 周期 + 内容范围」的定时生成配置,无投递信息。
生成任务GenerationJob报告的一次执行实例,状态包含 queued / running / retrying / done / failed。
幂等键idemKeytenantId + brandId + type + periodKey,同键的重复请求合并。
周期键periodKey日报 YYYY-MM-DD / 周报 YYYY-Www / 月报 YYYY-MM / 季报 YYYY-Qn。
周中快照partial=true周期未结束时手动生成的报告,覆盖周期初至今。

§3角色与权限矩阵 / RBAC

操作 \ 角色OwnerAdminMemberViewer
查看报告列表 / 预览 / 下载✓✓✓✓
手动「立即生成」✓✓✓—
批量下载✓✓✓✓
删除 / 批量删除✓✓——
新建 / 编辑 / 删除订阅✓✓✓—
跨品牌切换✓✓受品牌授权受品牌授权
租户隔离:所有列表 / 详情 / 操作必须强制 tenantId 过滤,禁止跨租户访问。

§4页面功能清单 / Feature List

F1 · 顶部全局过滤
  • 品牌筛选:单选;驱动整页(列表 / 订阅 / 生成)品牌隔离。
  • 时间预设:近 7/14/30/90/180 天;以 generatedTs 过滤报告。
F2 · 立即生成本周报
  • 右上角主按钮;触发本周周报生成。
  • 含「周中确认 → 去重覆盖确认 → 生成中状态 → 完成 toast」全链路。
F3 · 订阅管理
  • 管理「品牌 × 周期 × 内容范围」订阅项;列表跟随当前品牌隔离。
  • 新建 / 编辑使用独立子弹窗;不含投递信息。
F4 · 报告列表
  • 列:报告名称 / 类型 / 监测周期 / 生成时间 / 操作。
  • 排序:类型 / 生成时间 三态(asc/desc/none);默认 generatedAt desc。
  • 分页:固定 10 条 / 页,可切换 10/20/50。
  • 行操作:预览 / 下载 / 删除。
F5 · 批量操作(多选)
  • 「批量下载」「批量删除」进入多选模式,行最左出现 checkbox + 全选。
  • 多选 toolbar 显示「已选 N / 总 X」与执行 / 取消按钮。
  • 翻页 / 排序时跨页保留选择状态。
F6 · 报告预览
  • 行内「眼睛」icon 打开 modal,展示完整结构化报告。
  • 支持下载 PDF;按品牌 / 周期渲染。
F7 · 刷新列表
  • 列表 toolbar 左侧 icon 按钮,重新拉取当前过滤条件下的报告。
  • 用于异步生成完成后手动拉取最新状态。

§5数据模型 / Data Model

5.1 Report 实体
字段类型必填说明
idstring是报告唯一 ID(雪花/ULID)
tenantIdstring是租户 ID,强制隔离过滤
brandIdstring是品牌 ID
typeenum是daily / weekly / monthly / quarterly
periodKeystring是见 §2,与 type 组合唯一
periodStart / periodEnddate是周期闭区间
statusenum是见 §7 状态机
partialbool—周中快照标记
generatedAtdatetime—完成时间(成功后赋值)
fileUrlstring—对象存储路径(私有 URL)
fileSize / pages / checksumnum/string—文件元数据
failReasonstring—失败时记录错误码 + 简短描述
createdAt / updatedAtdatetime是审计字段
索引:(tenantId, brandId, generatedAt DESC) 主查询;UNIQUE(tenantId, brandId, type, periodKey) 保证幂等。
5.2 Subscription 实体
字段类型必填说明
idstring是订阅 ID
tenantId / brandIdstring是归属
typeenum是同 Report.type
cardsstring[]是内容卡片范围 ID 数组(与监控页对应)
statusenum是active / paused
timezonestring是租户时区,调度边界依赖
createdBy / createdAt—是审计
5.3 GenerationJob 实体
字段类型说明
jobIdstring任务 ID
reportIdstring对应 Report.id(同周期幂等共享)
idemKeystring幂等键,重复请求合并
triggerenummanual / scheduled / retry / backfill
priorityint0=manual, 1=scheduled, 2=retry
attemptsint当前重试次数
stateenumqueued / running / retrying / done / failed
startedAt / endedAtdatetime执行时间
errorCode / errorMsg—失败上下文

§6交互规格 / Interaction Spec

交互点触发 + 前置条件动作 / 反馈 / 边界
立即生成本周报 点击按钮;generating=false ① 周中?→ 弹「本周尚未结束」confirm(剩余 N 天,仅周一至今)
② 同周期已存在?→ 弹「本周周报已存在」confirm(覆盖刷新)
③ 通过 → 立即在列表置顶插入 status=running 占位行,按钮 disabled + spinner
④ 完成 → toast「已生成」/「已重新生成」
⑤ 失败 → toast 错误码 + 行变红,可手动重试
排序(类型 / 生成时间) 点击表头 三态循环 asc → desc → none;同时只 1 列激活;类型按 daily < weekly < monthly < quarterly 权重。
分页 点击页码 / 切换页大小 固定 10 / 页,可切 10/20/50;切页保留选择状态;总数显示「共 X 条 / 第 i/N 页」。
批量下载 / 删除 点击对应按钮 进入多选模式:thead + 行 checkbox 出现;toolbar 切换为「已选 N / 总 X · 执行 / 取消」
全选 cb 三态(unchecked / checked / indeterminate);选 0 项时执行按钮提示「请先勾选」
删除二次 confirm;下载直接执行;执行完退出多选
切换品牌 顶部品牌选择器 列表 / 订阅 / 生成全部跟随 brand;URL 持久化(query ?brand=),刷新保持。
预览 PDF 行内眼睛 icon;status=done 打开 modal 内嵌结构化报告;非 done 状态 icon 灰化不可点。
刷新列表 列表 toolbar icon 按钮 重新拉取当前过滤条件;icon 旋转 360° 反馈;toast「列表已刷新」。
订阅 · 新建 订阅 modal footer「新建订阅」 子弹窗内品牌只读(取当前品牌);周期单选;内容卡片多选;保存后回主弹窗列表刷新。

§7报告生成逻辑 / Generation Logic

主流程
① 触发(手动/定时) ② 幂等校验 + 入队 ③ worker 拉取 ④ 数据快照 ⑤ 聚合 + 派生 ⑥ 渲染 PDF ⑦ 落库 + 状态更新
7.1 状态机
  • queued 入队,等待 worker 拉取
  • running worker 执行中
  • retrying 失败后指数退避重试
  • done 成功,可预览 / 下载
  • partial 含降级缺口的成功
  • failed 重试耗尽,可手动重试
合法迁移:queued → running → done/partial/failed;running → retrying → running;failed → queued(手动重试)。
7.2 幂等键与覆盖规则
幂等键 idemKey = sha1(tenantId + brandId + type + periodKey);同键已有报告时:
  • 定时触发:跳过(已生成视为完成)。
  • 手动触发:进入「重新生成」二次确认 → 覆盖原报告(reportId 不变,文件版本 +1,generatedAt 更新)。
7.3 周期边界与周中快照
  • 日报:periodKey = YYYY-MM-DD,periodStart = periodEnd = 该日。
  • 周报:ISO 周;periodKey = YYYY-Www;periodStart = 周一 00:00(租户时区),periodEnd = 周日 23:59。
  • 月 / 季:自然月 / 季首末日。
  • 周中快照:当前时间 < periodEnd 时手动生成 → partial=true,periodEnd 取当前时间所在日末,报告名称后缀「· 周中快照」。
7.4 内容规则(按 type)
type核心内容默认页数
daily当日重点 + 异动事件 Top3 + 实时指标快照~2 页
weekly趋势对比 + SOV + 竞品对比 + 行动建议~8 页
monthly归因分析 + 健康度评分 + 月度复盘~14 页
quarterly战略汇总 + 季度归因 + 趋势预测~22 页
7.5 生成伪代码
function handleGenerate(req):
  idem = sha1(req.tenantId, req.brandId, req.type, req.periodKey)
  existing = ReportRepo.findByIdem(idem)
  if existing and req.trigger == 'scheduled': return existing  // 跳过
  if existing and req.trigger == 'manual':                     // 覆盖
      report = existing
      report.status = 'queued'; report.version += 1
  else:
      report = Report.create({...req, status:'queued'})
  Queue.enqueue({jobId, reportId:report.id, idemKey:idem, priority})
  return report

function worker.consume(job):
  report.status = 'running'
  try:
      snapshot = DataSourceAggregator.snapshot(report.brandId, report.period)
      metrics  = Aggregator.derive(snapshot)
      pdf      = Renderer.render(report.type, metrics)
      Storage.put(pdf, checksum)
      report.fileUrl/size/checksum/generatedAt = ...
      report.status = snapshot.hasGap ? 'partial' : 'done'
  catch e:
      if job.attempts < 3 and e.retryable:
          Queue.requeueWithBackoff(job, base=30s, factor=2)
          report.status = 'retrying'
      else:
          report.status = 'failed'; report.failReason = e.code

§8定时调度 / Scheduler

typecron(租户时区)覆盖周期触发集合
daily0 0 9 * * ?前一日 00:00 ~ 23:59遍历该租户下 status=active 且 type 匹配的 Subscription,按品牌入队
weekly0 0 9 ? * MON上一周 周一 ~ 周日
monthly0 0 9 1 * ?上月 1 日 ~ 月末
quarterly0 0 9 1 1,4,7,10 ?上季首末日
  • 时区:以租户 timezone 为准(如 Asia/Shanghai),调度器内部 UTC 计算后转换;夏令时 / 跨时区遵守 IANA 规则。
  • 错过窗口补偿:调度器恢复后仅补偿最近 1 个周期,避免雪崩;历史缺失由运营手动触发回填(trigger=backfill)。
  • 抖动:每个租户在窗口起点附加 ±0~60s 抖动,避免整点尖峰。

§9接口契约 / REST API

方法路径说明
GET/api/v1/reports列表;query: brandId, type, timePreset, sort, page, pageSize
GET/api/v1/reports/:id详情(含预览数据)
GET/api/v1/reports/:id/download下载 PDF(302 跳预签 URL,5 分钟有效)
POST/api/v1/reports/generate手动生成;body: {brandId, type, periodKey?, force?}
POST/api/v1/reports/:id/retry失败重试(幂等)
DELETE/api/v1/reports/:id删除单个
POST/api/v1/reports:batchDelete批量删除;body: {ids: []}
POST/api/v1/reports:batchDownload批量下载(返回 zip 预签 URL)
GET / POST / PATCH / DELETE/api/v1/subscriptions[/:id]订阅 CRUD
统一规范:HTTP 头携带 X-Tenant-Id 与 Bearer Token;返回 {code, message, data, traceId};分页 {items, total, page, pageSize}。
错误码:REPORT_NOT_FOUND / REPORT_GENERATING / IDEM_CONFLICT / QUOTA_EXCEEDED / BRAND_NO_DATA / PERIOD_INVALID 等。

§10高并发与架构 / Concurrency

10.1 队列拓扑
  • 主队列 report.gen(Kafka / RocketMQ),按租户 partition 路由。
  • 延迟队列 report.retry 承载指数退避重试。
  • 死信队列 report.dlq,运营可查询 / 重投。
10.2 worker 池
  • 无状态 worker,按 CPU + 内存指标水平扩缩。
  • at-least-once 消费 + 幂等键,保障最终一致。
10.3 配额限流
  • 租户级:默认 10 RPS / 100 并发,按套餐升降。
  • 品牌级:默认 2 并发,避免单品牌占用过多资源。
  • 超额:返回 QUOTA_EXCEEDED,前端提示稍后重试。
10.4 优先级
  • manual(0) > scheduled(1) > retry(2) > backfill(3),同级 FIFO。
  • 付费租户额外 +0.5 优先级权重。
10.5 弹性扩容
  • HPA:队列积压 > 500 持续 1 分钟扩容 +50%,阈值回落 5 分钟缩容。
  • 最大 worker 数硬上限避免上游数据源被打挂。
10.6 背压保护
  • 积压 > 阈值时,对低优先级 scheduled / retry 暂停 1 分钟,并对手动请求返回降级提示。

§11异常处理矩阵 / Error Handling

层级异常场景错误码处理策略 / 用户感知
数据源 监控页 API 超时 / 5xx SRC_UPSTREAM_5XX 指数退避重试 3 次(base 30s);仍失败 → 模块降级标注「数据获取失败」,整体 partial。
品牌无监测数据 BRAND_NO_DATA 生成「数据不足」占位报告;提示前往「品牌监测管理」配置;不计入失败率。
部分指标缺失 / 脏数据 SRC_FIELD_INVALID 字段级校验剔除异常值;缺口 chip 标注「派生 / 模拟」;可读性优先。
数据源版本不兼容 SRC_SCHEMA_MISMATCH 报警 + 阻塞该 brand 当批次生成;运维介入。
任务执行 渲染 PDF 引擎异常 RENDER_FAIL 3 次重试;记录堆栈与 traceId;前端展示「生成失败」+ 重试按钮。
任务执行超时(> 5 min) JOB_TIMEOUT 熔断释放资源,置 failed;自动 1 次重试;超时仍失败上报告警。
worker 崩溃 / OOM / 宿主宕机 WORKER_LOST visibility timeout 到期任务自动重新入队(at-least-once),幂等键保证不重复。
并发同周期请求 IDEM_CONFLICT 定时:跳过;手动:进入覆盖确认;同一 idemKey 在途任务仅 1 个。
下游存储不可写 STORAGE_DOWN 重试;持续 > 60s 触发熔断器,新任务快速失败提示稍后重试。
并发 / 调度 队列积压 / 月初尖峰 QUEUE_BACKLOG HPA 扩容 + 优先级削峰 + 低优暂停;监控大盘告警。
单租户突发海量请求 QUOTA_EXCEEDED 令牌桶限流;超额返回 429;故障域隔离不波及他租户。
调度器宕机错过窗口 SCHED_MISSED 恢复后仅补偿最近 1 个周期;历史缺失运营手动 backfill。
幂等键冲突(极端竞态) IDEM_RACE DB 唯一约束兜底;落败方读取已生成结果返回。
存储 / 一致性 元数据 / 文件写入失败 STORE_WRITE_FAIL 事务回滚,无半成品;重试 3 次;最终失败置 failed 并告警。
文件损坏 / checksum 不一致 STORE_CORRUPT 标记不可用,提示重新生成;保留报告元数据用于追溯。
对象存储延迟回源(不可读) STORE_NOT_READY 预签 URL 失败时短轮询;超 30s 提示稍后再试。
业务边界 品牌被删除 / 暂停监测 BRAND_INACTIVE 跳过定时;历史保留可查;手动触发返回明确提示。
订阅周期 / 内容变更 — 下一个周期生效;在途任务按旧配置完成。
非法周期 / 未来周期 PERIOD_INVALID 提交前校验拦截,不入队;前端 disable 按钮 + 提示。
租户欠费 / 套餐降级 TENANT_SUSPENDED 停止新生成;已生成报告只读可下载(保留期内)。
前端 / 安全 未授权访问 / token 过期 401 / 403 统一拦截跳登录 / 提示权限不足;不暴露资源存在性。
批量操作中网络中断 — 部分成功的明细在 toast 展示;UI 重新拉取保持一致性。
跨租户越权尝试 FORBIDDEN 后端强制 tenant 过滤;记录安全审计日志并告警。

§12非功能性需求 / NFR

12.1 性能 SLA
  • 列表 P95 < 300ms;预览 P95 < 1.5s。
  • 单份周报端到端 P95 < 90s;日报 < 30s。
  • 系统支撑 ≥ 1w 租户 / 10w 品牌 / 50w 报告 / 月。
12.2 可用性
  • 读路径可用性 ≥ 99.9%;生成成功率 ≥ 99.5%(不含 BRAND_NO_DATA)。
  • 故障域隔离:单租户 / 单数据源故障不影响整体。
12.3 安全
  • 所有 API 强制 tenant 过滤 + RBAC 鉴权。
  • 文件链接走短期预签 URL(5 分钟过期)。
  • 删除走软删(30 天保留);敏感操作审计日志(who / when / what / traceId)。
12.4 可观测
  • 指标:队列长度 / 成功率 / P95 耗时 / 重试次数 / 失败码分布 / 配额命中率。
  • 日志:结构化 + traceId 串联 API → Queue → Worker → Storage。
  • 告警:失败率 > 1% / 队列积压 > 阈值 / DLQ 非空 / SLA 击穿。
12.5 存储与保留
  • PDF 走对象存储 + CDN;元数据 MySQL(按租户分库)。
  • 保留策略:付费 12 个月 / 试用 3 个月;到期归档至冷存储。
12.6 国际化
  • 租户级 locale;报告内容支持 zh-CN / en-US(V2)。
  • 所有日期 / 数字按 locale 渲染。

§13埋点指标 / Tracking

事件名触发主要属性
report_page_view进入页面tenantId, brandId, timePreset
report_generate_click点击立即生成brandId, midweek(bool), hasExisting(bool)
report_generate_done生成完成brandId, type, durationMs, status, partial
report_preview打开预览reportId, type
report_download下载(单 / 批量)reportId / ids[], size
report_delete删除(单 / 批量)reportId / ids[]
report_sort_change切换排序key, dir
subscription_save新建 / 编辑订阅brandId, type, cards[], isEdit

§14验收标准 / Definition of Done

  • 页面区块(F1~F7)功能 100% 实现,多端响应式 ≥ 1024px。
  • 列表 / 预览 / 下载读路径 P95 达标;生成 P95 达标(见 §12.1)。
  • 同周期幂等:手动连点 / 并发请求均不产生重复报告(单测 + E2E 验证)。
  • 异常矩阵每一条均有对应单测;关键路径有 E2E 用例。
  • 所有 API 通过权限 / 租户隔离冒烟测试;越权返回 403。
  • 埋点事件按 §13 全量上报,数据看板可见。
  • 可观测:列表 / 队列 / worker 三大监控大盘上线,关键告警接入值班。
  • 文档:API 文档(OpenAPI)+ 运行手册(runbook)+ 故障恢复 SOP 齐备。