Cloud-Tour-to-Libo/docs/MAP_POI_READ_FIX.md

地图 POI 读取修复与本地验证

修复范围

• 地图 POI 列表和详情直接读取当前项目的 FalkorDB 图谱，不再依赖 PostgreSQL 的 POI 缓存表。
• 地图相关 FalkorDB 连接统一使用已有的 FALKORDB_HOST、FALKORDB_PORT、FALKORDB_PASSWORD 配置。密码只在后端使用，地图页面不新增登录或配置项。
• 按 2,000 条分页读取必要的地图字段，避免批量返回完整图谱属性。兼容 lng/lat 和 longitude/latitude。
• 使用稳定点位 ID 合并旧图谱的重复标签记录；保留业务分类，排除明确标记 map_poi=false 的辅助节点。公交辅助节点保留在公交图层。
• 连接失败返回 503 并记录项目、图谱上下文；不再表现为成功返回 0 个 POI。
• 统计数使用当前地图区域的实际点位；项目/图谱切换后不沿用旧点位或旧请求结果。
• 保留地图模板、熊 Logo、四个分类图标和 POI 详情图片。

旧 guiyang_new2 项目继续兼容读取其空间图谱 guiyang_spatial_v1；新创建的 JSON 图谱直接读取自身，不要求固定的项目英文标识。

本地验证（2026-08-31）

在基于 90f75d4、仅应用本次地图修改的独立代码副本中验证：

• 后端单元测试：93 项通过，其中地图相关测试 20 项。
• 前端测试：44 项通过；TypeScript 检查、Vite 生产构建通过。
• 本地 yunyou_libo：读取 2,799 个不同 POI。
• 本地贵阳旧空间图谱：读取 80,612 个不同 POI；现有导出快照中的 80,609 个 POI 全部包含在内。旧图谱额外有 3 条餐饮点位，未为凑数删除。
• 从实际地图 JSON 抽取 2,600 个 POI，经现有 JSON 校验和 FalkorDB 导入器写入独立临时图谱：读取字段与输入一致，跨分页查询和详情 HTTP 路由均返回 200。
• 上述 POI 测试主动禁止读取 PostgreSQL POI 表；现有图谱只读，临时测试图谱完成后已删除。

复跑本地测试（需要本地 FalkorDB 中已有荔波和贵阳测试数据）：

python3 scripts/verify_map_poi_read.py --map-json /path/to/map_poi_data.json

本地 FalkorDB 未启用密码；有/无密码时的连接参数由单元测试覆盖，未声称验证了生产密码。浏览器因停在登录页，未完成登录后的地图点击验收。以上验证不等于生产环境部署验收，也不涵盖 280 MB 文件的浏览器上传链路。本次不改上传架构、不导入或删除生产数据。