Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/device-lifecycle-fixed-asset-mcp-design.md
T
my_local_kimi_dev2 37ce5a3443 feat(mcp): 新增设备转固定资产写工具 device.lifecycle.fixed_asset.update(REQ-20261117-0003)
按 SN 精确匹配把 device_life_cycle.asset_state 转为固定资产(1),memo 写来源状态文案;
已是固定资产/已报废守卫拒绝,null 按库存商品处理;只写 asset_state/memo/modify_id/
modify_time 四列,不联动资产卡片/金蝶;零行级权限,prod 只绑研发专用 scope 6。
DeviceLifeCycle 实体补 memo 字段映射(DB 列早已存在,老系统从未映射)。
2026-11-17 09:41:24 +08:00

7.8 KiB
Raw Blame History

设备转固定资产 MCP 工具设计

  • 需求:REQ-20261117-0003(id 6618,设计任务 27534)
  • 状态:审批通过(2026-11-17 王恒拍板,见 §5)
  • 作者:王恒分身(Kimi)
  • 日期:2026-11-17

1. 背景与目标

运维侧需要一个把设备资产生命周期记录「转固定资产」的写工具:按 SN 精确匹配,把 device_life_cycle.asset_state 从其他状态改成 固定资产(1),并在 memo 写明来源状态。老系统没有独立的「转固定资产」接口(asset_state 都随出入库流程联动变化),目前只能人工改库。

用户拍板口径(2026-11-17 原话):

  • 输入就是 SN 号,精确匹配,不模糊
  • 可以从其他状态变成固定资产;不允许从固定资产状态变成其他
  • memo 就写「从什么状态变成固定资产」

2. 调研结论(代码依据)

2.1 表与字段(m0.device_life_cycle)

  • asset_state int,枚举:0:库存商品; 1:固定资产; 2:出租; 3:售出; 4:报废; 5:费用化 (注释见 xiaoqu-publicbeanandmap/beans/b0/DeviceLifeCycle.java:126,本地拷贝 xiaoqu-agent-service/entity/m0/DeviceLifeCycle.java:54)
  • ⚠️ memo 列在 DB 里真实存在:dev 库实测 DDL 有 memo varchar(256) DEFAULT ''(2026-11-17 查 192.168.1.181 xiaoqu_comples_d)。但参考库 bean 和本地实体拷贝都没有映射该列——老系统经 Redis MQ 的 LifeCycleInput.memo 只用于逻辑分支(ScheduledTask.java:393 判断"调拨入库/调拨出库"),BeanUtils.copyProperties 不会落 memo 列,所以该列历史基本为空。本工具是首次真正写它。实现时需给本地实体补 memo 字段。
  • 软删 soft_delete(0 正常),sn_code 有索引。

2.2 老系统相关行为(不复制,仅对齐语义)

  • 资产状态联动全部发生在出入库流程里(PublicService.java:2381-2461、WarehouseAllocationServiceImpl.java:741-820):出库按下单公司类型给 1(固定资产)/3(售出)/0(库存商品),报废出库给 4,费用化给 5。
  • 没有「单独把某台设备转固定资产」的接口。
  • 老系统查生命周期记录按 sn_code 等值 + id ASC LIMIT 1(AssetDepreciationLogTask.java:68-72),本工具同口径(防重复 SN 行取最早一条)。
  • 联动边界(重要):改成固定资产不会自动生成 m2 asset_info 资产卡片——资产卡片由 Redis 队列 InsertAssetInfoQueue 驱动(设备上线时入队,AssetDepreciationLogTask.java:61-138 消费,且非出纸机仅 asset_state=0 时才建卡)。金蝶侧「库存转资产」也有自己的校验链路(WarehouseAllocationController.java:1598-1616)。本工具只改 device_life_cycle 一表,不触碰资产卡片/金蝶(见 §5 拍板点 5)。

2.3 平台既有先例

完全对齐首个 kind=write 工具 warehouse.order.handler.update 的模式(doc/warehouse-order-handler-update-mcp-design.md):零行级权限、门禁全靠 scope、svc audit_log 全量落审计、ToolCallException 透出报错文案。

3. 工具契约

3.1 基本信息

项 值
工具名 device.lifecycle.fixed_asset.update
标题 设备转固定资产
category admin
kind write
数据源 纯 MySQL(m0 device_life_cycle),无 ES
权限 零行级权限;门禁完全靠 scope:prod 只绑研发专用 scope 6(code=code),dev seed 只绑测试专用 scope;不绑业务 scope 1/2/3/5

3.2 入参

参数 类型 必填 说明
snCode string 是 设备 SN,trim 后非空,精确匹配(sn_code = ?),不模糊

3.3 返回

