wx/hl-api-changelog

派生 0

API Changelog Bot dcd70ed61b fix: CitySelect 集合地/解散地下拉显示 JSON 字符串 BUG (任务 20260420)

2026-04-20 19:27:45 +08:00

10 KiB

原始文件 Blame 文件历史

fix(前端): CitySelect 集合地/解散地下拉显示 JSON 字符串而非城市名

类型: BUG（前端）
优先级: P1（核心产品编辑功能体验严重异常）
影响端: 管理后台（hl-ui）
后端是否需改动: ❌ 不需要。DB / API 数据完全正确，本次修复仅前端
是否影响保存: ❌ 不影响。保存数据完全正确，仅显示层 BUG，前端可放心修
任务文件: D:/work2/HL/docs/tasks/20260420_修复_行程开始结束下拉显示JSON.md
报 BUG 时间: 2026-04-20（wx 截图反馈）

一、现象描述

触发路径

管理后台 → 产品编辑 → 行程编排 → 任意 DAY（截图为 DAY 3「莫日格勒河之旅」）

页面 URL 示例：http://192.168.100.160:9527/product/edit?id=2045018534152478721

字段名说明（重要：截图标签 ≠ 代码字段名 ≠ 设计文档名）

截图上显示	设计文档 / 业务术语	前端 v-model	后端字段	DB 列
开始	集合地	`gatherPlace`	`gatherPlace`	`gather_place`
结束	解散地	`dismissalPlace`	`dismissalPlace`	`dismissal_place`

即截图所说的「开始 / 结束」就是「集合地 / 解散地」就是 gatherPlace / dismissalPlace。三套名字完全等价。

错误现象

两个下拉框（CitySelect 实例）的已选中显示文本直接渲染成了 JSON 字符串：

