# 项目地名搜索配置

地名搜索的项目配置保存在 Metadata DB 的 `public.projects.map_config.place_search`。
复用现有 JSONB 字段，不向各项目 BizDB 或 TimescaleDB 新增表。后端天地图 Key
仍通过 `TIANDITU_TOKEN` 提供，不写入项目地图配置或返回浏览器。

```json
{
  "place_search": {
    "enabled": true,
    "provider": "tianditu",
    "admin_code": "341126",
    "region": "凤阳县"
  }
}
```

`admin_code` 接受六位行政区编码或带 `156` 前缀的天地图编码。省级编码以
`0000` 结尾，市级编码以 `00` 结尾，其余按区县校验。`region` 是配置范围的
显示名称；区县级配置须与天地图的区县名称一致。市级搜索可返回不同区县的
候选，候选的 `district` 保留实际区县，响应的 `region` 返回配置范围。

配置缺失、关闭或无效时前端禁用查询；后端拒绝未配置项目的搜索请求。
前端启用条件、区域文案及结果校验均来自项目元数据，不再判断 GeoServer
工作空间。后端按经授权的 `X-Project-Id` 读取配置，搜索请求只接受 `keyword`，
调用方不能覆盖项目区域或分页限制。每次搜索最多返回 10 个候选。

## 管理接口

具备现有管理员权限的调用方可使用 `PATCH /api/v1/admin/projects/{project_id}`：

```json
{
  "map_config": {
    "place_search": {
      "enabled": true,
      "provider": "tianditu",
      "admin_code": "310000",
      "region": "上海市"
    }
  }
}
```

更新会合并 `map_config` 的顶层配置项，保留已有 `legend`、`coordinate_reference`
等字段。`place_search` 作为完整配置项替换；传 `null` 可清除此项，
`map_config` 自身不能为 `null`。项目元数据和管理接口均返回 `map_config`。
修改配置后刷新工作台以重新读取。

初始配置使用的一次性脚本已清理。后续通过上述管理接口维护项目配置；
初次写入前的逐项目行备份保存在忽略目录
`data/project-map-config/<project-id>-<timestamp>/before.json`。

## 2026-10-21 实际配置

| 项目代码 | 搜索范围 | 行政区编码 |
| --- | --- | --- |
| `tjwater_v2`、`tjwater` | 奉贤区 | `310120` |
| `fengyang_v2`、`fengyang` | 凤阳县 | `341126` |
| `md_v2`、`md` | 吴中区 | `320506` |
| `szh_v2`（苏州河） | 上海市 | `310000` |
| `zjb` | 湛江市 | `440800` |

共配置 8 条项目记录；3 个旧项目仍为 inactive。SZH 的 8 个实际模型节点经天地图
逆地理编码落在松江、青浦、闵行，因此采用上海市范围；木渎采用吴中区，湛江项目
采用市级范围，避免将近似配准的工程坐标当作区县边界依据。

配置前已备份完整元数据库并通过 `pg_restore --list` 校验：
`data/project-map-config/metadata-before-20261021T080257Z/system_hub.dump`。
SHA-256：`77dc13f874f81699a96d4584ac1f67f1b2048fe7c68175be8154c5e277c8689f`。
同时保留逐项目的行备份，核对除 `map_config` 与 `updated_at` 外所有字段保持原值，
已有图例、坐标参考和项目状态均保留。数据库字段注释同步为当前配置用途。

验证涵盖后端服务/接口/元数据配置、前端单元测试、奉贤桌面/窄屏搜索、凤阳项目
切换后搜索定位及未配置禁用。5 个活动项目均通过真实天地图搜索；浏览器测试使用
隔离接口数据，不代表部署环境的真实身份验收。Server OpenAPI 与供水 Agent 的
类型快照同步更新。配置已写入数据库，代码未提交、未推送或部署。

## 地图取点反编码

地址定位面板提供“地图取点”按钮。启用后点击地图查询该点附近的地名和完整地址，
首次查询成功后自动结束取点并保留结果和地图标记；失败时可重新取点。“结束取点”、
Escape、关闭工具或切换项目也会退出取点模式。
取点时暂停管网要素选择和绘图标注选择，并停止当前测量、绘图，退出后恢复常规选择。

后端接口为 `POST /api/v1/reverse-geocoding-requests`：

```json
{"longitude": 117.570309, "latitude": 32.868029}
```

坐标采用 EPSG:4326，复用授权项目的 `map_config.place_search` 和服务端
`TIANDITU_TOKEN`，无需另加数据库配置。返回规范化的 `PlaceSearchItem`，包括
`name`、`address`、`longitude`、`latitude`、`district`、`category` 与 `id`。
坐标始终保留输入的地图取点坐标，附近 POI 的坐标不替代点击位置。新结果显示标记，
不自动移动地图；用户可主动点击“重新定位”。连续取点取消前次请求，过期结果不能
覆盖新点；工具关闭、切换项目和退出取点时也会取消未完成请求。

反编码遵守相同的行政区范围校验：区县范围校验区县，市级范围允许所属不同区县。
范围外返回 422，无可用地址返回 404，服务异常或无效响应返回 502，配置缺失返回
503，超时返回 504。错误信息不包含服务商 Key 或带凭据的请求 URL。

使用天地图逆地理编码服务的 `postStr={"lon":...,"lat":...,"ver":1}` 与
`type=geocode` 参数。5 个活动项目均已用数据库实际配置通过真实接口查询，
并核对输出坐标保持输入值。桌面和 320px 浏览器测试使用隔离接口数据验证交互。

本次最终检查中，现有本地 `127.0.0.1:8000` 实例的 OpenAPI 请求连续两次超时。
真实天地图检查通过独立服务调用完成，浏览器使用隔离 API；既有运行实例的 HTTP
联调尚待该实例恢复响应后核对。本次未重启既有进程。