xiaoqu_mcp_service/xiaoqu-agent-service/doc/device-lifecycle-mcp-tool-design.md

设备生命周期查询 MCP 工具设计

需求：设备生命周期按 SN 查询（列表 + 详情两个工具），2026-09-23 用户拍板「按建议来」

工具一：hardware.device.lifecycle.query（当前状态，列表） 工具二：hardware.device.lifecycle.detail.query（事件时间线，详情）

背景

老系统 LifeCycleController.lifeCycleListByPage（xiaoqu-franchisee :63-161）分页查询 device_life_cycle 表（m0 库，mapper 在 mapper.m0，与 battery_fault_log 同库）， 实体 beans.b0.DeviceLifeCycle（xiaoqu-publicbeanandmap）。

表字段（23 个业务字段）：

• 标识：sn_code、device_type（0出纸机/1空感/2电池/3充电箱/4泡沫机/5蓝牙网关）
• 状态组：exchange_state（0未生产/1生产中/2生产完成/3出厂/4报废/5自用/6出库/7入库/8安装/9上线/10下线/11备用/12解除备用/13重工）、 up_exchange_state（上次流转状态）、road_state（-1初始化/0落地/1在途）、 inventory_state（-1初始化/0非在库/1在库）、network_state（0离线/1在线）、 asset_state（0库存商品/1固定资产/2出租/3售出/4报废/5费用化）
• 日期组：producing_date、produce_finish_date、ex_factory_date、first_use_date、 discard_date、again_produce_date、road_date（在途开始时间）、last_online_date
• 归属：agent_id/agent_name（资产使用公司）、asset_owner_id/asset_owner_name（资产所属公司）、destination（去向）
• 其他：last_op_user/last_op_date（最近流转人与时间）、last_latitude_and_longitude（最近经纬度）、 jindie_sync_state/jindie_internal_id（金蝶同步）

老接口的行为与坑：

1. 行级权限：按 isagent + agentId 过滤行（本次用户拍板：不做权限，都可以查）。
2. 字段级权限：FieldWebpageAuthority 按用户角色动态裁剪返回列（MCP 场景无此概念，不复制）。
3. 写死排除 exchange_state ∈ (0,1)：列表里永远看不到"未生产/生产中"的设备。 按 SN 查设备的场景下这个排除会把新投产设备查成"不存在"，不建议复制（见决策表）。
4. 在途时长是计算字段：roadState=1 && roadDate!=null 时 roadDays = roadDate 到今天的自然日数； 超过 Redis Dictionary.MaxRoadDays 时 roadDaysFlag=1（列表标红用）。
5. 多类型日期区间、在途天数区间等筛选项是为列表页设计的，按 SN 查询用不上，不复制。
6. WrapperUtils.beanToWrapper 对字符串列是 like 模糊匹配（snCode 实际为模糊查询）。

设计决策（用户已拍板 2026-09-23）

#	决策	说明
1	不做任何权限校验	用户拍板：都可以查；访问控制由 MCP ak/scope 层兜底（与 electricity.message 一致）
2	不复制 exchange_state 排除	老系统写死排除未生产/生产中，按 SN 精确查会误报"不存在"；新工具全状态可见。若要严格对齐老列表口径请告知
3	snCode 模糊匹配	对齐老系统 like 语义：传完整 SN 返回唯一一条；传片段返回多条分页列表
4	保留在途时长计算	roadDays / roadDaysFlag 是老列表的核心展示字段，服务端算好返回；Redis Dictionary.MaxRoadDays 缺失时 fail fast（与 paper 系列工具一致）
5	枚举全部配文案映射	deviceType/exchangeState/roadState/inventoryState/networkState/assetState/jindieSyncState 各配 *Text 字段，LLM 友好
6	金蝶字段原样返回	jindieSyncState/jindieInternalId 保留，排查资产同步问题时有用

参数契约

