2ba4250165
- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky - infra: docker-compose (minimal + full profiles) + init-sql + prometheus - arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto) - shared-proto: buf v2 + classes.proto (ClassService CRUD contract) - api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID - classes: NestJS golden template (error system + observability + middleware + CRUD + tests) - teacher-portal: Next.js + paper-feel UI design system - CI/CD: 4 workflows (go/ts/py/proto) - docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap
105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# data-ana 数据分析服务
|
||
|
||
> 版本：0.1（骨架）
|
||
> 日期：2026-07-07
|
||
> 状态：P4 待交付
|
||
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)
|
||
|
||
---
|
||
|
||
## 1. 模块职责
|
||
|
||
data-ana 是数据分析限界上下文（Python 实现），管理 Report、Mastery、Dashboard 聚合。
|
||
消费 core-edu 与 content 的领域事件，构建 ClickHouse 学情宽表，计算知识点掌握度。
|
||
对外提供学情仪表盘查询、班级/年级/学校维度报表、个性化推荐数据支撑。
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
|
||
| 类别 | 技术 | 版本 | 用途 |
|
||
|------|------|------|------|
|
||
| 语言 | Python | 3.12+ | 数据分析 |
|
||
| 框架 | FastAPI | 0.110+ | 异步 API |
|
||
| ORM | SQLAlchemy | 2.x | ClickHouse 查询 |
|
||
| 分析库 | ClickHouse | - | 学情宽表、实时聚合 |
|
||
| 任务 | Celery | 5.x | 异步计算任务 |
|
||
| 校验 | pydantic | 2.x | 运行时校验 |
|
||
| 追踪 | OpenTelemetry | - | 分布式追踪 |
|
||
|
||
---
|
||
|
||
## 3. 架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
BFF[BFF 聚合层] -->|gRPC| ANA[data-ana 服务]
|
||
K[(Kafka)] -->|消费事件| ANA
|
||
ANA --> PROJ[Projection<br/>事件 → ClickHouse]
|
||
ANA --> CALC[MasteryCalculator<br/>掌握度计算]
|
||
ANA --> RPT[ReportGenerator<br/>报表生成]
|
||
ANA -->[(ClickHouse<br/>学情宽表)]
|
||
ANA -.事件.-> K2[(Kafka<br/>edu.insight.mastery.updated)]
|
||
```
|
||
|
||
> 待 P4 交付时补充完整的分层架构图与事件消费管线图。
|
||
|
||
---
|
||
|
||
## 4. 核心流程图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant K as Kafka
|
||
participant ANA as data-ana
|
||
participant CH as ClickHouse
|
||
participant BFF as BFF
|
||
|
||
K->>ANA: edu.teaching.grade.recorded
|
||
ANA->>ANA: Projection 写入宽表
|
||
ANA->>ANA: 触发掌握度计算（Celery）
|
||
ANA->>CH: 更新 mastery 表
|
||
ANA->>K: 发布 edu.insight.mastery.updated
|
||
BFF->>ANA: gRPC GetDashboard(studentId)
|
||
ANA->>CH: 查询宽表聚合
|
||
ANA-->>BFF: DashboardDTO
|
||
```
|
||
|
||
> 待 P4 交付时补充：报表生成流程、掌握度算法流程、CDC 同步流程。
|
||
|
||
---
|
||
|
||
## 5. 对外契约
|
||
|
||
- **gRPC 服务**：DashboardService、MasteryService、ReportService（待 P4 定义 protobuf）
|
||
- **消费事件**：`edu.teaching.*`、`edu.content.*`
|
||
- **发布事件**：`edu.insight.mastery.updated`
|
||
- **ClickHouse 宽表**：student_wide_table、mastery_table、exam_analysis_table
|
||
|
||
> 待 P4 交付时补充完整 protobuf 定义与宽表 schema。
|
||
|
||
---
|
||
|
||
## 6. 依赖关系
|
||
|
||
- **上游**：teacher-bff、student-bff、parent-bff、ai（gRPC 查询学情）
|
||
- **下游**：ClickHouse、Kafka（消费与发布）、Celery（异步任务）
|
||
- **跨服务**：消费 core-edu/content 事件；发布掌握度事件被 core-edu 消费触发推荐
|
||
|
||
---
|
||
|
||
## 7. 架构约束
|
||
|
||
1. 查询必须走 ClickHouse 宽表，禁止实时计算
|
||
2. 事件消费必须幂等，基于 event_id 去重
|
||
3. 掌握度计算必须异步（Celery），不阻塞事件消费
|
||
4. 宽表查询响应时间 ≤ 5 秒
|
||
|
||
> 待 P4 交付时补充完整约束清单。
|
||
|
||
---
|
||
|
||
## 8. 架构决策
|
||
|
||
> 待 P4 交付时补充 ADR 记录，预计包括：Python+FastAPI 选型、ClickHouse 选型、Celery 异步框架选型、掌握度算法选型。
|