Files

T

my_local_kimi_dev2 4e27f8137d feat(mcp): 新增清机记录查询工具 hardware.cleanlog.list.query

对齐老系统 /hardwareCleanLog/listByPage，修正 5 处老接口坑（设计文档
doc/hardware-cleanlog-mcp-design.md §5）：agentId 传了仍叠加行级 ACL、
富化/图片按页批量消除 N+1、时间过滤明确落 modify_time、status=1 硬过滤
口径保持、type!=0 时 beforeCleanPics 恒空保持。

- 实体/Mapper 从 publicbeanandmap 逐字段复制（25+13 列全核对）
- PermissionService 新增 applyHardwareCleanLogRowFilter（镜像
  applyHardwareRowFilter 同一 getByIsAgent 变体）
- 分页 selectCount+LIMIT 物理分页，rows 上限 100 截断+notice
- 图片 type=0 行内 picurl，type!=0 按页 IN 批量查 hardware_clean_pic
  按 order_no 拼 OSS URL
- 入参校验抛 ToolCallException(INVALID_ARGUMENT)
- seed-dev.sql 补 hardware/ops-query scope 绑定；reference 文档登记 #45

测试：新增 6 个单测，全量 482 tests 全绿

2026-11-04 18:04:02 +08:00

5.3 KiB

Raw Blame History

清机记录 MCP 工具设计（hardware.cleanlog.list.query）

对应老接口：/hardwareCleanLog/listByPage（xiaoqu-franchisee HardwareCleanLogController.java:62-132）。老系统无清机详情接口，本期只做列表查询 1 个工具。

1. 工具定义

name：hardware.cleanlog.list.query
category：hardware，kind：read
数据源：m0 hardware_clean_log 主表 + m0 hardware_clean_pic 图片表（纯 MySQL）
Token：用户委托 Token（在线查询工具，不发服务 Token）
scope：按 hardware 系列惯例绑 prod scope 1/2/3/5

2. 入参

参数	类型	必填	说明
districtId	Long	否	站点过滤（等值）
propertyId	Long	否	物业过滤（等值）
agentId	Long	否	代理过滤（等值）——与老接口不同，传了也仍然叠加行级 ACL（见 §5 差异②）
snCode	String	否	SN 码模糊匹配
userId	Long	否	操作人
type	Integer	否	清机方式：0=大清洁 1=小清洁
userRoleType	Integer	否	操作人身份：0=代理 1=物业 2=保洁
startTime / endTime	String(yyyy-MM-dd HH:mm:ss)	否	时间范围，落 `modify_time`（与老接口口径一致，见 §5 差异①）
minCleanRfidCount / maxCleanRfidCount	Integer	否	清理卷数范围
page / rows	Integer	否	分页，rows 默认 20、上限 100（对齐 hardware.list.query）

排序固定 id desc（老接口默认排序，不开放 sidx/sord）。

3. 返回结构

扁平 rows[] + page/rows/total，每行：

{
  "id": 1, "snCode": "...", "userId": 1, "userName": "...", "userRoleType": 0,
  "type": 0, "typeText": "大清洁",
  "cleanRfidCount": 3, "cleanRfidDays": 7, "memo": "...",
  "agentId": 1, "agentName": "...", "propertyId": 1, "propertyName": "...",
  "districtId": 1, "districtName": "...",
  "positions": "...", "workNo": "...", "assignmentId": 1,
  "maintenanceAgentId": 1, "maintenanceAgentName": "...",
  "maintenancePropertyId": 1, "maintenancePropertyName": "...",
  "poweredType": 0, "createTime": "...", "modifyTime": "...",
  "beforeCleanPics": ["http://..."], "afterCleanPics": ["http://..."]
}

userRoleType / type / poweredType 配 *Text 文案（0=代理/1=物业/2=保洁；0=大清洁/1=小清洁；0=电源/1=电池）。
富化（agentName/propertyName/districtName/userName）走 Redis name:Agent:* / name:Properyt:* / name:District:* multiGet 批量 + user 表按页 IN 批量，修掉老接口逐条 N+1（老 HardwareCleanLogController.java:96-126）。
图片：type=0 用行内 before_clean_picurl/after_clean_picurl；type≠0 按页 hardware_clean_id IN (...) 批量查 hardware_clean_pic（type=0 图片行），按 order_no 排序拼 OSS URL http://{ossbucketname}.oss-cn-beijing.aliyuncs.com/{ossfolder}{fileName}。老接口只填 afterCleanPicS，MCP 版按 order_no 归入 after 列表、before 仅在 type=0 时有值，差异记入 §5。

4. 权限与过滤

行级权限：复用 PermissionService.applyHardwareRowFilter（同一 getByIsAgent 变体，落 agent_id/property_id，与清机表字段同名，语义 1:1）；tenant_service 免过滤逻辑内置。
硬过滤 soft_delete=0 且 status=1（保持老口径，status 其他值语义无文档，见 §5 差异③）。
分页：项目无分页拦截器，selectCount + LIMIT 物理分页（禁用 selectPage）。
报错：入参校验失败抛 ToolCallException（INVALID_ARGUMENT，文案透出，对齐 REQ-20261012-0003 之后的新工具风格）。

5. 与老接口的差异（不照搬的坑）

时间过滤字段名误导：老接口入参叫 startCreateTime/endCreateTime（"清机时间"）实际查 modify_time。MCP 参数改名 startTime/endTime，description 明确"按记录修改时间（即清机时间）过滤"。
agentId 绕过 ACL：老接口前端传 agentId 时完全跳过行级权限（HardwareCleanLogController.java:73）。MCP 版始终施加行过滤，agentId 只是额外的等值条件，无权数据返回空。
status 硬过滤：老接口一律 status=1 且 status 字段无枚举文档，MCP 版保持 status=1 并在工具描述注明"仅返回有效清机记录"。
webId 字段裁剪：老接口按页面字段配置裁剪返回列，MCP 无对应物，返回全字段（与 hardware.* 既有工具一致）。
图片 N+1 与 before 缺失：批量查询修正；type≠0 时 before 列表恒空（老系统如此，保持）。

6. 改动清单

新增实体：me.iiv.agent.entity.m0.HardwareCleanLog、HardwareCleanPic（从 publicbeanandmap beans/b0 复制改包名——注意 publicbeanandmap 不是 Maven 依赖，必须本地拷贝，PR #30/#31 踩坑记录）。
新增 Mapper：me.iiv.agent.mapper.m0.HardwareCleanLogMapper、HardwareCleanPicMapper。
新增工具类：mcp/tool/HardwareCleanLogTools.java（@Component implements ToolObject，@XqTool(category="hardware", kind="read")）。
单测：参数校验、行过滤调用、type=0/≠0 图片分支、富化批量、分页上限。
seed-dev.sql 补 scope 绑定；README 与 doc/agent-mcp-tools-reference.md 登记。

7. 上线步骤

remote-deploy → ToolSyncService 自动注册 → prod 库 scope_tool 手工绑 scope 1/2/3/5 → 生产冒烟（望京 SOHO / 国大·沁里样本站点）。

5.3 KiB Raw Blame History Unescape Escape