产品管理模块 - API接口文档

模块: 11-产品管理
版本: v1.0
日期: 2025-10-03
关联文档:

需求文档: docs/11-产品管理模块需求.md

原型图: yuanxing/09-产品管理原型图.md

数据库: sql/crm/11-crm_product.sql

📋 目录

1. 产品分类管理接口
2. 产品管理接口
3. 统计分析接口
4. 数据模型

1. 产品分类管理接口

1.1 查询分类列表（树形）

接口地址: GET /crm/product/category/tree

接口描述: 获取产品分类树形结构，用于分类选择器和分类管理页面

权限标识: crm:product:category:list

请求参数: 无

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "categoryName": "软件产品",
      "parentId": 0,
      "ancestors": "0",
      "sort": 1,
      "status": "0",
      "children": [
        {
          "id": 11,
          "categoryName": "CRM系统",
          "parentId": 1,
          "ancestors": "0,1",
          "sort": 1,
          "status": "0",
          "children": [
            {
              "id": 111,
              "categoryName": "标准版",
              "parentId": 11,
              "ancestors": "0,1,11",
              "sort": 1,
              "status": "0"
            }
          ]
        }
      ]
    }
  ]
}

1.2 查询分类详情

接口地址: GET /crm/product/category/{id}

接口描述: 根据ID查询分类详细信息

权限标识: crm:product:category:query

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | Long | 是 | 分类ID |

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "categoryName": "软件产品",
    "parentId": 0,
    "ancestors": "0",
    "sort": 1,
    "status": "0",
    "createTime": "2025-01-01 10:00:00",
    "remark": "软件类产品分类"
  }
}

1.3 新增分类

接口地址: POST /crm/product/category

接口描述: 新增产品分类

权限标识: crm:product:category:add

请求体:

{
  "categoryName": "软件产品",
  "parentId": 0,
  "sort": 1,
  "status": "0",
  "remark": "软件类产品分类"
}

请求参数说明: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | categoryName | String | 是 | 分类名称，最大100字符 | | parentId | Long | 否 | 父级分类ID，默认0（顶级） | | sort | Integer | 否 | 显示顺序，默认0 | | status | String | 否 | 状态：0-正常 1-停用，默认0 | | remark | String | 否 | 备注，最大500字符 |

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

1.4 修改分类

接口地址: PUT /crm/product/category

接口描述: 修改产品分类信息

权限标识: crm:product:category:edit

请求体:

{
  "id": 1,
  "categoryName": "软件产品",
  "parentId": 0,
  "sort": 1,
  "status": "0",
  "remark": "软件类产品分类"
}

请求参数说明: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | Long | 是 | 分类ID | | categoryName | String | 是 | 分类名称 | | parentId | Long | 否 | 父级分类ID | | sort | Integer | 否 | 显示顺序 | | status | String | 否 | 状态 | | remark | String | 否 | 备注 |

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

1.5 删除分类

接口地址: DELETE /crm/product/category/{ids}

接口描述: 删除产品分类（支持批量）

权限标识: crm:product:category:remove

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | ids | Long[] | 是 | 分类ID数组，多个用逗号分隔 |

业务规则:

如果分类下有子分类，不允许删除
如果分类下有产品，不允许删除

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

2. 产品管理接口

2.1 查询产品列表（分页）

接口地址: GET /crm/product/list

接口描述: 分页查询产品列表，支持多条件筛选

权限标识: crm:product:list

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Integer | 否 | 页码，默认1 | | pageSize | Integer | 否 | 每页条数，默认10 | | productName | String | 否 | 产品名称（模糊查询） | | productNo | String | 否 | 产品编号（模糊查询） | | categoryId | Long | 否 | 分类ID | | status | String | 否 | 状态：on-上架 off-下架 | | minPrice | BigDecimal | 否 | 最低价格 | | maxPrice | BigDecimal | 否 | 最高价格 | | minSaleCount | Integer | 否 | 最小销量 | | maxSaleCount | Integer | 否 | 最大销量 | | beginTime | String | 否 | 开始时间 yyyy-MM-dd HH:mm:ss | | endTime | String | 否 | 结束时间 yyyy-MM-dd HH:mm:ss |

