docs(mcp): 工具参考文档新增设备生命周期两个工具章节

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 说明，不报错。
+- 与老系统差异：不做代理角色限制；发货图片不返回。
+
+---
+
 ---
 
 ## 附录：在线查看工具清单