# ai06 阶段 2 交付物：模块架构设计文档

> AI 标识：ai06
> 负责模块：data-ana（P4）、ai（P5）
> 阶段：架构设计外包 · 阶段 2（模块架构设计）
> 日期：2026-07-09
> 关联文档：[ai06 阶段 1 确认书](./ai06-phase1-understanding.md)、[ai-allocation.md](./ai-allocation.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[pending-features.md](./roadmap/pending-features.md)
> 审查请求：本设计文档待 coord 按 ai-allocation.md §8 交叉审查（接口一致性 / 端口冲突 / Topic 重复 / 错误码重叠 / 黄金模板对齐）

---

## 设计原则与全局约束

本设计遵循以下强制约束（来自 project_rules.md + coding-standards.md + 004）：

1. **契约先行**：proto 已定义（analytics.proto / ai.proto），实现前不修改 proto，如需修改走 coord 流程
2. **CQRS 读写分离**：data-ana 是纯读模型服务（无 MySQL 写），ClickHouse 宽表由 CDC 投影构建
3. **事件驱动**：data-ana 消费 CDC + 领域事件；ai 不参与事件流（无状态）
4. **gRPC 优先**：004 §4.1 明确 BFF → 业务服务走 gRPC，两服务需实现 gRPC server（HTTP 保留作 Gateway 直连降级）
5. **DataScope 过滤**：004 §5.3 DataScope 6 级在查询层注入 WHERE
6. **三支柱可观测**：structlog + prometheus-client + OpenTelemetry（已具备，需补业务指标）
7. **降级模式**：外部依赖（ClickHouse / LLM / 下游 gRPC）不可用时返回骨架数据 + `degraded: true`
8. **Python 规范**：pydantic-settings 配置 / Pydantic 模型校验 / async 优先 / 类型注解强制 / ruff 零错误

---

# 模块架构设计文档 — data-ana

## 1. 模块内部分层图

```mermaid
flowchart TB
    subgraph Entry["入口层"]
        HTTP[FastAPI HTTP Router<br/>/analytics/* + /healthz + /readyz]
        GRPC[grpc.aio Server<br/>AnalyticsService]
    end

    subgraph Middleware["中间件层"]
        AUTH[AuthDepends<br/>校验 x-user-id / x-user-roles]
        SCOPE[DataScopeDepends<br/>注入 data_scope 元数据]
        TRACE[OTel FastAPIInstrumentor<br/>+ grpc.aio server interceptor]
    end

    subgraph Service["应用服务层 Application Service"]
        S1[AnalyticsService<br/>班级/学生/趋势查询编排]
        S2[MasteryService<br/>掌握度计算 + 事件发布]
        S3[ErrorBookService<br/>错题本查询]
    end

    subgraph Repo["数据访问层 Repository"]
        R1[ClickHouseRepository<br/>宽表查询 + DataScope WHERE 注入]
        R2[KafkaProducer<br/>mastery.updated 事件发布]
        R3[IamClient<br/>gRPC 调 iam.getEffectiveDataScope]
    end

    subgraph Consumer["CDC 消费者（后台任务）"]
        C1[CdcConsumer<br/>aiokafka AIOKafkaConsumer]
        C2[ExamCache<br/>exam_id→class_id 内存映射]
        C3[EventHandler<br/>grades/exams/homework/classes 路由]
    end

    subgraph Storage["存储 / 总线"]
        CH[(ClickHouse<br/>edu_analytics 库)]
        KAFKA[(Kafka<br/>edu-cdc.* + edu.insight.mastery.updated)]
        IAM[iam:3002 gRPC]
    end

    HTTP --> AUTH --> SCOPE --> S1
    HTTP --> S3
    GRPC --> S1
    S1 --> R1
    S3 --> R1
    S2 --> R1
    S2 --> R2
    SCOPE --> R3
    R1 --> CH
    R2 --> KAFKA
    R3 --> IAM

    C1 --> C3
    C3 --> C2
    C3 --> R1
    C1 --> KAFKA
```

**分层规则**：

- **入口层**：HTTP（保留作 Gateway 直连降级）+ gRPC（主入口，BFF 调用）。两入口共享同一 Application Service
- **中间件层**：FastAPI Depends 链（`AuthDepends` → `DataScopeDepends`）；gRPC 用 server interceptor 注入身份元数据
- **应用服务层**：编排查询 / 计算掌握度 / 发布事件，不直接访问存储
- **数据访问层**：ClickHouse 查询封装 + Kafka producer + gRPC client（调 iam）
- **CDC 消费者**：独立后台任务（lifespan 启动），与 HTTP/gRPC 入口解耦

## 2. 领域模型

data-ana 是**纯读模型服务**，不持有写聚合根。领域模型为**视图聚合**（ClickHouse 物化）：

### 聚合根（视图型）

| 聚合根             | 含义             | 物化载体                                  | 不变式                                                        |
| ------------------ | ---------------- | ----------------------------------------- | ------------------------------------------------------------- |
| `StudentDashboard` | 学生学情宽表     | ClickHouse `student_dashboard_view`       | 同一 (student_id, exam_id, knowledge_point_id) 仅保留最新版本 |
| `ClassPerformance` | 班级成绩聚合     | ClickHouse 即时聚合（不物化）             | 聚合维度为 class_id + 时间窗                                  |
| `StudentErrorBook` | 学生错题本       | ClickHouse `student_errors`               | 同一 (student_id, question_id) 累计 error_count               |
| `MasterySnapshot`  | 知识点掌握度快照 | ClickHouse `mastery_snapshot`（**新增**） | 同一 (student_id, knowledge_point_id) 保留历史版本            |

### 值对象

- `WeakPoint`：knowledge_point_id + title + mastery_level
- `TrendPoint`：date + score
- `DataScope`：level (SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL) + scope_ids（具体可见的 class_id / grade_id 列表）

### 聚合间通信

- 同服务内：直接函数调用（Application Service → Repository）
- 跨服务：仅通过 Kafka 事件（发布 `mastery.updated`）+ gRPC（调 iam 查 DataScope）

## 3. 数据模型（ClickHouse DDL）

> DDL 文件由 coord 统一管理在 `infra/clickhouse/ddl/`（待 coord 建立），data-ana 提供内容。

### 3.1 宽表 `student_dashboard_view`

```sql
-- 学生学情宽表：每次成绩写入产生一行，按 ORDER BY 去重保留最新版本
CREATE TABLE IF NOT EXISTS 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,       -- 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;
```

**索引策略**：

- ORDER BY `(student_id, exam_id, knowledge_point_id)`：主键索引，支持按学生查学情、按考试查成绩、按知识点查掌握度
- PARTITION BY `toYYYYMM(last_updated)`：按月分区，支持历史数据归档
- ReplacingMergeTree(last_updated)：同 ORDER BY 自动去重，保留 last_updated 最大版本（幂等消费保证）

### 3.2 错题本 `student_errors`

```sql
CREATE TABLE IF NOT EXISTS student_errors
(
    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.3 掌握度快照 `mastery_snapshot`（**新增**）

```sql
-- 知识点掌握度历史快照：每次掌握度计算产生新版本，支持趋势查询
CREATE TABLE IF NOT EXISTS 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'
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(calculated_at)
ORDER BY (student_id, knowledge_point_id, calculated_at);
```

### 3.4 用量计费 `ai_usage_log`（**新增，供 ai 服务写入**）

```sql
-- AI 用量记录：ai 服务通过 Kafka 事件投递，data-ana 消费落库
CREATE TABLE IF NOT EXISTS 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,
    occurred_at         DateTime64(3, 'UTC')
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(occurred_at)
ORDER BY (user_id, occurred_at);
```

### 3.5 读写分离策略

| 操作           | 路径                                | 说明                                       |
| -------------- | ----------------------------------- | ------------------------------------------ |
| 学情查询       | ClickHouse 宽表                     | 实时聚合，亚秒级响应                       |
| 错题本查询     | ClickHouse student_errors           | 实时查询                                   |
| 掌握度趋势     | ClickHouse mastery_snapshot         | 历史快照                                   |
| 掌握度计算     | CDC 触发 → 内存计算 → 写 ClickHouse | 派生数据，非事务写                         |
| DataScope 解析 | gRPC 调 iam                         | 实时查询，结果 Redis 缓存 5min（004 §6.3） |

## 4. API 设计

### 4.1 HTTP 端点（保留作 Gateway 直连降级）

| method | path                                        | 权限                          | 请求                                             | 响应                                                  | 说明                             |
| ------ | ------------------------------------------- | ----------------------------- | ------------------------------------------------ | ----------------------------------------------------- | -------------------------------- |
| GET    | `/healthz`                                  | —                             | —                                                | `{status, service}`                                   | liveness                         |
| GET    | `/readyz`                                   | —                             | —                                                | `{status, ready, degraded, clickhouse, cdc_consumer}` | readiness                        |
| GET    | `/metrics`                                  | —                             | —                                                | Prometheus 格式                                       | 指标                             |
| GET    | `/analytics/class/{class_id}/performance`   | `ANALYTICS_CLASS_READ`        | query: `subject_id?`, `start_date?`, `end_date?` | `ClassPerformanceResponse`                            | 班级成绩分析                     |
| GET    | `/analytics/student/{student_id}/weakness`  | `ANALYTICS_STUDENT_READ`      | query: `subject_id?`                             | `StudentWeaknessResponse`                             | 学生薄弱知识点（DataScope 过滤） |
| GET    | `/analytics/student/{student_id}/errorbook` | `ANALYTICS_STUDENT_READ`      | query: `page?`, `size?`                          | `StudentErrorBookResponse`                            | 学生错题本（DataScope 过滤）     |
| GET    | `/analytics/student/{student_id}/trend`     | `ANALYTICS_STUDENT_READ`      | query: `start_date`, `end_date`, `subject_id?`   | `LearningTrendResponse`                               | 学习趋势（**新增**）             |
| GET    | `/analytics/dashboard/teacher/{user_id}`    | `ANALYTICS_TEACHER_DASHBOARD` | query: `class_id?`                               | `TeacherDashboardResponse`                            | 教师仪表盘聚合（**新增**）       |

### 4.2 gRPC 契约（analytics.proto，待实现 server）

| RPC                   | 请求                                                                     | 响应               | 权限                     |
| --------------------- | ------------------------------------------------------------------------ | ------------------ | ------------------------ |
| `GetClassPerformance` | `GetClassPerformanceRequest{class_id, subject_id, start_date, end_date}` | `ClassPerformance` | `ANALYTICS_CLASS_READ`   |
| `GetStudentWeakness`  | `GetStudentWeaknessRequest{student_id, subject_id}`                      | `StudentWeakness`  | `ANALYTICS_STUDENT_READ` |
| `GetLearningTrend`    | `GetLearningTrendRequest{student_id, start_date, end_date}`              | `LearningTrend`    | `ANALYTICS_STUDENT_READ` |

**权限校验**：gRPC server interceptor 从 metadata 提取 `x-user-id` / `x-user-roles` / `x-data-scope`，调用 `AuthDepends` 等价逻辑。

### 4.3 Pydantic 请求/响应模型

```python
# 示例：班级成绩分析响应
class ClassPerformanceResponse(BaseModel):
    success: bool
    data: ClassPerformanceData
    degraded: bool = False

class ClassPerformanceData(BaseModel):
    class_id: str
    average_score: float
    pass_rate: float
    total_students: int
    scores: list[StudentScore] = []  # 详细成绩列表（受 DataScope 过滤）

class StudentScore(BaseModel):
    student_id: str
    score: float
    grade: str
```

## 5. 事件设计

### 5.1 消费的事件

| Topic                                                  | 来源                                              | 消息格式                                      | 消费动作                                                                     |
| ------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
| `edu-cdc.next_edu_cloud.core_edu_grades`               | Debezium CDC（core-edu MySQL）                    | Debezium JSON（before/after/source/op/ts_ms） | 解析 → 查 ExamCache 填 class_id → 计算掌握度 → upsert student_dashboard_view |
| `edu-cdc.next_edu_cloud.core_edu_exams`                | Debezium CDC                                      | Debezium JSON                                 | upsert ExamCache（exam_id → class_id, subject_id）                           |
| `edu-cdc.next_edu_cloud.core_edu_homework_submissions` | Debezium CDC（**新增订阅**）                      | Debezium JSON                                 | 记录作业提交行为 → 更新 student_dashboard_view                               |
| `edu-cdc.next_edu_cloud.classes`                       | Debezium CDC                                      | Debezium JSON                                 | 同步班级维度（head_teacher_id）用于教师 DataScope                            |
| `edu-cdc.next_edu_cloud.iam_users`                     | Debezium CDC（**新增订阅**）                      | Debezium JSON                                 | 同步用户 dataScope 用于查询过滤（避免每次查 iam）                            |
| `edu.insight.ai.usage`                                 | ai 服务 Kafka producer（**待 coord 新增 topic**） | JSON（UsageRecord）                           | 落 ai_usage_log 表                                                           |

**幂等性**：

- CDC 事件：依赖 ClickHouse `ReplacingMergeTree(last_updated)` 引擎按 ORDER BY 去重
- 领域事件（若消费）：基于 `event_id` 去重（Redis SETNX，TTL 7 天）

### 5.2 发布的事件

| 事件             | Topic                         | 触发时机                                        | 消费者                                        | Payload                                                                    |
| ---------------- | ----------------------------- | ----------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
| `MasteryUpdated` | `edu.insight.mastery.updated` | 掌握度计算完成（CDC grades 事件触发后异步计算） | core-edu（推荐个性化练习）、msg（掌握度预警） | `{event_id, student_id, knowledge_point_id, mastery_level, calculated_at}` |

**发布实现**（Python 无 Outbox 模式）：

- 掌握度计算是**派生数据**（非业务事务写），不需要 Outbox 保证事务一致
- 直接用 `aiokafka.AIOKafkaProducer` 发布，`idempotent=true` + 事务性 producer
- 失败重试 3 次，仍失败记录日志 + 落 `mastery_publish_failed` 本地表（待 P6 评估是否引入 Outbox）

## 6. 横切关注点对齐清单

### 6.1 权限装饰器等价物（FastAPI Depends）

```python
# 权限点常量（与 iam 权限点对齐）
class Permissions:
    ANALYTICS_CLASS_READ = "analytics:class:read"
    ANALYTICS_STUDENT_READ = "analytics:student:read"
    ANALYTICS_TEACHER_DASHBOARD = "analytics:teacher:dashboard"

async def require_permission(permission: str) -> UserContext:
    """FastAPI Depends 权限校验.

    从 x-user-id / x-user-roles 头提取身份，校验角色是否含 permission。
    """
    ...

async def inject_data_scope(ctx: UserContext = Depends(require_permission(...)))-> DataScope:
    """注入 DataScope（从 iam.getEffectiveDataScope 查询，Redis 缓存 5min）."""
    ...
```

### 6.2 错误码清单（前缀 `DATA_ANA_*`）

| 错误码                            | 触发条件                                | HTTP                | gRPC status        |
| --------------------------------- | --------------------------------------- | ------------------- | ------------------ |
| `DATA_ANA_UNAUTHORIZED`           | 缺失 x-user-id 头或 token 无效          | 401                 | UNAUTHENTICATED    |
| `DATA_ANA_FORBIDDEN`              | 角色无对应权限                          | 403                 | PERMISSION_DENIED  |
| `DATA_ANA_DATASCOPE_VIOLATION`    | 查询目标超出 DataScope 范围             | 403                 | PERMISSION_DENIED  |
| `DATA_ANA_CLICKHOUSE_UNAVAILABLE` | ClickHouse 不可达（降级模式仍返回骨架） | 200 + degraded:true | OK + degraded flag |
| `DATA_ANA_INVALID_DATE_RANGE`     | start_date > end_date                   | 400                 | INVALID_ARGUMENT   |
| `DATA_ANA_STUDENT_NOT_FOUND`      | student_id 不存在                       | 404                 | NOT_FOUND          |
| `DATA_ANA_CLASS_NOT_FOUND`        | class_id 不存在                         | 404                 | NOT_FOUND          |
| `DATA_ANA_INTERNAL_ERROR`         | 未捕获异常                              | 500                 | INTERNAL           |

### 6.3 Logger 初始化

- 位置：`main.py` `init_logger()`（已具备）
- 配置：`structlog.make_filtering_bound_logger(level)` + `TimeStamper(fmt="iso")` + `ConsoleRenderer`
- **改进**：生产环境改用 `structlog.processors.JSONRenderer()`（当前 ConsoleRenderer 适合开发）

### 6.4 Metrics 指标清单

| 指标名                                        | 类型      | 标签                 | 描述                       |
| --------------------------------------------- | --------- | -------------------- | -------------------------- |
| `data_ana_http_requests_total`                | Counter   | method, path, status | HTTP 请求总数              |
| `data_ana_http_request_duration_seconds`      | Histogram | method, path         | HTTP 请求延迟              |
| `data_ana_clickhouse_query_duration_seconds`  | Histogram | query_type           | ClickHouse 查询延迟        |
| `data_ana_clickhouse_query_total`             | Counter   | query_type, status   | ClickHouse 查询总数        |
| `data_ana_cdc_events_consumed_total`          | Counter   | table, op            | CDC 事件消费总数           |
| `data_ana_cdc_event_process_duration_seconds` | Histogram | table                | CDC 事件处理延迟           |
| `data_ana_cdc_consumer_lag`                   | Gauge     | topic, partition     | CDC 消费者 lag             |
| `data_ana_mastery_calculated_total`           | Counter   | —                    | 掌握度计算次数             |
| `data_ana_mastery_published_total`            | Counter   | status               | mastery.updated 事件发布数 |
| `data_ana_datascope_cache_hits_total`         | Counter   | —                    | DataScope 缓存命中         |

### 6.5 Tracer 初始化

- 位置：`main.py` `init_tracer()`（已具备）
- endpoint：`settings.otel_endpoint` + `/v1/traces`
- **改进**：gRPC server 注册 `grpc.aio.ServerInterceptor` 透传 W3C trace context

### 6.6 /healthz 检查逻辑

- liveness：仅进程存活（已具备）

### 6.7 /readyz 检查逻辑

```python
async def readyz() -> dict:
    return {
        "status": "ok" if all_ready else "degraded",
        "ready": all_ready,
        "degraded": not all_ready,
        "clickhouse": "ok" | "unreachable" | "not_configured",
        "cdc_consumer": "running" | "disabled" | "failed",
        "kafka_brokers": settings.kafka_brokers or None,
        "iam_grpc": "ok" | "unreachable",  # 新增：iam gRPC 连通性
        "timestamp": datetime.now(UTC).isoformat(),
    }
```

### 6.8 优雅关闭顺序

1. HTTP server stop accepting new requests（uvicorn graceful shutdown）
2. gRPC server graceful stop（等待在途 RPC 完成，30s 超时）
3. CDC consumer stop（等待在途消息处理完成，commit offset）
4. Kafka producer flush + close（确保 mastery.updated 事件已投递）
5. ClickHouse client close
6. iam gRPC channel close

**信号处理**：注册 `signal.SIGTERM` handler，触发上述顺序。

## 7. 与其他模块的交互点（契约清单）

| 方向   | 对方服务                  | 协议  | 接口/事件                                                           | 用途                          |
| ------ | ------------------------- | ----- | ------------------------------------------------------------------- | ----------------------------- |
| 被调用 | api-gateway               | HTTP  | `/analytics/*`                                                      | Gateway 代理                  |
| 被调用 | teacher-bff / student-bff | gRPC  | `AnalyticsService.*`                                                | BFF 聚合查询                  |
| 被调用 | ai                        | gRPC  | `AnalyticsService.GetStudentWeakness / GetLearningTrend`            | AI 个性化出题上下文           |
| 调用   | iam                       | gRPC  | `IamService.GetEffectiveDataScope`（**待 proto 新增**）             | DataScope 解析                |
| 消费   | core-edu（CDC）           | Kafka | `edu-cdc.next_edu_cloud.core_edu_grades/exams/homework_submissions` | 学情数据投递                  |
| 消费   | core-edu（CDC）           | Kafka | `edu-cdc.next_edu_cloud.classes`                                    | 班级维度同步                  |
| 消费   | iam（CDC）                | Kafka | `edu-cdc.next_edu_cloud.iam_users`                                  | 用户 dataScope 同步           |
| 消费   | ai                        | Kafka | `edu.insight.ai.usage`（**待 coord 新增**）                         | AI 用量落库                   |
| 发布   | —                         | Kafka | `edu.insight.mastery.updated`                                       | 掌握度更新通知 core-edu / msg |

## 8. 风险与假设

### 8.1 假设

- **假设 1**：iam 提供 `GetEffectiveDataScope(userId) → DataScope` gRPC API。若 iam 未提供，fallback 为：从 `x-user-roles` 头推导（admin=ALL, teacher=CLASS_TAUGHT, student=SELF），但无法支持细粒度年级/学校范围
- **假设 2**：core-edu 的 `core_edu_homework_submissions` 表存在 binlog。若不存在，作业相关学情无法通过 CDC 获取，需 core-edu 补表或走 Outbox 事件
- **假设 3**：ClickHouse `ReplacingMergeTree` 在查询时需 `FINAL` 关键字确保去重生效。当前查询未加 `FINAL`，可能读到重复版本。**修复**：所有查询加 `FINAL` 或使用 `argMax` 聚合
- **假设 4**：coord 同意新增 `edu.insight.ai.usage` topic。若不同意，ai 服务的用量计费需自建记录（破坏 ai 无状态原则）

### 8.2 技术风险

| 风险                        | 影响                                 | 缓解措施                                         |
| --------------------------- | ------------------------------------ | ------------------------------------------------ |
| ClickHouse 查询延迟超 5s    | 违反 P4 退出标准                     | 宽表索引优化 + 物化视图预聚合 + 查询超时 3s 降级 |
| CDC 消费者 lag 过大         | 学情数据延迟 > 5s                    | 监控 lag + 告警 + 水平扩展消费者（分区数提升）   |
| ExamCache 内存泄漏          | 长期运行 OOM                         | LRU 淘汰策略（max 10000 条）+ 定期清理过期 exam  |
| mastery.updated 事件丢失    | 下游 core-edu/msg 收不到通知         | Kafka producer `acks=all` + 本地失败表重试       |
| iam gRPC 不可达             | DataScope 无法解析 → 查询降级为 SELF | Redis 缓存 5min + fallback SELF 范围（最保守）   |
| ClickHouse `FINAL` 查询性能 | 查询变慢                             | 使用 `argMax` 替代 `FINAL`，或在写入时去重       |

### 8.3 未决设计决策（需 coord 仲裁）

1. **mastery.updated 发布是否需要 Outbox**：Python 无 Outbox 模式，建议直接 producer；但 004 §12.2 明确"事件发布：Outbox 模式 / 禁止直接 Kafka producer"。**冲突**：data-ana 是 Python 服务无 MySQL 写事务，Outbox 不适用。建议 coord 裁定：派生数据事件（非业务事务）允许直接 producer
2. **iam GetEffectiveDataScope proto 新增**：当前 iam.proto 仅有 `GetUserInfo`，无 DataScope 解析 API。需 coord 在 shared-proto 新增 `GetEffectiveDataScope` RPC
3. **edu.insight.ai.usage topic 新增**：004 §7.2 未列出，需 coord 确认是否新增

---

# 模块架构设计文档 — ai

## 1. 模块内部分层图

```mermaid
flowchart TB
    subgraph Entry["入口层"]
        HTTP[FastAPI HTTP Router<br/>/ai/* + /healthz + /readyz]
        GRPC[grpc.aio Server<br/>AiService 含 StreamChat]
    end

    subgraph Middleware["中间件层"]
        AUTH[AuthDepends<br/>校验 x-user-id / x-user-roles]
        RATE[RateLimitDepends<br/>Redis 令牌桶限流]
        TRACE[OTel + grpc interceptor]
    end

    subgraph Service["应用服务层"]
        S1[ChatService<br/>聊天编排 + Prompt 模板渲染]
        S2[QuestionGenerationService<br/>出题工作流编排]
        S3[ExpressionOptimizationService<br/>表达优化]
        S4[LessonPreparationWorkflow<br/>备课工作流 4 步编排]
    end

    subgraph Provider["LLM Provider 适配层"]
        P0[LLMProvider 抽象接口<br/>chat / stream_chat]
        P1[OpenAIProvider<br/>httpx 异步]
        P2[AnthropicProvider<br/>httpx 异步]
        P3[BaichuanProvider<br/>httpx 异步]
        P4[LocalOllamaProvider<br/>httpx 异步]
    end

    subgraph Template["Prompt 模板管理"]
        T1[PromptTemplateRegistry<br/>模板注册 + 渲染]
        T2[模板存储<br/>YAML 文件 / DB]
    end

    subgraph Client["下游 gRPC client"]
        C1[ContentClient<br/>查询知识点 / 题库]
        C2[DataAnaClient<br/>查询学情 / 薄弱点]
    end

    subgraph Usage["用量计费"]
        U1[UsageRecorder<br/>token 消耗统计]
        U2[KafkaProducer<br/>发布 edu.insight.ai.usage]
    end

    subgraph External["外部 / 存储"]
        LLM[LLM Provider API<br/>OpenAI/Anthropic/百川/Ollama]
        CONTENT[content:3005 gRPC]
        DATAANA[data-ana:3006 gRPC]
        KAFKA[(Kafka)]
        REDIS[(Redis<br/>限流 + 缓存)]
    end

    HTTP --> AUTH --> RATE --> S1
    HTTP --> S2
    HTTP --> S3
    GRPC --> S1
    GRPC --> S2
    S2 --> S4
    S4 --> C1
    S4 --> C2
    S1 --> T1
    S2 --> T1
    S1 --> P0
    S2 --> P0
    P0 --> P1
    P0 --> P2
    P0 --> P3
    P0 --> P4
    P1 --> LLM
    P2 --> LLM
    P3 --> LLM
    P4 --> LLM
    S1 --> U1
    S2 --> U1
    U1 --> U2
    U2 --> KAFKA
    RATE --> REDIS
    C1 --> CONTENT
    C2 --> DATAANA
```

**分层规则**：

- **入口层**：HTTP（保留作 Gateway 直连）+ gRPC（主入口，含 `StreamChat` 流式 RPC）
- **中间件层**：Auth + RateLimit（Redis 令牌桶，按 user_id 限流）
- **应用服务层**：4 个 Service，每个对应一类 AI 能力
- **Provider 适配层**：抽象 `LLMProvider` 接口，多适配器实现（策略模式）
- **Prompt 模板**：模板注册 + 渲染，模板存储可配置（YAML 文件 or DB）
- **下游 client**：gRPC 调 content / data-ana
- **用量计费**：token 消耗统计 + Kafka 事件外发

## 2. 领域模型

ai 是**无状态服务**，不持有持久化聚合根。领域模型为**请求/响应模型 + 工作流编排**：

### 聚合根（请求型，无持久化）

| 聚合根                       | 含义         | 生命周期                                                     |
| ---------------------------- | ------------ | ------------------------------------------------------------ |
| `ChatConversation`           | 单次聊天请求 | 单次请求                                                     |
| `QuestionGenerationTask`     | 出题任务     | 单次请求（备课工作流中多步）                                 |
| `ExpressionOptimizationTask` | 表达优化任务 | 单次请求                                                     |
| `LessonPreparationWorkflow`  | 备课工作流   | 跨多步（分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库） |

### 值对象

- `ChatMessage`：role + content
- `Usage`：prompt_tokens + completion_tokens + total_tokens
- `GeneratedQuestion`：question + answer + explanation
- `PromptTemplate`：name + system_prompt + user_template + variables

### 工作流编排（备课）

```mermaid
sequenceDiagram
    participant T as 教师
    participant BFF as teacher-bff
    participant AI as ai 服务
    participant Content as content
    participant DA as data-ana

    T->>BFF: 请求备课（class_id, subject_id）
    BFF->>AI: gRPC GenerateLessonPlan
    AI->>DA: gRPC GetStudentWeakness(class_id)
    DA-->>AI: 薄弱知识点列表
    AI->>Content: gRPC GetPrerequisites(knowledge_point_id)
    Content-->>AI: 前置依赖知识点
    AI->>AI: LLM 生成题目（基于学情 + 知识点）
    AI-->>BFF: 题目列表 + 推荐理由
    BFF-->>T: 题目供审核
    T->>BFF: 确认入库
    BFF->>Content: gRPC CreateQuestions
    Content-->>BFF: 入库成功
```

**工作流实现**：

- **简单场景**（4 步内）：FastAPI BackgroundTasks + asyncio.gather 并行查询
- **复杂场景**（含教师审核等待）：待 coord 仲裁是否引入 Temporal（004 §2.3 列出 Temporal 用于 AI 编排）

## 3. 数据模型

ai 服务**无独占数据库**，无 MySQL schema。所有数据通过 Kafka 事件外发（用量计费）或 gRPC 查询下游。

### 用量计费（Kafka 事件 → data-ana 落 ClickHouse）

```json
{
  "event_id": "uuid",
  "user_id": "user-xxx",
  "request_id": "req-xxx",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt_tokens": 150,
  "completion_tokens": 80,
  "total_tokens": 230,
  "latency_ms": 1200,
  "success": true,
  "occurred_at": "2026-07-09T12:00:00Z"
}
```

**Topic**：`edu.insight.ai.usage`（**待 coord 新增**）

### 缓存策略

| 数据                                   | 存储                          | TTL      | 失效策略               |
| -------------------------------------- | ----------------------------- | -------- | ---------------------- |
| Prompt 模板                            | Redis（模板变更事件驱动失效） | 1 小时   | 文件/DB 变更时主动失效 |
| LLM 响应（相同 prompt）                | Redis（hash 缓存）            | 30 分钟  | 短 TTL，避免陈旧       |
| DataScope（ai 不需要，仅 data-ana 用） | —                             | —        | —                      |
| 限流计数                               | Redis 令牌桶                  | 滑动窗口 | 自动过期               |

## 4. API 设计

### 4.1 HTTP 端点（保留作 Gateway 直连降级）

| method | path                      | 权限                     | 请求体                      | 响应                                 | 说明                   |
| ------ | ------------------------- | ------------------------ | --------------------------- | ------------------------------------ | ---------------------- |
| GET    | `/healthz`                | —                        | —                           | `{status, service}`                  | liveness               |
| GET    | `/readyz`                 | —                        | —                           | `{status, llm_configured, degraded}` | readiness              |
| GET    | `/metrics`                | —                        | —                           | Prometheus                           | 指标                   |
| POST   | `/ai/chat`                | `AI_CHAT`                | `ChatRequest`               | `ChatResponse`                       | LLM 聊天               |
| POST   | `/ai/chat/stream`         | `AI_CHAT`                | `ChatRequest`               | SSE stream                           | 流式聊天               |
| POST   | `/ai/generate/question`   | `AI_QUESTION_GENERATE`   | `GenerateQuestionRequest`   | `GeneratedQuestionResponse`          | 生成题目               |
| POST   | `/ai/optimize/expression` | `AI_EXPRESSION_OPTIMIZE` | `OptimizeExpressionRequest` | `OptimizedExpressionResponse`        | 优化表达               |
| POST   | `/ai/lesson/preparation`  | `AI_LESSON_PREPARE`      | `LessonPreparationRequest`  | `LessonPreparationResponse`          | 备课工作流（**新增**） |

### 4.2 gRPC 契约（ai.proto，待实现 server）

| RPC                  | 请求                                                   | 响应                                  | 权限                     | 说明                      |
| -------------------- | ------------------------------------------------------ | ------------------------------------- | ------------------------ | ------------------------- |
| `Chat`               | `ChatRequest{messages, model, temperature}`            | `ChatResponse{content, model, usage}` | `AI_CHAT`                | 非流式聊天                |
| `StreamChat`         | `ChatRequest`                                          | `stream ChatChunk`                    | `AI_CHAT`                | 流式聊天（SSE over gRPC） |
| `GenerateQuestion`   | `GenerateQuestionRequest{prompt, subject, difficulty}` | `GeneratedQuestion`                   | `AI_QUESTION_GENERATE`   | 生成题目                  |
| `OptimizeExpression` | `OptimizeExpressionRequest{text, context}`             | `OptimizedExpression`                 | `AI_EXPRESSION_OPTIMIZE` | 优化表达                  |

### 4.3 Pydantic 请求/响应模型

```python
class ChatRequest(BaseModel):
    messages: list[ChatMessage]
    model: str = "gpt-4o-mini"
    temperature: float = Field(0.7, ge=0.0, le=2.0)
    stream: bool = False

class ChatMessage(BaseModel):
    role: Literal["system", "user", "assistant"]
    content: str

class ChatResponse(BaseModel):
    success: bool
    data: ChatData
    degraded: bool = False

class ChatData(BaseModel):
    content: str
    model: str
    usage: Usage

class Usage(BaseModel):
    prompt_tokens: int
    completion_tokens: int
    total_tokens: int

class GenerateQuestionRequest(BaseModel):
    prompt: str = Field(..., min_length=1, max_length=2000)
    subject: str
    difficulty: Literal["easy", "medium", "hard"]
    knowledge_point_ids: list[str] = []  # 可选：靶向知识点

class GeneratedQuestionResponse(BaseModel):
    success: bool
    data: GeneratedQuestionData
    degraded: bool = False
```

## 5. 事件设计

### 5.1 消费的事件

ai 服务**不消费任何事件**（无状态，纯请求-响应）。

### 5.2 发布的事件

| 事件              | Topic                                       | 触发时机          | 消费者                                 | Payload                                                                                                                              |
| ----------------- | ------------------------------------------- | ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `AIUsageRecorded` | `edu.insight.ai.usage`（**待 coord 新增**） | 每次 LLM 调用完成 | data-ana（落 ClickHouse ai_usage_log） | `{event_id, user_id, request_id, provider, model, prompt_tokens, completion_tokens, total_tokens, latency_ms, success, occurred_at}` |

**发布实现**：

- 每次 LLM 调用后异步发布（不阻塞响应）
- `aiokafka.AIOKafkaProducer` + `acks=all`
- 失败重试 3 次，仍失败记录日志（不影响主流程）

## 6. 横切关注点对齐清单

### 6.1 权限装饰器等价物

```python
class Permissions:
    AI_CHAT = "ai:chat"
    AI_QUESTION_GENERATE = "ai:question:generate"
    AI_EXPRESSION_OPTIMIZE = "ai:expression:optimize"
    AI_LESSON_PREPARE = "ai:lesson:prepare"

async def require_permission(permission: str) -> UserContext:
    """从 x-user-id / x-user-roles 校验权限."""
    ...
```

### 6.2 错误码清单（前缀 `AI_*`）

| 错误码                      | 触发条件                                  | HTTP                | gRPC status        |
| --------------------------- | ----------------------------------------- | ------------------- | ------------------ |
| `AI_UNAUTHORIZED`           | 缺失 x-user-id 或 token 无效              | 401                 | UNAUTHENTICATED    |
| `AI_FORBIDDEN`              | 角色无对应权限                            | 403                 | PERMISSION_DENIED  |
| `AI_RATE_LIMITED`           | 触发限流                                  | 429                 | RESOURCE_EXHAUSTED |
| `AI_LLM_UNAVAILABLE`        | LLM Provider 不可达（降级模式仍返回骨架） | 200 + degraded:true | OK + degraded flag |
| `AI_LLM_TIMEOUT`            | LLM 调用超时（30s）                       | 504                 | DEADLINE_EXCEEDED  |
| `AI_INVALID_MODEL`          | model 名不支持                            | 400                 | INVALID_ARGUMENT   |
| `AI_INVALID_DIFFICULTY`     | difficulty 不在 easy/medium/hard          | 400                 | INVALID_ARGUMENT   |
| `AI_DOWNSTREAM_UNAVAILABLE` | content / data-ana gRPC 不可达            | 502                 | UNAVAILABLE        |
| `AI_PROMPT_RENDER_FAILED`   | Prompt 模板渲染失败（变量缺失）           | 500                 | INTERNAL           |
| `AI_INTERNAL_ERROR`         | 未捕获异常                                | 500                 | INTERNAL           |

### 6.3 Logger 初始化

- 位置：`main.py`（已具备）
- **改进**：生产环境改用 `JSONRenderer`

### 6.4 Metrics 指标清单

| 指标名                             | 类型      | 标签                                      | 描述               |
| ---------------------------------- | --------- | ----------------------------------------- | ------------------ |
| `ai_http_requests_total`           | Counter   | method, path, status                      | HTTP 请求总数      |
| `ai_http_request_duration_seconds` | Histogram | method, path                              | HTTP 请求延迟      |
| `ai_llm_calls_total`               | Counter   | provider, model, status                   | LLM 调用总数       |
| `ai_llm_call_duration_seconds`     | Histogram | provider, model                           | LLM 调用延迟       |
| `ai_llm_tokens_total`              | Counter   | provider, model, type (prompt/completion) | token 消耗总数     |
| `ai_llm_stream_chunks_total`       | Counter   | provider, model                           | 流式 chunk 总数    |
| `ai_grpc_calls_total`              | Counter   | downstream, method, status                | 下游 gRPC 调用总数 |
| `ai_rate_limit_hits_total`         | Counter   | user_id                                   | 限流命中次数       |
| `ai_usage_events_published_total`  | Counter   | status                                    | 用量事件发布数     |
| `ai_prompt_template_renders_total` | Counter   | template_name, status                     | 模板渲染次数       |

### 6.5 Tracer 初始化

- 位置：`main.py` `init_tracer()`（已具备，dev_mode 跳过）
- **改进**：gRPC server interceptor + 下游 gRPC client interceptor 透传 trace context

### 6.6 /healthz 检查逻辑

- liveness：仅进程存活（已具备）

### 6.7 /readyz 检查逻辑

```python
async def readyz() -> dict:
    return {
        "status": "ok",
        "service": "ai",
        "llm_configured": settings.llm_available,
        "degraded": not settings.llm_available,
        "providers": {
            "openai": bool(settings.openai_api_key),
            "anthropic": bool(settings.anthropic_api_key),
            "baichuan": bool(settings.baichuan_api_key),
            "local_ollama": bool(settings.ollama_base_url),
        },
        "downstream_grpc": {
            "content": "ok" | "unreachable",  # 新增
            "data_ana": "ok" | "unreachable",  # 新增
        },
        "redis": "ok" | "unreachable",  # 新增（限流依赖）
    }
```

### 6.8 优雅关闭顺序

1. HTTP server stop accepting new requests
2. gRPC server graceful stop（**关键**：等待在途 `StreamChat` 流式 RPC 完成，60s 超时，避免截断用户响应）
3. LLM 流式请求 drain（等待 httpx stream 完成）
4. Kafka producer flush + close（确保用量事件已投递）
5. 下游 gRPC channels close（content / data-ana）
6. Redis connection close

## 7. 与其他模块的交互点（契约清单）

| 方向   | 对方服务     | 协议  | 接口/事件                                                  | 用途               |
| ------ | ------------ | ----- | ---------------------------------------------------------- | ------------------ |
| 被调用 | api-gateway  | HTTP  | `/ai/*`                                                    | Gateway 代理       |
| 被调用 | teacher-bff  | gRPC  | `AiService.*`                                              | BFF 聚合 AI 能力   |
| 调用   | content      | gRPC  | `KnowledgeGraphService.GetPrerequisites / GetLearningPath` | 出题上下文查询     |
| 调用   | content      | gRPC  | `TextbookService.*`（若需教材上下文）                      | 出题教材关联       |
| 调用   | data-ana     | gRPC  | `AnalyticsService.GetStudentWeakness / GetLearningTrend`   | 个性化出题学情查询 |
| 调用   | LLM Provider | HTTP  | OpenAI 兼容 REST `/chat/completions`                       | LLM 推理           |
| 发布   | —            | Kafka | `edu.insight.ai.usage`（**待 coord 新增**）                | 用量计费外发       |

## 8. 风险与假设

### 8.1 假设

- **假设 1**：content 服务实现了 `KnowledgeGraphService` gRPC server。当前 content.proto 已定义但未实现 gRPC server（ai05 阶段 2 设计中）。ai 调用前需确认 content gRPC 可用
- **假设 2**：data-ana 实现了 `AnalyticsService` gRPC server（本设计文档已设计）。ai 调用前需确认 data-ana gRPC 可用
- **假设 3**：coord 同意新增 `edu.insight.ai.usage` topic。若不同意，用量计费降级为 ai 本地日志（不落 ClickHouse，影响成本分析）
- **假设 4**：Redis 可用（限流依赖）。若 Redis 不可用，限流降级为"无限制"（风险：LLM 成本失控），或降级为内存令牌桶（单实例有效，多实例不一致）

### 8.2 技术风险

| 风险                   | 影响             | 缓解措施                                                        |
| ---------------------- | ---------------- | --------------------------------------------------------------- |
| LLM 调用延迟高（>30s） | 用户体验差       | 超时 30s + 降级骨架响应 + 流式优先（用户感知首字延迟）          |
| LLM 成本失控           | 财务风险         | Redis 令牌桶限流（每用户每分钟 10 次）+ 用量计费监控 + 告警阈值 |
| LLM Provider 单点故障  | 服务不可用       | 多 Provider 适配器 + 自动 failover（OpenAI 失败切 Anthropic）   |
| 流式 RPC 中断          | 用户响应截断     | gRPC server graceful shutdown 60s drain + 客户端重连机制        |
| Prompt 注入攻击        | LLM 输出恶意内容 | 输入 sanitize + system prompt 加安全约束 + 输出过滤             |
| 下游 gRPC 不可达       | 备课工作流失败   | 降级：跳过学情查询，仅基于 prompt 生成题目 + `degraded: true`   |

### 8.3 未决设计决策（需 coord 仲裁）

1. **备课工作流是否引入 Temporal**：004 §2.3 列出 Temporal 用于 AI 编排，但简单 4 步工作流可用 FastAPI BackgroundTasks。建议：M14 用 BackgroundTasks，M15 评估是否迁移 Temporal
2. **`edu.insight.ai.usage` topic 新增**：需 coord 在 shared-proto events.proto 新增 `AIUsageEvent` message + 004 §7.2 新增 topic
3. **LLM Provider 配置化路由**：是否在 shared-py 建立通用 `LLMProvider` 抽象（供未来其他 Python 服务复用）。建议 P5 阶段在 ai 服务内部实现，P6 评估是否提取到 shared-py
4. **Prompt 模板存储位置**：YAML 文件（简单，无 DB）vs DB（动态更新）。建议 P5 用 YAML 文件（`services/ai/src/ai/prompts/*.yaml`），P6 评估迁移 DB

---

# 阶段 2 总结

ai06 已完成阶段 2 模块架构设计，产出 data-ana 与 ai 两份设计文档。核心设计决策：

## data-ana 设计要点

1. **分层**：HTTP + gRPC 双入口共享 Application Service；CDC 消费者独立后台任务
2. **数据模型**：4 张 ClickHouse 宽表（student_dashboard_view / student_errors / mastery_snapshot / ai_usage_log），ReplacingMergeTree 引擎保证幂等
3. **权限**：FastAPI Depends 链（require_permission + inject_data_scope），DataScope WHERE 注入 ClickHouse 查询
4. **事件**：消费 6 个 CDC topic + 发布 `edu.insight.mastery.updated`（直接 producer，非 Outbox，因派生数据非事务写）
5. **gRPC**：实现 `AnalyticsService` server（analytics.proto 已定义）
6. **降级**：ClickHouse 不可达返回骨架 + degraded:true；iam gRPC 不可达降级为 SELF DataScope

## ai 设计要点

1. **分层**：HTTP + gRPC 双入口；LLM Provider 适配层（策略模式，4 适配器）
2. **无状态**：无 DB，用量计费通过 Kafka 事件外发
3. **权限**：FastAPI Depends + Redis 令牌桶限流（每用户每分钟 10 次）
4. **工作流**：备课 4 步编排（学情查询 → 知识点推荐 → 题目生成 → 教师审核入库），简单场景用 BackgroundTasks
5. **gRPC**：实现 `AiService` server（含 `StreamChat` 流式 RPC）；gRPC client 调 content / data-ana
6. **降级**：LLM 不可达返回骨架 + degraded:true；下游 gRPC 不可达降级跳过

## 待 coord 交叉审查项（汇总）

| #   | 议题                                                                                 | 涉及文档                |
| --- | ------------------------------------------------------------------------------------ | ----------------------- |
| 1   | data-ana 发布 `edu.insight.mastery.updated` 用直接 producer（非 Outbox）是否合规     | 004 §12.2               |
| 2   | 新增 `edu.insight.ai.usage` topic + `AIUsageEvent` proto message                     | 004 §7.2 + events.proto |
| 3   | iam 新增 `GetEffectiveDataScope` gRPC RPC                                            | iam.proto               |
| 4   | data-ana / ai 实现 gRPC server 决策                                                  | 004 §4.1                |
| 5   | ClickHouse DDL 管理位置（建议 `infra/clickhouse/ddl/`）                              | infra/                  |
| 6   | ai 备课工作流是否引入 Temporal                                                       | 004 §2.3                |
| 7   | 端口冲突检查：data-ana 3006 / ai 3008（无冲突）                                      | full-stack-runbook      |
| 8   | 错误码前缀检查：`DATA_ANA_*` / `AI_*`（与其他服务不重叠）                            | —                       |
| 9   | 黄金模板对齐：Python 服务无 NestJS 装饰器，权限校验用 FastAPI Depends 等价物是否认可 | —                       |

下一步：等待 coord 交叉审查通过后，进入阶段 3（按图实施）。

---

**AI Agent**: ai06 (data-ana + ai)
**Branch**: 单仓库并行模式（直接提交 main）
**Coordinator**: coord-ai