Saas-voc/docs/AI-VOC-INSIGHT-LIFECYCLE.md

AI VOC 洞察生命周期审计

审计范围：E:\workspace\Saas-voc 前端与 E:\workspace\server\saas-voc-server 后端。 审计对象：反馈收件箱、AI VOC 洞察、行动创建面板、SaasPlatformService、后端 AnalysisRun / Action 路由与本地仓储。 审计时间：2026-08-06

1. 结论摘要

当前系统已经形成一条可运行的 VOC 工作流：

真实评价
  -> 证据准备与筛选
  -> AI 结构化洞察 / deterministic 规则摘要
  -> 用户查看原始证据并提交行动表单
  -> ActionItem 进入行动中心

其中，证据回跳、证据 ID 校验、needs_validation 标记、AnalysisRun 持久化状态和 Action 创建审计已经具备。当前的“人工确认”由用户查看洞察后主动打开并提交“创建行动项”面板来体现，但还不是一个可查询、可审计、可阻断后续动作的独立业务状态。

因此当前实现适合表达“生成结果并由人决定是否转行动”，还不适合表达完整的“洞察发布、行动执行、效果验证、结果回流”闭环。

2. 当前已实现的证据到行动链路

2.1 证据进入分析上下文

ai-voc-insight 通过 AiVocInsightService.prepare(...) 对数据集中的有效评价进行准备：

• 按本品、竞品或全部范围筛选；
• 按负向、中性或正向倾向筛选；
• 按样本上限截取输入；
• 为每条评价生成稳定的证据 ID，并保留评价正文、商品、来源、评分、日期和主题；
• 生成样本量、来源分布、情感分布和主题分布，作为分析输入审计信息。

feedback-inbox 提供同一类评价的队列和详情视图。详情页保留原始评价正文、主题判断、同类样本量、来源类型、置信表达和处理建议；证据链接通过 reviewId 回到收件箱详情。

2.2 AnalysisRun 记录生成过程

点击生成后，前端先调用：

POST /workspaces/:workspaceId/analyses

请求类型为 analysisType: voc_insight，目标为当前 workspace，并把筛选条件、输入证据 ID、主题统计、样本数和来源/情感统计写入 input。后端创建记录时状态为 pending，接口返回 202。

随后前端用：

PATCH /workspaces/:workspaceId/analyses/:id

把运行推进到 processing，生成结束后再写入 result、evidenceCount、终态和时间戳。后端上下文能力明确声明 analysisExecution: false，所以当前 AnalysisRun 是生成过程的持久化记录，实际 AI 执行仍由前端调用 AI 网关完成。

2.3 AI 结果形成结构化洞察

AI 输入携带 evidenceId，提示约束要求每条洞察引用输入中的真实 ID，并输出：

• 发现、用户未满足需求和建议动作；
• 严重程度、置信度和机会状态；
• evidenceIds、evidenceCount 和验证指标；
• 风险与后续追问。

AI 返回结果会再次解析和归一化：未知证据 ID 会被过滤，没有有效证据引用的洞察会被丢弃；如果没有可验证洞察、请求超时或网关异常，则从同一输入生成 deterministic 规则摘要并明确标记为待验证。前端展示引用数量和每个证据 ID，并可跳回 feedback-inbox 查看原始评价。

2.4 人工确认与行动创建

当前 UI 的人工决策路径是：

1. 用户在洞察卡片中查看发现、用户需求、机会状态、风险、验证指标和引用证据；
2. 用户点击“创建行动项”，打开 action-create-panel；
3. 面板预填洞察标题和描述，描述包含洞察发现、建议动作、验证指标和 AI 路径的证据 ID；
4. 用户可以修改标题、描述、优先级、负责人和截止日期；

5. 用户提交表单后调用：

   POST /workspaces/:workspaceId/actions
   

6. 后端要求 action:write 权限，校验负责人是 workspace 内的 active 成员，创建 ActionItem，初始状态默认为 open，并记录 action.created 审计事件。

feedback-inbox 也能从单条反馈直接创建行动草稿，并把原始反馈和主题上下文带入面板。前端用本地 createdActionIds 防止当前页面重复点击，但该集合不是后端关联关系。

需要特别区分：页面文案中的“已确认”与正式确认状态不是同一件事。当前没有 confirmedBy、confirmedAt、确认意见或洞察决策接口；用户提交 ActionItem 可以视作一次显式的人为转行动决定，但这次决定没有作为独立记录保存。

3. AnalysisRun 状态语义

后端 AnalysisRun 的状态转移和字段约束如下：