返回示例:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "productNo": "PRD20250101001",
      "productName": "CRM系统标准版",
      "categoryId": 11,
      "categoryName": "CRM系统",
      "model": "V5.4.0",
      "unit": "套",
      "barcode": "6901234567890",
      "price": 12800.00,
      "cost": 8000.00,
      "minPrice": 10000.00,
      "stock": 100,
      "lowStock": 10,
      "status": "on",
      "description": "适合中小企业的CRM系统",
      "images": "/upload/product/001.jpg,/upload/product/002.jpg",
      "saleCount": 156,
      "createTime": "2025-01-01 10:00:00",
      "updateTime": "2025-01-15 16:30:00",
      "remark": ""
    }
  ],
  "total": 89
}

2.2 查询产品详情

接口地址: GET /crm/product/{id}

接口描述: 根据ID查询产品详细信息

权限标识: crm:product:query

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | Long | 是 | 产品ID |

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "productNo": "PRD20250101001",
    "productName": "CRM系统标准版",
    "categoryId": 11,
    "categoryName": "CRM系统",
    "model": "V5.4.0",
    "unit": "套",
    "barcode": "6901234567890",
    "price": 12800.00,
    "cost": 8000.00,
    "minPrice": 10000.00,
    "stock": 100,
    "lowStock": 10,
    "status": "on",
    "description": "适合中小企业的CRM系统，包含客户管理、销售管理、数据分析等功能",
    "images": "/upload/product/001.jpg,/upload/product/002.jpg",
    "saleCount": 156,
    "createTime": "2025-01-01 10:00:00",
    "createBy": 1,
    "updateTime": "2025-01-15 16:30:00",
    "updateBy": 1,
    "remark": "标准版产品"
  }
}

2.3 新增产品

接口地址: POST /crm/product

接口描述: 新增产品信息

权限标识: crm:product:add

请求体:

{
  "productNo": "PRD20250101001",
  "productName": "CRM系统标准版",
  "categoryId": 11,
  "model": "V5.4.0",
  "unit": "套",
  "barcode": "6901234567890",
  "price": 12800.00,
  "cost": 8000.00,
  "minPrice": 10000.00,
  "stock": 100,
  "lowStock": 10,
  "status": "on",
  "description": "适合中小企业的CRM系统",
  "images": "/upload/product/001.jpg,/upload/product/002.jpg",
  "remark": "标准版产品"
}

请求参数说明: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | productNo | String | 是 | 产品编号，唯一，最大50字符 | | productName | String | 是 | 产品名称，最大200字符 | | categoryId | Long | 否 | 分类ID | | model | String | 否 | 型号/规格，最大100字符 | | unit | String | 否 | 单位，默认"个"，最大20字符 | | barcode | String | 否 | 条码，最大100字符 | | price | BigDecimal | 是 | 标准价格，保留2位小数 | | cost | BigDecimal | 否 | 成本价，保留2位小数 | | minPrice | BigDecimal | 否 | 最低价格，保留2位小数 | | stock | Integer | 否 | 库存数量，默认0 | | lowStock | Integer | 否 | 库存预警值，默认10 | | status | String | 否 | 状态：on-上架 off-下架，默认on | | description | String | 否 | 产品描述，文本类型 | | images | String | 否 | 产品图片，多个用逗号分隔 | | remark | String | 否 | 备注，最大500字符 |

校验规则:

产品编号不能重复
标准价格必须大于0
如果设置了最低价格，最低价格必须≤标准价格
如果设置了成本价，成本价必须≤标准价格

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

2.4 修改产品

接口地址: PUT /crm/product

接口描述: 修改产品信息

权限标识: crm:product:edit

请求体:

{
  "id": 1,
  "productNo": "PRD20250101001",
  "productName": "CRM系统标准版",
  "categoryId": 11,
  "model": "V5.4.0",
  "unit": "套",
  "barcode": "6901234567890",
  "price": 12800.00,
  "cost": 8000.00,
  "minPrice": 10000.00,
  "stock": 100,
  "lowStock": 10,
  "status": "on",
  "description": "适合中小企业的CRM系统",
  "images": "/upload/product/001.jpg,/upload/product/002.jpg",
  "remark": "标准版产品"
}