• snCode：String，必填非空；like 模糊匹配（对齐老系统），命中唯一即单设备详情语义。
• page：Integer，默认 1（<1 归一为 1）。
• rows：Integer，默认 20、上限 100；>100 截断为 100 并在 notice 提示（与项目现有工具惯例一致）。

固定条件：soft_delete=0，按 id ASC 稳定排序（对齐老系统）。

返回契约

total / page / rows / notice? / records[]
record:
  snCode / deviceType / deviceTypeText
  exchangeState / exchangeStateText / upExchangeState / upExchangeStateText
  roadState / roadStateText / roadDate / roadDays / roadDaysFlag
  inventoryState / inventoryStateText / networkState / networkStateText
  assetState / assetStateText
  destination / agentId / agentName / assetOwnerId / assetOwnerName
  producingDate / produceFinishDate / exFactoryDate / firstUseDate / discardDate / againProduceDate
  lastOpUser / lastOpDate / lastOnlineDate / lastLatitudeAndLongitude
  jindieSyncState / jindieSyncStateText / jindieInternalId
  createTime / modifyTime

• 所有日期：yyyy-MM-dd HH:mm:ss（Asia/Shanghai），null 原样为 null。
• roadDays：仅 roadState=1 && roadDate!=null 时返回自然日数，否则 null；roadDaysFlag 默认 0， roadDays > MaxRoadDays 时为 1。
• 枚举值遇到未知 code：*Text 返回 未知(code)，原 code 照常返回（与 device_average 工具一致）。
• upExchangeState 为 null 时 upExchangeStateText 为 null。

代码结构

• entity/m0/DeviceLifeCycle：MyBatis-Plus 实体，映射 device_life_cycle 全字段。
• mapper/m0/DeviceLifeCycleMapper：BaseMapper，无需自定义 SQL（条件简单，LambdaQueryWrapper 即可）。
• mcp/tool/DeviceLifecycleTools：@XqTool(category="hardware", kind="read") + @Tool(name="hardware.device.lifecycle.query")；参数校验、枚举文案映射、在途时长计算、notice 拼接。

无权限校验、无 ES、无跨库 join，单表分页查询。

验证

• DeviceLifecycleToolsTest（mock Mapper）：空 snCode 拒绝且零 Mapper 交互；rows 上限截断 notice； soft_delete/id ASC 条件透传；枚举文案映射（含未知 code 与 null）；roadDays/roadDaysFlag 计算 （在途未超期/超期/非在途三种）；MaxRoadDays 字典缺失 fail fast；返回字段完整性；Spring AI schema。
• 全量 Maven 测试确认无回归。

工具二：hardware.device.lifecycle.detail.query（详情时间线）

老系统 AssetDepreciationSetController.lookDetail（xiaoqu-franchisee :141-418）按 SN 聚合 6 个数据源， 返回按操作时间倒序的生命周期事件列表（AssetDetailsOutput：title + 中文标签 LinkedHashMap）。

事件来源（全部 soft_delete=0）

事件 type	标题	来源	库	时间字段	字段
unproduced	未生产	hardware_sncode.create_time	m0	createTime	orderNo/orderPack/materialNo/materielFullName/nfcBound/sysversion/hardVersion/memo/operator
producing	生产中	hardware_sncode.unbing_time（null 则不产生）	m0	unbingTime	operator
produced	生产完成	hardware_check_record limit 1	m0	modifyTime	operator
inbound	入库	warehouse_in_details（order_state=3）	m2	inConfirmTime	inOrderNo/warehouseTypeName/applyUserName/applyTime/warehouseName/inConfirmUserName/inDate
rework	重工	同上，仓库号=1000000998	m2	同上	同上
outbound	出库	warehouse_out_details（order_state=3）	m2	outConfirmTime	outOrderNo/warehouseTypeName/applyUserName/applyTime/warehouseName/useCustomerName/outConfirmUserName/outDate + shipping
exFactory	出厂	同上，仓库号=BJ001	m2	同上	同上
install	安装	hardware_install_log（logType=0）	m0	onlineTime	agentName/propertyName/districtName/address/operator
online	上线	同上（logType=1）	m0	同上	同上
offline	下线	同上（logType=2）	m0	同上	同上
backup	备用	ES hardwarelog（term snCode + term logType=备用机操作日志，id DESC，size 1000）	云集群	createTime	agentName/propertyName/districtName/event/operator(userName)

