Merge worktree branch merge-15-modules-to-main-5ug5xJ
This commit is contained in:
SpecialX
@@ -7,6 +7,7 @@
|
||||
> 日期：2026-07-09（v1 by ai06）/ 2026-07-10（v2 审核修订 by ai11）
|
||||
> 关联文档：[ai-allocation.md](../../../docs/architecture/ai-allocation.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features.md](../../../docs/architecture/roadmap/pending-features.md)、[known-issues.md](../../../docs/troubleshooting/known-issues.md)
|
||||
> 审核修订说明：ai-allocation.md §3.2 将 data-ana 重新分配给 ai11（ai 单独分配给 ai12），ai11 接手后对 ai06 v1 进行审核，本版为 v2 修订。
|
||||
> v2.1 审核修订（ai11）：核查发现多处 004 章节引用断裂（§4.2/§11.4/§11.5/§15.3 在 004 正文中不存在，coord-cross-review §6 整改清单要求 coord 补充但尚未落实），已改为引用 coord-cross-review.md 对应裁决；修正 topic 命名统一为 `edu.insight.mastery.updated`；补充 events.proto AIUsageEvent 缺失说明。
|
||||
|
||||
---
|
||||
|
||||
@@ -41,11 +42,11 @@
|
||||
- ClickHouse（独占读模型，宽表 `student_dashboard_view` / `student_errors` / `mastery_snapshot` / `ai_usage_log`）
|
||||
- Redis（DataScope 缓存 5min + 预警去重位图 + CDC 幂等去重 SETNX，004 §6.3 缓存策略矩阵）
|
||||
- Kafka（消费 Debezium CDC 事件 + 发布 `edu.insight.mastery.updated` 派生数据事件）
|
||||
- iam gRPC（调 `GetEffectiveDataScope` 解析数据范围，已仲裁 P4 补全，见 004 §15.3 #5）
|
||||
- iam gRPC（调 `GetEffectiveDataScope` 解析数据范围，已仲裁 P4 补全，见 [coord-cross-review.md §2](../../docs/architecture/coord-cross-review.md) #3）
|
||||
- **通信方式**：
|
||||
- 入口：HTTP（`/analytics/*`，保留作 Gateway 直连降级）+ **gRPC** `AnalyticsService`（P4 启用主入口，BFF 调用）
|
||||
- 出口：Kafka 消费（CDC 主通道 + 领域事件订阅备通道）；Kafka 发布（`edu.insight.mastery.updated`，**未实现**，属派生数据豁免 Outbox，见 004 §12.2）
|
||||
- **端口**：HTTP=3006（见 [data-ana config.py:7](../src/data_ana/config.py) + [api-gateway config.go:55](../../api-gateway/internal/config/config.go)）；**gRPC=50055**（004 §1.2 服务清单 + §4.2 gRPC 启用阶段矩阵：P4 启用）
|
||||
- 出口：Kafka 消费（CDC 主通道 + 领域事件订阅备通道）；Kafka 发布（`edu.insight.mastery.updated`，**未实现**，属派生数据豁免 Outbox，见 [coord-cross-review.md §3.3](../../docs/architecture/coord-cross-review.md) + 004 §12.2）
|
||||
- **端口**：HTTP=3006（见 [data-ana config.py:7](../src/data_ana/config.py) + [api-gateway config.go:55](../../api-gateway/internal/config/config.go)）；**gRPC=50055**（[coord-cross-review.md §4.3](../../docs/architecture/coord-cross-review.md) 全局端口矩阵 + [matrix.md §2](../../docs/architecture/issues/matrix.md)：P4 启用）
|
||||
|
||||
## 2. 我的限界上下文
|
||||
|
||||
@@ -79,7 +80,7 @@
|
||||
| events.proto | `HomeworkEvent` | 备通道（未消费） | 未来双消费：作业提交/批改事件 → 更新学情 |
|
||||
| events.proto | `ClassEvent` | 备通道（未消费） | 未来双消费：班级变更事件 → 同步班级维度 |
|
||||
| analytics.proto | `GetClassPerformanceRequest` 等 | 自身暴露契约（待实现 gRPC server） | P4 启用 gRPC=50055 后暴露 `AnalyticsService` |
|
||||
| iam.proto | `GetEffectiveDataScopeRequest`（**待 coord 在 iam.proto 新增**，004 §15.3 #5 已裁决 P4 补全） | 调用契约 | gRPC 调 iam 解析 DataScope，结果 Redis 缓存 5min |
|
||||
| iam.proto | `GetEffectiveDataScopeRequest`（**待 coord 在 iam.proto 新增**，[coord-cross-review.md §2](../../docs/architecture/coord-cross-review.md) #3 已裁决 P4 补全；当前 iam.proto 仅有 4 RPC，无此 RPC，**P4 阻塞项**） | 调用契约 | gRPC 调 iam 解析 DataScope，结果 Redis 缓存 5min |
|
||||
|
||||
### 暴露的 API / 事件
|
||||
|
||||
@@ -94,7 +95,7 @@
|
||||
| GET | `/analytics/student/{student_id}/weakness` | 学生薄弱知识点（mastery < 0.6） |
|
||||
| GET | `/analytics/student/{student_id}/errorbook` | 学生错题本 |
|
||||
|
||||
> **响应信封约束**：以上 HTTP 端点当前实现为 `{success, data, degraded}` 结构，违反 004 §11.5 统一响应信封 ActionState（Python 服务必须改 ActionState，degraded 作为 `details.degraded` 子字段）。阶段 2 设计已对齐（见 02-architecture-design.md §4.3）。
|
||||
> **响应信封约束**：以上 HTTP 端点当前实现为 `{success, data, degraded}` 结构，违反统一响应信封 ActionState（[coord-cross-review.md §5.3](../../docs/architecture/coord-cross-review.md) 已裁决 Python 服务必须改 ActionState，degraded 作为 `details.degraded` 子字段）。阶段 2 设计已对齐（见 02-architecture-design.md §4.3）。
|
||||
|
||||
**gRPC 契约**（analytics.proto，P4 启用 server，端口 50055）：
|
||||
|
||||
@@ -113,11 +114,13 @@
|
||||
|
||||
| 事件 | Topic（004 §7.2） | 触发时机 | 消费者（004 §7.3） | Outbox 合规性 |
|
||||
| ---------------- | ----------------------------- | -------------- | --------------------------------------- | ----------------------------------------------------------- |
|
||||
| `MasteryUpdated` | `edu.insight.mastery.updated` | 掌握度计算完成 | core-edu（推荐个性化练习）、msg（预警） | **豁免 Outbox**（派生数据，见 004 §12.2 + §15.3 #6 已仲裁） |
|
||||
| `MasteryUpdated` | `edu.insight.mastery.updated` | 掌握度计算完成 | core-edu（推荐个性化练习）、msg（预警） | **豁免 Outbox**（派生数据，见 [coord-cross-review.md §3.3](../../docs/architecture/coord-cross-review.md) + 004 §12.2） |
|
||||
|
||||
> **当前未实现发布**：data-ana 当前只消费不发布。掌握度计算完成后通过 `aiokafka.AIOKafkaProducer` 直接发布（已豁免 Outbox，004 §15.3 #6 仲裁结论），下游 core-edu / msg 消费。失败重试 3 次仍失败落 `mastery_publish_failed` 本地表。
|
||||
> **当前未实现发布**：data-ana 当前只消费不发布。掌握度计算完成后通过 `aiokafka.AIOKafkaProducer` 直接发布（已豁免 Outbox，coord-cross-review.md §3.3 仲裁结论），下游 core-edu / msg 消费。失败重试 3 次仍失败落 `mastery_publish_failed` 本地表。
|
||||
|
||||
- **错误码前缀**：`DATA_ANA_*`（004 §11.4 错误码前缀矩阵已登记，清单见阶段 2 §6.2）
|
||||
> **Topic 命名一致性**：本模块统一使用 `edu.insight.mastery.updated`（与 004 §7.2 + matrix.md §4 对齐）。contract.md 早期版本写 `edu.data_ana.mastery.events`，已在 v2.1 修正。
|
||||
|
||||
- **错误码前缀**：`DATA_ANA_*`（[matrix.md §6](../../docs/architecture/issues/matrix.md) 错误码前缀矩阵已登记，清单见阶段 2 §6.2）
|
||||
- **缓存**：Redis（DataScope 缓存 5min 事件驱动失效 / CDC event_id 幂等去重 SETNX TTL 7d / 预警去重位图）；学情宽表走 ClickHouse 实时，CDC 同步延迟 < 5s
|
||||
|
||||
## 4. 我的技术栈
|
||||
@@ -145,7 +148,7 @@
|
||||
- **交付物**（pending-features P4）：DataAna 学情诊断宽表 5s 内返回 + CDC 链路延迟 < 5s + **双轨读策略落地（实时查主库 + 聚合查宽表）** + CDC 模式回写黄金模板 README + 打 tag `v0.4.0-p4`
|
||||
- **依赖上游**：
|
||||
- P1 地基：api-gateway 路由 + arch.db 扫描器 Python 支持
|
||||
- P2 身份：iam `GetEffectiveDataScope` gRPC（已仲裁 P4 补全，见 004 §15.3 #5）
|
||||
- P2 身份：iam `GetEffectiveDataScope` gRPC（已仲裁 P4 补全，见 [coord-cross-review.md §2](../../docs/architecture/coord-cross-review.md) #3；**当前 iam.proto 未实现，P4 阻塞项**）
|
||||
- P3 核心教学：core-edu 写成绩到 MySQL（Debezium 监听 binlog）+ Outbox 领域事件（备通道）
|
||||
- P4 同期：content 服务（提供知识点 ID 供掌握度计算，content → data-ana 事件流见 004 §4 服务依赖图）
|
||||
- **下游依赖我**：
|
||||
@@ -160,8 +163,8 @@
|
||||
> Python 服务无 NestJS 装饰器体系，权限校验等通过等价方式实现。
|
||||
|
||||
- [ ] 权限装饰器等价物：**当前 HTTP 端点全部裸露，无权限校验**。Gateway 层做 JWT 校验，但 data-ana 本身未校验 `x-user-id` / DataScope。**阶段 2 需设计 FastAPI Depends 权限依赖 + DataScope 过滤注入**
|
||||
- [ ] 错误码前缀统一：**当前无错误码体系**，降级时返回 `degraded: true` 标记但无业务错误码。**阶段 2 需定义 `DATA_ANA_*` 错误码清单**（004 §11.4 已登记前缀）
|
||||
- [ ] **响应信封对齐 ActionState**（004 §11.5 已仲裁 P0 整改）：当前 `{success, data, degraded}` 偏离结构，须改为 `{success: true, data: T}` / `{success: false, error: {code, message, details?, traceId?}}`，degraded 作为 `details.degraded` 子字段
|
||||
- [ ] 错误码前缀统一：**当前无错误码体系**，降级时返回 `degraded: true` 标记但无业务错误码。**阶段 2 需定义 `DATA_ANA_*` 错误码清单**（[matrix.md §6](../../docs/architecture/issues/matrix.md) 已登记前缀）
|
||||
- [ ] **响应信封对齐 ActionState**（[coord-cross-review.md §5.3](../../docs/architecture/coord-cross-review.md) 已裁决 P0 整改）：当前 `{success, data, degraded}` 偏离结构，须改为 `{success: true, data: T}` / `{success: false, error: {code, message, details?, traceId?}}`，degraded 作为 `details.degraded` 子字段
|
||||
- [x] logger / metrics / tracer 三支柱（已具备，见 main.py + clickhouse_client.py；生产改 JSONRenderer）
|
||||
- [x] `/healthz` + `/readyz` 健康检查（已具备，readyz 含 ClickHouse ping + CDC 状态；**待补 Redis + iam gRPC 连通性检查**）
|
||||
- [ ] 优雅关闭 SIGTERM：当前 lifespan 仅关闭 CDC task + ClickHouse client，**未注册 SIGTERM 信号处理器**显式 drain。阶段 2 设计顺序：HTTP stop → gRPC graceful stop 30s → CDC commit offset → Kafka producer flush → ClickHouse close → iam channel close
|
||||
@@ -210,17 +213,17 @@
|
||||
|
||||
## coord 交叉审查结论对齐（v2 修订，原 v1 标题"待 coord 交叉审查的跨模块契约对齐项"）
|
||||
|
||||
> v1 提请的 5 项跨模块契约对齐项，coord 已在 [coord-cross-review.md](../../../docs/architecture/coord-cross-review.md) 完成仲裁，裁决结论中涉及架构设计意图的部分已沉淀到 004 对应章节（004 §15.3 共性问题 #1-#7）。本节 v2 改为"对齐状态"。
|
||||
> v1 提请的 5 项跨模块契约对齐项，coord 已在 [coord-cross-review.md](../../../docs/architecture/coord-cross-review.md) 完成仲裁。本节 v2.1 改为"对齐状态"，并标注落实情况。
|
||||
|
||||
| # | 议题（v1 提请） | coord 裁决结论（004 §15.3） | data-ana 文档对齐状态（v2） |
|
||||
| # | 议题（v1 提请） | coord 裁决结论（coord-cross-review.md） | data-ana 文档对齐状态（v2.1） |
|
||||
| --- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| 1 | **data-ana 是否发布 `edu.insight.mastery.updated` 事件** | §15.3 #6：派生数据事件豁免 Outbox，允许直接 Kafka producer | ✅ v2 已对齐：§3 标注"豁免 Outbox"，阶段 2 §5.2 设计直接 producer 链路 |
|
||||
| 2 | **data-ana / ai 是否需要实现 gRPC server** | §4.2 gRPC 启用阶段矩阵：P4 content + data-ana 启用 | ✅ v2 已对齐：§1 标注"gRPC=50055 P4 启用"，阶段 2 §1 分层图含 grpc.aio Server |
|
||||
| 3 | **CDC 直连 vs Outbox 领域事件双通道** | §15.3 #6 + ADR-008：维持 CDC 为主通道；events.proto 作为业务语义补充，待 P4 后期评估是否双消费 | ✅ v2 已对齐：§3 双通道说明 + 标注"领域事件为备通道" |
|
||||
| 4 | **data-ana DataScope 过滤实现位置** | §15.3 #5：iam 新增 `GetEffectiveDataScope` gRPC RPC（P4 补全）；data-ana 在 ClickHouse 查询 SQL 拼接时注入 WHERE | ✅ v2 已对齐：§3 列出 iam.proto 调用契约；阶段 2 §6.1 设计 `inject_data_scope` Depends |
|
||||
| 5 | **data-ana ClickHouse DDL 管理位置** | §15.3 #7：采纳 `infra/clickhouse/ddl/`（coord 建立），data-ana 提供 DDL 内容 | ✅ v2 已对齐：阶段 2 §3 标注"DDL 文件由 coord 统一管理在 `infra/clickhouse/ddl/`" |
|
||||
| 6 | **新增 `edu.insight.ai.usage` topic**（v1 阶段 2 §8.3 #3 提请） | §15.3 #4：补登，见 004 §7.2 | ✅ v2 已对齐：阶段 2 §5.1 列出消费此 topic |
|
||||
| 7 | **iam GetEffectiveDataScope proto 新增**（v1 阶段 2 §8.3 #2 提请） | §15.3 #5：P4 补全 | ✅ v2 已对齐：§3 列出 iam.proto 调用契约 |
|
||||
| 1 | **data-ana 是否发布 `edu.insight.mastery.updated` 事件** | §3.3：派生数据事件豁免 Outbox，允许直接 Kafka producer | ✅ v2 已对齐：§3 标注"豁免 Outbox"，阶段 2 §5.2 设计直接 producer 链路 |
|
||||
| 2 | **data-ana / ai 是否需要实现 gRPC server** | §2.1：P4 content + data-ana 启用 gRPC | ✅ v2 已对齐：§1 标注"gRPC=50055 P4 启用"，阶段 2 §1 分层图含 grpc.aio Server |
|
||||
| 3 | **CDC 直连 vs Outbox 领域事件双通道** | §3.3 + ADR-008：维持 CDC 为主通道；events.proto 作为业务语义补充，待 P4 后期评估是否双消费 | ✅ v2 已对齐：§3 双通道说明 + 标注"领域事件为备通道" |
|
||||
| 4 | **data-ana DataScope 过滤实现位置** | §2 #3：iam 新增 `GetEffectiveDataScope` gRPC RPC（P4 补全）；data-ana 在 ClickHouse 查询 SQL 拼接时注入 WHERE | ✅ v2 已对齐：§3 列出 iam.proto 调用契约；阶段 2 §6.1 设计 `inject_data_scope` Depends |
|
||||
| 5 | **data-ana ClickHouse DDL 管理位置** | §4：采纳 `infra/clickhouse/ddl/`（coord 建立），data-ana 提供 DDL 内容 | ✅ v2 已对齐：阶段 2 §3 标注"DDL 文件由 coord 统一管理在 `infra/clickhouse/ddl/`" |
|
||||
| 6 | **新增 `edu.insight.ai.usage` topic**（v1 阶段 2 §8.3 #3 提请） | §3.2：补登，见 004 §7.2；**events.proto AIUsageEvent message 待 coord 补充** | ✅ v2 已对齐：阶段 2 §5.1 列出消费此 topic；⚠️ events.proto 缺 AIUsageEvent 定义 |
|
||||
| 7 | **iam GetEffectiveDataScope proto 新增**（v1 阶段 2 §8.3 #2 提请） | §2 #3：P4 补全；**当前 iam.proto 仅 4 RPC，未实现，P4 阻塞项** | ✅ v2 已对齐：§3 列出 iam.proto 调用契约；⚠️ iam.proto 未实现 |
|
||||
|
||||
> v1 §8.3 "未决设计决策"3 项全部已被 coord 仲裁，v2 不再列为"未决"。文档后续修订如发现新冲突，按 ai-allocation.md §9.4 proto 变更流程提请 coord。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user