4.0 KiB
4.0 KiB
V2.3 关系表写入与预计算闭环设计
背景
V2.2 已经完成分区关系表、迁移预演、读优化 API，以及版本详情、需求池、与我相关、小宝预警的快读接入。剩余风险在写路径：前端保存仍写入 AppData，如果关系表不同步，V2.2 快读数据会逐渐变旧，用户仍可能在大数据量下回落到完整 JSON 文档加载。
V2.3 的目标是在不改前端 Store 写入形状的前提下，把 AppData 保存后的稳定业务数据同步到关系表，并让小宝预警摘要进入可标脏、可预计算的状态。
范围
本阶段做：
- AppData 写入成功后触发关系表增量同步。
- 覆盖 V2.2 快读依赖的核心 key：
products-overview、members、task-categories、requirements、version-plans、dev-tasks、test-cases、bugs、work-activities、task-worklogs、overtime、xiaobao-risk-snapshots、xiaobao-risk-insights。 - 对会影响发版风险的变更标记
xiaobao_risk_summaries.dirty = true，并在已有快照数据存在时写入当前摘要。 - 增加轻量 API 响应耗时日志和 Prisma 慢查询日志。
- 保留 V2.2 读 API 和前端 fallback 机制。
本阶段不做：
- 不直接新增全量领域 CRUD 替代前端 AppData Store。
- 不引入 Redis、Elasticsearch、Prometheus 或 Grafana。
- 不把小宝完整规则引擎搬到后端；后端只维护快读摘要和 dirty 状态。
- 不做跨客户端字段级合并，AppData 乐观锁仍是当前并发边界。
架构
新增 AppDataV23SyncService，由 DataService.put() 在 AppData 成功写入之后调用。同步服务读取当前所有允许的 AppData key，复用 mapAppDataToV22Rows() 生成关系行，然后只同步本次 key 影响的表。
写入策略按数据形状分两类：
- 当前态表：按分区作用域先删后建，保证 AppData 删除的数据能从关系表消失。需求按
productId作用域；版本计划、开发任务、测试用例、BUG 按versionId作用域；产品、项目、版本、成员、任务类型按当前快照整体刷新。 - 证据/历史表：使用
createMany(skipDuplicates: true)写入追加记录，避免重复导入；已有历史不因 AppData 当前文档缺失而删除。
DataService.put() 的错误策略是 AppData 成功即返回成功。同步失败时记录错误日志，不回滚 AppData，不让用户保存动作卡死。原因是兼容窗口内 AppData 仍是写入事实源，V2.2 快读有 fallback 能兜底；把同步失败暴露为保存失败会造成更差的可用性。
小宝摘要
小宝摘要采用两层策略：
xiaobao-risk-snapshots保存时，从最新快照写入或更新xiaobao_risk_summaries，dirty=false。- 版本计划、开发任务、测试用例、BUG、工作活动、工时和加班变更时，找出受影响版本，标记对应摘要
dirty=true。如果摘要尚不存在，创建一条保守的attention摘要，提示前端关系表快读可用但需要重新计算。
摘要 summary 字段保留兼容形状：至少包含 versionId、riskLevel、riskScore、confidence、riskSignature、dirty、updatedAt。前端仍可继续使用 V2.2 映射层消费。
监控
轻量监控只写日志：
- 全局
ApiTimingInterceptor记录超过阈值的 HTTP 请求，默认阈值 1000ms，可用API_SLOW_REQUEST_MS调整。 PrismaService开启 query event，记录超过阈值的 SQL，默认阈值 300ms，可用PRISMA_SLOW_QUERY_MS调整。
这为后续接 Prometheus/Grafana 保留观测点，但 V2.3 不引入新基础设施。
测试策略
后端测试优先覆盖边界：
- AppData stale version 冲突不触发同步。
- AppData 写入成功后才触发同步。
- 同步失败只记录日志，不影响 AppData 响应。
- 需求同步按 product 分区作用域替换。
- 版本详情核心表按 version 分区作用域替换。
- 小宝快照能刷新摘要；任务/用例/BUG/计划变更能标脏摘要。
- API timing interceptor 只记录慢请求。
- Prisma 慢查询配置解析可测试。