请求参数说明: 同新增接口，但需要传入id

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

2.5 删除产品

接口地址: DELETE /crm/product/{ids}

接口描述: 删除产品（支持批量）

权限标识: crm:product:remove

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | ids | Long[] | 是 | 产品ID数组，多个用逗号分隔 |

业务规则:

如果产品在商机、报价单、合同中被引用，不允许直接删除
建议使用下架功能代替删除

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

2.6 批量上架/下架

接口地址: PUT /crm/product/status

接口描述: 批量修改产品状态（上架/下架）

权限标识: crm:product:edit

请求体:

{
  "ids": [1, 2, 3],
  "status": "on"
}

请求参数说明: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | ids | Long[] | 是 | 产品ID数组 | | status | String | 是 | 状态：on-上架 off-下架 |

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

2.7 批量调价

接口地址: PUT /crm/product/price

接口描述: 批量调整产品价格

权限标识: crm:product:edit

请求体:

{
  "ids": [1, 2, 3],
  "priceType": "price",
  "adjustType": "percent",
  "adjustValue": 10.0,
  "remark": "年度调价"
}

请求参数说明: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | ids | Long[] | 是 | 产品ID数组 | | priceType | String | 是 | 价格类型：price-标准价 cost-成本价 minPrice-最低价 | | adjustType | String | 是 | 调整方式：percent-百分比 fixed-固定金额 | | adjustValue | BigDecimal | 是 | 调整值（百分比或固定金额） | | remark | String | 否 | 调价备注 |

返回示例:

{
  "code": 200,
  "msg": "操作成功"
}

2.8 导出产品

接口地址: POST /crm/product/export

接口描述: 导出产品数据到Excel

权限标识: crm:product:export

请求体: 查询参数同2.1列表查询接口

返回: Excel文件流

2.9 导入产品

接口地址: POST /crm/product/import

接口描述: 批量导入产品数据

权限标识: crm:product:import

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | file | MultipartFile | 是 | Excel文件 | | updateSupport | Boolean | 否 | 是否更新已存在的产品，默认false |

返回示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 100,
    "success": 95,
    "fail": 5,
    "errors": [
      {
        "row": 3,
        "error": "产品编号已存在"
      },
      {
        "row": 7,
        "error": "分类不存在"
      }
    ]
  }
}

2.10 下载导入模板

接口地址: POST /crm/product/importTemplate

接口描述: 下载产品导入Excel模板

权限标识: crm:product:import

请求参数: 无

返回: Excel文件流

2.11 根据编号查询产品

接口地址: GET /crm/product/no/{productNo}

接口描述: 根据产品编号查询产品信息

权限标识: crm:product:query

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | productNo | String | 是 | 产品编号 |

返回示例: 同2.2查询详情接口

2.12 产品搜索（下拉选择）

接口地址: GET /crm/product/search

接口描述: 根据关键词搜索产品，用于产品选择器

权限标识: crm:product:list

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | keyword | String | 否 | 搜索关键词（产品名称/编号） | | categoryId | Long | 否 | 分类ID | | status | String | 否 | 状态，默认只查询上架产品 | | limit | Integer | 否 | 返回条数，默认10 |

返回示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "productNo": "PRD20250101001",
      "productName": "CRM系统标准版",
      "categoryName": "CRM系统",
      "price": 12800.00,
      "unit": "套",
      "stock": 100
    }
  ]
}

2.13 库存预警列表

接口地址: GET /crm/product/stockAlert

接口描述: 查询库存低于预警值的产品列表

权限标识: crm:product:list

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Integer | 否 | 页码，默认1 | | pageSize | Integer | 否 | 每页条数，默认10 |

返回示例:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "productNo": "PRD20250101001",
      "productName": "CRM系统标准版",
      "stock": 5,
      "lowStock": 10,
      "alertLevel": "warning"
    }
  ],
  "total": 8
}

3. 统计分析接口

3.1 产品统计概览

接口地址: GET /crm/product/statistics/overview

接口描述: 获取产品统计概览数据

权限标识: crm:product:list

