Initial Commit

utils/map-setup.md

@@ -0,0 +1,118 @@
+# 高德地图小程序集成配置说明
+
+## 1. 申请高德地图API Key
+
+1. 访问高德开放平台：https://lbs.amap.com/dev/
+2. 注册开发者账号并实名认证
+3. 创建应用，选择"微信小程序"平台
+4. 获取API Key，复制到 `config/config.js` 的 `amapKey` 字段
+
+## 2. 配置微信小程序合法域名
+
+在微信小程序后台（mp.weixin.qq.com）的"开发设置"中添加以下合法域名：
+
+**request合法域名：**
+- https://restapi.amap.com
+
+**uploadFile合法域名：**
+- https://restapi.amap.com
+
+**downloadFile合法域名：**
+- https://restapi.amap.com
+
+## 3. 位置权限配置
+
+app.json 中已配置位置权限：
+```json
+{
+  "permission": {
+    "scope.userLocation": {
+      "desc": "你的位置信息将用于小程序位置接口的效果展示"
+    }
+  },
+  "requiredBackgroundModes": ["location"],
+  "requiredPrivateInfos": ["getLocation"]
+}
+```
+
+## 4. 使用的功能
+
+当前实现的地图功能包括：
+
+### 基础功能
+- GPS定位获取当前位置
+- 高德地图逆地理编码（经纬度转地址）
+- 地图标记显示
+- 位置权限管理
+- 定时位置更新
+
+### 高级功能
+- 好友位置显示
+- 附近用户搜索
+- 位置距离计算
+- 地图区域自适应
+- 位置隐私保护
+
+### API集成
+- 与后端位置服务完整对接
+- 支持位置上传和好友位置获取
+- 附近用户搜索功能
+- 位置历史记录
+
+## 5. 文件结构
+
+```
+miniprogram/
+├── libs/
+│   └── amap-wx.js          # 高德地图SDK
+├── utils/
+│   ├── map-config.js       # 地图配置和工具类
+│   └── api-client.js       # API客户端（已添加位置相关方法）
+├── pages/map/
+│   ├── map.js              # 地图页面逻辑
+│   ├── map.wxml            # 地图页面模板
+│   └── map.wxss            # 地图页面样式
+└── config/
+    └── config.js           # 配置文件（需要添加amapKey）
+```
+
+## 6. 注意事项
+
+1. **API Key安全**：不要将API Key提交到公开仓库
+2. **权限引导**：首次使用时会引导用户授权位置权限
+3. **网络环境**：高德API需要网络连接，注意处理网络异常
+4. **坐标系**：使用GCJ02坐标系（高德地图标准）
+5. **性能优化**：位置更新采用30秒间隔，避免频繁请求
+
+## 7. 测试建议
+
+1. 真机测试位置权限和定位功能
+2. 测试网络异常情况的处理
+3. 验证好友位置显示是否正常
+4. 检查地图标记和交互功能
+
+## 8. 故障排除
+
+### 定位失败
+- 检查位置权限是否开启
+- 确认网络连接正常
+- 验证高德API Key是否有效
+
+### 地址解析失败
+- 检查合法域名配置
+- 确认API Key额度是否充足
+- 验证网络请求是否被拦截
+
+### 地图显示异常
+- 检查坐标数据格式
+- 确认地图组件属性配置
+- 验证标记数据结构是否正确
+
+## 9. 扩展功能
+
+可以根据需要添加更多功能：
+- 路径规划和导航
+- POI搜索
+- 地理围栏
+- 轨迹回放
+- 多种地图图层