wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/17_前端接线_新建订单选主题向导接口对照-后端已实现仅需接线-管理后台.md

11 KiB
原始文件 Blame 文件历史

【前端接线·管理后台】「新建订单」向导第1步「选主题」接口对照——后端核心全已实现，仅需前端接线（含联动第2步「选产品」）

页面：管理后台 → 订单 → 新建订单（order-v2/new）第1步「选主题」、联动第2步「选产品」 | 服务：hl-product-service-v2（order-picker 端点）+ hl-order-service-v3（热门下单量，内部 Feign）| 无 PR，后端零改动 | 负责：mmg 核验方式：2026-06-17 源码全链路审计（热门链路追到 order-v3 Mapper 真查订单表）+ 测试服 admin token 经网关 9443 实测 3 端点全 200

⚠️ 关键判定：核心接口全部已实现且实测可用，没有缺失的必备接口

这个页面用到的后端接口全部已上线，热门标识是真实计算（不是写死/Mock）。需要前端处理的只有 2 处「前端本地实现」（搜索、最近选过）、1 处「确认删除」（分类 tab，wx 已批注不需要）、1 处「待 wx 拍板」（卡片地区标签）。

术语对照（必读，否则字段对不上）：前端「主题」= 后端「产品线 ProductLine」(lineId)；前端「产品/版本」= 后端「产品 Product」(productId)；前端「SKU/规格/档位」= 后端「档位 tier」(tierSeq)。

接口对照总表