{"name":"黑山头镇","level"...
{"name":"海拉尔区","level"...

期望现象

应该只显示城市名，例如：

「黑山头镇」或 fullPath「内蒙古自治区/呼伦贝尔市/额尔古纳市/黑山头镇」
「海拉尔区」或 fullPath「内蒙古自治区/呼伦贝尔市/海拉尔区」

对照参考（同 DAY 内显示正常的元素）

同一 DAY 的 「途经路线」 显示正常：黑山头镇 → 白桦林景区 → 莫日格勒河 → 海拉尔区
这部分走的是 <span>{{ pt.name }}</span> 直接渲染（RouteTagBar.vue 行 70-82），不经过 n-select，所以不会触发本 BUG。

二、根因分析（前端 BUG，已通过三尺定位确认）

三尺数据验证

DB 真值（hl_product_service.product_itinerary_day 表）✅ 数据合法：

{"name":"黑山头镇","level":"street","adcode":"150784","fullPath":"内蒙古自治区/呼伦贝尔市/额尔古纳市/黑山头镇","levelName":"镇"}

API 响应（GET /admin/product/item/{id}）✅ 原样返回 dict（JsonObjectTypeHandler 自动反序列化为 LinkedHashMap），契约一致。
前端渲染（CitySelect.vue + n-select tag 模式）❌ BUG 在此

直接 BUG 文件

文件：D:/work2/hl-ui/src/components/CitySelect.vue

关键代码段：

// 行 58-64：n-select 的 value 永远是 stringify 字符串
const currentValue = computed(() => {
  if (!props.value) return null
  if (props.nameOnly) return props.value || null
  return JSON.stringify(props.value)   // → '{"name":"黑山头镇","level":...}'
})

// 行 143-161：watch immediate，仅当 options 为空时注入 1 项
watch(() => props.value, (newVal) => {
  if (newVal && options.value.length === 0) {
    options.value = [{
      label: formatLabel(newVal),
      value: JSON.stringify(newVal),
      tip: newVal,
    }]
  }
}, { immediate: true })

模板（行 164-180）：

<n-select
  :value="currentValue"      <!-- '{"name":"黑山头镇",...}' -->
  :options="options"
  filterable remote tag       <!-- ⚠️ 关键：tag 模式 -->
  :filter="() => true"
  ...
/>

根因机制（n-select tag 模式 + watch 时序竞态）

n-select 启用 tag 模式后，若传入的 value（已是 stringify 后的 JSON 串）在初次渲染时尚未在 options 中匹配到，会把 value 字符串本身当作"用户已创建的标签"渲染出来，并缓存该标签。
watch 虽然 immediate: true 注入 option，但因 props.value 在 setup 阶段可能为 null（store 异步加载详情数据）→ watch 跳过 → options 为空。
后续 store 注入数据触发 watch 再补 option 时，n-select 已经把"未匹配 value"渲染成 stringify 标签了，并不会回头重新匹配 label。

直接证据链

DAY 3 dismissalPlace.name 是「海拉尔区」→ 截图显示 {"name":"海拉尔区","level"...
截图字符串 = JSON.stringify(props.value) 的前缀，与代码逻辑完全吻合
同 DAY 的 routePoints 走 span 渲染，正常显示城市名

同组件其他用法是否受影响

searchForm.cityName（restaurant 搜索栏）：使用 nameOnly 模式，不受影响
RouteTagBar.vue 中的 gather/dismissal：完整 dict 模式，受影响

三、修复方案（前端 AI 三选一）

方案 A（⭐ 推荐，根治 + 改动最小）

操作：删 D:/work2/hl-ui/src/components/CitySelect.vue 行 176 的 tag 属性。

  <n-select
    :value="currentValue"
    :options="options"
    ...
    filterable
    remote
-   tag
    :filter="() => true"
    @search="handleSearch"
    @update:value="handleChange"
  />

效果：

n-select 进入"严格枚举"模式，找不到 option 时显示 placeholder 而不是把 value 当 tag 渲染。
watch 行 143-161 保留（保证刷新页面时 options 至少有当前 value 一项），覆盖回显场景。

风险点：

原 tag 用于让用户在搜索结果之外手动输入新城市；但本组件 searchDistrict 已通过 ?keywords= 远程搜（高德 API 覆盖全国行政区划），业务上不需要 tag。
如担心兜底，走方案 B 或 C。

方案 B（最小侵入，保留 tag 能力）

把 watch 改为同步 watchEffect，并保证 options 在每次 props.value 变化时强制覆盖（去掉 length === 0 短路条件）：

import { watchEffect } from 'vue'

watchEffect(() => {
  const v = props.value
  if (!v) return
  if (props.nameOnly) {
    options.value = [{ label: v, value: v }]
  } else {
    const stringified = JSON.stringify(v)
    const exists = options.value.some(o => o.value === stringified)
    if (!exists) {
      options.value = [
        { label: formatLabel(v), value: stringified, tip: v },
        ...options.value
      ]
    }
  }
})

效果：

保证 props.value 一变化（包括 store 异步注入），option 立即对齐，n-select 能匹配到 label，不走 tag 字符串渲染分支。

风险点：

仍依赖 n-select 内部"是否已渲染过 tag"的状态机。在某些极端时序下（首帧 value 已注入但 options 尚未更新到 DOM）仍可能有 1 帧闪烁。

方案 C（兼容性最好，不动任何业务逻辑）

n-select 增加 :render-tag 自定义渲染函数，强制把 tag 显示成 props.value.fullPath || props.value.name，与 options.label 一致。

<n-select
  ...
  :render-tag="renderTag"
/>

import { h } from 'vue'

function renderTag({ option }) {
  // option.tip 是 watch 注入时存的原始 dict
  const dict = option.tip || (typeof option.value === 'string' ? safeParse(option.value) : null)
  if (!dict) return option.label || option.value
  return h('span', null, dict.fullPath || dict.name)
}

function safeParse(s) {
  try { return JSON.parse(s) } catch { return null }
}

效果：

即使 n-select 把未匹配 value 当 tag 渲染，自定义 renderTag 也能保证显示文本是城市名。

风险点：

naive-ui 的 render-tag API 行为在不同版本可能略有差异（建议先看一眼当前使用的 naive-ui 版本文档）。

四、验收标准（修完请前端自查）

进入产品编辑页（任意已有 gather_place 的产品，例如 http://192.168.100.160:9527/product/edit?id=2045018534152478721），DAY 3「开始 / 结束」下拉框显示城市名（不再是 JSON 字符串）
切换不同 DAY，每个 DAY 的「开始 / 结束」均正常显示
点开下拉框，远程搜索其他城市仍可正常切换
切换后保存产品，重新打开编辑页，回显的城市仍正确
restaurant 搜索栏的城市筛选（CitySelect nameOnly 模式）功能未受影响

五、影响面

同组件复用点：
- searchForm.cityName（restaurant 搜索栏，nameOnly 模式）→ 不受影响
- RouteTagBar.vue 中的 gather / dismissal → 受影响
受影响产品数：所有 gather_place / dismissal_place 不为空的产品的编辑页均中招。
是否影响保存：不影响。store 里 productData.itinerary[i].gatherPlace 仍是后端返回的合法 dict，保存时 transformToSaveDays（行 460-470）原样回传，保存数据正确。仅"显示"层 BUG。
是否影响校验：不影响。校验 day.gatherPlace?.name（ItineraryStep.vue 行 32）能拿到 name。

六、后端附加提醒（非阻塞，不需要本次修，记录在册）

hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductItinerarySaveReqVO.java 行 40 / 44：

@ApiModelProperty(value = "集合地(高德行政区JSON)", required = true, notes = "{name,adcode,center,level}")
private Object gatherPlace;

@ApiModelProperty(value = "解散地(高德行政区JSON)", required = true, notes = "{name,adcode,center,level}")
private Object dismissalPlace;

问题：notes 注释里写的字段集 {name,adcode,center,level} 与 DB / API 实际字段集 {name,level,adcode,fullPath,levelName} 不一致：

多了 fullPath / levelName
少了 center

建议：等本次前端 BUG 修复确认无问题后，下个批次同步注释为 {name,level,adcode,fullPath,levelName} 并明确"此字段透传，至少包含 name 用于显示"。本次不动。

七、参考文件路径

受影响组件：D:/work2/hl-ui/src/components/CitySelect.vue（第 176 行 tag 是元凶）
调用方：D:/work2/hl-ui/src/views/product/edit/components/itinerary/RouteTagBar.vue 行 48-66
store：D:/work2/hl-ui/src/store/productEdit.js#loadDetail 行 255-335 / transformToSaveDays 行 460-470
后端 VO：D:/work2/HL/hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductItinerarySaveReqVO.java
任务文件（含完整三尺定位）：D:/work2/HL/docs/tasks/20260420_修复_行程开始结束下拉显示JSON.md

10 KiB 原始文件 Blame 文件历史 Unescape Escape

fix(前端): CitySelect 集合地/解散地下拉显示 JSON 字符串而非城市名

一、现象描述

触发路径

字段名说明（重要：截图标签 ≠ 代码字段名 ≠ 设计文档名）

错误现象

期望现象

对照参考（同 DAY 内显示正常的元素）

二、根因分析（前端 BUG，已通过三尺定位确认）

三尺数据验证

直接 BUG 文件

根因机制（n-select tag 模式 + watch 时序竞态）

直接证据链

同组件其他用法是否受影响

三、修复方案（前端 AI 三选一）

方案 A（⭐ 推荐，根治 + 改动最小）

方案 B（最小侵入，保留 tag 能力）

方案 C（兼容性最好，不动任何业务逻辑）

四、验收标准（修完请前端自查）

五、影响面

六、后端附加提醒（非阻塞，不需要本次修，记录在册）

七、参考文件路径

10 KiB

原始文件 Blame 文件历史