# admin/product-v2: POI 搜索按城市限定 — 城市字段已在响应里, 在 `itinerary[0].gatherPlace`

> **服务**: hl-product-service-v2 (端口 8083)
> **关联**: 11_feat_admin_itinerary-mileage-anomaly-warnings.md 的第四节"前端建议改造 B"
> **日期**: 2026-05-11
> **影响范围**: 管理端产品编辑(step2) POI 搜索控件 — 仅前端改造, 后端 0 改动

---

## ⚠️ 关键变化(澄清前端误判)

前端反馈"产品详情没返回城市, 没法按 cityCode 限定 POI 搜索"。**这个判断不准确**:

- 顶层 `ProductDetailRespVO` 确实没有 `city/cityCode` 字段
- 但 `itinerary[i].gatherPlace` / `itinerary[i].dismissalPlace` 这两个 JSON 字段 **早就含完整城市/行政区信息**(后端从高德 POI 选点时就一并存了 cityName / adcode / districtName / provinceName / fullPath / township)

后端**不需要新加字段**, 前端直接读 `itinerary[0].gatherPlace.cityName / adcode` 即可。

---

## 一、字段位置实证

正式服 GET `/admin/product/item/{id}` 实测响应(产品 2053003990289129474、2052985893312008193、2052926308213891073 三例一致):

```json
{
  "data": {
    "itinerary": [
      {
        "dayNumber": 1,
        "gatherPlace": {
          "name": "云上呼伦贝尔",
          "poiId": "B0FFL...",
          "adcode": "150702",
          "address": "呼伦贝尔东山国际机场",
          "cityName": "呼伦贝尔市",
          "fullPath": "内蒙古自治区/呼伦贝尔市/海拉尔区/胜利街道",
          "location": { "lng": 119.809336, "lat": 49.5568 },
          "towncode": "150702010000",
          "township": "胜利街道",
          "districtName": "海拉尔区",
          "provinceName": "内蒙古自治区"
        },
        "dismissalPlace": { /* 同样结构 */ }
      }
    ]
  }
}
```

`dismissalPlace` 字段结构同 `gatherPlace`。

---

## 二、前端实现建议

### 1. 城市数据源(优先级)

```typescript
function getProductCity(detail) {
  const firstDay = detail.itinerary?.[0];
  const gather = firstDay?.gatherPlace;
  // 高德 POI 搜索 region 参数支持 adcode (推荐) 或 cityname
  return {
    cityName: gather?.cityName,
    adcode: gather?.adcode,
    fullPath: gather?.fullPath,
  };
}
```

### 2. 高德 POI 搜索调用

```typescript
// 高德 web 服务 v3 关键字搜索: region + citylimit=true
const params = {
  key: AMAP_KEY,
  keywords: userInput,
  region: productCity.adcode,      // adcode 比 cityname 更精确
  city_limit: true,                 // 强制只在 region 内搜
  output: 'json',
};
```

### 3. POI 搜索结果显示完整地址(根因防御)

每个 POI 结果项除了 `name` 之外, 把 `district + township` 也显示出来:

```
[结果项]
  恩和                                       ← name
  呼伦贝尔市 / 额尔古纳市 / 恩和俄罗斯族民族乡  ← district + township
```

让运营肉眼区分同名异地 POI(例如"恩和"在宝日希勒镇 vs 恩和俄罗斯族民族乡)。

---

## 三、边界场景处理

### Case A: DAY 1 集合地还没填(新建产品首次进 step2)

- 此时 `itinerary[0].gatherPlace` 是 `null`
- 第一个 POI 选择无 city 可限定 → **降级为全国搜索**, 选完后 setState 本地缓存 `cityName/adcode`
- 后续所有 POI 选择(DAY 1 节点 / DAY 1 解散 / DAY 2+...)都拿本地缓存做 region 限定

```typescript
const [productCity, setProductCity] = useState(null);
// 编辑已有产品时初始化:
useEffect(() => {
  if (detail.itinerary?.[0]?.gatherPlace?.cityName) {
    setProductCity(getProductCity(detail));
  }
}, [detail]);
// 用户选完 DAY 1 集合地后:
function onGatherPlacePicked(poi) {
  if (!productCity) {
    setProductCity({ cityName: poi.cityName, adcode: poi.adcode });
  }
  // ... 落库
}
```

### Case B: 跨城市产品(如内蒙呼伦贝尔 + 蒙古国边境)

- 取 DAY 1 gather 即可, 这是产品的"主城市"
- 跨城市产品本身在编辑时, 跨城段的 POI 会被 detector 的 `单段 > 100km` warning 命中, 让运营人工确认, 不依赖 region 限定

### Case C: gatherPlace 是老行政区格式(无 cityName, 只有 adcode + fullPath)

- 测试服新 schema 是行政区粒度, 字段更少
- 兜底: `cityName = fullPath?.split('/')?.[1]`(第 1 段省, 第 2 段市)
- 或: 拿 adcode 前 4 位 → 高德反查城市

```typescript
function extractCity(place) {
  if (!place) return null;
  if (place.cityName && place.adcode) return { cityName: place.cityName, adcode: place.adcode };
  if (place.fullPath) {
    const parts = place.fullPath.split('/');
    return { cityName: parts[1], adcode: place.adcode };
  }
  return null;
}
```

---

## 四、后端不需要做的事

明确不做(避免误改):

- ❌ 不在 `ProductDetailRespVO` 顶层加 `cityName/adcode` 冗余字段(数据已在 itinerary 里, 加冗余字段反而双源更易错乱)
- ❌ 不加 `product.city` 数据库字段(产品级城市当前业务无明确归属, "产品起点 = itinerary[0].gather" 这个隐式约定足够用)
- ❌ 不抽 `routeInfo.city` 字段(routeInfo VO 当前不含 city, 改它需要改 Entity + VO + 保存逻辑, 不值)

---

## 五、Test plan(给 mmg)

- [ ] 编辑产品 `2053003990289129474`, 在 DAY 4 集合地 POI 搜索输入"恩和", 验证只返回额尔古纳市恩和(50.83°), 不返回宝日希勒错点(49.28°)
- [ ] 新建产品, DAY 1 集合地选呼伦贝尔机场后, DAY 2/3/4 节点 POI 搜索自动限定到呼伦贝尔市
- [ ] POI 结果项显示 `district + township`, 让运营肉眼区分同名 POI
- [ ] 跨城市产品(如海拉尔出发去阿尔山)能正常编辑, 跨城段触发 detector warning 但不阻塞保存

---

## 六、参考

- 上一份 changelog: `11_feat_admin_itinerary-mileage-anomaly-warnings.md` 第四节有 POI 搜索改造的高层建议
- 实证脚本(只读 dump 字段): `D:\work2\HL\.tmp\prod_smoke_pr1939_mileage_warnings.py` (修改版可复用)
- 高德 web 服务文档: https://lbs.amap.com/api/webservice/guide/api/search (POI 搜索, region + citylimit 参数)