[FLUSS-2021] Add design documents for lake snapshot file storage migration

- Add detailed design document
- Add implementation code examples
- Add implementation checklist
- Add summary and guide

This addresses issue apache#2021: Move lake snapshot from ZK to file storage

Author: buvb

docs/design/issue-2021-lake-snapshot-migration/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,202 @@
+# Lake Snapshot 从 ZooKeeper 迁移到文件系统 - 实现指南
+
+> **Issue**: [#2021 - Consider move lake snapshot from zk to file just like did for kv snapshot](https://github.com/apache/fluss/issues/2021)
+
+## 📖 快速导航
+
+### 1️⃣ 首先阅读：总览
+- **[SUMMARY.md](SUMMARY.md)** - 问题背景、解决方案总览、工作量评估
+
+### 2️⃣ 深入理解：详细设计
+- **[lake-snapshot-migration-design.md](lake-snapshot-migration-design.md)** - 完整的技术设计文档
+  - 核心设计思路
+  - 数据结构设计
+  - 文件路径规范
+  - 向后兼容策略
+  - 详细实施步骤
+  - 风险和缓解措施
+
+### 3️⃣ 开始编码：代码示例
+- **[implementation-code-examples.md](implementation-code-examples.md)** - 完整的代码示例
+  - LakeTableSnapshotHandle 完整代码
+  - LakeTableSnapshotHandleJsonSerde 完整代码
+  - FlussPaths 新增方法
+  - ZooKeeperClient 核心修改
+  - CoordinatorEventProcessor 修改
+  - 测试代码示例
+
+### 4️⃣ 逐步实施：检查清单
+- **[implementation-checklist.md](implementation-checklist.md)** - 逐步实施指南
+  - 阶段 1: 新增基础数据结构
+  - 阶段 2: 添加路径工具方法
+  - 阶段 3: 修改 ZooKeeper 客户端
+  - 阶段 4: 修改 Coordinator 逻辑
+  - 阶段 5: 全面测试
+  - 阶段 6: 文档和代码审查
+
+---
+
+## 🎯 问题概述
+
+**当前状态**：
+- LakeTableSnapshot 完整存储在 ZooKeeper 中
+- 包含所有 bucket 的详细信息（log offsets, timestamps, partition info）
+- 数据量大，给 ZooKeeper 带来压力
+
+**目标状态**：
+- **文件系统**：存储完整的 LakeTableSnapshot 对象（大对象）
+- **ZooKeeper**：只存储轻量级的 LakeTableSnapshotHandle（小对象，指向文件）
+- 保持完全向后兼容
+
+---
+
+## 🏗️ 核心设计
+
+### 新增数据结构
+
+```java
+// 轻量级句柄，存储在 ZooKeeper 中
+public class LakeTableSnapshotHandle {
+    private final long snapshotId;
+    private final long tableId;
+    private final FsPath metadataFilePath;  // 指向文件的路径
+    
+    public LakeTableSnapshot retrieveLakeTableSnapshot() { ... }
+}
+```
+
+### 文件存储路径
+
+```
+{remote.data.dir}/lake-snapshots/{databaseName}/{tableName}-{tableId}/snapshot-{snapshotId}.json
+```
+
+示例：
+```
+hdfs://namenode/fluss-data/lake-snapshots/default/my_table-123/snapshot-1.json
+```
+
+### 版本化格式
+
+- **Version 1** (旧格式): 完整的 LakeTableSnapshot 存储在 ZK
+- **Version 2** (新格式): LakeTableSnapshotHandle 存储在 ZK，数据在文件中
+
+### 向后兼容
+
+```java
+// 读取时自动识别版本
+public Optional<LakeTableSnapshot> getLakeTableSnapshot(...) {
+    byte[] data = zkClient.getData(path);
+    int version = parseVersion(data);
+    
+    if (version == 1) {
+        return deserializeFromZK(data);  // 旧格式
+    } else if (version == 2) {
+        LakeTableSnapshotHandle handle = deserializeHandle(data);
+        return handle.retrieveLakeTableSnapshot();  // 新格式，从文件读取
+    }
+}
+```
+
+---
+
+## 📊 文件变更
+
+| 类型 | 文件 | 说明 |
+|------|------|------|
+| 新增 | `LakeTableSnapshotHandle.java` | 轻量级句柄类 |
+| 新增 | `LakeTableSnapshotHandleJsonSerde.java` | 序列化器 |
+| 修改 | `FlussPaths.java` | 添加路径工具方法 |
+| 修改 | `ZkData.java` | 添加 handle 的 encode/decode |
+| 修改 | `ZooKeeperClient.java` | 核心读写逻辑 |
+| 修改 | `CoordinatorEventProcessor.java` | 调用新 API |
+
+---
+
+## ⏱️ 工作量评估
+
+**总计：14-21 小时，建议 2-3 天完成**
+
+| 阶段 | 时间 |
+|------|------|
+| 基础数据结构 | 2-3h |
+| 路径工具方法 | 1-2h |
+| ZK 客户端修改 | 4-6h |
+| Coordinator 修改 | 2-3h |
+| 全面测试 | 3-4h |
+| 文档和审查 | 2-3h |
+
+---
+
+## 🚀 快速开始
+
+### Step 1: 阅读文档（30 分钟）
+```bash
+# 按顺序阅读
+1. SUMMARY.md                           # 总览
+2. lake-snapshot-migration-design.md    # 详细设计
+3. implementation-code-examples.md      # 代码示例
+```
+
+### Step 2: 环境准备（15 分钟）
+```bash
+# 确认配置
+- remote.data.dir 已配置
+- 文件系统可访问（HDFS/S3/本地）
+- ZooKeeper 可连接
+- 开发环境正常
+```
+
+### Step 3: 开始编码（按 checklist 执行）
+```bash
+# 打开实施清单
+implementation-checklist.md
+
+# 逐个阶段完成，勾选完成项
+# 每个阶段完成后运行测试
+```
+
+### Step 4: 提交 PR
+```bash
+# 确保所有测试通过
+mvn clean test
+
+# 创建 PR
+git checkout -b feature/issue-2021-lake-snapshot-file-storage
+git add .
+git commit -m "Move lake snapshot from ZK to file storage"
+git push origin feature/issue-2021-lake-snapshot-file-storage
+
+# 在 PR 中关联 Issue #2021
+```
+
+---
+
+## ✅ 关键检查点
+
+在提交 PR 前，确保：
+
+- [ ] 所有新增类都有单元测试
+- [ ] 所有修改的方法都有测试覆盖
+- [ ] 向后兼容性测试通过
+- [ ] 集成测试通过
+- [ ] 代码覆盖率 > 75%
+- [ ] 代码风格检查通过
+- [ ] 添加了必要的日志
+- [ ] 更新了相关文档
+
+---
+
+## 🤝 需要帮助？
+
+1. **查看代码示例**：`implementation-code-examples.md` 有完整的代码
+2. **参考现有实现**：查看 KV Snapshot 的实现
+   - `CompletedSnapshotHandle.java`
+   - `CompletedSnapshotStore.java`
+   - `ZooKeeperCompletedSnapshotHandleStore.java`
+3. **在 Issue 中提问**：https://github.com/apache/fluss/issues/2021
+
+---
+
+**祝你实现顺利！💪🚀**
+