Basemap Pusher: catalog and distribution gateway for existing tiles

A Go service that scans existing basemap tile directories and vector files,
catalogues them in SQLite, issues scoped access tokens, and serves tiles and
downloads to downstream systems. It deliberately does not generate or process
raster data: GIS software produces the tiles, this service catalogues,
authorises and distributes them.

Capabilities
- scans basemap tile directories (manifest-based or raw z/x/y) and vector
  assets (.geojson, .json, .zip, shapefiles with sidecars)
- token auth with per-resource grants, expiry and coarse scopes (read, slice)
- resource health inspection flags a moved or deleted tile root before a client
  hits a 404
- downstream push with exponential-backoff retries and manual re-queue
- image slicing jobs driven by the GDAL bundled with QGIS, including VRT
  mosaicking so successive drone flights accumulate into one seamless layer
- a narrow, non-admin slicing API for external callers: submit, poll,
  idempotent by job code, completion callback
- ops console covering health, ledger, tokens, pushes, scans, slicing and
  service info
- native Windows service install/start/stop with crash recovery, auto-start and
  a rotating log file, so no NSSM or WinSW wrapper is needed

Verified with 49 tests plus live runs against real tile data and real GDAL.

docs/INSAR_MANAGEMENT_SYSTEM_V2.md

@@ -0,0 +1,201 @@
+# Insar_management_system_v2 接入说明
+
+本文档说明 `Z:\Code\Insar_management_system_v2` 如何接入当前 `tile-server`，不需要修改推送服务外部的公开匿名路由，全部走带 token 的受保护接口。
+
+## 结论
+
+当前 `tile-server` 经过兼容后，可以支撑 `Insar_management_system_v2` 的底图和 GeoJSON/SHP 调用，但前提是目标系统把原先的固定静态路径改成带 token 的调用方式。
+
+支持范围：
+
+- 底图瓦片
+- GeoJSON 文件直连读取
+- Shapefile 或 `.zip` 方式下载
+
+不需要目标系统实现“接收推送”的回调接口。
+
+## 推荐调用方式
+
+假设服务地址为：
+
+```text
+http://127.0.0.1:8910
+```
+
+假设访问 token 为：
+
+```text
+bmp_xxxxxxxxxxxxxxxxx
+```
+
+### 1. 底图瓦片
+
+推荐直接使用默认版本兼容路由：
+
+```text
+GET /tiles/{code}/{z}/{x}/{y}.ext?token=...
+```
+
+示例：
+
+```text
+http://127.0.0.1:8910/tiles/google_image/{z}/{x}/{y}.webp?token=bmp_xxx
+http://127.0.0.1:8910/tiles/gaode_image/{z}/{x}/{y}.webp?token=bmp_xxx
+http://127.0.0.1:8910/tiles/gaode_shp/{z}/{x}/{y}.webp?token=bmp_xxx
+```
+
+说明：
+
+- `google_image`、`gaode_image`、`gaode_shp` 可以直接保留下划线写法
+- 服务内部会归一化到对应底图库 code
+- 路由会自动解析该底图的默认版本
+
+如果你希望显式锁定版本，也可以继续使用：
+
+```text
+GET /tiles/{code}/{version}/{z}/{x}/{y}.ext?token=...
+```
+
+### 2. GeoJSON
+
+推荐直接按原始相对路径访问：
+
+```text
+GET /geojson/{relative/path}.geojson?token=...
+```
+
+示例：
+
+```text
+http://127.0.0.1:8910/geojson/全国行政区.geojson?token=bmp_xxx
+```
+
+说明：
+
+- 支持按原始相对路径访问
+- 也支持按文件名访问
+- 也支持按内部 vector code 访问
+- 返回内容为实际 GeoJSON 文件内容，可直接 `fetch(...).json()`
+
+### 3. SHP
+
+推荐按原始相对路径下载：
+
+```text
+GET /shp/{relative/path}.shp?token=...
+```
+
+示例：
+
+```text
+http://127.0.0.1:8910/shp/landuse/parcel.shp?token=bmp_xxx
+```
+
+说明：
+
+- 如果底层资源是 `.shp + .dbf + .shx ...` 组合，服务会自动打包成 zip 返回
+- 如果底层资源本来就是 `.zip`，则直接返回 zip
+
+如果你希望继续按内部 code 下载，也可以使用：
+
+```text
+GET /vectors/{code}/download?token=...
+```
+
+## Token 传递方式
+
+支持以下方式，推荐前端场景使用查询参数：
+
+### 查询参数
+
+```text
+?token=bmp_xxx
+```
+
+### Header
+
+```text
+Authorization: Bearer bmp_xxx
+```
+
+或：
+
+```text
+X-Access-Token: bmp_xxx
+```
+
+## 前端改造建议
+
+### 底图常量
+
+把原先：
+
+```js
+`${TILE_BASE}/tiles/google_image/{z}/{x}/{y}.webp`
+```
+
+改成：
+
+```js
+`${TILE_BASE}/tiles/google_image/{z}/{x}/{y}.webp?token=${encodeURIComponent(TILE_TOKEN)}`
+```
+
+其他底图同理。
+
+### 行政区 GeoJSON
+
+把原先：
+
+```js
+`${TILE_BASE}/geojson/全国行政区.geojson`
+```
+
+改成：
+
+```js
+`${TILE_BASE}/geojson/全国行政区.geojson?token=${encodeURIComponent(TILE_TOKEN)}`
+```
+
+## 推荐接入流程
+
+1. 在 `tile-server` 管理页或管理 API 扫描底图目录和矢量目录。
+2. 创建一个专供 `Insar_management_system_v2` 使用的 token。
+3. token 授权对应底图和需要访问的 GeoJSON/SHP 资源。
+4. 在 `Insar_management_system_v2` 中把静态地址改成带 token 的服务地址。
+
+## 创建 token 时的资源填写规则
+
+### 底图
+
+填写底图库 code，例如：
+
+```text
+google-image
+gaode-image
+gaode-shp
+```
+
+### 矢量
+
+现在既可以填内部 code，也可以直接填原始路径，例如：
+
+```text
+全国行政区.geojson
+landuse/parcel.shp
+```
+
+## 适配边界
+
+当前服务负责的是：
+
+- 扫描
+- 目录管理
+- token 鉴权
+- 底图瓦片输出
+- GeoJSON/SHP 输出
+
+当前服务不负责：
+
+- 生成切片
+- 把矢量转换成 GeoJSON
+- 修改 `Insar_management_system_v2` 代码