light-databoard/docs/material_api.md

维护耗材模块接口文档

创建耗材项接口

消息协议

• JSONRPC-2.0

Method

• /material/create

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/material/create",
    "params": {
        "title": "LED灯泡",
        "type": "照明设备",
        "unit": "个",
        "quantity": 2,
        "price": 50.00
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名	类型	说明	必填	备注
title	string	耗材名称	是	最大长度50字符
type	string	耗材类型	是	照明设备/网络设备/其他
unit	string	单位	是	个/件/米/套等
quantity	int	数量	是	必须大于0
price	float64	单价	是	必须大于等于0

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "id": 1,
        "title": "LED灯泡",
        "type": "照明设备",
        "unit": "个",
        "quantity": 2,
        "price": 50.00,
        "total_price": 100.00,
        "created_at": "2024-03-20T10:00:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "数量必须大于0",
        "code": 400,
        "data": {
            "field": "quantity"
        }
    }
}

获取耗材项详情接口

Method

• /material/detail

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/material/detail",
    "params": {
        "id": 1
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名	类型	说明	必填	备注
id	uint	耗材项ID	是

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "id": 1,
        "title": "LED灯泡",
        "type": "照明设备",
        "unit": "个",
        "quantity": 2,
        "price": 50.00,
        "total_price": 100.00,
        "created_at": "2024-03-20T10:00:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "耗材项不存在",
        "code": 400,
        "data": {
            "field": "id"
        }
    }
}

更新耗材项接口

Method

• /material/update

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/material/update",
    "params": {
        "id": 1,
        "quantity": 3,
        "price": 55.00
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名	类型	说明	必填	备注
id	uint	耗材项ID	是
title	string	耗材名称	否	最大长度50字符
type	string	耗材类型	否	照明设备/网络设备/其他
unit	string	单位	否	个/件/米/套等
quantity	int	数量	否	必须大于0
price	float64	单价	否	必须大于等于0

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "id": 1,
        "title": "LED灯泡",
        "type": "照明设备",
        "unit": "个",
        "quantity": 3,
        "price": 55.00,
        "total_price": 165.00,
        "created_at": "2024-03-20T10:00:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "耗材项不存在",
        "code": 400,
        "data": {
            "field": "id"
        }
    }
}

删除耗材项接口

Method

• /material/delete

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/material/delete",
    "params": {
        "id": 1
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名	类型	说明	必填	备注
id	uint	耗材项ID	是

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "耗材项不存在",
        "code": 400,
        "data": {
            "field": "id"
        }
    }
}

获取耗材列表接口

Method

• /material/list

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/material/list",
    "params": {
        "page": 1,
        "page_size": 20,
        "type": "照明设备"
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名	类型	说明	必填	备注
page	integer	当前页码	否	默认1
page_size	integer	每页记录数	否	默认20，最大100
type	string	耗材类型	否	照明设备/网络设备/其他

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "count": 1,
        "rows": [
            {
                "id": 1,
                "title": "LED灯泡",
                "type": "照明设备",
                "unit": "个",
                "quantity": 2,
                "price": 50.00,
                "total_price": 100.00,
                "created_at": "2024-03-20T10:00:00Z"
            }
        ]
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无效的耗材类型",
        "code": 400,
        "data": {
            "field": "type"
        }
    }
}

业务规则说明

1. 耗材名称、类型、单位、数量、单价为必填项
2. 数量必须大于0
3. 单价不能为负数
4. 总价自动计算（单价 × 数量）
5. 耗材项创建后不可修改名称
6. 耗材项删除后不可恢复
7. 列表查询支持按类型过滤
8. 分页查询默认每页20条记录，最大100条