版本:2026-08-06
范围:E:\workspace\Saas-voc 前端、E:\workspace\server\saas-voc-server 后端
目标:把当前可运行的“反馈证据 -> AI 洞察 -> 行动项创建”提升为可审计、可执行、可验证、可持续学习的 VOC 业务闭环。
当前系统已经具备一条可用的生成链路:反馈收件箱提供可筛选的原始评价,AI VOC 页面准备证据并生成结构化洞察,洞察可以回跳到原始评价并预填行动项,后端 AnalysisRun 和 ActionItem 也已经有状态、权限、审计和来源字段。
但目前的链路仍停在“生成结果并创建行动项”,还没有完整表达以下业务事实:
AnalysisRun.completed/partial 是计算运行状态,不是业务确认状态;当前没有独立的确认、驳回或“补证据”记录。ActionItem,但现有行动中心仍通过本地 DomesticAnalyticsAdapterService.actions(dataset) 生成规则行动,来源和状态没有统一。completedAt,但没有基线、目标、观察窗口、观测值、验证结论或未测量原因。sourceAnalysisId=null、sourceInsightId=null、空 evidenceIds,会产生一条没有证据链的行动项。PATCH analysis 目前允许写入任意 JSON 结果,尚未在服务端强制校验 insight.evidenceIds 属于本次 input.evidenceIds。因此下一阶段不以增加更多“AI 摘要卡片”为主,而以三个可度量结果为主:
可追溯:每个可执行行动都能回到洞察、分析运行和原始证据
可决策:每个洞察都有显式的人审结论,AI 生成完成不等于业务确认
可验证:每个完成行动都有结果或明确的未测量原因,并能进入下一轮 VOC 分析
| 环节 | 当前实现 | 已具备能力 | 当前限制 |
|---|---|---|---|
| 反馈证据 | src/modules/feedback-inbox/feedback-inbox.component.ts:157-245、feedback-inbox.models.ts:13-27 |
来源、情感、主题、样本量、置信级别、详情回看 | 主要由前端数据集即时计算,没有统一的反馈事件/证据登记表 |
| AI 输入 | src/modules/ai-voc-insight/ai-voc-insight.service.ts:63-94 |
过滤范围、样本上限、证据 ID、主题和情感/来源统计 | 输入快照缺少模型、提示词、规则和分类版本;服务端不认识输入证据集合 |
| AI/规则生成 | ai-voc-insight.service.ts:96-152、:154-186 |
结构化 JSON、超时降级、deterministic fallback、needs_validation |
结果解析和证据白名单主要在前端;fallback 仍可直接打开行动创建面板 |
| 运行记录 | ai-voc-insight.component.ts:265-345、:507-642 |
pending -> processing -> completed/partial/failed、历史恢复、终态锁定、审计 |
运行状态没有拆成洞察业务状态;生成执行在前端,analysisExecution: false |
| 洞察展示 | ai-voc-insight.component.html:311-394 |
finding、user need、severity、confidence、opportunity status、recommendation、validation metric、证据回跳 | 没有“已阅证据/确认/驳回/补证据”的持久化交互 |
| 洞察转行动 | ai-voc-insight.component.html:427-440、action-create-panel.component.ts:81-115 |
自动带入 sourceAnalysisId、sourceInsightId、evidenceIds、validationMetric |
createdActionIds 只在页面内存中;没有幂等键;没有按机会状态阻断 |
| 单条反馈转行动 | feedback-inbox.component.ts:255-325、:281-304 |
可从反馈详情预填行动项 | 当前未携带分析/洞察来源,绕过证据->洞察关系;前端本地集合无法跨刷新判断已创建 |
| Action API | server/src/modules/saas-platform/routes.ts:221-266 |
分页、权限、成员校验、来源审计、状态更新 | 当前缺少行动详情、决策和验证 API;尚未表达效果回流 |
| 来源完整性 | server/src/modules/saas-platform/domain.ts:142-200、migrations/003...、004... |
同 workspace、已完成/部分完成的 voc_insight、洞察 ID、证据子集校验 |
仅校验行动创建时的来源;不校验生成结果本身,也不校验人审决策 |
| 行动中心 | src/modules/domestic-voc/framework/domestic-action-workbench.component.ts:88-106 |
有看板、体验优化、产品迭代、策略四个视图 | 读取 analytics.actions(dataset) 本地规则结果,没有消费 SaasPlatformService.actions() 或更新 ActionItem |
| 持久化 | server/src/modules/saas-platform/local-platform.repository.ts:208-287、Parse/Postgres repository |
三种 repository 接口已对齐 | local repository 为进程内数组,重启丢失;Postgres 迁移 003/004 必须在部署验收时确认已执行 |
AnalysisRun: pending -> processing -> completed | partial | failed | cancelled
ActionItem: open -> planned -> in_progress -> completed | blocked | cancelled
AnalysisRun 的终态约束在 server/src/modules/saas-platform/domain.ts:95-140 已有实现;ActionItem 的状态更新在各 repository 已有实现。但缺少业务层状态机:
Insight: draft -> confirmed | rejected | needs_more_evidence -> published -> archived
ActionValidation: pending -> effective | partially_effective | ineffective | not_measured
第一条用于判断“洞察能否进入正式行动”,第二条用于判断“行动是否解决了问题”。它们需独立于 AnalysisRun.status 和 ActionItem.status。
| 优先级 | 断点 | 业务风险 | 处理原则 |
|---|---|---|---|
| P0 | 没有独立的人审决策;needs_validation 仍可创建行动 |
AI/规则摘要可能被误当作正式结论 | 先保存决策,再允许可执行行动;“补证据”只能生成数据收集任务 |
| P0 | 生成结果的证据白名单只在前端完成 | 任何可写入 API 的客户端都可能提交无关证据 | 服务端对结果做 schema、证据子集、coverage 一致性校验 |
| P0 | 反馈收件箱快捷行动绕过洞察 | 行动缺少洞察与分析批次归因 | 改为“加入分析/创建待验证项”;确需快捷行动时必须用独立的原始反馈来源模型 |
| P0 | AI ActionItem 与行动中心断开 | 用户看不到刚创建的行动,也缺少状态推进入口 | 行动中心改读 SaaS Action API,并保留本地规则行动为独立来源 |
| P1 | 没有洞察版本、发布和归档 | 重新生成会覆盖上下文,难以比较口径变化 | 引入 InsightRecord 版本化,AnalysisRun 只代表一次计算 |
| P1 | 完成行动没有结果回流 | 缺少“哪类 VOC 被解决”的事实依据 | 引入 ActionValidation,完成行动必须记录验证结果或未测量原因 |
| P1 | 反馈缺少统一事件与快照 | 增量同步、去重、跨周期主题追踪不稳定 | 引入稳定 evidence registry 和 ingestion quality |
| P2 | 没有相似反馈/跨周期记忆 | 重复主题反复生成,分析师需要手工合并 | 规则过滤后再做向量相似检索,保留人工合并/拆分 |
| P2 | AI 质量和成本不可运营 | 缺少判断模型升级收益的事实依据 | 建立 golden set、schema/evidence 评估、延迟/成本看板和版本回归 |
| P2 | 没有受控的周报和问答 | 信息只能停留在页面内,组织传播成本高 | 只输出带引用的摘要,确认和行动仍回到平台完成 |
目标:任何进入正式行动中心的事项,都能证明“谁审阅了哪些证据、确认了什么、基于哪次分析、准备如何验证”。
InsightDecision建议新增 voc.insight_decision(Parse 对应 VocInsightDecision):
| 字段 | 类型 | 约束/含义 |
|---|---|---|
publicId |
text/UUID | 对外 ID |
workspaceId |
FK/text | 与 source analysis 一致 |
sourceAnalysisId |
FK/text | 必须是 voc_insight 且状态为 completed/partial |
sourceInsightId |
text | 必须存在于 analysis.result.insights[].id |
decision |
enum | confirmed、rejected、needs_more_evidence |
reviewedEvidenceIds |
jsonb/array | 非空,且是该 insight 的 evidenceIds 子集 |
comment |
text | 决策理由;rejected 和 needs_more_evidence 必填 |
decidedBy |
user ID | 当前 workspace active 成员 |
decidedAt |
timestamp | 服务端写入,不信任客户端时间 |
createdAt/updatedAt |
timestamp | 审计与幂等 |
约束:同一 (workspaceId, sourceAnalysisId, sourceInsightId) 只允许一个当前决策;重新判断产生新版本或显式 supersede 记录,不静默覆盖旧决策。
建议 API:
POST /api/saas/workspaces/:workspaceId/insight-decisions
GET /api/saas/workspaces/:workspaceId/insight-decisions?analysisId=:id
GET /api/saas/workspaces/:workspaceId/insight-decisions/:id
POST /actions 增加 sourceDecisionId。服务端必须检查决策与分析、洞察、workspace 三者一致:
confirmed:允许创建 experience/product/strategy/general 行动。needs_more_evidence:只允许创建 data_quality 的补证据任务,标题和验证指标必填。rejected:正式行动创建入口关闭。needs_more_evidence,除非已有明确人工 confirmed。AnalysisRun grounding contract保留当前 AnalysisRun,但要求 input 和 result 使用固定版本结构:
input: {
schemaVersion: 1;
evidenceIds: string[];
filters: { scope: 'all' | 'own' | 'competitor'; sentiment: string; sampleLimit: number };
datasetSnapshotId: string;
promptVersion?: string;
model?: string;
ruleVersion?: string;
taxonomyVersion?: string;
redaction: { applied: boolean; fieldCounts: Record<string, number> };
}
result: {
schemaVersion: 1;
mode: 'ai' | 'deterministic';
evidenceCoverage: number;
insights: Array<{ id: string; evidenceIds: string[]; opportunityStatus: string; validationMetric: string }>;
risks: string[];
followUpQuestions: string[];
}
服务端在 PATCH /analyses/:id 的终态写入前执行:
insight.evidenceIds 为非空且属于 input.evidenceIds。evidenceCoverage 等于实际被引用的去重证据数除以输入证据数,由服务端重算。mode=deterministic 必须写成 partial,且所有 insight 至少有 needs_validation 或显式风险说明。mode=ai、partial、completed 的结构均通过同一 schema validator。model/promptVersion/ruleVersion/taxonomyVersion,用于回归和审计;日志仅保存脱敏统计,不保存原始反馈正文。在现有 sourceAnalysisId/sourceInsightId/evidenceIds/validationMetric 之上增加:
sourceDecisionId: string | null
creationKey: string // workspace + analysis + insight + decision,唯一
sourceKind: 'insight' | 'raw_feedback' | 'rule_action'
creationKey 用于双击、刷新重试和多标签页幂等。现有 domain.ts:149-193 的来源完整性检查继续保留,并扩展为校验 sourceDecisionId。
对于反馈收件箱:
reviewId 加入分析批次,不直接创建正式 ActionItem。sourceKind=raw_feedback 和 sourceFeedbackIds,UI 必须显式标注“原始反馈行动”,并与 AI 洞察行动区分;其验证指标和后续洞察归因单独处理。在 ai-voc-insight.component.html 当前洞察卡片上增加一个明确的“决策区”,不把“生成完成”当作“已确认”:
证据覆盖率、输入证据数、已审阅证据数、运行模式和当前决策状态。确认洞察、驳回、需要补证据 才可提交。needs_validation、deterministic 或低覆盖率洞察只显示“需要补证据”;确认后才显示“创建正式行动”。sourceDecisionId 读取来源;二次提交返回既有行动时,UI 显示“已存在行动”,不再创建第二条。reviewId 回跳。raw_feedback 或 data_quality 类型。createdActionIds 内存集合,避免刷新后重复创建。AI 洞察、原始反馈、规则行动。GET /workspaces/:workspaceId/actions 读取,支持状态、优先级、负责人、到期日、来源分析筛选。ActionItem -> InsightDecision -> Insight -> AnalysisRun -> Evidence。PATCH /actions/:id,完成时若没有验证记录,状态显示“待验证”而不是“问题已解决”。DomesticAnalyticsAdapterService.actions() 保留为规则建议来源,迁移期用标签区分,不与 SaaS ActionItem 混在同一个完成计数中。partial + needs_validation,并沿用人审门槛。| 指标 | 目标 | 口径 |
|---|---|---|
| Evidence precision | >= 99% | 洞察引用 ID 中属于本次输入的比例;服务端拒绝未知 ID |
| Evidence coverage correctness | 100% | 存储 coverage 与去重引用数/输入数一致 |
| Decision traceability | >= 99% | 正式行动能找到决策、洞察、分析运行和至少 1 条证据 |
| Unconfirmed action leakage | 0 | 未确认洞察不得创建正式行动 |
| Duplicate action rate | < 1% | 相同 creationKey 的重复创建数/创建请求数 |
| UI recoverability | 100% | 刷新、重新登录、历史恢复后决策和来源仍可见 |
验收用例:
evidenceId、跨 analysis 的 evidenceId、空证据数组,API 返回 4xx 且数据库无脏结果。needs_more_evidence 后只能创建补证据任务。creationKey 对应的 ActionItem。目标:让洞察成为可版本化的业务资产,让行动完成后能产生下一轮分析的事实输入。
InsightRecord新增独立洞察实体,AnalysisRun 只保留计算运行:
| 字段 | 含义 |
|---|---|
publicId/workspaceId |
洞察资产和权限边界 |
insightKey |
稳定主题键,由 taxonomy + product/category + normalized topic 组成 |
version |
同一 insightKey 的递增版本 |
sourceAnalysisId |
产生该版本的运行 |
status |
draft/confirmed/published/archived |
title/finding/userNeed/recommendation |
可编辑业务内容 |
evidenceIds/evidenceCoverage |
版本快照,随源数据刷新时保持不变 |
ownerUserId/publishedBy/publishedAt |
运营责任和发布审计 |
supersedesId/archiveReason |
版本链和归档原因 |
ActionValidation新增 voc.action_validation(Parse 对应 VocActionValidation):
publicId, workspaceId, actionId, metricKey, baselineValue,
targetValue, observationWindowStart, observationWindowEnd,
observedValue, verdict, notMeasuredReason, notes,
verifiedBy, verifiedAt, createdAt, updatedAt
verdict:effective | partially_effective | ineffective | not_measured。当 not_measured 时 notMeasuredReason 必填;行动只有在验证记录提交后才显示“已验证完成”。
FeedbackEvidence统一反馈登记表/registry,至少包含:稳定内部 ID、来源平台/渠道、原始来源 ID、产品/类别、正文哈希、时间戳、情感/主题版本、去重键、快照批次、可见性和数据质量状态。原始正文与脱敏正文分开保存,AI 只拿到最小必要字段。
Evidence / Decision / Actions / Validation / Versions 五个页签。ineffective 或 partially_effective 时,系统生成复盘草稿和下一轮补证据问题,不自动创建新的产品行动。| 指标 | 目标 |
|---|---|
| Published insight provenance | 100% |
| Version overwrite | 0 |
| Action validation completion | >= 80% of completed actions within due window |
| Verified action rate | >= 70% of completed actions |
| Feedback-to-insight reuse | >= 60% of published insights can list their evidence snapshot |
| Trend explanation grounding | >= 95% of explanations contain valid evidence/metric references |
验收:发布 v1 后编辑产生 v2,v1 仍可恢复;行动完成但没有验证记录时,系统拒绝标记“已解决”或强制进入待验证;提交验证后能在洞察详情显示结果,并能作为下一次 AnalysisRun.input 的统计来源。
目标:在 P0/P1 数据可信和闭环可回流后,降低重复分析成本并让 AI 升级可量化。
AiEvaluationRun:记录 golden set、模型、提示词版本、schema pass rate、evidence precision、decision agreement、latency、token/cost、fallback rate。TopicMergeSplit:保存主题合并/拆分操作、操作者、旧 key、新 key 和生效时间,维护跨周期主题记忆。ReportDelivery:记录周报版本、收件范围、引用的 insight/action/validation ID 和发送结果,不保存无来源的自由生成结论。| 指标 | 目标 |
|---|---|
| Golden set schema pass rate | >= 99% |
| Evidence precision | >= 99.5% |
| Human decision agreement | >= 85% |
| AI fallback rate | < 10%,异常期可单独告警 |
| Median insight latency | < 15s for configured sample window |
| Duplicate topic review load | 下降 >= 30% |
| Weekly report citation coverage | 100% |
验收:同一 golden set 上比较模型/提示词版本,报告可重现;任一 evidence precision 或 schema pass rate 低于门槛时,版本保持非 production;周报中的每条重要结论至少能跳到一个洞察和一条原始证据。
InsightDecision 的 domain、repository、Parse/Postgres migration、routes、audit 和测试。ActionItem 的 sourceDecisionId/sourceKind/creationKey,实现服务端决策门禁和幂等。PATCH analysis 终态写入前加入 schema + evidence subset + coverage validator。schema_migration 已应用 003_action_item_insight_source.sql、004_action_item_source_integrity.sql;未确认前不把 Postgres 视为已验收。raw_feedback 类型。SaasPlatformService.actions(),支持列表、详情、状态更新和来源回跳。InsightRecord 版本化和发布/归档页面。ActionValidation 表单、接口、查询和验证结果回流。依赖规则:P0 的决策门禁、服务端 grounding 和 Action API 接通完成前,不做自动发布、自动创建行动、自动发送周报或无引用的对话式推荐。
confirmed/rejected/needs_more_evidence 决策,含人员、时间、理由和已阅证据。completed 只代表计算结束,不代表洞察成立;confirmed 才是正式行动入口。raw_feedback,并独立归因。src/modules/ai-voc-insight/ai-voc-insight.component.ts、ai-voc-insight.component.html、ai-voc-insight.service.ts、ai-voc-insight.models.tssrc/modules/feedback-inbox/feedback-inbox.component.ts、feedback-inbox.component.html、feedback-inbox.models.tssrc/modules/shared/components/action-create-panel/action-create-panel.component.ts、action-create-panel.component.htmlsrc/app/core/services/saas-platform.service.tssrc/modules/domestic-voc/framework/domestic-action-workbench.component.ts、domestic-action-workbench.component.html、src/app/core/services/domestic-analytics-adapter.service.tssrc/modules/saas-platform/domain.ts、src/modules/saas-platform/routes.tssrc/modules/saas-platform/local-platform.repository.ts、parse-rest-voc.repository.ts、postgres-platform.repository.tsmigrations/002_saas_platform.sql、migrations/003_action_item_insight_source.sql、migrations/004_action_item_source_integrity.sqlsrc/db/migrations.tsdocs/AI-VOC-INSIGHT-LIFECYCLE.md