Harmon
747eed63b0
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.
4.8 KiB
Product
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
- 状态先于库存。 打开界面第一眼要看到"有没有东西在报警、有什么待处理"，而不是资源总数。
- 台账要能验真。 每一条资源都应能就地验证（看一眼图、复制 XYZ 模板、试拉一张），而不是只列一条记录。
- 危险操作要设防。 停用令牌、重扫、改默认版本都会影响线上取图，必须有确认与后果说明。
- 生产与分发分离。 任何新能力都要问一句：这是不是把"生产"塞进了网关？默认答案是不要。
- 小部署面是特性，不是妥协。 新增依赖前先证明它值得牺牲单文件部署。
Accessibility & Inclusion
内部工具，无正式合规要求。仍应满足：键盘可达、焦点可见、正文对比度 ≥ 4.5:1、不用纯颜色单独承载状态（状态同时有文字）。