Webman不内置地图能力，仅通过HTTP调用百度Web服务API实现地理编码与反查，地图渲染完全依赖前端BMap JS SDK；定位需HTTPS环境，后端返回JSON数据供前端渲染。
Webman 本身不内置地图能力，必须靠前端 JS + 后端 HTTP 调用协同完成定位与展示，不能只靠 Python 端“搞定”。
Webman 后端只负责地理编码和反查，不处理地图渲染
Webman 是 Python 框架，它能做的只有：调用百度 Web 服务 API（如 geocoding/v3、reverse_geocoding/v3）做地址 ↔ 坐标转换，或转发前端定位结果做业务逻辑处理。地图容器、缩放、标记、控件等全部依赖浏览器端的 BMap JS SDK。
- 后端无法直接调用
BMap.Geolocation或BMap.Map—— 这些是浏览器全局对象，只在前端生效 - 常见错误：在 Webman 视图函数里写
map.centerAndZoom(...)，会报ReferenceError: BMap is not defined - 正确分工：Webman 返回 JSON 数据（如经纬度、地址文本），前端用
fetch拿到后交给BMap渲染
前端必须引入百度地图 JS SDK，且需 HTTPS
从 2024 年起，Chrome、Safari 等主流浏览器已强制要求 navigator.geolocation 在 HTTPS 下才能启用高精度定位；百度 JS SDK 的 BMap.Geolocation 也依赖此机制。HTTP 页面即使引入了 https://api.map.baidu.com/api?v=3.0&ak=xxx，getCurrentPosition 也会静默失败或降级为 IP 定位（城市级，误差 >1km）。
调用百度PaddleOCR‑VL大模型API，支持PDF、Word、PPT、图片等多格式文档解析，精准识别印刷体、手写体、表格、公式、图表、印章等复杂元素，支持100+语言，可处理不规则布局和跨页长文档。触发词：文档解析、VLM解析、大模型OCR、PaddleOCR、多模态文档、手写识别、公式识别、复杂版面。
- 本地开发调试时，可用
localhost（浏览器认为其安全），但127.0.0.1或自定义域名需配 HTTPS - 检查控制台是否报错：
Only secure origins are allowed或Geolocation permission denied - 确保
ak已在百度地图开放平台配置了当前域名白名单（含端口，如localhost:8000）
Webman 中调用百度 Web 服务 API 的关键参数
后端调用如地址解析，应使用百度 Web 服务 API（非 JS SDK），接口稳定、无需前端上下文，且无跨域问题。注意几个易错点：
-
geocoding/v3接口必须带output=json和有效ak，否则返回 400 或空响应 - 中文地址需
urllib.parse.quote编码，例如address=urllib.parse.quote("北京市海淀区中关村") - 反查接口
reverse_geocoding/v3的location参数格式必须是"lat,lng"（纬度在前），不是"lng,lat"，填反会导致返回错误城市 - 生产环境务必加超时和重试：
requests.get(url, timeout=5)，避免因百度接口抖动阻塞 Webman 请求线程
定位失败时别硬刷页面，先看 status 码
前端用 BMap.Geolocation.getCurrentPosition 失败时，this.getStatus() 返回的是百度自定义状态码，不是 HTTP 状态码。常见值有：BMAP_STATUS_SUCCESS（0）、BMAP_STATUS_PERMISSION_DENIED（1）、BMAP_STATUS_TIMEOUT（2）、BMAP_STATUS_UNKNOWN_ERROR（3）。iOS 15+ 默认禁用定位，用户需手动进「设置 → Safari → 定位服务」开启；Android WebView 需额外注入 WebChromeClient 支持权限弹窗。
- 不要只判断
r.point是否为空——status 为 1 或 2 时r可能是undefined，直接取r.point会报Cannot read property 'point' of undefined - 建议统一兜底逻辑：status !== 0 时，fallback 到百度 IP 定位（
new BMap.LocalCity().get()），至少拿到城市名 - Webman 后端若收到空坐标，不应直接抛异常，而应回传
{"code": 400, "msg": "定位不可用"}，由前端决定展示默认地图或提示用户授权
最常被忽略的是：百度地图 JS SDK 的定位能力本质是“浏览器能力代理”，它不替代原生定位，只是封装和增强。Webman 的角色始终是数据中转与业务校验，而非地图引擎。把责任边界划清楚，比堆代码更重要。
