udpate

public/docs.md

@@ -0,0 +1,109 @@
+# 地图两点距离计算工具
+
+## 简介
+
+使用高德地图 API，输入起点地址和终点地址，自动计算两者之间的直线距离。
+
+## 快速开始
+
+### 1. 安装 Deno
+
+```bash
+# Linux/macOS (WSL)
+curl -fsSL https://deno.land/install.sh | sh
+
+# macOS
+brew install deno
+```
+
+### 2. 配置高德 API Key
+
+**申请步骤：**
+1. 访问 [高德开放平台](https://console.amap.com/dev/key/app)
+2. 注册/登录账号
+3. 点击「控制台」→「应用管理」→「创建新应用」
+4. 填写应用名称，点击「添加 Key」
+5. 勾选 **Web 服务** 权限
+6. 复制生成的 Key
+
+**配置环境变量：**
+
+在项目根目录创建 `.env` 文件：
+
+```bash
+AMAP_KEY=你的高德APIKey
+```
+
+### 3. 运行程序
+
+```bash
+deno run -A https://kevisual.xiongxiao.me/root/test-map-distance/index.ts
+```
+
+### 4. 查看结果
+
+程序运行完成后，会在当前目录生成 `distance-results.json` 文件：
+
+```json
+[
+  {
+    "from": "起点地址",
+    "to": "终点地址",
+    "distanceMeters": 1120000,
+    "distanceKm": "1120.00"
+  }
+]
+```
+
+## 本地开发
+
+代码路径：https://git.xiongxiao.me/test/test-map-distance
+
+### 目录结构
+
+```
+test-map-distance/
+├── .env              # 环境变量（API Key）
+├── address.json      # 地址列表配置
+├── distance-results.json  # 计算结果（自动生成）
+├── plan/
+│   └── v0.0.1.md     # 设计文档
+└── public/
+    └── docs.md       # 使用说明
+```
+
+### address.json 格式
+
+```json
+[
+  { "from": "北京市", "to": "上海市" },
+  { "from": "广州市", "to": "深圳市" }
+]
+```
+
+## 实现原理
+
+1. **地理编码**：使用高德地图 [地理编码 API](https://restapi.amap.com/v3/geocode/geo) 将地址转换为经纬度坐标
+2. **距离计算**：使用 Haversine 公式计算两点间的直线距离
+
+```typescript
+// Haversine 公式
+const R = 6371000; // 地球半径（米）
+const dLat = (to.lat - from.lat) * Math.PI / 180;
+const dLng = (to.lng - from.lng) * Math.PI / 180;
+const a = Math.sin(dLat/2)² + Math.cos(from.lat) * Math.cos(to.lat) * Math.sin(dLng/2)²;
+const distance = R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
+```
+
+## 常见问题
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| `USERKEY_PLAT_NOMATCH` | API Key 未启用 Web 服务 | 登录高德开放平台，勾选 Web 服务权限 |
+| `请在环境变量中设置 AMAP_KEY` | 未配置 .env 文件 | 创建 .env 文件并设置 AMAP_KEY |
+| `地址解析失败` | 地址无法被识别 | 使用更详细或更简化的地址 |
+
+## 参考链接
+
+- [高德开放平台](https://lbs.amap.com/)
+- [Deno 官方文档](https://deno.com/)