feat: poi id required

docs/2026-04-13_summary.md

@@ -38,6 +38,7 @@
 - 已补充上游 timeout 配置和 504 错误映射，避免外部超时被混淆为普通 500。
 - 已修正 `stops` 非空校验，并更新前端文档中 `deep_links` 与 `summary` 的语义边界说明。
 - 已为 FastAPI 增加可配置 CORS 中间件，默认允许本地 `localhost/127.0.0.1` 任意端口联调。
+- 已切换到严格 deep-link 模式：所有点必须先完成 POI 校验并拿到 `poi_id`，成功结果必须包含 deep link，否则直接失败。
 
 ## 下一步建议
 

docs/agent_design.md

@@ -119,6 +119,23 @@
 
 这样做的目的是把“长期规则”和“本次任务上下文”拆开，减少 prompt 污染。
 
+### 5.3 当前严格执行流
+
+当前版本已不再把“地址解析是否足够精确”和“deep link 是否能生成”完全交给模型决定。
+
+当前执行流如下：
+
+1. 服务端先对起点、终点、所有途经点做前置解析
+2. 每个点都必须成功完成：
+  - `maps_text_search` 命中精确 POI
+  - `maps_search_detail` 返回稳定坐标
+  - 取得 `poi_id`
+3. 任意一个点解析模糊、缺少 `poi_id`、或地理结果交叉校验失败，直接返回错误
+4. 只有在所有点都通过后，才把“预解析点位 JSON”交给 Agent
+5. Agent 只负责候选顺序、逐段驾车计算、最佳路线选择、summary 和 warnings
+6. 服务端最后再直接调用 `maps_schema_personal_map` 生成 deep link
+7. 如果 deep link 生成失败，则整个请求失败
+
 ## 6. 已实现的代码护栏
 
 ### 6.1 输入护栏
@@ -132,6 +149,7 @@
 - `origin_mode=fixed` 时必须提供 `origin_address`
 - 终点地址不能同时出现在 `stops`
 - `max_permutations` 如果传入，必须大于 0
+- `need_deep_link` 必须为 `true`
 
 ### 6.2 执行规模护栏
 
@@ -157,6 +175,9 @@
 - `origin_mode=current_location` 时禁止返回固定 `resolved_origin`
 - 成功结果必须至少有一个 candidate
 - `best_route` 必须能在 `candidates` 中找到对应项
+- `success` 必须为 `true`
+- 成功结果必须包含至少一个 deep link
+- 成功结果中的所有点必须带有 `poi_id`
 
 ### 6.4 配置护栏
 
@@ -188,6 +209,8 @@
 - 高德远程 MCP 连通性已验证
 - 单个途经点请求可成功返回结构化结果
 - 超限请求可返回 422，并中止模型执行
+- 已改为严格 deep-link 模式：成功结果必须包含 deep link，否则直接失败
+- 已增加前置点位解析与 POI 校验阶段，缺少 `poi_id` 或命中模糊时直接失败
 
 当前尚未完成：
 
@@ -227,6 +250,7 @@
 - `current_location` 模式尚未做专门增强
 - `need_html` 目前尚未实现独立展示层
 - 没有缓存机制，请求成本与工具调用次数直接相关
+- 当前严格策略可能会拒绝一部分“人看上去可接受、但程序判断为不够精确”的地址输入
 
 ## 10. 下一阶段 TODO
 

docs/frontend_api.md

@@ -111,7 +111,8 @@ Content-Type: application/json
   - 当前固定为 `driving`
 - `need_deep_link`
   - 可选
-  - 是否需要生成 deep link
+  - 当前必须为 `true`
+  - 该服务的成功结果必须包含 deep link
 - `deep_link_mode`
   - 可选
   - 可选值：`personal_map`、`route_plan`、`auto`
@@ -260,6 +261,7 @@ Content-Type: application/json
 - `deep_links`
   - 给前端做按钮跳转使用
   - 这是唯一应被前端当作链接处理的字段
+  - 当前成功结果至少会包含 `personal_map`
 - `summary`
   - 可直接展示给用户的简要说明
   - 这是纯展示文案，不是结构化链接字段，也不应被前端解析为跳转地址
@@ -324,6 +326,7 @@ Content-Type: application/json
 补充说明：
 
 - `deep_links` 中可能同时存在多个字段，也可能只有其中一个字段有值
+- 当前实现中，成功结果会强制生成 `personal_map`
 - 前端应只根据 `deep_links` 的字段值控制按钮展示，不要依赖 `summary` 推断应展示哪个按钮
 - `summary` 里可能会提到“个人地图链接”或“导航链接”，但这里只是说明文字，不保证包含真实 URL
 - 如果 `personal_map` 存在，表示当前更适合导入点位方案
@@ -343,8 +346,11 @@ Content-Type: application/json
 
 - 请求结构不合法
 - `stops` 为空
+- `need_deep_link=false`
 - 固定起点缺少 `origin_address`
 - 终点同时出现在 `stops`
+- 任意点未能解析到足够精确的 POI
+- 任意点缺少 `poi_id`
 - 请求候选上限超过服务上限
 - 实际排列数超过上限