按 SN 精确匹配把 device_life_cycle.asset_state 转为固定资产(1),memo 写来源状态文案; 已是固定资产/已报废守卫拒绝,null 按库存商品处理;只写 asset_state/memo/modify_id/ modify_time 四列,不联动资产卡片/金蝶;零行级权限,prod 只绑研发专用 scope 6。 DeviceLifeCycle 实体补 memo 字段映射(DB 列早已存在,老系统从未映射)。
7.8 KiB
7.8 KiB
设备转固定资产 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_stateint,枚举: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.181xiaoqu_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 行为与校验(按顺序)
- snCode 必填、trim 后非空 → 否则
INVALID_ARGUMENT - 查
device_life_cycle:sn_code = snCode AND soft_delete = 0 ORDER BY id ASC LIMIT 1→ 不存在NOT_FOUND_OR_FORBIDDEN「设备生命周期记录不存在(sn_code=…)」 - 当前
asset_state == 1(固定资产)→ 拒绝:INVALID_ARGUMENT「当前已是固定资产,不允许重复转换」——这也天然满足「不允许从固定资产变成其他」(工具目标状态固定为 1,永不写其他值) - 当前
asset_state == 4(报废)→ 拒绝:INVALID_ARGUMENT「设备已报废,不允许转固定资产」(拍板点 1:报废不允许转) - 当前
asset_state为 null → 按 0(库存商品)处理(拍板点 3) - 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) - 写 svc
audit_log(操作人、入参、新旧 asset_state、request_id),与既有写工具一致 - 报错统一
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 王恒)
- 报废(4)设备允许转固定资产? —— ❌ 不允许,加守卫:asset_state=4 直接报错拒绝
- 已是固定资产时的行为 —— ✅ 报错拒绝(INVALID_ARGUMENT),防止静默 no-op 和 memo 被覆写
- asset_state 为 null 的历史行 —— ✅ 按 0(库存商品)处理,memo 写「从库存商品变成固定资产」
- 是否同步更新 last_op_user / last_op_date —— ✅ 不动;只写 modify_id/modify_time 留痕
- 是否联动生成 m2 asset_info 资产卡片 / 触发金蝶同步 —— ✅ 不联动,本工具只改 device_life_cycle
- 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 可见、已固定资产设备调用报明确错误)。