add windmill instructions

windmill/README.md

@@ -0,0 +1,73 @@
+
+
+Read file: /Users/liam/code/shorturl-analytics/windmill/sync_shorturl_from_mongo_to_clickhouse.ts
+
+Read file: /Users/liam/code/shorturl-analytics/windmill/sync_shorturl_from_mongo_to_clickhouse.ts
+
+Read file: /Users/liam/code/shorturl-analytics/windmill/sync_shorturl_event_from_mongo.ts
+
+Read file: /Users/liam/code/shorturl-analytics/windmill/sync_shorturl_event_from_mongo.ts
+
+Read file: /Users/liam/code/shorturl-analytics/windmill/sync_shorturl_from_mongo_to_clickhouse.ts
+
+Read file: /Users/liam/code/shorturl-analytics/windmill/sync_shorturl_event_from_mongo.ts
+这两个脚本是使用 Windmill 平台开发的数据同步工具，用于将短链接相关数据从 MongoDB 数据库同步到 ClickHouse 数据库。
+
+## 1. sync_shorturl_from_mongo_to_clickhouse.ts
+
+**功能**: 将 MongoDB 中的短链接数据（short 表）同步到 ClickHouse 的 links 表
+
+**主要特点**:
+- 增量同步: 记录上次同步位置，只处理新增数据
+- 批量处理: 默认每批次处理 100 条记录，可配置
+- 超时控制: 设置最大运行时间（默认 30 分钟）
+- 数据重复检查: 检查 ClickHouse 中是否已存在相同记录
+- 错误处理: 完善的错误处理和日志记录
+
+**数据转换**:
+- 将 MongoDB 中的短链接记录（包含 slug、origin、创建时间等）转换为 ClickHouse 表结构
+- 处理特殊字段如日期时间、标签数组等
+- 转换字段包括: link_id、original_url、created_at、created_by、title、description、tags、is_active、expires_at、team_id、project_id
+
+**执行流程**:
+1. 从 Windmill 变量获取 MongoDB 和 ClickHouse 连接配置
+2. 获取上次同步状态（时间戳和记录ID）
+3. 连接 MongoDB，批量查询符合条件的新记录
+4. 检查这些记录是否已存在于 ClickHouse
+5. 转换数据格式并生成 SQL 插入语句
+6. 执行插入操作并记录结果
+7. 更新同步状态，为下次同步做准备
+
+## 2. sync_shorturl_event_from_mongo.ts
+
+**功能**: 将 MongoDB 中的短链接点击事件数据（trace 表）同步到 ClickHouse 的 link_events 表
+
+**主要特点**:
+- 与第一个脚本类似，但处理的是访问事件数据
+- 默认批量处理规模更大（1000 条/批次）
+- 超时时间更长（60 分钟）
+- 支持完整的事件元数据保存
+
+**数据转换**:
+- 将 MongoDB 中的访问事件记录转换为 ClickHouse 事件表结构
+- 记录的字段更丰富，包括:
+  - link_id: 短链接ID
+  - visitor_id: 访客ID
+  - session_id: 会话ID
+  - event_type: 事件类型（点击、转化等）
+  - 设备信息: ip_address、user_agent、device_type、browser、os
+  - 来源信息: referrer、utm 参数
+  - 行为数据: time_spent_sec、is_bounce、conversion_type 等
+
+**执行流程**:
+与第一个脚本基本相同，但处理的是 trace 表的数据，并且将其转换为 link_events 表所需的格式。
+
+## 两者共同点:
+
+1. **增量同步机制**: 记录同步状态，每次只处理新数据
+2. **容错设计**: 超时控制、错误处理、异常恢复机制
+3. **配置灵活**: 可通过参数控制批量大小、超时时间等
+4. **数据验证**: 确保已同步数据不会重复
+5. **详细日志**: 记录同步过程中的关键事件和状态
+
+这两个脚本共同构成了短链接分析系统的数据管道，实现了从 MongoDB（可能是原始数据存储）到 ClickHouse（分析型数据库）的数据迁移，为短链接分析平台提供数据基础。