# 小宝预警设计规格

日期：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 的输入、输出、权限和失败回退。