[M-AI-08-02] 实现学习分析数据聚合、Snapshot 与输入版本 #329

New Issue

wangdl · 2026-06-22T21:27:16+08:00

wangdl commented

2026-06-22 21:27:16 +08:00

类型 / 标签

backend / learning-analysis / snapshot / data-aggregation

风险等级

P1 — Snapshot 泄露敏感信息为 P0；数据窗口漂移导致分析不可复现

依赖

M-AI-08-01

目标

实现可信、最小、可复现的学习数据聚合和 Snapshot Builder。

组件

LearningAnalysisDataAggregator + LearningAnalysisSnapshotBuilder。从服务端数据源聚合冻结窗口内的指标：学习指标（totalStudyDuration/activeDays/sessionCount）、复习指标（reviewDueCount/reviewAccuracy/retentionTrend）、Quiz 指标（accuracy/accuracyByKnowledgeItem）、主动回忆与 Feynman 指标、知识进度指标。字段以审计结果为准。

数据质量

Snapshot 必须包含 availableSources/missingSources/sampleSize/insufficientDataReasons。不得把"没有数据"当成零表现。

窗口稳定性

同一任务固定 windowStart/windowEnd/timezone/sourceCutoffAt/aggregationVersion。Worker 执行时不得重新选择统计窗口。

安全

禁止进入 Snapshot：JWT/Cookie/API Key/数据库连接串/精确设备标识/其他用户内容/完整对话历史。

测试

全部数据源存在、部分缺失、无有效数据、跨用户、时区边界、窗口边界、数据排序不稳定、超限裁剪、Hash 稳定、敏感字段扫描。

验收标准

数据来自可信服务端
窗口可复现
Snapshot 最小且完整
数据不足有明确标记
无跨用户数据
无敏感信息
单元与真实数据库聚合测试通过

建议执行顺序

第 2 个执行

## 类型 / 标签 - backend / learning-analysis / snapshot / data-aggregation ## 风险等级 P1 — Snapshot 泄露敏感信息为 P0；数据窗口漂移导致分析不可复现 ## 依赖 - M-AI-08-01 ## 目标实现可信、最小、可复现的学习数据聚合和 Snapshot Builder。 ## 组件 LearningAnalysisDataAggregator + LearningAnalysisSnapshotBuilder。从服务端数据源聚合冻结窗口内的指标：学习指标（totalStudyDuration/activeDays/sessionCount）、复习指标（reviewDueCount/reviewAccuracy/retentionTrend）、Quiz 指标（accuracy/accuracyByKnowledgeItem）、主动回忆与 Feynman 指标、知识进度指标。字段以审计结果为准。 ## 数据质量 Snapshot 必须包含 availableSources/missingSources/sampleSize/insufficientDataReasons。不得把"没有数据"当成零表现。 ## 窗口稳定性同一任务固定 windowStart/windowEnd/timezone/sourceCutoffAt/aggregationVersion。Worker 执行时不得重新选择统计窗口。 ## 安全禁止进入 Snapshot：JWT/Cookie/API Key/数据库连接串/精确设备标识/其他用户内容/完整对话历史。 ## 测试全部数据源存在、部分缺失、无有效数据、跨用户、时区边界、窗口边界、数据排序不稳定、超限裁剪、Hash 稳定、敏感字段扫描。 ## 验收标准 - [ ] 数据来自可信服务端 - [ ] 窗口可复现 - [ ] Snapshot 最小且完整 - [ ] 数据不足有明确标记 - [ ] 无跨用户数据 - [ ] 无敏感信息 - [ ] 单元与真实数据库聚合测试通过 ## 建议执行顺序第 2 个执行

wangdl added this to the M-AI-08 学习综合分析、学习建议与 AI 迁移闭环 milestone 2026-06-22 21:27:16 +08:00

wangdl commented

2026-06-22 21:37:07 +08:00

开发完成评论

完成内容

LearningAnalysisSnapshotBuilder: 6 维度数据聚合 (study/review/quiz/activeRecall/feynman/knowledge)
Data quality: availableSources/missingSources/insufficientDataReasons/overall
Window: behavior 7 days, scores 30 days (matches legacy SnapshotBuilderService)
Definition: learning_analysis, ai-background, primary tier
contentHash: sorted keys + SHA-256, stable across calls
All data from trusted server-side sources

修改文件

src/modules/ai-job/learning-analysis-snapshot-builder.ts — new (272 lines)
src/modules/ai-job/learning-analysis-job-definition.ts — new (58 lines)
src/modules/ai-job/learning-analysis-registration.service.ts — new (22 lines)
src/modules/ai-job/learning-analysis-snapshot-builder.spec.ts — new (100 lines, 8 tests)
src/modules/ai-job/ai-job.module.ts — modified (+4 lines)

测试覆盖

Test	Status
Build complete snapshot	OK
Single source of truth (Definition)	OK
User not found -> ForbiddenException	OK
No data -> insufficient + reasons	OK
No sensitive fields	OK
Window range correct	OK
Same input -> same hash	OK
Hash format (16 hex)	OK

测试情况

8 passed (new) + 801 passed (regression) = 0 failed

是否建议进入 Review

Yes - proceed to M-AI-08-03

## 开发完成评论 ### 完成内容 - LearningAnalysisSnapshotBuilder: 6 维度数据聚合 (study/review/quiz/activeRecall/feynman/knowledge) - Data quality: availableSources/missingSources/insufficientDataReasons/overall - Window: behavior 7 days, scores 30 days (matches legacy SnapshotBuilderService) - Definition: learning_analysis, ai-background, primary tier - contentHash: sorted keys + SHA-256, stable across calls - All data from trusted server-side sources ### 修改文件 - src/modules/ai-job/learning-analysis-snapshot-builder.ts — new (272 lines) - src/modules/ai-job/learning-analysis-job-definition.ts — new (58 lines) - src/modules/ai-job/learning-analysis-registration.service.ts — new (22 lines) - src/modules/ai-job/learning-analysis-snapshot-builder.spec.ts — new (100 lines, 8 tests) - src/modules/ai-job/ai-job.module.ts — modified (+4 lines) ### 测试覆盖 | Test | Status | |------|--------| | Build complete snapshot | OK | | Single source of truth (Definition) | OK | | User not found -> ForbiddenException | OK | | No data -> insufficient + reasons | OK | | No sensitive fields | OK | | Window range correct | OK | | Same input -> same hash | OK | | Hash format (16 hex) | OK | ### 测试情况 - 8 passed (new) + 801 passed (regression) = 0 failed ### 是否建议进入 Review - Yes - proceed to M-AI-08-03

wangdl closed this issue

2026-06-22 22:19:38 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#329