feat: add project-scoped operations

2026-10-22 18:40:20 +08:00
parent d320972d57
commit 1d061f6099
73 changed files with 4384 additions and 228 deletions
@@ -0,0 +1,109 @@
+# 项目地名搜索配置
+
+地名搜索的项目配置保存在 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
+联调尚待该实例恢复响应后核对。本次未重启既有进程。