# 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、不用纯颜色单独承载状态（状态同时有文字）。