用途：为基于 ClickHouse 的分析类应用提供生产级参考架构，覆盖项目布局、数据流、多租户模式与运维拓扑，适合设计新平台或评审现有集成。
主要能力：
- 项目结构：SQL DDL 作为唯一事实来源放在 clickhouse/schemas/，命名查询函数放 clickhouse/queries/，迁移放 clickhouse/migrations/，另有 ingestion、api、jobs 等模块。
- 数据流：数据单向流动，源（Webhook、API、Kafka、S3）→ 批量摄取层（缓冲+批量，单次插入 1 万行以上）→ ClickHouse（原始 MergeTree → 物化视图 → 聚合表）→ API 只读聚合表 → 仪表盘。
- 三层表结构：原始追加事件表、小时聚合、日汇总，物化视图在 INSERT 时自动填充聚合。原始表骨架示例：CREATE TABLE analytics.events_raw (...) ENGINE = MergeTree() ORDER BY (tenant_id, event_type, toDate(created_at), user_id) PARTITION BY toYYYYMM(created_at) TTL created_at + INTERVAL 90 DAY; 完整 DDL 见 references/schema-design.md。
- 多租户：默认共享表并把 tenant_id 放在 ORDER BY 首位，可扩展到 1 万以上租户；另有每租户独立数据库、行级安全（RBAC）等方案及权衡。
- 客户端：使用单例 @clickhouse/client 与参数化查询，只读聚合表。
- 架构决策记录：涵盖引擎（MergeTree + AggregatingMergeTree）、多租户、摄取、聚合（物化视图而非定时任务）、格式（JSONEachRow）、压缩（字符串 ZSTD(3)、整数 Delta）。
使用方式：按五步走——先定项目结构，再理数据流，然后设计三层 Schema，选择多租户隔离策略，最后实现客户端模块；评审现有代码时可 Grep createClient( 定位客户端模块，并检查 API 层是否误查原始表。
适用场景：多租户分析平台设计、Node.js/TypeScript 仪表盘查询、现有 ClickHouse 集成评审。
限制：需先掌握 ClickHouse 基础（表引擎、ORDER BY 排序键、分区）；客户端示例基于 TypeScript/Node.js；多环境配置需另用 clickhouse-multi-env-setup 技能。常见问题包括跨租户泄漏（缺 WHERE tenant_id）、仪表盘数据陈旧（物化视图未建）、Schema 漂移（手工改 DDL）、查询慢（查了原始表）。