页面数据块 后端落地 取数方式 前端动作
主题卡片网格 ✅ 已实现 GET /admin/product/line/order-picker 直接接
「热」角标 + 「热门主题·直接进入」 ✅ 已实现（真实算） 同上 hot 字段；入口=filter(hot==true) 本地筛，不要新接口
顶部统计头（在售数/SKU总/最低人均） ⚠️ 无接口 从上面列表前端派生 本地算
搜索框（主题/目的地/关键词） ⚠️ 无入参 在已返回列表本地模糊匹配 本地搜
分类筛选 tab（西藏/云南/日本…） ✅ 确认删除 后端无目的地数据源，无法过滤 直接删
「最近选过」 ⚠️ 无接口 localStorage 本地历史 本地存取
第2步「选择产品」 ✅ 已实现 GET /admin/product/item/order-picker?lineId= 直接接
选档位/规格 ✅ 已实现 GET /admin/product/item/{productId}/tiers 直接接
网关路由 ✅ 全放行 /admin/product/** → product-v2 经网关 9443 调通
卡片「国内·西藏」地区标签 ✅ wx 拍 A：不显示 第1步主题 VO 不返回，后端零改动 地区标签不显示

1. 第1步「选主题」主接口（直接接）

GET /admin/product/line/order-picker（经网关 9443，路由已配 /admin/product/**）

  • 入参：无（不分页，一次性返回全部在售主题；数据权限由后端按当前管理员自动过滤）
  • 返回：Result<List<OrderPickerThemeVO>>
字段 类型 含义
lineId String（雪花，序列化为字符串） 主题ID，下一步选产品要传它
name String 主题名称（布达拉宫朝圣…）
description String 主题描述
coverImageUrl String 主题封面图 URL
productType String CORE=核心产品 / GROUP=小蒙马 / CUSTOM=私人定制
skuCount Integer 该主题下已上架产品的档位总数（= 页面「X 个 SKU」）
fromPrice String（金额，可能为 null） 最低成人起价（= 页面「起 ¥XXXX / 人」；全无价返 null，前端兜底）
hot Boolean 是否热门（见第 2 节）
  • 只返「ACTIVE + 下挂 ≥1 个已上架产品」的在售主题，按排序号升序。
  • ⚠️ fromPrice 是字符串（后端 @JsonSerialize(ToStringSerializer)，防大数精度丢失），前端展示前自行 parseFloat。

请求示例：

GET https://api.test.1814.love:9443/admin/product/line/order-picker
Authorization: Bearer {adminToken}

响应示例（节选，实测）：

{
  "code": 200,
  "data": [
    { "lineId": "2056937785918369794", "name": "呼伦贝尔产品-yst", "productType": "CORE",
      "skuCount": 6, "fromPrice": "3105.00", "hot": true,
      "coverImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...png", "description": "..." },
    { "lineId": "2043694738304880641", "name": "草原深度游", "productType": "CORE",
      "skuCount": 3, "fromPrice": "2980.00", "hot": false, "coverImageUrl": "...", "description": "..." }
  ]
}

2. 热门（「热」角标 + 「热门主题·直接进入」入口）——真实落地，无需新接口

  • hot 是唯一数据源：近 90 天下单量在当前返回列表内降序排名前 30%（向上取整、至少 1 名）且下单量 > 0 → true。
  • 链路已核到底：product-v2 → 内部 Feign → order-v3 GET /v3/internal/order/stats/product-order-count → 真 selectCount 查 order_main 表（非 Mock）。实测当前测试库返回 1 个 hot=true 主题，证明实时计算生效。
  • 「热门主题·直接进入」不是独立接口 = 同一份 order-picker 列表里 hot==true 的子集，前端本地 filter 即可，不要再找/要求新接口。
  • 降级行为：order-v3 不可用时，列表照常返回但所有 hot=false（不报错、不阻断），前端按 hot=false 正常渲染即可（此时无角标、无热门入口属预期降级）。
  • 口径说明（非 bug，设计如此）：热门按「下单量（含未支付/已取消单）」算，不是「成交量」；在售主题很少时可能出现「几乎都标热」。如要改成「成交热」口径需 wx 另拍，目前保持现状。

3. 统计头 / 搜索框 / 最近选过 —— 前端本地实现，后端无接口（也不需要）

  • 统计头（在售主题数 / SKU 总数 / 最低人均）：无独立接口，从第 1 节列表直接派生：
    • 在售主题数 = list.length
    • SKU 总数 = Σ skuCount
    • 最低人均 = min(fromPrice)（后端口径是「最低成人起价」，与「最低人均」基本等价；后端无单独「人均」概念）
  • 搜索框：order-picker 零入参、不分页、一次返全量（量级 = 公司在售主题数，很小）。前端在已返回列表上按 name / description 本地模糊匹配即可，后端无需加参。
  • 「最近选过」：后端无最近浏览接口（全范围 grep recent/viewed/footprint/history 仅命中小程序 C 端，与后台无关）。前端用 localStorage 自存浏览历史，无需对接后端。

4. 分类筛选 tab（全部/西藏/内蒙古/云南…）—— 确认删除

  • wx 批注「不需要」正确，额外实锤：product_line 表根本没有 region / 目的地 / 分类 任何结构化列（只有 name / product_type / description / seasons / tags / cover…），后端本就无法按目的地过滤主题。
  • → 前端直接删这排 tab，不要让后端补地区维度（那是另一个数据建模工程，非本页范畴）。

5. 第2步「选择产品」+ 选档位（直接接）

5.1 选产品列表：GET /admin/product/item/order-picker?lineId={第1步选中的lineId}&keyword=&pageNo=1&pageSize=20

  • lineId 必填；keyword 可选（按产品名模糊）；分页。
  • 返回 PageResult<OrderPickerProductVO>，字段（实测全有）：
字段 类型 含义
productId String 产品ID（前端「版本」）
name / subtitle String 产品名 / 副标题
tripDays / tripNights Integer 行程天数 / 晚数
tags List<String> 产品标签（实测返回 ["国内"] 之类）
coverImageUrl String 封面图
startPrice String（金额，可 null） 起步价（各档位未来可售最低成人价的最小值）
tierPrices List 档位起价列表（档位序号/名称/描述/该档起价）
hot Boolean 是否热销（同主题热门口径，order-v3 90 天下单量前 30%）
nextSaleDate LocalDate（可 null） 最近可售日（CORE/CUSTOM 取价格日历最早未来可售日，GROUP 取最近未来班期出发日）

5.2 选档位/规格：GET /admin/product/item/{productId}/tiers

  • 返回 List，字段 tierSeq（规格序号，1 起）/ tierName（如「舒适」）/ tierDescription。
  • tierSeq 是后续算价/下单的入参，选档后带上。

6. 网关路由（无缺口）

  • /admin/product/** → lb://hl-product-service-v2，同时覆盖 /admin/product/line/** 与 /admin/product/item/**，两个 order-picker 端点经网关 9443 正常调通。
  • order-v3 的 /v3/internal/... 是 product-v2 内部 Feign LB 直连（不经网关，admin token 直调会被安全过滤返 403），前端不直接调它，不算路由缺口。

✅ 已拍板：卡片「国内·西藏」地区标签 —— 不显示（wx 2026-06-17 拍 A）

页面每张主题卡片左上原有「国内·西藏 / 国内·云南」地区标签。第1步 order-picker（OrderPickerThemeVO）不返回任何标签字段（数据虽存在于 product_line.tags、第2步产品 VO 也返 tags，但第1步主题 VO 未透出）。

结论：分类 tab 既已删，卡片地区标签一并不显示，后端零改动。 前端去掉卡片上的地区标签，不需要地区字段。（备查：若日后又要显示，最低成本是后端给 OrderPickerThemeVO 补 tags 字段，1 个字段、低风险，但「国内·」国别前缀无干净来源。）

测试服实测（admin token 经网关 9443，2026-06-17）

端点 结果
GET /admin/product/line/order-picker code=200，9 个在售主题，SKU 总 33，最低起价 ¥10，热门 1 个（hot=true 实时算出）
GET /admin/product/item/order-picker?lineId=... code=200，返回字段含 productId/name/subtitle/tripDays/tripNights/tags/coverImageUrl/startPrice/tierPrices/hot/nextSaleDate
GET /admin/product/item/{productId}/tiers code=200，返回 tierSeq/tierName/tierDescription

前端 TODO 清单

  1. 第1步卡片网格：接 GET /admin/product/line/order-picker（无参）。
  2. 「热」角标：用返回项 hot 渲染；「热门主题·直接进入」= 本地 filter(hot==true)，不要新接口。
  3. 统计头：本地算（length / Σ skuCount / min(fromPrice)）。
  4. 搜索框：本地按 name/description 匹配，不传后端。
  5. 删除分类筛选 tab（后端无数据源）。
  6. 「最近选过」：localStorage 本地实现。
  7. 第2步选产品：GET /admin/product/item/order-picker?lineId={上一步lineId}；选档位 GET /admin/product/item/{productId}/tiers，带 tierSeq 进算价/下单。
  8. 卡片地区标签：不显示（wx 已拍 A，后端零改动）。
  9. 金额字段 fromPrice/startPrice 是字符串，展示前 parseFloat，注意 null 兜底。