按 SN 精确匹配把 device_life_cycle.asset_state 转为固定资产(1),memo 写来源状态文案; 已是固定资产/已报废守卫拒绝,null 按库存商品处理;只写 asset_state/memo/modify_id/ modify_time 四列,不联动资产卡片/金蝶;零行级权限,prod 只绑研发专用 scope 6。 DeviceLifeCycle 实体补 memo 字段映射(DB 列早已存在,老系统从未映射)。
119 lines
7.8 KiB
Markdown
119 lines
7.8 KiB
Markdown
# 设备转固定资产 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 可见、已固定资产设备调用报明确错误)。
|