From 04f75080629ec718b93017815d8090524dfeda6d Mon Sep 17 00:00:00 2001 From: wangheng Date: Thu, 24 Sep 2026 09:46:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(mcp):=20=E5=B7=A5=E5=85=B7=E5=8F=82?= =?UTF-8?q?=E8=80=83=E6=96=87=E6=A1=A3=E6=96=B0=E5=A2=9E=E8=AE=BE=E5=A4=87?= =?UTF-8?q?=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E4=B8=A4=E4=B8=AA=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E7=AB=A0=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../doc/agent-mcp-tools-reference.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md b/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md index 4f14e14..8d46e5f 100644 --- a/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md +++ b/xiaoqu-agent-service/doc/agent-mcp-tools-reference.md @@ -884,6 +884,48 @@ --- +## 35. hardware.device.lifecycle.query + +按 SN 查询设备生命周期当前状态，复刻老系统 `/lifeCycle/lifeCycleListByPage`。 +完整设计见 [device-lifecycle-mcp-tool-design.md](device-lifecycle-mcp-tool-design.md)。 + +- 分类：hardware ｜ 类型：读 +- 数据来源：m0 `device_life_cycle`，固定 `soft_delete=0`，`sn_code` 模糊匹配，id 升序分页。 +- 入参：`snCode`（必填，非空，模糊匹配）；`page`（默认 1）；`rows`（默认 20，上限 100，超出截断并在 notice 说明）。 +- 返回五组状态及中文文案：流转（exchangeState，含上一步 upExchangeState）、在途（roadState）、 + 在库（inventoryState）、联网（networkState）、资产（assetState）； + 另有生产/出厂/首用/报废/重工日期、归属公司（assetOwner）、最近流转人与时间、 + 最近在线时间与经纬度、金蝶同步状态。 +- 在途设备（roadState=1 且 roadDate 非空）返回 `roadDays`（在途天数）与 `roadDaysFlag`（超期标记）； + 阈值取 Redis Hash `Dictionary.MaxRoadDays`，缺失或非法时 fail fast 抛错，不静默兜底。 +- roadState/inventoryState 含 `-1=初始化`；未知枚举值返回 `未知(code)`，不抛错。 +- 与老系统差异：不做任何行/字段权限过滤；不复制老系统 `exchange_state∈(0,1)` 的排除，全状态可见。 + +## 36. hardware.device.lifecycle.detail.query + +按 SN 查询设备生命周期事件时间线，复刻老系统 `/assetDepreciationSet/lookDetail`。 + +- 分类：hardware ｜ 类型：读 +- 入参：`snCode`（必填，非空，精确匹配，自动去空格）。 +- 事件来源（全部固定 `soft_delete=0`）： + - 未生产：m0 `hardware_sncode` 生产档案（订单号/批次/物料/NFC/软硬件版本，时间取建档时间）； + - 生产中：`hardware_sncode.unbing_time`（解绑时间）； + - 生产完成：m0 `hardware_check_record`（时间取 modify_time；老系统标题「生成完成」系笔误，改为「生产完成」）； + - 入库/重工：m2 `warehouse_in_details`（`order_state=3` 已确认；仓库号 `1000000998` 为重工仓，标题改为「重工」）； + - 出库/出厂：m2 `warehouse_out_details`（`order_state=3`；仓库号 `BJ001` 为出厂仓，标题改为「出厂」）， + 附发货信息（优先 `mall_order_no` 查 m1 `mall_order_logistics`：sendMode=0 快递返回物流公司/单号， + 1 自行派送返回派送人，其余不返回；物流公司名直接用冗余列 `logistics_name`，不 join mall_logistics）； + - 安装/上线/下线：m0 `hardware_install_log`（logType 0/1/2）； + - 备用：ES 云集群 `hardwarelog` 索引（term snCode + term logType=备用机操作日志，id DESC，上限 1000； + 低阶 RestClient 实现，生产 ES 7.7.1 与高阶客户端不兼容；ES 异常 fail fast）。 +- 事件统一为 `{type,title,time,fields}`，按操作时间倒序；备用机日志时间文本解析回时间参与排序，解析失败沉底。 +- 代理/物业/站点/仓库/操作人名称批量 `selectBatchIds` 解析（避免老代码逐条查询的 N+1），解析不到返回 null 不抛错。 +- SN 在 Redis Set `SpecialSncode` 中跳过备用机日志查询（对齐老系统）。 +- SN 不存在时返回 `found=false`、`events=[]` 并在 notice 说明，不报错。 +- 与老系统差异：不做代理角色限制；发货图片不返回。 + +--- + --- ## 附录：在线查看工具清单