{
  "snCode": "XQ...",
  "deviceType": 0,
  "deviceTypeText": "出纸机",
  "oldAssetState": 0,
  "oldAssetStateText": "库存商品",
  "newAssetState": 1,
  "newAssetStateText": "固定资产",
  "memo": "从库存商品变成固定资产",
  "modifyTime": "2026-11-17 10:00:00",
  "requestId": "..."
}

3.4 行为与校验(按顺序)

  1. snCode 必填、trim 后非空 → 否则 INVALID_ARGUMENT
  2. 查 device_life_cycle:sn_code = snCode AND soft_delete = 0 ORDER BY id ASC LIMIT 1 → 不存在 NOT_FOUND_OR_FORBIDDEN「设备生命周期记录不存在(sn_code=…)」
  3. 当前 asset_state == 1(固定资产)→ 拒绝:INVALID_ARGUMENT「当前已是固定资产,不允许重复转换」——这也天然满足「不允许从固定资产变成其他」(工具目标状态固定为 1,永不写其他值)
  4. 当前 asset_state == 4(报废)→ 拒绝:INVALID_ARGUMENT「设备已报废,不允许转固定资产」(拍板点 1:报废不允许转)
  5. 当前 asset_state 为 null → 按 0(库存商品)处理(拍板点 3)
  6. UPDATE 该 id 行:asset_state=1、memo='从<原状态文案>变成固定资产'、modify_id=<Token 操作人 userId>、modify_time=now();不动 exchange_state / road_state / inventory_state / last_op_user / last_op_date / agent_id / asset_owner_* / jindie_*(这不是流转事件,拍板点 4)
  7. 写 svc audit_log(操作人、入参、新旧 asset_state、request_id),与既有写工具一致
  8. 报错统一 ToolCallException 透出明确文案(对齐新工具风格)

3.5 memo 文案

固定格式:从<原状态文案>变成固定资产,枚举文案映射:0库存商品/1固定资产/2出租/3售出/4报废/5费用化。实际允许的来源状态只有 0/2/3/5/null(1 与 4 被守卫拦截)。示例:从库存商品变成固定资产、从出租变成固定资产。不加来源前缀(用户明确口径)。

4. 测试要点

  • 参数校验:snCode 空/null/纯空格 → INVALID_ARGUMENT
  • SN 不存在 → NOT_FOUND_OR_FORBIDDEN;soft_delete=1 的记录视为不存在
  • 已是固定资产(asset_state=1)→ INVALID_ARGUMENT 且不产生 UPDATE
  • 报废(asset_state=4)→ INVALID_ARGUMENT 且不产生 UPDATE
  • 允许的来源状态(0/2/3/5/null)→ 均成功转 1,memo 文案正确(含 null→库存商品 的归一)
  • UPDATE 只写 asset_state/memo/modify_id/modify_time 四列,其他字段不被触碰(mock 验证 set 列集合)
  • audit_log 调用参数正确

5. 拍板结论(2026-11-17 王恒)

  1. 报废(4)设备允许转固定资产? —— ❌ 不允许,加守卫:asset_state=4 直接报错拒绝
  2. 已是固定资产时的行为 —— ✅ 报错拒绝(INVALID_ARGUMENT),防止静默 no-op 和 memo 被覆写
  3. asset_state 为 null 的历史行 —— ✅ 按 0(库存商品)处理,memo 写「从库存商品变成固定资产」
  4. 是否同步更新 last_op_user / last_op_date —— ✅ 不动;只写 modify_id/modify_time 留痕
  5. 是否联动生成 m2 asset_info 资产卡片 / 触发金蝶同步 —— ✅ 不联动,本工具只改 device_life_cycle
  6. scope —— ✅ prod 只绑研发专用 scope 6,与 warehouse.order.handler.update 同款隔离

6. 改动清单(预估)

  • entity/m0/DeviceLifeCycle.java:补 memo 字段(DB 列已存在,仅补映射)
  • 新工具类 DeviceLifecycleFixedAssetTools(或并入 DeviceLifecycleTools,实现时按类内聚定)
  • 单测 DeviceLifecycleFixedAssetToolsTest
  • seed-dev.sql:测试专用 scope 绑定(kind=write 自动段)
  • README 工具表 + doc/agent-mcp-tools-reference.md 登记
  • prod:ToolSyncService 自动注册后,手工 INSERT IGNORE 绑 scope 6

7. 冒烟与上线

按 2026-11-07 强制流程:./deploy/test-up.sh 起测试环境 → scopeCode=test 签 Token → 写冒烟全在测试环境跑(真实转固定资产 + 各守卫用例含报废拒绝 + DB 复核后改回原状)→ remote-deploy → 生产只读核验(健康检查 401、tools/list 可见、已固定资产设备调用报明确错误)。