已生成的报告
—| 报告名称 | 类型 | 监测周期 | 生成时间 | 操作 |
|---|
监测报告 · 产品需求文档(PRD for 研发) 面向研发的完整规格:功能 · 交互 · 数据模型 · 接口 · 生成逻辑 · 异常 · 非功能 · 验收 收起展开查看
§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。 |
| 幂等键 | idemKey | tenantId + brandId + type + periodKey,同键的重复请求合并。 |
| 周期键 | periodKey | 日报 YYYY-MM-DD / 周报 YYYY-Www / 月报 YYYY-MM / 季报 YYYY-Qn。 |
| 周中快照 | partial=true | 周期未结束时手动生成的报告,覆盖周期初至今。 |
§3角色与权限矩阵 / RBAC
| 操作 \ 角色 | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| 查看报告列表 / 预览 / 下载 | ✓ | ✓ | ✓ | ✓ |
| 手动「立即生成」 | ✓ | ✓ | ✓ | — |
| 批量下载 | ✓ | ✓ | ✓ | ✓ |
| 删除 / 批量删除 | ✓ | ✓ | — | — |
| 新建 / 编辑 / 删除订阅 | ✓ | ✓ | ✓ | — |
| 跨品牌切换 | ✓ | ✓ | 受品牌授权 | 受品牌授权 |
租户隔离:所有列表 / 详情 / 操作必须强制
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 实体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 是 | 报告唯一 ID(雪花/ULID) |
tenantId | string | 是 | 租户 ID,强制隔离过滤 |
brandId | string | 是 | 品牌 ID |
type | enum | 是 | daily / weekly / monthly / quarterly |
periodKey | string | 是 | 见 §2,与 type 组合唯一 |
periodStart / periodEnd | date | 是 | 周期闭区间 |
status | enum | 是 | 见 §7 状态机 |
partial | bool | — | 周中快照标记 |
generatedAt | datetime | — | 完成时间(成功后赋值) |
fileUrl | string | — | 对象存储路径(私有 URL) |
fileSize / pages / checksum | num/string | — | 文件元数据 |
failReason | string | — | 失败时记录错误码 + 简短描述 |
createdAt / updatedAt | datetime | 是 | 审计字段 |
索引:
(tenantId, brandId, generatedAt DESC) 主查询;UNIQUE(tenantId, brandId, type, periodKey) 保证幂等。5.2 Subscription 实体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 是 | 订阅 ID |
tenantId / brandId | string | 是 | 归属 |
type | enum | 是 | 同 Report.type |
cards | string[] | 是 | 内容卡片范围 ID 数组(与监控页对应) |
status | enum | 是 | active / paused |
timezone | string | 是 | 租户时区,调度边界依赖 |
createdBy / createdAt | — | 是 | 审计 |
5.3 GenerationJob 实体
| 字段 | 类型 | 说明 |
|---|---|---|
jobId | string | 任务 ID |
reportId | string | 对应 Report.id(同周期幂等共享) |
idemKey | string | 幂等键,重复请求合并 |
trigger | enum | manual / scheduled / retry / backfill |
priority | int | 0=manual, 1=scheduled, 2=retry |
attempts | int | 当前重试次数 |
state | enum | queued / running / retrying / done / failed |
startedAt / endedAt | datetime | 执行时间 |
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
| type | cron(租户时区) | 覆盖周期 | 触发集合 |
|---|---|---|---|
| daily | 0 0 9 * * ? | 前一日 00:00 ~ 23:59 | 遍历该租户下 status=active 且 type 匹配的 Subscription,按品牌入队 |
| weekly | 0 0 9 ? * MON | 上一周 周一 ~ 周日 | |
| monthly | 0 0 9 1 * ? | 上月 1 日 ~ 月末 | |
| quarterly | 0 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 齐备。