feat(mcp): 新增出纸机查询工具 hardware.list/detail.query (REQ-20260910-0012)

xiaoqu-agent-service/doc/agent-mcp-tools-reference.md

@@ -279,6 +279,62 @@
 
 ---
 
+## 10. hardware.list.query
+
+分页查询出纸机列表，对应老系统 `POST /hardware/listByPage`（HardwareViewController）。
+
+- 分类：hardware ｜ 类型：读
+- 数据来源：m0 库 `hardware_view` 视图，固定 `soft_delete = 0`、`id DESC`
+- 行级权限（`PermissionService.applyHardwareRowFilter`，与站点同一 `getByIsAgent(propertyFlag=true, className="property_id")` 变体）：
+  - 总部（isagent=0）：全部；
+  - 代理商（isagent=1）：`agent_id IN (自己 + 直属下级 + warehouse_agent_auth 代管代理)`，有代管物业授权时再 `OR property_id IN (agent_manage_district_auth 代管物业)`；
+  - 销售部门非负责人：`property_id IN (自己创建的物业 + 代管代理名下物业)`，与上一条互斥。
+- 富化（修正老接口 N+1，按页批量）：`agentName`/`propertyName`/`districtName` 走 Redis key `name:Agent:{id}` / `name:Properyt:{id}` / `name:District:{id}` multiGet；断纸状态 `piStatus` 批量读 `Assignment:{snCode}:29`（无 key 返回 0）；本页非空 `imsi` 一次性 IN 查 `networkcard` 表。返回 `hardware_view` 全字段，不做字段级权限裁剪。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| snCode | string | 否 | sn码，模糊匹配 |
+| deviceType | number | 否 | 设备类型：0=厕纸机 1=擦手纸机 |
+| status | number | 否 | 设备状态：1=在线 2=故障 3=离线 |
+| online | number | 否 | 上下线状态：1=上线 2=下线 |
+| lockMachineState | number | 否 | 锁机状态：0=未锁机 1=已锁机 |
+| agentId | number | 否 | 代理商 id，正整数，精确匹配 |
+| propertyId | number | 否 | 物业 id，正整数，精确匹配 |
+| districtId | number | 否 | 站点 id，正整数，精确匹配 |
+| buildingId | number | 否 | 楼 id，正整数，精确匹配 |
+| floor | string | 否 | 楼层，精确匹配 |
+| imsi | string | 否 | imsi码，精确匹配 |
+| page | number | 否 | 页码，从 1 开始，默认 1 |
+| rows | number | 否 | 每页条数，默认 20，上限 100（超出截断为 100 并在 notice 提示） |
+
+**出参 records 字段**：`hardware_view` 全字段（snCode、deviceType、status/online/lockMachineState 状态四元组、sysversion/firmwareVersion/voiceVersion/advertiseVersion、imsi、电量/纸量/电池族、各功能开关、memo 等，时间格式 `yyyy-MM-dd HH:mm:ss`）+ 富化字段 `agentName`/`propertyName`/`districtName`/`piStatus` + 物联网卡字段 `factoryType`/`carrier`/`dataBalance`/`dataUsage`/`iccid`/`msisdn`（按 imsi 匹配，无卡为 null）。
+
+---
+
+## 11. hardware.detail.query
+
+按 snCode 或 id 查询出纸机详情（二选一必填），行级权限与 `hardware.list.query` 一致。
+
+- 分类：hardware ｜ 类型：读
+- 数据来源：m0 库 `hardware_view` + `district_district_strategy`（站点信息）+ `networkcard`（物联网卡）
+- 设备不存在或无权查看时 `record=null` 并在 notice 说明（两者不区分，不泄露设备是否存在）。
+
+**入参**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| snCode | string | 条件必填 | sn码，精确匹配；与 id 二选一 |
+| id | number | 条件必填 | 设备 id，正整数，精确匹配；与 snCode 二选一 |
+
+**出参**：
+
+- `record`：hardware_view 全字段 + 与列表同一套富化（agentName/propertyName/districtName、piStatus、物联网卡 factoryType/carrier/dataBalance/dataUsage/iccid/msisdn）。
+- `record.site`（关联站点，district 表现有字段）：`districtId`、`districtName`、`province`、`city`、`countyseat`、`address`、`contact`、`phone`、`buildingId`、`floor`。注意 district 表无经纬度和楼名字段，楼座/楼层取 hardware_view。
+
+---
+
 ## 附录：在线查看工具清单
 
 ```bash