hl-api-changelog/changelogs/2026-04/2026-04-18-resource-pagination-and-search-fixes.md

资源模块分页与搜索修复（素材 limit 参数 + 活动/餐厅/服务按城市搜索）

• 日期: 2026-04-18
• 服务: hl-resource-service（端口 8082）
• 类型: BUG 修复（非破坏性，向后兼容）
• 优先级: P2
• 前端影响: 无需改代码，但会有"分页不再多算空页 / 搜索匹配范围扩大"的观感变化
• 关联 PR: #798、#806
• 关联 Issue: #797、#804

---

总览

本次合并两个修复到 dev，都在 hl-resource-service：

PR	影响接口	问题	修复
#798	GET /admin/material/list	前端传 ?limit=12 后端不识别，始终按默认 pageSize=20 返回	pageSize 字段追加 @JsonAlias("limit")，并新增 setLimit setter
#806	GET /admin/activity/items、GET /admin/restaurant/items、GET /admin/service/items	keyword 只匹配名称/描述/亮点，搜"呼伦贝尔"等城市名匹配不到	keyword like 条件扩展到省/市/区（或地址）字段

⚠️ GET /admin/scenic/spots（景区列表）未改动，保持原行为（按用户要求）。

---

修复一：素材列表支持 limit 参数（PR #798）

影响接口

GET /admin/material/list

现象对比

修复前：

请求: GET /admin/material/list?page=1&limit=12&categoryCode=product&fileType=image
响应: { "data": { "records": [...共 20 条...], "total": 56, "page": 1, "pageSize": 20 } }

• 前端本来就在传 ?limit=12，但后端字段名叫 pageSize，不识别 limit，直接走默认值 20
• 前端计算 总页数 = ceil(total / limit) = ceil(56 / 12) = 5，但实际后端按 pageSize=20 返回 → 真实页数只有 3
• 用户点到第 4、5 页 → records 为空数组，体验是"后面几页是空的"

修复后：

请求: GET /admin/material/list?page=1&limit=12&categoryCode=product&fileType=image
响应: { "data": { "records": [...共 12 条...], "total": 56, "page": 1, "pageSize": 12 } }

• limit 被后端识别，pageSize 回传为请求的 limit 值
• 前端分页控件算出的页数与后端实际页数一致，不再出现空页

行为保持不变：

• 前端如果传 ?pageSize=15 → 后端仍按 15 处理（原行为）
• 同时传 ?pageSize=20&limit=12 → 以 limit=12 为准（@JsonAlias 会覆盖同名字段，不建议前端同时传）
• 不传任何分页参数 → 默认 pageSize=20

前端适配

• 无需改代码。前端本来就传 limit，之前是无效参数，现在生效
• 观感变化：分页器的页数显示可能"变少了"，那是因为之前的页数是虚高的；真实数据没变
• 若前端之前为了兼容"后面是空页"写过判断（如跳到最后一页发现是空就回退），可以保留，不会有副作用

接口契约

请求：

GET /admin/material/list?page=1&limit=12&categoryCode=product&fileType=image
Authorization: Bearer {token}
tenant-id: {租户ID}

常用查询参数：

参数	类型	必填	说明
page	Integer	否	页码，默认 1
pageSize / limit	Integer	否	每页条数，默认 20；两个名字后端都认，推荐 pageSize
categoryCode	String	否	素材分类码（例：product）
fileType	String	否	文件类型（例：image）

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [ /* 素材对象列表 */ ],
    "total": 56,
    "page": 1,
    "pageSize": 12
  },
  "success": true
}

---

修复二：活动/餐厅/服务列表 keyword 支持省市区模糊搜索（PR #806）

影响接口

接口	模块	说明
GET /admin/activity/items	游玩项目	活动列表（按 keyword / cityKeyword 检索）
GET /admin/restaurant/items	餐厅	餐厅列表
GET /admin/service/items	服务	服务项列表

GET /admin/scenic/spots（景区）未改，保持原行为。

现象对比

修复前（以 activity 为例）：

请求: GET /admin/activity/items?keyword=呼伦贝尔&page=1&pageSize=20
响应: { "data": { "records": [], "total": 0, ... } }   ← 0 条

• keyword 只 like 匹配 name / description / highlights 三个字段
• 如果一条活动名字叫"草原骑马"、描述里没写"呼伦贝尔"，就算它 city 是"呼伦贝尔"，也搜不到

修复后：

请求: GET /admin/activity/items?keyword=呼伦贝尔&page=1&pageSize=20
响应: { "data": { "records": [...呼伦贝尔下面的活动...], "total": 18, ... } }

• keyword like 匹配范围扩大到 名称 + 描述 + 亮点 + 省 + 市 + 区
• 搜"海拉尔"、"内蒙古"、"额尔古纳"等都会命中对应地名的记录

各接口的 keyword 匹配字段

接口	修复前 keyword 匹配字段	修复后 keyword 匹配字段
/admin/activity/items	name, description, highlights	name, description, highlights, province, city, district
/admin/restaurant/items	name, description, highlights	name, description, highlights, province, city, district
/admin/service/items	name, description, highlights	name, description, highlights, province, city, address (service_item 表无 district 字段,用 address 代替)

与 cityKeyword 的关系

• cityKeyword 是三个接口已有的独立参数，仍然只按 city 字段模糊匹配
• 前端若同时传 keyword 和 cityKeyword，两者是 AND 组合（都要满足），行为不变
• 建议前端保持现有用法不动；单独搜框用 keyword 即可覆盖绝大多数场景

前端适配

• 无需改代码。keyword 参数名、类型、返回结构完全不变
• 观感变化：同一个 keyword 在活动/餐厅/服务列表里可能比以前多返回一些结果（因为多匹配了省/市/区字段），这是预期内的
• 若前端文案里显式写了"按名称/描述搜索"，建议改成更宽松的"按名称、描述、地点搜索"（可选，非强制）

接口契约（以 activity 为例，另两个类似）

请求：

GET /admin/activity/items?keyword=呼伦贝尔&page=1&pageSize=20
Authorization: Bearer {token}
tenant-id: {租户ID}

常用查询参数（均为可选）：

参数	类型	说明
keyword	String	关键词（本次扩展：名称/描述/亮点/省/市/区）
cityKeyword	String	仅按城市匹配（未变）
page	Integer	页码，默认 1
pageSize	Integer	每页条数，默认 20

响应结构：保持原样，不赘述。

---

向后兼容性

• ✅ 接口路径、请求参数名、响应字段结构、HTTP code、业务 code 完全不变
• ✅ 前端已有代码无需任何修改
• ✅ 景区接口未动
• ⚠️ 两个修复会带来"分页页数更准"和"搜索结果变多"的观感变化，属于预期行为

---

重启服务

仅需重启 hl-resource-service（端口 8082）

• 测试环境：通过 Deploy Panel 重启（参考 memory/deploy-panel.md）
• 正式环境：本次先不上正式
• DDL 变更：无
• 配置变更：无

---

关联信息

项	值
PR #798	fix(resource): 素材列表分页兼容前端 limit 参数 → dev
PR #806	fix(resource): 活动/餐厅/服务列表 keyword 支持省市区模糊搜索 → dev
Issue #797	素材列表 limit 参数不生效导致分页虚高
Issue #804	活动/餐厅/服务按城市名搜索匹配不到
服务	hl-resource-service（8082）