发货信息 shipping（出库/出厂事件内嵌）：优先 mall_order_no、否则 out_order_no 查 m1 mall_order_logistics（soft_delete=0）；sendMode=0 → {mode:"快递", logisticsName, logisticsOrderNo}， sendMode=1 → {mode:"自行派送", deliverName}，其余/查不到不返回 shipping。 物流公司名直接用 mall_order_logistics.logistics_name 冗余列，不再 join mall_logistics（刻意的简化）。

老接口的坑与对策

1. 权限：仅代理角色 + 按公司过滤 → 按拍板不做权限。
2. SN 不在 hardware_sncode → 老接口报错「设备编号不正确」；新工具返回 found=false, events=[] + notice。
3. 老代码多处 NPE（名称解析不判空、sendMode null 拆箱）→ 全部 null 安全，查不到为 null。
4. 备用机日志 ES 异常被 catch 吞掉 → fail fast 抛 IllegalStateException（项目惯例）。
5. SN 在 Redis 集合 SpecialSncode 中跳过备用机日志查询（对齐老系统）。
6. 发货图片 OSS 列表不返回（对 LLM 无用，刻意差异）。
7. 老系统标题「生成完成」为笔误，改为「生产完成」。
8. 老排序 comparator 对相等时间违反契约 → 新排序 time DESC、null 排最后，稳定排序。
9. 老代码逐条 selectById 解析名称（N+1）→ 批量收集 id 后 selectBatchIds 一次解析。

参数契约

• snCode：String，必填非空，自动 trim；精确匹配（详情语义就是单台设备）。

返回契约

snCode / found / notice? / total / events[]
event: type / title / time / fields{...}

• time：yyyy-MM-dd HH:mm:ss（Asia/Shanghai）；入库/出库的 inDate/outDate 为 yyyy-MM-dd。
• events 按 time 倒序，null 时间排最后。

代码结构

• entity/m0：DeviceLifeCycle、HardwareSncode、HardwareInstallLog、HardwareCheckRecord、District（仅 id/districtName）
• mapper/m0：对应 5 个 BaseMapper
• entity/m2：WarehouseInDetails、WarehouseOutDetails、Warehouse（仅 id/warehouseNo）
• mapper/m2：对应 3 个 BaseMapper
• es/HardwareLogEsGateway(+Impl)：备用机日志查询，只注入 esCloudRestClient 低阶客户端 （生产 ES 7.7.1 与高阶客户端不兼容，见 EsClientConfig 注释）；ES 异常抛 IllegalStateException
• mcp/tool/DeviceLifecycleTools：两个 @Tool 方法，参数校验、枚举文案映射、在途时长计算、 事件聚合与名称批量解析、notice 拼接

验证

• DeviceLifecycleToolsTest（mock 各 Mapper + Gateway + Redis）： 列表——空 snCode 拒绝、rows 截断 notice、枚举映射、roadDays/roadDaysFlag、MaxRoadDays 缺失 fail fast； 详情——SN 不存在返回 found=false、各事件类型聚合与字段映射、出厂/重工仓库号特判、 发货信息两种 sendMode、SpecialSncode 跳过 ES、名称解析 null 安全、时间倒序、Spring AI schema。
• HardwareLogEsGatewayImplTest（mock RestClient）：term 过滤、id DESC、size 1000、 createTime epoch 毫秒归一、ES 异常包装。
• 全量 Maven 测试确认无回归。