# 维护耗材模块接口文档

## 创建耗材项接口

#### 消息协议
- JSONRPC-2.0

#### Method
- /material/create

#### 请求参数示例:
```json
{
    "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                 |

#### 成功响应示例:
```json
{
    "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
    }
}
```

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "数量必须大于0",
        "code": 400,
        "data": {
            "field": "quantity"
        }
    }
}
```

## 获取耗材项详情接口

#### Method
- /material/detail

#### 请求参数示例:
```json
{
    "jsonrpc": "2.0",
    "method": "/material/detail",
    "params": {
        "id": 1
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}
```

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

#### 成功响应示例:
```json
{
    "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
    }
}
```

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "耗材项不存在",
        "code": 400,
        "data": {
            "field": "id"
        }
    }
}
```

## 更新耗材项接口

#### Method
- /material/update

#### 请求参数示例:
```json
{
    "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                 |

#### 成功响应示例:
```json
{
    "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
    }
}
```

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "耗材项不存在",
        "code": 400,
        "data": {
            "field": "id"
        }
    }
}
```

## 删除耗材项接口

#### Method
- /material/delete

#### 请求参数示例:
```json
{
    "jsonrpc": "2.0",
    "method": "/material/delete",
    "params": {
        "id": 1
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}
```

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

#### 成功响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "ok",
        "code": 200
    }
}
```

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "耗材项不存在",
        "code": 400,
        "data": {
            "field": "id"
        }
    }
}
```

## 获取耗材列表接口

#### Method
- /material/list

#### 请求参数示例:
```json
{
    "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  | 耗材类型              | 否   | 照明设备/网络设备/其他        |

#### 成功响应示例:
```json
{
    "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
    }
}
```

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无效的耗材类型",
        "code": 400,
        "data": {
            "field": "type"
        }
    }
}
```

## 业务规则说明

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