Harmon
73ad03fa59
Scanner - manifest lookup is now depth-bounded and prunes numeric zoom directories, so a scan no longer walks the whole tile payload - rescans only report a version as updated when something actually changed - overlapping runs are refused instead of interleaving their bookkeeping Hot path - token authorisation loads only that token grants and throttles the last_used_at write instead of touching it on every tile - SQLite runs in WAL with a busy timeout and a real connection pool - the catalog lookup used by /tiles no longer loads every basemap Security - the admin surface requires ADMIN_TOKEN (bearer) or ADMIN_USER/ADMIN_PASSWORD (basic), and the service refuses to bind off-host without credentials - CORS is an explicit allow-list; newly minted tokens never reach a redirect URL - client tokens are redacted from the access log Operations - resource health inspection flags a moved or deleted tile root before a 404 - pushes retry with backoff and can be re-queued by hand; the schedule lives in the database so a restart does not lose it - access log plus /metrics counters Image slicing - tile_jobs drive the GDAL bundled with QGIS via scripts/gdal2tiles-qgis.bat - layer_sources remembers what a layer is made of: submit one source to append a flight, or all of them to rebuild the layer as a VRT mosaic with no tile seams; the console exposes both, including a one-click rebuild - slicing is available to integrations through a narrow slice token scope (submit, poll, idempotent by code, completion callback) Console - rebuilt around a fixed rail and single-view navigation with health and outstanding work leading, instead of one long scrolling page Windows service - native install/start/stop/status with crash recovery, auto-start and a rotating log file, so no NSSM wrapper is needed - start-all.bat and stop-all.bat are removed: they killed the process by port with taskkill, which fought the service restart policy Verified with 49 tests and live runs against real tile data and real GDAL.
68 lines
4.8 KiB
Markdown
68 lines
4.8 KiB
Markdown
# Product
|
||
|
||
<!-- impeccable:product-schema 1 -->
|
||
|
||
## Platform
|
||
|
||
web
|
||
|
||
## Stack
|
||
|
||
既有代码已确定：Go 1.26 标准库 HTTP 服务 + `modernc.org/sqlite`，运维界面是编译进二进制的单个 Go HTML 模板（`services/api-go/internal/basemapapi/admin_template.go`），无构建步骤、无 JS 框架。
|
||
|
||
*（决策来源：用户授权按推荐执行）* 运维界面继续维持"零依赖、单文件内嵌、无前端构建"的约束——单个 exe 可直接部署是本项目最大的运维优势，引入前端工具链会破坏它。允许使用原生 JS 与内联 CSS。
|
||
|
||
## Users
|
||
|
||
**主要用户：内部 GIS / 运维工程师。** 场景是日常运维与排障——盘点和核对底图、矢量资源，签发和回收访问令牌，处理推送失败，查看扫描与请求的异常。他们熟悉瓦片、XYZ 模板、token 这些概念，不需要教学，需要的是**一眼看到状态、一步完成操作**。
|
||
|
||
**次要用户：下游系统对接方。** 通过 token 拉取瓦片/矢量，或接收推送回调；他们主要消费 API 与回调负载，只在排查对接问题时才会打开运维台。
|
||
|
||
## Product Purpose
|
||
|
||
`basemap-pusher` 是底图与矢量资源的**编目与分发网关**。它不生成数据，只做四件事：扫描既有目录、编目、签发令牌、按令牌放行下载与推送描述。
|
||
|
||
存在的意义是把"谁能取哪张底图"这件事从散落的目录和口头约定，收敛成一份可审计的台账。成功 = 运维能自己回答"这张底图现在能不能取、谁有权限、上周谁改过"，而不必去翻服务器文件系统。
|
||
|
||
## Positioning
|
||
|
||
**它刻意不做切片。** 与上一代成果管理服务（PostgreSQL/PostGIS + Python worker + 切片流水线）相反，本服务把"生产"和"分发"切开：GIS 软件负责出片，产物落到 `data/tiles/<code>/z/x/y.ext`，网关只扫、只编目、只分发。
|
||
|
||
这个机制的价值是**部署面极小**：单个 Go 二进制 + 一个 SQLite 文件 + 两个目录。相邻的"成果平台"做不到这一点。
|
||
|
||
## Operating Context
|
||
|
||
- 数据以**目录即真相**：`BASEMAP_SCAN_ROOT` 下的目录结构就是事实来源，启动扫描或手动重扫即刷新台账。
|
||
- 两种底图目录风格：带 `manifest.json` 的目录，和裸 `z/x/y.ext` 目录（后者按目录名自动入库）。
|
||
- 矢量资源在 `VECTOR_SCAN_ROOT` 下递归扫描 `.geojson` / `.json` / `.zip` / `.shp`（shapefile 按需打包下载）。
|
||
- 访问令牌通过 `Authorization: Bearer`、`X-Access-Token`、`token=` 查询参数投递——查询参数对瓦片客户端（地图库直接拼 URL）是必需的，不是可选项。
|
||
- 推送是向下游系统发 HTTP 回调，携带资源描述符。
|
||
- 部署形态：Windows 批处理脚本启停（`start-all.bat` / `stop-all.bat`），默认只绑 `127.0.0.1`。
|
||
|
||
## Capabilities and Constraints
|
||
|
||
**已确认能力**：目录扫描与编目、默认版本管理、令牌签发/停用/有效期、令牌鉴权取图、矢量下载（shapefile 动态打包）、兼容路由（`/geojson/...`、`/shp/...`、无版本号的瓦片路由）、下游推送、访问日志与 Prometheus 指标（`/metrics`）。管理面支持 HTTP Basic（浏览器）与 Bearer（API）。
|
||
|
||
**已确认约束**：
|
||
- 存储是单文件 SQLite，单实例部署；扫描锁是进程内的。
|
||
- 运维界面必须能表达**失败与待处理**，而不只是库存数量。
|
||
- 不引入前端构建步骤。
|
||
- **明确不做**：栅格切片、重投影、金字塔构建。影像转底图属于上游 GIS 工具的职责。
|
||
|
||
**明确未决**：影像切片是否以"作业化调用外部 GDAL"的形式纳入（已记为后续候选，当前不在范围内）。
|
||
|
||
## Evidence on Hand
|
||
|
||
真实的底图目录与矢量文件在 `data/` 下（`data/tiles/` 含 gaode_image / gaode_shp / google_image，实为 webp 瓦片；`data/geojson/` 含一份约 53MB 的 GeoJSON）。这些是真实数据，可用于验证界面，但**不得**在界面文案里虚构容量、QPS、SLA 或客户信息。
|
||
|
||
## Product Principles
|
||
|
||
1. **状态先于库存。** 打开界面第一眼要看到"有没有东西在报警、有什么待处理"，而不是资源总数。
|
||
2. **台账要能验真。** 每一条资源都应能就地验证（看一眼图、复制 XYZ 模板、试拉一张），而不是只列一条记录。
|
||
3. **危险操作要设防。** 停用令牌、重扫、改默认版本都会影响线上取图，必须有确认与后果说明。
|
||
4. **生产与分发分离。** 任何新能力都要问一句：这是不是把"生产"塞进了网关？默认答案是不要。
|
||
5. **小部署面是特性，不是妥协。** 新增依赖前先证明它值得牺牲单文件部署。
|
||
|
||
## Accessibility & Inclusion
|
||
|
||
内部工具，无正式合规要求。仍应满足：键盘可达、焦点可见、正文对比度 ≥ 4.5:1、不用纯颜色单独承载状态（状态同时有文字）。 |