110 lines
5.5 KiB
Markdown
110 lines
5.5 KiB
Markdown
# 项目地名搜索配置
|
||
|
||
地名搜索的项目配置保存在 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
|
||
联调尚待该实例恢复响应后核对。本次未重启既有进程。
|