Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/hardware-statistics-query-mcp-tool-design.md
T
xiaoqu-ai 91d8e6e7a8 feat(mcp): hardware.statistics.query 按物业统计设备数/在线/故障/离线
背景:CRM 经营画像需要"每客户设备数、离线数"。当前做法同步 devices 全量
(71,034 行,抽样 1000 台仅 13 台绑定物业,其余 property_id="0"),代价远大于收益。

本工具直接返回聚合结果:
- 入参 propertyId 或 propertyIds(≤20,去重),includeUnbound 默认 false
- 返回每物业 total/online/fault/offline + data_cutoff_at + notice
- 口径与 hardware.list.query 一致:hardware_view、soft_delete=0、status 1/2/3
- 行级权限复用 PermissionService.applyHardwareRowFilter
- 每物业 4 次 selectCount(项目未注册分页拦截器;无 clone 先例,重建 wrapper)

测试:DeviceStatisticsToolsTest 5 例(参数校验/超限/计数/权限调用/去重)全过。
设计文档:doc/hardware-statistics-query-mcp-tool-design.md(含待评审三问)。
2026-10-20 16:34:08 +08:00

87 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# hardware.statistics.query · MCP 工具设计
> 状态:待评审(评审通过后回写追加决策)
> 关联:CRM 客户经营画像 v1.1「设备台数 / 设备离线」因子
> 日期:2026-10-20
## 1. 背景
CRM 经营画像需要"某客户有几台设备、几台离线",用于:
- 价值分因子「设备台数」;
- 风险分因子「设备异常(离线占比)」。
当前下游做法是同步 `devices.changes.list`(`m0.hardware_view` 全量)后在 CRM 侧聚合,实测问题:
| 问题 | 数据 |
|---|---|
| 未绑定物业的设备占绝大多数 | 抽样 1000 台,`property_id != 0` 的仅 **13 台(1.3%)**;未绑定用字符串 `"0"` 表示(不是空串) |
| 全量 71,034 行 | 同步 98.7% 无效行,占磁盘、拖慢同步 |
| 下游还要自己维护投影表 | 与"只读查询"的定位不符 |
结论:下游只需要统计值,应由 MCP 直接提供聚合结果。
## 2. 老系统行为与坑
| 项 | 结论 |
|---|---|
| 老接口 | `hardware/listByPage`(`HardwareTools.hardware.list.query` 已对齐),支持 `propertyId` / `districtId` / `status` / `online` 过滤并返回 `total` |
| 无现成统计接口 | 工具目录 60 个工具中**没有**站点设备数统计工具;`district.paper.statistics.query` 只统计用纸(米/人次/换纸卷数),不含设备数 |
| 数据源 | `m0.hardware_view` 是**当前状态视图**,无历史 → 统计只反映调用时刻 |
| 状态枚举 | `status`:1=在线 2=故障 3=离线;`soft_delete=0` 为有效行 |
| 未绑定表示 | `property_id = 0`(字符串/数值零),不是空 |
## 3. 决策表
| 决策 | 选择 | 备选 | 理由 |
|---|---|---|---|
| 工具名 | `hardware.statistics.query` | `device.statistics.query` / `hardware.count.query` | 与既有 `hardware.*`、`district.paper.statistics.query` 命名一致 |
| 入参 | `propertyId`(单个)或 `propertyIds`(≤20) | 全租户一次返回 | 下游按客户查询;全量返回等于把聚合成本转给调用方,且无分页语义 |
| 默认是否含未绑定 | **不含**(`includeUnbound=false`) | 含 | 未绑定无法归属客户,计入会污染"客户设备数" |
| 返回结构 | `items[]` 每物业一行:`total/online/fault/offline` + `data_cutoff_at` + `notice` | 只返回四个总数 | 下游需要多客户时一次拿全 |
| 权限 | 复用 `PermissionService.applyHardwareRowFilter` | 新写过滤逻辑 | 与 `hardware.list.query` 完全一致,避免第二套权限口径 |
| 查询方式 | 每个物业 4 次 `selectCount` | 单条 `GROUP BY` | 项目未注册分页拦截器;`LambdaQueryWrapper` 无 clone 先例,重建 wrapper 更安全。20 物业 = 80 次轻量 count,可接受 |
## 4. 参数契约
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `propertyId` | Long | 否(与 propertyIds 二选一) | 物业 id,正整数 |
| `propertyIds` | Long[] | 否 | 物业 id 列表,上限 20;重复值去重 |
| `includeUnbound` | Boolean | 否 | 默认 false;true 时计入 `property_id = 0` 的设备 |
校验:两者至少提供一个;id 必须为正;数量 ≤ 20;否则 `IllegalArgumentException`。
## 5. 返回契约
```json
{
"items": [
{"property_id": 17, "total": 10, "online": 6, "fault": 2, "offline": 2}
],
"data_cutoff_at": "2026-10-20T08:40:00Z",
"notice": "数据源为 hardware_view 当前状态视图,仅反映调用时刻;未绑定物业设备未计入"
}
```
## 6. 与老系统差异
- 老系统无对应统计接口(只有分页列表 + total);本工具是其聚合封装,口径一致(同一张视图、同一套 status 枚举、同一套行级权限)。
- 不返回设备明细,避免下游误当列表用。
## 7. 测试要点
| # | 用例 |
|---|---|
| 1 | 未提供 propertyId / propertyIds → 报错 |
| 2 | 非正整数 / 超过 20 个 → 报错 |
| 3 | 单物业 → 4 个计数正确、返回 `data_cutoff_at` |
| 4 | 每个计数都调用行级权限过滤 |
| 5 | propertyIds 重复值去重 |
## 8. 待评审确认
1. 是否同意"默认排除未绑定设备"?
2. 单次上限 20 个物业是否合适?
3. 是否需要同时返回 `district_id` 维度(当前只按物业)?