373 lines
12 KiB
Markdown
373 lines
12 KiB
Markdown
# 小宝预警设计规格
|
||
|
||
日期：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 的输入、输出、权限和失败回退。
|