Release date: 2026-06-28

This is the first open-source preview release of Map Tile Fetcher after the two
handoff projects were merged into one Go Web application.

## English

### Highlights

- Unified the product around one Go backend and retired the former .NET range
  downloader runtime.
- Added one Web UI with two task creation modes:
  - Administrative Region Download
  - Range Download
- Added shared service credential inputs for Tianditu and Mapbox so both
  download modes use the same token fields.
- Kept SQLite as the lightweight control database for users, sessions, task
  records, task runs, task sources, artifacts, failures, and scheduling.
- Added direct bbox task support for rectangular range downloads.
- Added expanded map selection and polygon range selection. Polygon range tasks
  currently use generated task-scoped GeoJSON to reuse the existing tile-cover
  pipeline.
- Added task scheduling with immediate and one-time scheduled execution.
- Added per-task output selection for ZIP file-tree artifacts and MBTiles.
- Added artifact download, failure record persistence, and retry-failed-tiles
  workflow.
- Added optional local no-login mode while keeping login enabled by default for
  deployment.
- Added release preflight validation and GitHub Actions validation.
- Added bilingual README files and bilingual user manuals.

### Public Interfaces

Primary endpoints:

- `POST /api/tasks`
- `GET /api/tasks`
- `GET /api/tasks/:id`
- `PUT /api/tasks/:id/pause`
- `PUT /api/tasks/:id/resume`
- `DELETE /api/tasks/:id`
- `DELETE /api/tasks/:id/purge`
- `GET /api/tasks/:id/download`
- `GET /api/tasks/:id/failures`
- `POST /api/tasks/:id/retry-failures`

Task creation supports:

- `mode: "bbox"` for range tasks
- legacy-compatible region `levels`
- `sources`
- `scheduleMode`
- `runAt`
- `output.format`

### Compatibility Notes

- The legacy SQLite `plans` table is still preserved as a compatibility layer.
  Runtime code now uses task-record naming where practical.
- SQLite stores metadata and indexes only. Raw tiles, ZIP files, MBTiles files,
  logs, runtime databases, and generated data remain filesystem artifacts.
- Real tokens are not included in the repository. Only placeholders such as
  `YOUR_TIANDITU_TOKEN`, `YOUR_MAPBOX_TOKEN`, and `YOUR_MAPBOX_SKU` are safe in
  Git.

### Validation

The release preflight passed before tagging:

```powershell
cd apps/admin-region-tiler
node .\scripts\release_preflight.mjs
```

The preflight covers:

- `go test ./...`
- `node --check ./static/script.js`
- `node --check ./scripts/smoke_ui.mjs`
- browser UI smoke for region and range task creation
- sensitive-value scan
- generated-file scan

## 中文

### 版本重点

- 将产品统一为一个 Go 后端，旧 .NET 范围下载器运行代码已退役。
- 新增统一 Web UI，支持两种任务创建模式：
  - 行政区划下载
  - 范围框选下载
- 新增统一服务凭证输入区，天地图和 Mapbox token 在两种下载模式中共用同一入口。
- 保留 SQLite 作为轻量控制数据库，用于用户、会话、任务记录、任务运行、任务源、产物、失败记录和计划任务。
- 支持矩形范围下载的直接 bbox 任务。
- 支持放大地图选择和多边形范围选择。当前多边形范围任务会生成任务专用 GeoJSON，以复用已有 tile-cover 管线。
- 支持立即执行和单次定时执行。
- 支持按任务选择 ZIP 文件树产物或 MBTiles 产物。
- 支持产物下载、失败记录持久化和失败瓦片重试闭环。
- 支持本地可选免登录，同时部署场景默认保持登录启用。
- 新增发布预检脚本和 GitHub Actions 验证。
- 新增中英文 README 和中英文用户使用手册。

### 公开接口

主要接口：

- `POST /api/tasks`
- `GET /api/tasks`
- `GET /api/tasks/:id`
- `PUT /api/tasks/:id/pause`
- `PUT /api/tasks/:id/resume`
- `DELETE /api/tasks/:id`
- `DELETE /api/tasks/:id/purge`
- `GET /api/tasks/:id/download`
- `GET /api/tasks/:id/failures`
- `POST /api/tasks/:id/retry-failures`

任务创建支持：

- `mode: "bbox"` 范围任务
- 兼容旧行政区划 `levels` 请求
- `sources`
- `scheduleMode`
- `runAt`
- `output.format`

### 兼容说明

- SQLite 中旧 `plans` 表仍作为兼容层保留。运行时代码已尽量收敛到 task record 命名。
- SQLite 只保存元数据和索引。原始瓦片、ZIP、MBTiles、日志、运行数据库和生成数据仍是文件系统产物。
- 仓库不包含真实 token。Git 中只允许保留 `YOUR_TIANDITU_TOKEN`、`YOUR_MAPBOX_TOKEN`、`YOUR_MAPBOX_SKU` 等占位符。

### 验证

打 tag 前已通过发布预检：

```powershell
cd apps/admin-region-tiler
node .\scripts\release_preflight.mjs
```

发布预检覆盖：

- `go test ./...`
- `node --check ./static/script.js`
- `node --check ./scripts/smoke_ui.mjs`
- 浏览器 UI 冒烟，覆盖行政区划和范围任务创建
- 敏感信息扫描
- 生成物扫描