feat(data-ana): 完整实现 data-ana 数据分析服务

包含 CDC consumer、analytics/mastery/warning service、grpc server、repository、ClickHouse DDL 等

scripts/clickhouse-init.sql

@@ -1,37 +1,89 @@
 -- ClickHouse 数据库初始化脚本
--- 适用服务：data-ana（数据分析）
--- 表结构：student_dashboard_view（学生学情宽表）/ student_errors（错题本）
--- 与 services/data-ana/src/data_ana/clickhouse_client.py 中的查询字段对齐
+-- 适用服务：data-ana（D6 智能洞察领域）
+-- 5 张宽表（ai-allocation §5 强制）：
+--   1. student_dashboard_view  学生学情宽表（成绩/班级/知识点维度）
+--   2. student_errors          学生错题本
+--   3. mastery_snapshot        知识点掌握度历史快照
+--   4. ai_usage_log            AI 用量计费记录（ai 服务投递，data-ana 消费）
+--   5. attendance_logs         学生考勤记录（core-edu attendance 表 CDC 同步）
+--
+-- 引擎对齐 02-architecture-design.md §3：ReplacingMergeTree 按 ORDER BY 去重 + version 列保留最新版本
+-- 查询规范：所有 SELECT 必须加 FINAL 或使用 argMax 聚合确保去重生效（P0 整改）
 --
 -- 使用方式（启用 ClickHouse 时执行一次）：
 --   clickhouse-client --multiquery < scripts/clickhouse-init.sql
--- 注意：ClickHouse 为可选依赖，未配置时 data-ana 服务进入降级模式。
+-- 注意：ClickHouse 为可选依赖，未配置时 data-ana 服务进入降级模式（返回骨架数据）。
 
 -- 数据库
 CREATE DATABASE IF NOT EXISTS edu_analytics;
 
--- 学生学情宽表（考试/班级/知识点维度）
+-- ===== 1. 学生学情宽表（成绩写入产生一行，按 ORDER BY 去重保留最新版本） =====
 CREATE TABLE IF NOT EXISTS edu_analytics.student_dashboard_view (
-  student_id String,
-  class_id String,
-  exam_id String,
-  subject_id String,
-  score Float64,
-  rank_in_class UInt32,
-  knowledge_point_id String,
-  mastery_level Float32,
-  error_count UInt32,
-  last_updated DateTime
-) ENGINE = MergeTree()
-ORDER BY (student_id, class_id, exam_id);
+    student_id         String,
+    class_id           String,
+    exam_id            String,
+    subject_id         String,
+    score              Float64,
+    rank_in_class      UInt32,
+    knowledge_point_id String,
+    mastery_level      Float32,            -- 0.0-1.0
+    error_count        UInt32,
+    last_updated       DateTime64(3, 'UTC')
+) ENGINE = ReplacingMergeTree(last_updated)
+PARTITION BY toYYYYMM(last_updated)
+ORDER BY (student_id, exam_id, knowledge_point_id)
+SETTINGS index_granularity = 8192;
 
--- 学生错题表（错题本）
+-- ===== 2. 学生错题本 =====
 CREATE TABLE IF NOT EXISTS edu_analytics.student_errors (
-  student_id String,
-  question_id String,
-  knowledge_point_id String,
-  error_count UInt32,
-  last_error_time DateTime,
-  content String
-) ENGINE = MergeTree()
-ORDER BY (student_id, knowledge_point_id);
+    student_id          String,
+    question_id         String,
+    knowledge_point_id  String,
+    error_count         UInt32,
+    last_error_time     DateTime64(3, 'UTC'),
+    content             String
+) ENGINE = ReplacingMergeTree(last_error_time)
+PARTITION BY toYYYYMM(last_error_time)
+ORDER BY (student_id, question_id);
+
+-- ===== 3. 掌握度历史快照（每次掌握度计算产生新版本，支持趋势查询） =====
+CREATE TABLE IF NOT EXISTS edu_analytics.mastery_snapshot (
+    student_id          String,
+    knowledge_point_id  String,
+    subject_id          String,
+    mastery_level       Float32,
+    calculated_at       DateTime64(3, 'UTC'),
+    calculation_method  LowCardinality(String)   -- 'weighted_moving_avg' / 'simple_avg' / 'forgetting_curve'
+) ENGINE = MergeTree
+PARTITION BY toYYYYMM(calculated_at)
+ORDER BY (student_id, knowledge_point_id, calculated_at);
+
+-- ===== 4. AI 用量计费记录（ai 服务通过 Kafka 事件投递，data-ana 消费落库） =====
+CREATE TABLE IF NOT EXISTS edu_analytics.ai_usage_log (
+    request_id          String,
+    user_id             String,
+    provider             LowCardinality(String),  -- 'openai' / 'anthropic' / 'baichuan' / 'local'
+    model                LowCardinality(String),
+    prompt_tokens        UInt32,
+    completion_tokens    UInt32,
+    total_tokens         UInt32,
+    latency_ms           UInt32,
+    success              Boolean,
+    cost_cents           UInt32,                  -- 计费（分），便于聚合
+    occurred_at          DateTime64(3, 'UTC')
+) ENGINE = ReplacingMergeTree(occurred_at)
+PARTITION BY toYYYYMM(occurred_at)
+ORDER BY (request_id);                            -- 按 request_id 幂等去重
+
+-- ===== 5. 学生考勤记录（core-edu attendance 表 CDC 同步） =====
+CREATE TABLE IF NOT EXISTS edu_analytics.attendance_logs (
+    student_id          String,
+    class_id            String,
+    attendance_date     Date,
+    status              LowCardinality(String),  -- 'present' / 'absent' / 'late' / 'leave'
+    recorded_by         String,                  -- 教师用户 ID
+    remark              String DEFAULT '',
+    occurred_at         DateTime64(3, 'UTC')
+) ENGINE = ReplacingMergeTree(occurred_at)
+PARTITION BY toYYYYMM(attendance_date)
+ORDER BY (student_id, class_id, attendance_date);