docs(小宝预警): 增加设计规格

2026-06-29 16:34:26 +08:00
parent 7f24e16491
commit 5a41904ba6
1 changed files with 372 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-29-xiaobao-warning-design.md
+++ b/docs/superpowers/specs/2026-06-29-xiaobao-warning-design.md
@@ -0,0 +1,372 @@
+# 小宝预警设计规格
+
+日期：2026-06-29
+
+## 背景
+
+小宝预警是版本级项目风险预警能力，目标是帮助项目管理人员和版本成员提前判断版本是否能按期发版。如果不能按期发版，需要说明原因、预计延期到多久、建议什么时间点发版，以及当前风险是在变好还是变坏。
+
+本功能与现有健康度不同。现有健康度更偏当前状态评分；小宝预警需要覆盖发版预测、风险趋势、静默风险、AI 解读和日报证据。
+
+## 目标
+
+- 在主导航工作区中增加“小宝预警”，位置在“与我相关”上方。
+- 管理人员可以查看所有版本预警；非管理人员只能查看自己作为版本成员参与的版本预警。
+- 以规则引擎为主，稳定计算风险分、风险等级、预计可发日期、延期天数、风险原因、趋势和置信度。
+- 当风险达到触发条件时，自动生成 AI 解读，不要求用户手动点击按钮。
+- 将日报和工作活动数据纳入风险证据，避免只看任务状态。
+- 支持静默风险，识别长期无更新、无日报、无活动、无人处理的版本。
+
+## 非目标
+
+- 不在第一版实现独立后台定时 Agent 编排。
+- 不让 AI 自动修改版本截止日期、任务状态、成员或任何业务实体。
+- 不用 AI 直接替代规则判断；AI 只解释规则结果和证据。
+- 不把小宝预警塞入 `/workspace` 页面内部，而是作为独立页面。
+
+## 导航和权限
+
+新增导航项：
+
+```ts
+工作区
+- 小宝预警
+- 与我相关
+- 产品
+- 项目
+- 版本
+- 需求池
+- 加班记录
+```
+
+路径：
+
+```ts
+/xiaobao-warning
+```
+
+新增权限组“小宝预警”：
+
+```ts
+xiaobao.warning:view
+xiaobao.warning:manage
+```
+
+可见范围：
+
+- 有 `xiaobao.warning:manage`：查看所有未结束版本预警。
+- 只有 `xiaobao.warning:view`：只查看 `version.members` 中包含当前用户的版本预警。
+- 没有 `xiaobao.warning:view`：不显示“小宝预警”导航。
+
+默认角色：
+
+- 超级管理员：`*`
+- 产品经理：`xiaobao.warning:view` + `xiaobao.warning:manage`
+- 开发工程师：`xiaobao.warning:view`
+- 测试工程师：`xiaobao.warning:view`
+- 设计师：`xiaobao.warning:view`
+
+已有角色数据已持久化在 `members` AppData key 中。新增权限时，需要在成员 store 读取旧角色时为系统预置角色补齐新权限，避免老数据中的产品经理无法看到小宝预警。
+
+## 分析范围
+
+小宝预警只分析未结束版本：
+
+```ts
+planned
+developing
+paused
+```
+
+不分析：
+
+```ts
+released
+closed
+```
+
+版本来源使用产品概览中的版本树。开发任务通过需求的 `versionId` 归属到版本，测试用例和 Bug 直接通过 `versionId` 归属到版本，计划任务通过 `versionId` 归属到版本。
+
+## 风险模型
+
+新增独立风险分 `riskScore`，范围 0-100，数值越高表示风险越高。它不复用现有健康度分，避免“健康度高是好、风险分高是坏”的语义混淆。
+
+等级：
+
+```ts
+on_track        // 风险低，可按期
+attention       // 需要关注，但暂未预测延期
+at_risk         // 有明显延期风险
+likely_delayed  // 预计会延期
+blocked         // 当前不具备发版条件
+```
+
+核心输出：
+
+```ts
+interface XiaobaoVersionRisk {
+  versionId: string;
+  riskScore: number;
+  riskLevel: 'on_track' | 'attention' | 'at_risk' | 'likely_delayed' | 'blocked';
+  expectedReleaseDate?: string;
+  forecastReleaseDate?: string;
+  delayDays: number;
+  confidence: number;
+  confidenceLevel: 'low' | 'medium' | 'high';
+  reasons: RiskReason[];
+  silentRisks: SilentRisk[];
+  trend: RiskTrend;
+  dailyEvidence: VersionDailyEvidence;
+  aiInsight?: XiaobaoRiskInsight;
+}
+```
+
+## 预测依据
+
+风险引擎输入：
+
+- Version：状态、开始日期、期望发版日期、当前阶段、成员。
+- VersionPlan：调研、产品方案、UI 计划状态、计划结束时间、实际开始和完成时间、超期原因。
+- Requirement：当前版本关联需求范围。
+- DevTask：状态、阻塞、预计开始和截止、执行预估、AI 预估、实际开始和结束。
+- TestCase：轮次、状态、计划测试时间、执行预估、AI 预估、失败和阻塞原因。
+- Bug：状态、严重程度、计划修复时间、执行预估、AI 预估、修复和关闭时间。
+- WorkActivity：今日和最近工作日的交付、推进、新增、风险、进展说明。
+- TaskWorklog：日报和手工进展说明。
+- 工作日历：复用中国工作日历和 `addWorkHours` 推算预计完成时间。
+
+剩余工作量估算：
+
+- DevTask：按状态进度扣减剩余工时，`todo=100%`、`in_progress=50%`、`testing=20%`、`submitted=0%`。
+- TestCase：未执行、执行中、阻塞的用例计入剩余测试工作量。
+- Bug：未关闭 Bug 计入剩余修复工作量。缺少估时时按严重程度给兜底值。
+- VersionPlan：未完成计划若计划截止晚于版本截止，计入计划风险；若已经实际进行中但长期无更新，计入静默风险。
+
+预计可发日期：
+
+```ts
+forecastReleaseDate = addWorkHours(now, remainingWorkHours)
+```
+
+如果 `forecastReleaseDate` 晚于 `expectedReleaseDate`，计算 `delayDays` 并提高风险等级。
+
+## AI 自动触发
+
+AI 解读不通过按钮手动触发，而是在风险触发后自动生成。
+
+不触发：
+
+- `on_track`
+
+默认不触发，仅展示规则摘要：
+
+- `attention`
+
+但 `attention` 出现明显风险变化时也触发 AI。
+
+自动触发：
+
+- `at_risk`
+- `likely_delayed`
+- `blocked`
+
+额外触发条件：
+
+- `riskScoreDelta >= 15`
+- `forecastReleaseDate` 较上次延后至少 1 个工作日
+- P1/P2 Bug 数增加
+- 测试失败数增加
+- 阻塞项新增
+- 距离期望发版日期小于等于 1 天且仍有未完成项
+- 静默风险新出现
+- `confidence` 明显下降
+
+AI 输入必须是压缩后的事实和证据，不传整页 UI 状态。
+
+AI 输出：
+
+```ts
+interface XiaobaoRiskInsight {
+  summary: string;
+  why: string[];
+  forecast: string;
+  recommendedReleaseWindow?: string;
+  suggestedActions: string[];
+  ownerHints: string[];
+  generatedAt: string;
+}
+```
+
+AI 不写业务实体，只写预警解读缓存。
+
+## AI 解读缓存
+
+新增 AppData key：
+
+```ts
+xiaobao-risk-insights
+```
+
+缓存结构：
+
+```ts
+interface XiaobaoRiskInsightCacheItem {
+  versionId: string;
+  riskSignature: string;
+  insight: XiaobaoRiskInsight;
+  generatedAt: string;
+  providerInfo?: {
+    providerId?: string;
+    model?: string;
+  };
+}
+```
+
+`riskSignature` 根据版本风险输入生成。签名未变化时复用缓存，签名变化时重新生成 AI 解读，避免管理人员打开全量版本时重复消耗 token。
+
+## 风险趋势
+
+新增 AppData key：
+
+```ts
+xiaobao-risk-snapshots
+```
+
+每次生成风险时记录快照：
+
+```ts
+interface XiaobaoRiskSnapshot {
+  versionId: string;
+  date: string;
+  riskScore: number;
+  riskLevel: XiaobaoRiskLevel;
+  forecastReleaseDate?: string;
+  openBugCount: number;
+  failedTestCount: number;
+  blockedCount: number;
+  silentRiskCount: number;
+  confidence: number;
+  createdAt: string;
+}
+```
+
+页面展示最近 7 天趋势：
+
+- 当前风险分。
+- 较昨日变化。
+- 连续上升、连续下降、基本稳定等趋势文案。
+- AI 解读需要读取趋势摘要，解释风险是在变坏还是变好。
+
+第一版在用户打开小宝预警页面时写入当天快照。后续若需要更可靠的无人访问场景趋势，可升级为服务端定时快照，但这不是第一版硬要求。
+
+## 静默风险
+
+静默风险作为独立风险因子进入 `riskScore`，也可以触发 AI 解读。
+
+默认阈值：
+
+```ts
+noUpdateDays >= 5      // 5 天无更新
+noReportDays >= 8      // 8 天无日报
+noActivityDays >= 4    // 4 天无活动
+unhandledDays >= 3     // 3 天无人处理
+```
+
+数据来源：
+
+- `work-activities` 判断版本是否有交付、推进、风险和进展说明。
+- `task-worklogs` 判断版本成员是否有日报。
+- DevTask/TestCase/Bug 的 `updatedAt` 判断是否长期无人处理。
+- 当前未完成项判断是否存在无人接手、阻塞未解除、Bug 未推进。
+
+静默风险不一定立即判定延期，但需要提高风险分，并在 AI 解读中说明“风险来自缺少可见推进证据”。
+
+## 置信度
+
+新增预测置信度 `confidence`，范围 0-100。它表达数据是否足以支撑预测，不表示 AI 主观自信。
+
+影响因素：
+
+- 是否设置期望发版日期。
+- 未完成 DevTask/TestCase/Bug 是否有估时。
+- 测试用例是否存在并覆盖当前版本。
+- Bug 是否有计划修复时间或估时。
+- 版本成员是否完整。
+- 最近是否有日报或工作活动。
+- 风险快照是否连续。
+- AI 解读缓存是否匹配当前风险签名。
+
+置信度等级：
+
+```ts
+low
+medium
+high
+```
+
+低置信度时，小宝需要提示：
+
+```text
+当前数据不足，预测仅供参考。建议补充估时、测试计划、Bug 修复计划或近期进展说明。
+```
+
+## 日报证据
+
+小宝预警不直接复用 `DailyReportPanel` 的展示结构，而是复用底层数据，按版本生成证据摘要：
+
+```ts
+interface VersionDailyEvidence {
+  todayDeliveries: EvidenceItem[];
+  todayProgress: EvidenceItem[];
+  todayRisks: EvidenceItem[];
+  progressNotes: EvidenceItem[];
+  needsProgressItems: EvidenceItem[];
+  recentActivityCount: number;
+  lastActivityAt?: string;
+}
+```
+
+默认纳入今天和最近 3 个工作日证据。这样可以避免某一天没有日报导致误判，也能发现连续多天无推进。
+
+## 页面交互
+
+小宝预警页面包含：
+
+- 顶部汇总：高风险版本数、预计延期版本数、阻塞版本数、低置信度版本数。
+- 筛选：产品、项目、风险等级、趋势、静默风险、低置信度。
+- 版本预警卡片：版本上下文、风险分、趋势、期望发版日期、预计可发日期、延期天数、AI 摘要。
+- 详情 Drawer：预测依据、日报证据、小宝建议、风险快照趋势。
+
+卡片点击进入 Drawer，不直接跳转离开页面。Drawer 中可提供跳转版本详情的入口。
+
+## 降级和错误处理
+
+- AI 配置不可用：仍展示规则预警，AI 区域显示“AI 解读暂不可用”。
+- AI 调用失败：保留规则结论，不写入 insight 缓存。
+- 风险数据不足：风险等级可为 `attention`，同时降低 `confidence`。
+- 快照缺失：趋势显示“暂无趋势”，不阻塞当前风险判断。
+- 日报证据为空：正常展示，并可能触发静默风险。
+- 管理人员版本很多：只对可见且触发条件满足的版本请求 AI 解读，并通过 `riskSignature` 去重。
+
+## 测试范围
+
+需要覆盖：
+
+- 权限过滤：管理人员全量、非管理人员仅版本成员、无权限不显示。
+- 风险分计算：开发剩余、测试失败、Bug 增加、阻塞、临近发版。
+- AI 触发：等级触发、`attention` 风险剧变触发、`on_track` 不触发。
+- 趋势：风险连续上升、下降、稳定。
+- 静默风险：无更新、无日报、无活动、无人处理。
+- 置信度：缺少截止日期、缺少估时、缺少日报、快照不连续。
+- AI 缓存：签名不变复用缓存，签名变化重新生成。
+- 日报证据：按版本聚合 `work-activities` 和 `task-worklogs`。
+
+## 文档影响
+
+实现时需要同步更新：
+
+- `docs/architecture.md`：新增小宝预警引擎、趋势快照和 AI 解读缓存。
+- `docs/decisions.md`：新增关于规则优先、AI 自动解读、风险趋势和静默风险的设计决策。
+- `docs/workflow.md`：补充小宝预警可见范围、AI 触发和日报证据工作流。
+- `docs/roadmap.md`：将 Risk Watch Agent 从规划项升级为小宝预警计划项。
+- `docs/agent-spec.md`：补充 Risk Watch Agent 的输入、输出、权限和失败回退。