先取数据，再安全入库。

这页文档随项目一起运行，不加载外部 CDN。下面先说明数据来源和凭据，再列出后端实际开放的接口。

01数据源高德或已授权运营商

02采集与转换Provider 统一字段

03项目数据库小程序查询展示

CREDENTIALS

两个 Key，方向正好相反

后台生成的 Key 不是“数据源 Key”。它只保护我们自己的入库接口。

向外读取

`AMAP_API_KEY`

在高德开放平台申请的 Web 服务凭据。内置高德采集器拿它查询充电站 POI。

谁签发: 高德开放平台
放在哪里: 服务端 .env
能做什么: 读取名称、地址、坐标等目录数据

向内写入

`nci_...`

在本项目后台生成的采集 Key。远程采集程序用它把标准 JSON 写入本站。

谁签发: 附近充电后台
放在哪里: X-Ingestion-Key 请求头
能做什么: 仅调用场站摄取接口，可撤销轮换

内置高德采集器不需要 nci_... Key。它和后端运行在同一环境，直接写本项目数据库；只有部署在别处的外部采集程序才需要入库 Key。

DATA ACCESS

现在如何获取一批充电站

当前内置实现使用高德 POI 目录，适合生成场站基础资料。

1
申请高德 Web 服务 Key
在高德控制台创建应用，添加类型为“Web 服务”的 Key。不要把 Key 写进小程序前端。
打开高德控制台 ↗

配置全国查询

把凭据写入项目根目录的真实 .env，不要只修改 .env.example：

AMAP_API_KEY=你的高德Web服务Key
AMAP_CITY_ADCODES=ALL
AMAP_KEYWORD=充电站
AMAP_MAX_PAGES_PER_REGION=100
AMAP_REQUEST_INTERVAL_MS=250

3
检查、探测并执行同步
配置检查不会显示 Key 原文。字段探测只访问高德公开 Web POI 接口，只输出字段名和能力判断且不修改数据库。全国任务按城市即时入库；中断后再次运行会从检查点继续。
```
cd backend
..\.venv\Scripts\python.exe -m app.collector check-config
..\.venv\Scripts\python.exe -m app.collector probe-amap-fields --region 320100
..\.venv\Scripts\python.exe -m app.collector sync-amap
```
4
设置定时运行
测试可使用常驻模式；生产环境建议交给 Windows 任务计划程序、systemd 或容器定时拉起。
```
..\.venv\Scripts\python.exe -m app.collector watch-amap --interval-hours 24
```

接入动态数据、手机界面采集或本地模拟

授权动态数据写入 POST /api/v1/ingestion/live-snapshots。根目录独立 mobile_collector 先从受保护任务接口读取数据库已有的高德场站，再分批控制专用 Android 手机补齐；默认 dry-run，只有显式 --upload 才写入。模拟快照仅供后台联调。

cd ..
.\.venv\Scripts\python.exe -m mobile_collector doctor
.\.venv\Scripts\python.exe -m mobile_collector collect-amap --station-id 37106
$env:NCI_INGESTION_KEY = "nci_后台创建的完整Key"
.\.venv\Scripts\python.exe -m mobile_collector collect-amap-batch --limit 20 --delay-seconds 2 --upload
Remove-Item Env:NCI_INGESTION_KEY
cd backend
..\.venv\Scripts\python.exe -m app.collector simulate-live --station-limit 20 --ttl-minutes 10
..\.venv\Scripts\python.exe -m app.collector clear-simulated-live

数据边界

全国同步请求量较大，受高德账号配额约束；配额恢复后重复执行即可继续。采集器会使用高德实际返回的名称、地址、坐标、POI 分类、商圈、营业时间、停车类型、联系电话、室内楼层和导航入口。高德公开 Web POI 文档没有承诺返回实时空闲枪、快慢充数量和充电电价，cost 也只是部分生活类 POI 的人均消费，因此不会拿它冒充电价。

高德官方 AutoSDK 的 ChargingStationInfo 和 DeepChargingPrice 确实定义了快慢充总数/空闲数以及电费、服务费，但这属于 AutoSDK/授权深度能力，不是普通 Web 服务 Key 的保证字段。项目已经加入兼容解析：授权响应若正式包含完整字段会自动写入动态快照；只有 available_pile_count 时因缺少总数和快慢充拆分，会保持枪口详情为未知。项目不会调用 AutoSDK 暴露的 AOS 内部路径或抓取高德 App 私有接口。

现阶段未找到同时覆盖中国大陆全国、场站级实时空闲与价格、且允许免费复用的合法公共 API。Open Charge Map 可补充少量开放目录，地方政府数据通常只覆盖当地，台湾 TDX 的分钟级动态数据只适用于台湾地区；大陆实时数据应通过运营商/聚合平台授权 API，或自有设备的 OCPP/OCPI 数据接入。

手机界面 Provider 不抓包、不调用私有接口，只读取专用设备上正常可见的场站页；仍需确认账号授权、服务条款、频率与复用范围。公开 API 和用户小程序会移除 source、外部 ID 与供应方站点 ID，完整溯源只保留在运营后台。

API REFERENCE

后端接口目录

正在读取 /openapi.json…

公开接口后台会话采集 Key

正在生成接口目录…