# 地图配置指南

## 当前状态

系统当前使用**占位地图模式**，这是一个功能完整的地图演示方案，允许您在不配置 API Key 的情况下使用所有地图相关功能。

> **✅ 占位地图模式的优势：**
> - 无需注册任何地图服务
> - 所有功能正常可用（标记、绘图、测量等）
> - 零配置，开箱即用
> - 适合开发、测试和演示

## 如果需要真实地图

如果您希望显示真实的卫星影像和街道地图，有两个选择：

### 选项 1: 使用 Leaflet + OpenStreetMap（推荐，免费）

Leaflet 使用免费的 OpenStreetMap 数据，无需 API Key。

**步骤：**

1. 确保组件中使用 `provider="leaflet"` 参数（已默认配置）

```tsx
<BaseMap
  provider="leaflet"  // 使用 Leaflet
  initialCenter={[116.4074, 39.9042]}
  initialZoom={13}
/>
```

2. Leaflet 会自动从 CDN 加载，首次加载可能需要几秒钟

**Leaflet 提供的地图图层：**
- 🗺️ 街道地图：OpenStreetMap
- 🛰️ 卫星影像：ArcGIS World Imagery
- ⛰️ 地形图：OpenTopoMap

### 选项 2: 使用高德地图（需要注册）

如果您需要更详细的中国地图数据，可以使用高德地图。

**步骤：**

#### 1. 注册高德开放平台账号

访问：https://console.amap.com/

#### 2. 创建应用并获取 Key

1. 登录控制台
2. 进入"应用管理" → "我的应用"
3. 点击"创建新应用"
4. 填写应用信息
5. 点击"添加Key"，选择 "Web端(JS API)"
6. 获取两个值：
   - **Key** (API Key)
   - **安全密钥** (Security JS Code)

#### 3. 配置 API Key

编辑文件 `/lib/mapLoader.ts`：

```typescript
const AMAP_CONFIG = {
  // 替换为你的高德地图API Key
  key: '你的API_KEY',
  
  // 替换为你的安全密钥
  securityJsCode: '你的SECURITY_JS_CODE',
  
  version: '2.0',
  plugins: [],
};
```

#### 4. 在组件中使用

```tsx
<BaseMap
  provider="amap"  // 使用高德地图
  initialCenter={[116.4074, 39.9042]}
  initialZoom={13}
/>
```

**高德地图提供的图层：**
- 🗺️ 电子地图：详细的街道、建筑、POI
- 🛰️ 卫星影像：高清卫星图片
- ⛰️ 地形图：高程数据
- 🔀 混合图层：卫星影像 + 道路标注

## 当前系统中的地图使用

系统中以下模块使用了地图组件：

### 1. 地块管理
- **地块 GIS 地图** (`/components/field/FieldGISMap.tsx`)
  - 当前使用: `provider="leaflet"`
  - 功能: 地块空间分布、绘制、查询

### 2. 土壤数据
- **土壤采样点分布** (`/components/field/SoilBaseData.tsx`)
  - 当前使用: 默认 provider
  - 功能: 采样点标记、空间分析

### 3. 农机管理
- **农机实时定位** (多个组件)
  - 功能: 实时位置追踪、轨迹回放

### 4. 地理围栏
- **围栏管理** (`/components/machinery/security/`)
  - 功能: 绘制围栏、报警管理

## 地图功能对比

| 功能 | 占位地图 | Leaflet | 高德地图 |
|------|---------|---------|----------|
| 标记点 | ✅ | ✅ | ✅ |
| 绘制多边形 | ✅ | ✅ | ✅ |
| 测距工具 | ✅ | ✅ | ✅ |
| 图层切换 | ✅ | ✅ | ✅ |
| 真实地图 | ❌ | ✅ | ✅ |
| 中国地图优化 | ❌ | ⚠️ | ✅ |
| 需要 API Key | ❌ | ❌ | ✅ |
| 费用 | 免费 | 免费 | 免费额度* |

*高德地图：个人开发者每日免费配额 30万次

## 常见问题

### Q: 为什么显示"地图演示模式"？

A: 系统检测到未配置真实地图 API Key，自动切换到占位地图模式。这是正常行为，所有功能仍然可用。

### Q: 占位地图可以用于生产环境吗？

A: 占位地图主要用于开发和演示。生产环境建议配置真实地图服务以获得更好的用户体验。

### Q: Leaflet 地图加载失败怎么办？

A: Leaflet 从 unpkg.com CDN 加载。如果网络环境无法访问该 CDN，可以：
1. 使用国内 CDN 镜像
2. 本地部署 Leaflet 库
3. 使用高德地图（国内服务）

### Q: 高德地图配置后仍然显示占位地图？

A: 检查以下几点：
1. API Key 是否正确填写（没有空格）
2. 安全密钥是否配置
3. 浏览器控制台是否有错误信息
4. 是否已刷新页面清除缓存

### Q: 如何切换默认地图提供商？

A: 修改 BaseMap 组件的默认参数：

```typescript
// /components/shared/BaseMap.tsx
export const BaseMap = forwardRef<BaseMapRef, BaseMapProps>((
  {
    provider = 'leaflet',  // 改为 'amap' 或 'placeholder'
    ...
  }
))
```

## 性能建议

1. **开发环境**: 使用占位地图，快速开发
2. **测试环境**: 使用 Leaflet，无需 API Key
3. **生产环境**: 根据需求选择 Leaflet 或高德地图

## 技术支持

如需更多帮助，请查看：
- Leaflet 文档: https://leafletjs.com/
- 高德地图 JS API 文档: https://lbs.amap.com/api/jsapi-v2/summary
- OpenStreetMap: https://www.openstreetmap.org/

## 更新日志

- **2025-10-25**: 优化占位地图显示效果，添加配置指南
- **2025-10-25**: 默认使用 Leaflet，提供免费地图方案
