数据仓（yidun-mplatform-clickhouse）
判定产生的海量明细在这里入仓，看板与报表从这里取数。读写分离：
mq只写，facade只读。
1. 业务定位
承担两个方向：
| 方向 | 链路 |
|---|---|
| 明细入库 | 各业务 Kafka 消息 → dwd_* 明细表 |
| 统计出库 | ads_*_view_all 预聚合 / dwd_*_all 明细 → Dubbo 查询接口 |
消费的消息包括名单命中（Yidun_Mp_List_Hit）、规则命中（Yidun_Mp_Rule_Hit）、策略命中、内容安全统计、智能风控/反打金/工作室/处置明细等。
2. 架构与模块划分
| 模块 | 类型 | 职责 |
|---|---|---|
common、domain | jar | 错误码、操作符、风险等级常量、DO |
service/base | jar | DAO + Manager + MyBatis mapper（ClickHouse SQL） |
service/business | jar | 业务编排 |
mq | app | 各 *SinkClickHouseConsumer 明细入库 |
facade/dubbo-api + dubbo-provider | Dubbo | 统计查询契约与实现 |
3. 核心链路
入库失败由 *RecordRecover 负责重试，避免单条坏数据阻塞批次。
4. 查询契约
| 契约 | 场景 |
|---|---|
ListHitFacade | 名单命中统计 |
RuleHitFacade | 规则命中统计 |
ReportStatFacade | 举报统计 |
DisposeInfoStatFacade | 处置统计 |
AntiGoldClusterStatFacade | 反打金团伙统计 |
AntispamDataStatFacade | 内容安全统计 |
IRiskCheckDetailStatFacade | 智能风控检测明细 |
IRiskDashboard*StatFacade | 智能风控看板 |
IRiskStudioResultStatFacade | 工作室识别统计 |
IRiskPiracyStatFacade | 盗版统计 |
5. 数据源划分
ClickHouse 分三套数据源，由 clickhouse.datasource.* 开关装配：
| 数据源 | 承载 |
|---|---|
iRisk | 智能风控（检测明细、看板、工作室、盗版） |
antispam | 内容安全 |
mplatform | 平台侧命中、举报、处置、反打金 |
库表约定：
- 写侧：本地明细表
dwd_*。 - 读侧：
dwd_*_all（明细查询）与ads_*_view_all（统计看板）。 - 建表 DDL 不在本仓库，由数仓侧维护。
6. 设计模式与扩展点
| 扩展点 | 位置 | 说明 |
|---|---|---|
| 新明细类型 | mq 下新增 *SinkClickHouseConsumer + Manager + Dao | 接入新 topic |
| 失败恢复 | *RecordRecover | 单条失败重试 |
| 新查询契约 | facade/dubbo-api 新增 Facade + Provider | 对外提供新统计 |
| 分页换算 | Provider 层 offset/page 转换 | 统一分页语义 |
7. 上下游依赖
| 方向 | 模块 | 说明 |
|---|---|---|
| 上游 | checker-rule、checker-namelist、mplatform-strategy、intelligent-risk、mplatform-event | Kafka 明细来源 |
| 下游 | intelligent-risk | 看板、处置、反打金统计 |
| 下游 | checker-rule、checker-namelist | 命中统计调度 |
8. 工程约束与变更红线
- 读写分离不可打破：
mq只写、facade只读，混用会导致数据源竞争。 - 批量写入是硬要求：逐条 insert 在 ClickHouse 上会写放大。
- 看板口径由表决定：查询
ads_*_view_all与dwd_*的结果天然不同，改表等于改口径。 - DDL 变更走数仓：本仓库没有建表语句，私自加字段会在线上失败。
- 消费失败必须可重放：依赖
*RecordRecover，不要吞异常。
9. 关键代码索引
| 主题 | 路径 | 说明 |
|---|---|---|
| 名单命中入库 | yidun-mplatform-clickhouse/mq/src/main/java/.../consumer/ListHitSinkClickHouseConsumer.java | Kafka → dwd |
| 规则命中入库 | yidun-mplatform-clickhouse/mq/src/main/java/.../consumer/RuleHitSinkClickHouseConsumer.java | Kafka → dwd |
| 查询契约 | yidun-mplatform-clickhouse/facade/dubbo-api/src/main/java/.../api/ListHitFacade.java | 名单命中统计 |
| 查询实现 | yidun-mplatform-clickhouse/facade/dubbo-provider/src/main/java/.../provider/ListHitProvider.java | Provider 层 |
| 数据源配置 | yidun-mplatform-clickhouse/service/base/src/main/java/.../component/ch/ | 三套数据源 |
| SQL 映射 | yidun-mplatform-clickhouse/service/base/src/main/resources/mybatis/mappers/ | ClickHouse SQL |
10. 排查要点
| 现象 | 定位 | 结论 |
|---|---|---|
| 看板数据为 0 | 查上游是否投递 topic | 判定被短路，明细根本没产生 |
| 明细有、看板少 | 看预聚合表刷新 | ads_*_view_all 依赖数仓刷新 |
| 某段时间数据缺失 | 看 Kafka 堆积与消费位点 | 消费中断或 *RecordRecover 积压 |
| 相同查询结果不一致 | 确认查的是 dwd_* 还是 ads_*_view_all | 表不同，口径不同 |
| 查询超时 | 看时间范围与分页 | 大范围扫明细表，应走预聚合 |