请求参数: 无

返回示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "totalCount": 89,
    "onlineCount": 76,
    "offlineCount": 13,
    "totalSaleCount": 1256,
    "monthAddCount": 5,
    "alertCount": 8
  }
}

3.2 热销产品排行

接口地址: GET /crm/product/statistics/hot

接口描述: 获取热销产品排行榜

权限标识: crm:product:list

请求参数: | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | limit | Integer | 否 | 返回条数，默认10 |

返回示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 3,
      "productNo": "PRD20250101003",
      "productName": "办公自动化系统",
      "saleCount": 234,
      "totalAmount": 2059200.00
    }
  ]
}

3.3 分类产品统计

接口地址: GET /crm/product/statistics/category

接口描述: 按分类统计产品数量和销量

权限标识: crm:product:list

请求参数: 无

返回示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "categoryId": 1,
      "categoryName": "软件产品",
      "productCount": 45,
      "saleCount": 856,
      "totalAmount": 12500000.00
    }
  ]
}

4. 数据模型

4.1 ProductCategoryBo（分类业务对象）

public class CrmProductCategoryBo extends BaseEntity {
    /** 主键ID */
    @NotNull(message = "主键不能为空", groups = { EditGroup.class })
    private Long id;

    /** 分类名称 */
    @NotBlank(message = "分类名称不能为空", groups = { AddGroup.class, EditGroup.class })
    private String categoryName;

    /** 父级ID */
    private Long parentId;

    /** 祖级列表 */
    private String ancestors;

    /** 显示顺序 */
    private Integer sort;

    /** 状态 */
    private String status;

    /** 备注 */
    private String remark;
}

4.2 ProductCategoryVo（分类视图对象）

public class CrmProductCategoryVo implements Serializable {
    /** 主键ID */
    @ExcelProperty(value = "ID")
    private Long id;

    /** 分类名称 */
    @ExcelProperty(value = "分类名称")
    private String categoryName;

    /** 父级ID */
    private Long parentId;

    /** 祖级列表 */
    private String ancestors;

    /** 显示顺序 */
    @ExcelProperty(value = "显示顺序")
    private Integer sort;

    /** 状态 */
    @ExcelProperty(value = "状态", converter = ExcelDictConvert.class)
    @ExcelDictFormat(dictType = "sys_normal_disable")
    private String status;

    /** 创建时间 */
    @ExcelProperty(value = "创建时间")
    private LocalDateTime createTime;

    /** 备注 */
    @ExcelProperty(value = "备注")
    private String remark;

    /** 子分类列表 */
    private List<CrmProductCategoryVo> children;
}

4.3 ProductBo（产品业务对象）

public class CrmProductBo extends BaseEntity {
    /** 主键ID */
    @NotNull(message = "主键不能为空", groups = { EditGroup.class })
    private Long id;

    /** 产品编号 */
    @NotBlank(message = "产品编号不能为空", groups = { AddGroup.class, EditGroup.class })
    private String productNo;

    /** 产品名称 */
    @NotBlank(message = "产品名称不能为空", groups = { AddGroup.class, EditGroup.class })
    private String productName;

    /** 分类ID */
    private Long categoryId;

    /** 型号/规格 */
    private String model;

    /** 单位 */
    private String unit;

    /** 条码 */
    private String barcode;

    /** 标准价格 */
    @NotNull(message = "标准价格不能为空", groups = { AddGroup.class, EditGroup.class })
    private BigDecimal price;

    /** 成本价 */
    private BigDecimal cost;

    /** 最低价格 */
    private BigDecimal minPrice;

    /** 库存数量 */
    private Integer stock;

    /** 库存预警值 */
    private Integer lowStock;

    /** 状态 */
    private String status;

    /** 产品描述 */
    private String description;

    /** 产品图片 */
    private String images;

    /** 备注 */
    private String remark;
}

4.4 ProductVo（产品视图对象）

public class CrmProductVo implements Serializable {
    /** 主键ID */
    @ExcelProperty(value = "ID")
    private Long id;

    /** 产品编号 */
    @ExcelProperty(value = "产品编号")
    private String productNo;