状态	语义	当前进入方式	关键约束
pending	请求已创建，等待生成开始	POST /analyses 创建后的初始状态	没有结果，未开始处理
processing	生成正在进行	前端 PATCH 状态；若未提供 startedAt，后端自动补时间	只能从 pending 进入；前端负责实际生成
completed	AI 结果完整完成	AI 结果成功解析并写入	必须有 result；终态不可再次 PATCH
partial	有结果但需要人工复核，当前主要用于 deterministic fallback	规则摘要写入结果	必须有 result；终态不可再次 PATCH
failed	本次生成没有可用结果	AI 请求、解析或持久化流程报告失败	必须有非空 errorSummary；终态不可再次 PATCH
cancelled	运行被取消	后端允许从 pending 或 processing 取消	当前没有前端取消控件；终态不可再次 PATCH

允许的状态转移是：

pending    -> processing | cancelled | failed
processing -> completed | partial | failed | cancelled
completed  -> terminal
partial    -> terminal
failed     -> terminal
cancelled  -> terminal

后端还会自动补齐：进入 processing 时的 startedAt，以及进入任意终态时的 completedAt。GET 列表支持按状态筛选和游标分页；前端只恢复 voc_insight、当前 workspace 且状态为 completed 或 partial 并且有结果的运行。

当前 local-platform.repository 使用进程内数组保存 AnalysisRun 和 ActionItem，服务重启后记录会丢失；Parse REST / Postgres 仓储具备持久化实现。该差异必须在本地演示和验收环境中明确标注。

4. AI 与 deterministic fallback 的区别

AI 模式

• AI 网关状态为已配置时，由 AiVocInsightService.generate(...) 调用 AiAnalysisService.streamAnalysis(...)；
• 输出要求为结构化 JSON，并经过 JSON 提取、字段归一化和证据 ID 校验；
• 结果 mode 为 ai，前端将 AnalysisRun 写成 completed；
• AI 可以输出 supported、partially_supported、needs_validation 或 not_supported，但最终仍需人工判断；
• 生成内容只能把当前输入评价当作事实证据，不得凭空补充销量、金额、比例或原话。

deterministic fallback 模式

当 AI 网关未配置，或 AI 请求、解析发生异常时，系统按固定主题规则聚合当前证据：

• 以主题分组并生成规则摘要；
• 每条摘要保留可回溯的证据 ID；
• 所有机会状态设为 needs_validation；
• 同时给出样本外推风险和后续补证问题；
• 结果 mode 为 deterministic，前端将 AnalysisRun 写成 partial，并提示人工复核后再转行动。

deterministic fallback 是可解释的可用性降级，属于规则层信号；主题命中仍需人工复核，尚不足以表达总体问题率或已确认机会。

5. 三条业务不变量

以下三条不变量是当前链路必须保持的业务契约。现状中的“已实现”与“仍需补强”分别列出，避免把 UI 行为误当成后端保证。

不变量一：证据 ID 必须可回溯

规则： 每条洞察的 evidenceIds 必须是本次分析上下文 evidence[].id 的子集；每个引用都能回到反馈收件箱的原始评价；evidenceCount 和覆盖率只能基于实际引用 ID 计算。

现状： AI 提示词要求真实 ID，结果归一化会过滤未知 ID，并丢弃没有有效引用的洞察；规则摘要也保留真实 ID。前端提供引用链接和证据回跳。

缺口： ActionItem 没有 analysisId、insightId 或 evidenceIds 字段。AI 创建行动时证据 ID 会进入描述文本，收件箱直接创建行动时主要带入原始反馈文本，因此数据库层还没有强引用约束。

不变量二：needs_validation 与已确认机会保持区分

规则： 样本不足、规则降级、主题边界不确定或证据覆盖不足的洞察必须保持 needs_validation；此状态只触发补证、人工复核或带验证指标的草稿，正式发布前需要显式确认。

现状： deterministic 结果统一使用 needs_validation；AI 缺失或非法机会状态时归一化默认使用 needs_validation；结果页展示“待验证”标签和验证指标。

缺口： 当前 openAction(...) 没有根据 opportunityStatus 阻断操作，用户仍可以直接为 needs_validation 洞察创建 ActionItem；后端也没有对结果内容或样本阈值做服务端校验。

不变量三：行动前必须有可审计的人工确认

规则： 只有用户查看了证据并明确确认洞察成立、确认验证目标和行动责任后，才允许创建可执行行动；确认人、时间、决策和意见必须可查询，并写入审计。

现状： 创建行动前必须经过用户点击和表单提交；后端用 action:write 权限保护创建接口，并记录 action.created。这能阻止纯展示状态自动创建行动。

缺口： 当前没有独立的确认 API 或确认字段，尚未区分“确认”“驳回”“需要补充证据”；也缺少用户完成证据审阅的可验证记录。行动创建本身是隐式确认，且对 needs_validation 没有统一阻断。

6. 尚缺的闭环能力

