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

119 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 设备转固定资产 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 返回
```json
{
"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 可见、已固定资产设备调用报明确错误)。