    /** 产品名称 */
    @ExcelProperty(value = "产品名称")
    private String productName;

    /** 分类ID */
    private Long categoryId;

    /** 分类名称 */
    @ExcelProperty(value = "产品分类")
    private String categoryName;

    /** 型号/规格 */
    @ExcelProperty(value = "型号/规格")
    private String model;

    /** 单位 */
    @ExcelProperty(value = "单位")
    private String unit;

    /** 条码 */
    @ExcelProperty(value = "条码")
    private String barcode;

    /** 标准价格 */
    @ExcelProperty(value = "标准价格")
    private BigDecimal price;

    /** 成本价 */
    @ExcelProperty(value = "成本价")
    private BigDecimal cost;

    /** 最低价格 */
    @ExcelProperty(value = "最低价格")
    private BigDecimal minPrice;

    /** 库存数量 */
    @ExcelProperty(value = "库存数量")
    private Integer stock;

    /** 库存预警值 */
    @ExcelProperty(value = "库存预警值")
    private Integer lowStock;

    /** 状态 */
    @ExcelProperty(value = "状态", converter = ExcelDictConvert.class)
    @ExcelDictFormat(dictType = "crm_product_status")
    private String status;

    /** 产品描述 */
    private String description;

    /** 产品图片 */
    private String images;

    /** 销售次数 */
    @ExcelProperty(value = "销售次数")
    private Integer saleCount;

    /** 创建时间 */
    @ExcelProperty(value = "创建时间")
    private LocalDateTime createTime;

    /** 更新时间 */
    @ExcelProperty(value = "更新时间")
    private LocalDateTime updateTime;

    /** 备注 */
    @ExcelProperty(value = "备注")
    private String remark;
}

5. 数据字典

5.1 产品状态 (crm_product_status)

字典值	字典标签	说明
on	上架	产品可销售
off	下架	产品不可销售

6. 权限标识汇总

权限标识	说明
crm:product:category:list	产品分类列表查询
crm:product:category:query	产品分类详情查询
crm:product:category:add	产品分类新增
crm:product:category:edit	产品分类修改
crm:product:category:remove	产品分类删除
crm:product:list	产品列表查询
crm:product:query	产品详情查询
crm:product:add	产品新增
crm:product:edit	产品修改
crm:product:remove	产品删除
crm:product:export	产品导出
crm:product:import	产品导入

7. 注意事项

价格精度: 所有价格字段保留2位小数
产品编号: 建议格式为 PRD+yyyyMMdd+4位流水号，确保唯一性
图片路径: 多个图片用英文逗号分隔，存储相对路径
库存管理: 库存功能为可选功能，不需要库存管理的产品可以忽略stock相关字段
分类删除: 删除分类前需检查是否有子分类和关联产品
产品删除: 建议使用下架功能代替删除，保留历史数据
批量操作: 批量操作需要注意事务一致性
权限控制: 成本价字段仅特定权限用户可见
数据脱敏: 导出时需要根据权限控制成本价等敏感字段的导出

文档结束

11-产品管理API接口.md 22 KB История Исходник

产品管理模块 - API接口文档

📋 目录

1. 产品分类管理接口

1.1 查询分类列表（树形）

1.2 查询分类详情

1.3 新增分类

1.4 修改分类

1.5 删除分类

2. 产品管理接口

2.1 查询产品列表（分页）

2.2 查询产品详情

2.3 新增产品

2.4 修改产品

2.5 删除产品

2.6 批量上架/下架

2.7 批量调价

2.8 导出产品

2.9 导入产品

2.10 下载导入模板

2.11 根据编号查询产品

2.12 产品搜索（下拉选择）

2.13 库存预警列表

3. 统计分析接口

3.1 产品统计概览

3.2 热销产品排行

3.3 分类产品统计

4. 数据模型

4.1 ProductCategoryBo（分类业务对象）

4.2 ProductCategoryVo（分类视图对象）

4.3 ProductBo（产品业务对象）

4.4 ProductVo（产品视图对象）

5. 数据字典

5.1 产品状态 (crm_product_status)

6. 权限标识汇总

7. 注意事项

11-产品管理API接口.md 22 KB

История Исходник