6.1 行动效果回流

当前 ActionItem 只有执行状态、负责人、优先级、截止时间和完成时间，没有以下对象或字段：

• 关联的 analysisRunId、insightId、evidenceIds；
• 行动目标、验证指标、基线值、目标值和观测窗口；
• 执行后的观测值、效果结论、验证人和验证时间；
• “有效、部分有效、无效、未测量”等效果状态；
• 从效果结果回写洞察置信度、机会状态或下一轮 AnalysisRun 的机制。

所以当前链路止于“行动已创建/执行状态变化”，还没有“行动是否解决了用户问题”的证据闭环。

6.2 洞察发布生命周期

AnalysisRun 的 completed / partial 是计算运行状态，不是洞察的业务发布状态。当前不存在独立 Insight 实体或版本对象，也没有：

draft -> confirmed -> published -> archived

所需的发布人、发布时间、版本号、确认意见、归档原因、回滚关系和跨页面可见性策略。当前历史列表只能恢复有结果的 AnalysisRun，尚未表达某条洞察是否已被正式发布给产品、运营或管理层。

7. 下一轮验收标准

P0：形成可审计、可阻断的闭环

1. 洞察与证据强关联

   • Given 一次 voc_insight AnalysisRun，When 结果保存，Then 每条洞察只能引用该运行输入中的证据 ID，服务端拒绝未知 ID、空引用和跨运行引用。
   • Given 从洞察创建行动，Then ActionItem 至少保存 analysisRunId、insightId 和去重后的 evidenceIds，页面仍可从行动跳回原始评价。

2. 人工确认成为显式门槛

   • Given 洞察状态为 needs_validation 或 deterministic fallback，When 用户未提交确认，Then创建行动请求被 UI 和 API 双重阻断。
   • Given 用户完成证据审阅，Then可提交 confirmed、rejected 或 needs_more_evidence 决策，并保存 confirmedBy、confirmedAt、确认说明及审计事件。
   • Given 洞察已经确认，Then 创建行动必须携带确认记录 ID；确认记录不可被静默覆盖。

3. AnalysisRun 执行契约稳定

   • Given 同一生成请求发生刷新、重试或网络延迟，Then 应保持单一有效运行和单次终态写入；运行完成后只允许一次终态提交。
   • Given AI 成功，Then状态为 completed 且 result 可恢复；Given deterministic fallback，Then状态为 partial 且结果中明确 mode: deterministic 和 needs_validation。
   • Given 生成失败，Then状态为 failed 且有可读 errorSummary；终态之后的 PATCH 必须被拒绝。

4. 行动效果可回流

   • Given ActionItem 被标记完成，Then必须有验证指标、观测窗口和效果记录，或明确记录“未测量”的原因。
   • Given 效果记录提交，Then可以按行动、洞察、主题和时间范围查询，并生成下一轮分析的输入。

P1：建立洞察资产的发布与运营能力

1. 独立洞察发布生命周期

   • Given AnalysisRun 产生结果，Then生成一个带版本号的洞察草稿，而不是直接把运行结果当作发布资产。
   • Only confirmed 洞察可进入 published；已发布版本不可被原地覆盖，修改必须生成新版本。
   • Given 洞察归档，Then保留归档人、归档时间、原因和历史版本，并能恢复指定版本。

2. 历史、行动和效果一体化视图

   • 可按洞察查看证据、确认记录、关联行动、执行状态和效果结果；
   • 可按主题查看多次 AnalysisRun 的趋势，区分 AI、规则降级和人工修订版本；
   • 页面刷新、跨页面跳转和权限变化后，仍能恢复同一洞察上下文。

3. 质量与回归评估

   • 为证据引用正确率、needs_validation 识别率、人工确认通过率、行动完成率和效果回流完整率建立可重复测试；
   • AI 输出和 deterministic fallback 使用同一套 schema 校验、引用校验和审计断言；
   • 对低样本、无证据、未知证据 ID、网关超时、重复提交和终态修改建立自动化验收用例。

8. 审计依据

• 前端：src/modules/feedback-inbox/feedback-inbox.component.ts、feedback-inbox.component.html；
• 前端：src/modules/ai-voc-insight/ai-voc-insight.component.ts、ai-voc-insight.component.html、ai-voc-insight.service.ts、ai-voc-insight.models.ts；
• 前端：src/modules/shared/components/action-create-panel/action-create-panel.component.ts、action-create-panel.component.html；
• 前端：src/app/core/services/saas-platform.service.ts；
• 后端：src/modules/saas-platform/domain.ts、routes.ts、local-platform.repository.ts；
• 后端：src/modules/saas-platform/parse-rest-voc.repository.ts、postgres-platform.repository.ts 中 AnalysisRun / Action 的持久化实现。