=== x-tdt-map ===
Contributors: kanxsh
Tags: travel-map, china-map, tianditu, footprints, map, 天地图, 足迹地图, 旅行
Requires at least: 6.8
Tested up to: 6.8
Requires PHP: 8.1
Stable tag: 1.4.12
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

基于天地图 API 的 WordPress 足迹地图插件，支持省份聚合与「省→市→点」三级下钻，合规展示你的旅行足迹。

== Description ==

x-tdt-map 是一个轻量、合规、开箱即用的 WordPress 足迹地图插件。它基于天地图 API（符合国内地图法规），让你在后台添加去过的地点，前端以清晰的分层交互展示旅行足迹：

* **省份聚合 + 三级下钻**：全国视图按省显示数量徽标（单地点红 / 多地点橙）；点省进入该省，按地级市显示绿色市徽标；点市渲染该省该市的足迹点并自动居中。直辖市（京沪津渝）点进去直接显示足迹点。
* **子景点挂父足迹**：一个地点含多个景点时，在父足迹下维护「景点名 | 链接」清单，前台信息窗口统一列出，聚合只算父级。
* **三种标记配色**：默认（橙）、有链接（主题蓝）、无链接（醒目品红）。
* **自动识别省 / 市**：添加足迹自动逆地理编码并归属省份与地级市；海外地址走 OpenStreetMap 解析。
* **三种前端展示**：自定义地图路径（全屏独立页）、短代码 `[x_tdt_map]`、Gutenberg 块。
* **年份筛选**：`[x_tdt_map year="2025"]` 按年份查看足迹。
* **数据独立**：足迹存于自定义表 `wp_footprints`，设置存于 `wp_footprints_settings`，卸载可保留。
* **开放许可**：GPL-2.0-or-later，可自由使用、修改、再分发。

== Installation ==

1. 将插件文件夹上传到站点的 `/wp-content/plugins/` 目录。
2. 在 WordPress 后台「插件」页面找到 **x-tdt-map**，点击「激活」。
3. 前往[天地图开放平台](https://console.tianditu.gov.cn/api/key) 申请 API Key（建议同时申请「浏览器端」与「服务端」两种 Token）。
4. 进入「足迹 → 足迹设置」填入 Token 并保存。
5. 进入「足迹 → 添加足迹」添加你的第一个地点，前端即可通过短代码 / 区块 / 自定义路径查看地图。

== Frequently Asked Questions ==

= 地图显示"天地图 API 未加载"？ =

检查 Token 是否正确设置，且创建应用时类型是否为"浏览器端"。

= 年份筛选不生效？ =

年份维度已单独做缓存键隔离；若异常，尝试清除页面缓存或用隐身窗口查看。

= 能否用于海外地点？ =

支持。海外地址走 OpenStreetMap 解析并做国别校验，防止误落国内；但天地图底图仅覆盖国内，海外点会显示在空白底图上（已知限制，后续完善）。

= 删除插件后数据会怎样？ =

默认卸载即删除 `wp_footprints` 与 `wp_footprints_settings` 两张表。如需保留，先在「足迹 → 足迹设置」勾选「卸载时保留足迹数据」再删除插件。

== Screenshots ==

1. 全国视图：按省份显示数量徽标（单地点红 / 多地点橙）。
2. 点省下钻：按地级市显示绿色市徽标。
3. 点市下钻：渲染该省该市的足迹点并自动居中。
4. 后台添加足迹：地图点击定位 + 子景点清单维护。

（将对应截图分别保存为 `screenshot-1.png`、`screenshot-2.png`、`screenshot-3.png`、`screenshot-4.png`，放在插件根目录，WordPress.org 会自动按序号展示。）

== Changelog ==

= 1.4.12 =
* 修复直辖市（京沪津渝）下钻空白——省级无地级市时直接展示该省足迹点
* 清理废弃的「区县」后端，消除每次保存足迹的 1+N 次边界请求
* 加固省份快速切换时的竞态保护

= 1.4.11 =
* 省层级不再显示足迹点，点位仅在点进地级市后展示，解决徽标与点位混杂

= 1.4.10 =
* 下钻粒度由区/县改为地级市（省→市→点）
* 点省即时出底图、无链接标记改醒目品红、进市自动居中

= 1.4.9 =
* 引入区县级下钻（后于 1.4.10 升级为地级市）

= 1.4.8 =
* 子景点挂父足迹

= 1.4.7 =
* 插件署名、许可证声明、LICENSE 文件、防直接访问等规范化

= 1.3.0 =
* Gutenberg 块修复、地图路径重写、海外 OSM 解析等多项修复与优化

== Upgrade Notice ==

= 1.4.10 =
下钻粒度调整为「省→市→点」，历史足迹的城市归属由前端几何「点在多边形内」自动补全，无需逐条重存。
