From fdd5e4b4e2daa0a36759e335ff1ad2a8999bdbc4 Mon Sep 17 00:00:00 2001
From: Harmon <rs_bhm@163.com>
Date: Fri, 16 Oct 2026 10:48:11 +0800
Subject: [PATCH] Add a task-oriented usage guide

docs/GUIDE.md walks through the jobs people actually do, rather than listing
routes: minting a token and fetching a first tile, wiring the tile template into
Leaflet and OpenLayers, accumulating drone imagery across several flights and
deciding when a mosaic rebuild is worth it, integrating a downstream system, a
symptom-to-cause troubleshooting table, and the day-to-day console actions.

API.md stays the reference; the README points at both.
---
 README.md     |   7 +-
 docs/GUIDE.md | 243 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 248 insertions(+), 2 deletions(-)
 create mode 100644 docs/GUIDE.md

diff --git a/README.md b/README.md
index 0e6dd7c..19e00ce 100644
--- a/README.md
+++ b/README.md
@@ -115,8 +115,11 @@ Supported token delivery:
 
 ## API
 
-See [docs/API.md](./docs/API.md) for a calling guide with auth, request/response
-examples and the LAN exposure checklist.
+- [docs/GUIDE.md](./docs/GUIDE.md) — task-oriented walkthrough: first tile,
+  integrating with a map frontend, accumulating drone imagery over several
+  flights, downstream integration and troubleshooting.
+- [docs/API.md](./docs/API.md) — endpoint reference: auth, every route grouped by
+  purpose, slicing request/job shapes, error codes, LAN exposure checklist.
 
 ### System
 
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
new file mode 100644
index 0000000..d7b582a
--- /dev/null
+++ b/docs/GUIDE.md
@@ -0,0 +1,243 @@
+# 使用指南
+
+按**任务**走的操作手册。接口字段速查见 [API.md](./API.md)。
+
+本指南以本机部署为例：
+
+- 服务地址：`http://192.168.1.62:8910`（静态 IP，局域网可达）
+- 运维台：`http://127.0.0.1:8910/admin/`（**仅本机**）
+- 数据目录：`D:\Code\tile-server\data`（切片在 `tiles\`，矢量在 `geojson\`）
+
+---
+
+## 一、五分钟跑通：拿到第一张图
+
+### 1. 在运维台签发一个令牌
+
+浏览器打开 `http://127.0.0.1:8910/admin/` → **访问令牌** → 签发。
+
+- **底图编码**：填已入库的 code，例如 `gaode-image`
+- **有效时长**：留空走默认 30 天
+- 勾不勾"允许提交切片任务"，决定这个令牌能不能调切片接口
+
+签完页面顶部会显示**明文令牌**，形如 `bmp_xxxxxxxx`。**只显示这一次**，立刻复制存好。
+
+### 2. 确认底图已入库
+
+运维台 **底图** 页能看到 `gaode-image` / `gaode-shp` / `google-image`，并显示级别范围和格式。
+
+取图模板长这样：
+
+```text
+http://192.168.1.62:8910/tiles/gaode-image/current/{z}/{x}/{y}.webp
+```
+
+### 3. 取一张验证
+
+```powershell
+curl.exe -o 0.webp -w "%{http_code} %{content_type}`n" `
+  "http://192.168.1.62:8910/tiles/gaode-image/current/0/0/0.webp?token=<令牌>"
+```
+
+返回 `200 image/webp` 就通了。
+
+### 4. 放进地图前端
+
+取图模板本身就是前端要的格式，两种用法：
+
+**Leaflet**
+
+```javascript
+const token = 'bmp_xxxxxxxx';
+const urlTemplate = 'http://192.168.1.62:8910/tiles/gaode-image/current/{z}/{x}/{y}.webp';
+
+L.tileLayer(urlTemplate + '?token=' + token, {
+  tileSize: 256,
+  minZoom: 0,
+  maxZoom: 13,          // 用底图详情里的 maxZoom
+  attribution: '内部底图'
+}).addTo(map);
+```
+
+**OpenLayers**
+
+```javascript
+new ol.layer.Tile({
+  source: new ol.source.XYZ({
+    url: 'http://192.168.1.62:8910/tiles/gaode-image/current/{z}/{x}/{y}.webp?token=bmp_xxxxxxxx',
+    crossOrigin: 'anonymous'
+  })
+});
+```
+
+> 令牌走查询参数（`?token=`）是给地图客户端设计的——`<img>` 和瓦片库没法设请求头。
+> 代价是令牌会出现在 URL 里，所以**给前端用的令牌要单独签发、单独设短有效期**，别和管理令牌混用。
+
+### 5. 也可以让程序自己去问目录
+
+不要让前端写死 code，让它先查目录：
+
+```powershell
+curl.exe -H "Authorization: Bearer <令牌>" http://192.168.1.62:8910/api/v1/catalog/basemaps
+```
+
+返回里每个底图带 `url_template`、`min_zoom`、`max_zoom`、`tile_format`，
+前端照着渲染即可。目录会**按令牌授权自动过滤**——没有权限的底图不会出现。
+
+---
+
+## 二、无人机影像：一次次的累加
+
+目标：一个图层 `uav-2026`，飞一次加一次，最终是一张完整的图。
+
+### 准备
+
+1. 运维台 **访问令牌** 签发一个勾了 **"允许提交切片任务"** 的令牌
+2. 这个令牌不需要任何底图授权——它只用来提交切片，读不到图
+
+### 第一次飞行
+
+```powershell
+$TOKEN = "bmp_xxxxxxxx"
+
+curl.exe -X POST http://127.0.0.1:8910/api/v1/slice/jobs `
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" `
+  -d '{"target_code":"uav-2026","source_paths":["D:\\uav\\flight-a.tif"],"zoom_min":0,"zoom_max":18}'
+```
+
+返回 `202` 和任务对象，`status` 是 `pending`。
+
+### 几天后又飞了
+
+**同一个 `target_code`，只提交新影像**，就是累加：
+
+```powershell
+curl.exe -X POST http://127.0.0.1:8910/api/v1/slice/jobs `
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" `
+  -d '{"target_code":"uav-2026","source_paths":["D:\\uav\\flight-b.tif"],"zoom_min":0,"zoom_max":18}'
+```
+
+新影像覆盖到哪算哪，之前飞的地方原样保留（命令里带了 `--exclude`，空白瓦片不会落盘，
+所以不会把旧影像"挖出洞"）。
+
+### 看进度
+
+```powershell
+curl.exe -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8910/api/v1/slice/jobs/<任务id>
+```
+
+`status` 走 `pending → running → succeeded / failed`。
+失败时 `message` 有原因，完整输出在 `log_path`。
+
+### 什么时候需要"重建"
+
+日常累加是**按瓦片**覆盖的：如果两次飞行在**同一张 256px 瓦片内**有重叠，
+整块瓦片会来自较新的那次，可能出现瓦片边界的可见接缝。
+
+**重叠很小的话不用管。** 真觉得有接缝时，做一次镶嵌重建：
+
+运维台 → **影像切片** → 图层源清单 → 点该图层的 **「重建为镶嵌」**。
+
+它会自动读出这个图层记录的全部源影像、沿用当前已发布的级别范围，
+先 `gdalbuildvrt` 拼成一张虚拟栅格再切，重叠区**逐像素**合成，没有接缝。
+
+### 图层现在由哪些影像构成
+
+```powershell
+curl.exe -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8910/api/v1/slice/layers/uav-2026/sources
+```
+
+运维台同一页也有这张清单。
+
+### 两个注意点
+
+- **`target_code` 必须是英文数字**（如 `uav-2026`）。中文会被归一化掉导致报错。
+  想显示"2026无人机影像"，由**你的前端自己映射** code → 中文名。
+- 切片是**单并发**的，按提交顺序执行。一次提交多个图层要排队，但不会阻塞接口。
+
+---
+
+## 三、给下游系统对接
+
+### 方式一：下游主动拉（推荐）
+
+下游拿一个令牌，调目录 → 拿 `url_template` → 自己取图。
+
+```powershell
+curl.exe -H "Authorization: Bearer <令牌>" http://192.168.1.62:8910/api/v1/catalog/basemaps
+```
+
+好处：地址由服务方维护，换 IP / 加图层下游不用改代码。
+
+### 方式二：服务方推送描述
+
+在运维台 **推送** 页配好目标系统（回调地址 + 可选请求头），
+资源更新时把描述推给下游，下游收到后再自己来拉。
+
+- 推送是**异步**的，提交后先返回 `pending`
+- 失败自动重试（30s、60s），状态在推送记录里看
+- 失败记录可以点 **重推**
+
+### 切片完成回调
+
+提交切片任务时带上 `callback_url`：
+
+```json
+{"target_code":"uav-2026","source_paths":["D:\\uav\\b.tif"],"callback_url":"http://portal-a/api/tile-jobs/done"}
+```
+
+任务结束时服务会 POST：
+
+```json
+{"event":"tile.job.finished","job":{ ...任务对象... }}
+```
+
+失败同样自动退避重试。
+
+---
+
+## 四、常见问题速查
+
+| 现象 | 原因 | 怎么办 |
+|---|---|---|
+| `401 invalid token` | 令牌错、过期或被停用 | 运维台令牌页看状态；重新签发 |
+| `403 token has no access` | 令牌有效但没授权这个底图 | 用有该底图授权的令牌，或重新签发 |
+| `403 admin endpoints are loopback-only` | 从别的机器调了管理接口 | 管理接口只能在本机调；远程请用业务令牌走 `/api/v1/catalog`、`/tiles` |
+| `403 ... slice scope` | 令牌没勾"允许提交切片任务" | 重新签发并勾上 |
+| `404` 取图 | 该 z/x/y 没切出来，或资源已下线 | 运维台 **底图** 页看该版本的"在位/文件缺失"标记 |
+| 取图地址里是 `127.0.0.1` | 改过 base URL 但没重扫 | 运维台点 **立即扫描**，模板是扫描时生成的 |
+| 切片任务 `failed` | 源影像路径不对、不是栅格、GDAL 报错 | 看任务的 `message` 和 `log_path` |
+| 页面打不开 | 在别的机器访问了 `/admin/` | 管理台仅本机；远程只能调业务接口 |
+| 别的网段访问不通 | 路由器没有两个网段之间的路由 | 找网络管理员加路由 |
+
+---
+
+## 五、日常运维
+
+运维台各页对应的动作：
+
+| 页面 | 用途 |
+|---|---|
+| **总览** | 待处理事项（失败的扫描/推送、缺失的资源）+ 实时指标 |
+| **底图** | 台账、默认版本、取图模板、**就地验真**（粘贴令牌试拉一张） |
+| **矢量** | 矢量资源与下载地址，同样可验真 |
+| **令牌** | 签发 / 停用，查看授权范围与最近使用时间 |
+| **推送** | 目标系统、推送记录、失败重推 |
+| **扫描** | 扫描源、立即扫描、扫描历史 |
+| **影像切片** | 提交切片、任务列表、图层源清单与重建 |
+| **服务** | 版本、对外地址、探针与指标入口 |
+
+**故障排查第一站是日志**：
+
+```powershell
+Get-Content D:\Code\tile-server\bin\logs\basemap-pusher.log -Tail 50
+```
+
+访问日志每行形如 `GET /tiles/xxx/... 200 320B 2ms`，令牌已脱敏成 `***`。
+
+**服务管理**（`install/uninstall/start/stop` 需管理员）：
+
+```powershell
+scripts\service.bat status
+scripts\service.bat restart
+```
\ No newline at end of file