WIP feat: 添加 l7 map skills

skills/l7/COMPLETENESS_REPORT.md

@@ -0,0 +1,365 @@
+# L7 Skills 文档完备性分析报告
+
+生成时间：2026年1月26日
+
+## 📊 概览
+
+本报告基于 L7 官方 API 文档（site/docs/api）与当前 Skills 文档（skills/references）的对比分析。
+
+### 现有 Skills 文档统计
+
+**总计：20 个文档**
+
+#### 按目录分类：
+
+- **Core（核心）**: 3 个
+  - scene.md (场景初始化)
+  - scene-lifecycle.md (场景生命周期)
+  - scene-methods.md (场景方法)
+
+- **Data（数据）**: 4 个
+  - source-geojson.md
+  - source-csv.md
+  - source-json.md
+  - source-parser.md
+
+- **Layers（图层）**: 6 个
+  - point.md (点图层)
+  - line.md (线图层)
+  - polygon.md (面图层)
+  - heatmap.md (热力图)
+  - image.md (图片图层)
+  - raster.md (栅格图层)
+
+- **Visual（视觉）**: 2 个
+  - mapping.md (视觉映射)
+  - style.md (样式配置)
+
+- **Interaction（交互）**: 3 个
+  - events.md (事件处理)
+  - popup.md (弹窗)
+  - components.md (组件)
+
+- **Animation（动画）**: 1 个
+  - layer-animation.md (图层动画)
+
+- **Performance（性能）**: 1 个
+  - optimization.md (性能优化)
+
+---
+
+## ✅ 已覆盖的核心功能
+
+### 1. Scene 场景 ✅
+
+- ✅ 场景初始化
+- ✅ 场景生命周期
+- ✅ 场景方法（完整的 API）
+
+### 2. 基础图层 ✅
+
+- ✅ PointLayer（点图层）
+- ✅ LineLayer（线图层）
+- ✅ PolygonLayer（面图层）
+- ✅ HeatmapLayer（热力图）
+- ✅ ImageLayer（图片图层）
+- ✅ RasterLayer（栅格图层）
+
+### 3. 数据源 ✅
+
+- ✅ GeoJSON
+- ✅ CSV
+- ✅ JSON
+- ✅ Parser（解析器）
+
+### 4. 视觉编码 ✅
+
+- ✅ 颜色、大小、形状映射
+- ✅ 样式配置
+
+### 5. 交互功能 ✅
+
+- ✅ 事件处理
+- ✅ Popup
+- ✅ Components（Marker、Controls、Legend）
+
+### 6. 动画和性能 ✅
+
+- ✅ 图层动画
+- ✅ 性能优化
+
+---
+
+## ❌ 缺失的重要功能
+
+### 🔴 高优先级（推荐补充）
+
+#### 1. 地图引擎配置（Map）
+
+**官方文档位置**: `site/docs/api/map/`
+
+缺失内容：
+
+- ❌ **GaodeMap**（高德地图）- 最常用的底图
+- ❌ **Mapbox**（Mapbox 地图）
+- ❌ **MapLibre**（开源地图）
+- ❌ **Map**（独立地图引擎）
+- ❌ BMap（百度地图）
+- ❌ Tencent（腾讯地图）
+- ❌ Tianditu（天地图）
+- ❌ Leaflet
+
+**推荐新增文档**:
+
+- `skills/references/core/map-types.md` - 地图类型配置（已在 index.md 中引用但未实现）
+
+#### 2. 瓦片图层（Tile Layers）
+
+**官方文档位置**: `site/docs/api/tile/`
+
+缺失内容：
+
+- ❌ **VectorTileLayer**（矢量瓦片）- 重要的大数据渲染方案
+- ❌ **RasterTileLayer**（栅格瓦片）
+- ❌ **GeoJSONVTTileLayer**（GeoJSON 切片）
+- ❌ **TileDebugLayer**（瓦片调试）
+
+**推荐新增文档**:
+
+- `skills/references/layers/tile-vector.md`
+- `skills/references/layers/tile-raster.md`
+
+#### 3. 数据源补充
+
+**官方文档位置**: `site/docs/api/source/`
+
+缺失内容：
+
+- ❌ **MVT**（Mapbox Vector Tile）- 矢量瓦片数据源
+- ❌ **Image** 数据源
+- ❌ **Raster** 数据源
+- ❌ **RasterTile** 数据源
+- ❌ **NDI** 数据源（遥感影像）
+- ❌ **RGB** 数据源（遥感影像）
+
+**推荐新增文档**:
+
+- `skills/references/data/source-mvt.md`
+- `skills/references/data/source-raster.md`
+
+#### 4. 图层通用特性
+
+**官方文档位置**: `site/docs/api/base_layer/` 和各图层的子页面
+
+缺失内容：
+
+- ❌ **BaseLayer**（图层基类）- 所有图层的通用方法
+- ❌ **Layer Options**（图层配置）
+- ❌ **Layer Methods**（图层方法：show/hide/fitBounds/setIndex 等）
+- ❌ **Layer Events**（图层事件：click/mousemove/mouseout 等）
+
+每个图层类型都有详细的子文档：
+
+- ❌ color.md（颜色映射详解）
+- ❌ size.md（大小映射详解）
+- ❌ shape.md（形状类型详解）
+- ❌ scale.md（数据映射详解）
+- ❌ animate.md（动画配置详解）
+- ❌ style.md（样式配置详解）
+- ❌ source.md（数据源配置详解）
+- ❌ options.md（图层配置详解）
+
+**推荐新增文档**:
+
+- `skills/references/layers/base-layer.md` - 图层基类和通用方法
+- `skills/references/layers/layer-events.md` - 图层事件详解
+
+#### 5. 高级组件
+
+**官方文档位置**: `site/docs/api/component/`
+
+部分缺失：
+
+- ✅ Marker（已包含在 components.md）
+- ✅ Popup（已有独立文档）
+- ✅ Control（已包含在 components.md）
+- ❌ **MarkerLayer**（Marker 统一管理）
+- ❌ **LayerPopup**（图层绑定弹窗）
+- ❌ **Zoom** 控件（缩放控制）
+- ❌ **Scale** 控件（比例尺）
+- ❌ **Logo** 控件
+- ❌ **Fullscreen** 控件（全屏控制）
+- ❌ **ExportImage** 控件（导出图片）
+- ❌ **MapTheme** 控件（地图主题切换）
+- ❌ **MouseLocation** 控件（鼠标位置显示）
+- ❌ **Geolocate** 控件（定位控制）
+- ❌ **LayerSwitch** 控件（图层切换）
+- ❌ **Swipe** 控件（卷帘对比）
+
+**推荐新增文档**:
+
+- `skills/references/interaction/controls.md` - 各类控件详解
+- `skills/references/interaction/layer-popup.md` - 图层弹窗
+- `skills/references/interaction/marker-layer.md` - MarkerLayer
+
+### 🟡 中优先级（可选补充）
+
+#### 6. React 组件
+
+**官方文档位置**: `site/docs/api/react/`
+
+- ❌ React 绑定和组件封装
+
+**推荐新增文档**:
+
+- `skills/references/frameworks/react.md`
+
+#### 7. 其他特殊图层
+
+**官方文档位置**: `site/docs/api/other/`
+
+- ❌ **MaskLayer**（遮罩图层）
+- ❌ **WindLayer**（风场图层）
+- ❌ **CanvasLayer**（Canvas 图层）
+- ❌ **CityBuildingLayer**（城市建筑）
+- ❌ **GeometryLayer**（几何图层）
+- ❌ **EarthLayer**（地球图层）
+
+**推荐新增文档**:
+
+- `skills/references/layers/other-layers.md`（已在 index.md 引用但内容不完整）
+
+#### 8. 高级特性
+
+**官方文档位置**: `site/docs/api/experiment/` 和 `site/docs/api/debug/`
+
+- ❌ 实验性功能
+- ❌ 调试工具
+
+### 🟢 低优先级（补充性内容）
+
+#### 9. 纹理（Texture）
+
+- ❌ 线图层纹理配置（`line_layer/texture.md`）
+
+#### 10. 教程内容
+
+**官方文档位置**: `site/docs/tutorial/`
+
+当前 skills 主要关注 API，教程性内容较少。
+
+---
+
+## 📋 具体建议补充清单
+
+### 第一批（核心必备，共 5 个）
+
+1. ✅ `skills/references/core/map-types.md` - 地图引擎配置（高德、Mapbox、MapLibre、Map）
+2. ✅ `skills/references/layers/base-layer.md` - 图层基类和通用方法
+3. ✅ `skills/references/layers/tile-vector.md` - 矢量瓦片图层
+4. ✅ `skills/references/data/source-mvt.md` - MVT 数据源
+5. ✅ `skills/references/interaction/controls.md` - 控件详解（Zoom、Scale、Fullscreen 等）
+
+### 第二批（功能完善，共 5 个）
+
+6. `skills/references/layers/layer-events.md` - 图层事件详解
+7. `skills/references/interaction/layer-popup.md` - 图层弹窗
+8. `skills/references/interaction/marker-layer.md` - MarkerLayer
+9. `skills/references/layers/tile-raster.md` - 栅格瓦片图层
+10. `skills/references/data/source-raster.md` - 栅格数据源
+
+### 第三批（深度扩展，共 5 个）
+
+11. `skills/references/visual/color-mapping.md` - 颜色映射详解
+12. `skills/references/visual/size-mapping.md` - 大小映射详解
+13. `skills/references/visual/shape-types.md` - 形状类型详解
+14. `skills/references/layers/mask.md` - 遮罩图层
+15. `skills/references/frameworks/react.md` - React 集成
+
+---
+
+## 📊 完备性评分
+
+| 类别                                   | 完备度           | 评分       |
+| -------------------------------------- | ---------------- | ---------- |
+| 核心场景（Scene）                      | ███████████ 100% | ⭐⭐⭐⭐⭐ |
+| 基础图层（Point/Line/Polygon/Heatmap） | ██████████░ 95%  | ⭐⭐⭐⭐⭐ |
+| 数据源（GeoJSON/CSV/JSON）             | ████████░░░ 75%  | ⭐⭐⭐⭐   |
+| 地图引擎配置                           | ░░░░░░░░░░░ 0%   | ⭐         |
+| 瓦片图层                               | ░░░░░░░░░░░ 0%   | ⭐         |
+| 视觉编码                               | ████████░░░ 80%  | ⭐⭐⭐⭐   |
+| 交互组件                               | ██████░░░░░ 60%  | ⭐⭐⭐     |
+| 动画                                   | ████████░░░ 80%  | ⭐⭐⭐⭐   |
+| 性能优化                               | ████████░░░ 80%  | ⭐⭐⭐⭐   |
+| 框架集成                               | ░░░░░░░░░░░ 0%   | ⭐         |
+
+**总体完备度：约 57%**
+
+---
+
+## 🎯 优先级行动建议
+
+### 立即补充（Week 1）
+
+1. **地图引擎配置** - 这是使用 L7 的第一步，非常重要
+2. **图层基类文档** - 帮助理解所有图层的通用特性
+3. **控件详解** - 完善交互功能文档
+
+### 短期补充（Week 2-3）
+
+4. **矢量瓦片** - 大数据渲染的核心方案
+5. **MVT 数据源** - 配合矢量瓦片使用
+6. **图层事件** - 完善交互功能
+
+### 中期补充（Month 2）
+
+7. 各图层的详细子文档（color/size/shape/scale）
+8. 高级组件（LayerPopup、MarkerLayer 等）
+9. 特殊图层（Mask、Wind 等）
+
+### 长期补充（Month 3+）
+
+10. React 框架集成
+11. 实验性功能
+12. 调试工具
+
+---
+
+## 💡 文档结构建议
+
+当前 skills 文档结构清晰，建议保持：
+
+```
+skills/references/
+├── core/          # 核心功能（Scene、Map）
+├── data/          # 数据源
+├── layers/        # 图层类型
+├── visual/        # 视觉编码
+├── interaction/   # 交互功能
+├── animation/     # 动画
+├── performance/   # 性能优化
+└── frameworks/    # 框架集成（新增）
+```
+
+---
+
+## 📝 总结
+
+**优点**：
+
+- ✅ 核心场景（Scene）文档非常完善，包含生命周期和方法
+- ✅ 基础图层（6 种主要图层）都已覆盖
+- ✅ 基础数据源（GeoJSON/CSV/JSON）齐全
+- ✅ 文档结构清晰，遵循统一规范
+- ✅ 代码示例丰富，实用性强
+
+**不足**：
+
+- ❌ 缺少地图引擎配置文档（这是使用 L7 的第一步）
+- ❌ 缺少瓦片图层（大数据场景的核心方案）
+- ❌ 控件文档不够详细（只有概述，缺少各控件的详细用法）
+- ❌ 缺少图层通用特性文档（BaseLayer）
+- ❌ 缺少框架集成文档（React）
+
+**建议**：
+优先补充前 5 个文档（地图引擎、图层基类、矢量瓦片、MVT、控件详解），可将完备度提升至 75% 以上。