基础参数管理接口文档

一、模块概述

基础参数管理模块提供 20 种海关业务参数（海关关区、运输方式、监管方式等）的管理和采集功能。包含管理端 CRUD、从第三方 API 采集同步数据、差异对比、变更记录等能力。

基础路径：/bc-param

二、接口列表

序号	接口名称	请求方式	URL	请求格式	说明
1	管理页分页查询	POST	/bc-param/page	FORMDATA	查询 bc_param 正式表
2	采集页分页查询	POST	/bc-param/collect-page	FORMDATA	查询 bc_param_collect 暂存表
3	全量参数	GET	/bc-param/all	—	从 Redis 缓存读取，只返回有效+启用数据
4	获取采集时间	GET	/bc-param/collect-time	—	获取最近一次采集时间
5	变更记录查询	GET	/bc-param/change-log/{id}	—	查询指定参数的变更记录
6	同步差异对比	GET	/bc-param/collect-diff/{collectId}	—	采集记录与正式记录的差异对比
7	新增/修改	POST	/bc-param/save	JSON	暂未开放
8	启用/禁用	POST	/bc-param/enable-or-disable	JSON	启用或禁用参数
9	批量保存排序	POST	/bc-param/save-sort	JSON	批量更新排序值
10	全量采集	POST	/bc-param/collect-all	JSON	从外部 API 采集数据到暂存表
11	批量同步	POST	/bc-param/batch-sync	JSON	将暂存表数据同步到正式表

三、公共说明

3.1 统一响应体 ResultResponse

所有接口统一使用 ResultResponse<T> 作为响应载体。

字段	类型	说明
code	Integer	状态码（200:成功、500:异常、403:无权限）
msg	String	响应消息（成功:"success"，失败:错误描述）
data	T	响应数据（成功时返回业务数据，失败时为 null）
other	Object	其他数据（非必要不返回）

3.2 分页参数

分页接口继承 PageRequest，公共分页参数如下：

字段	类型	必填	说明
pageNum	Integer	否	当前页码，默认 1
pageSize	Integer	否	每页条数，默认 20，最大 200

3.3 参数类型编码 type 枚举

code	名称	code	名称
1	海关关区	11	随附单证代码
2	运输方式	12	计量单位
3	监管方式	13	币种
4	征免性质	14	征免方式
5	国别	15	用途
6	国内地区	16	危险品包装类别
7	监管类别名称	17	集装箱规格
8	指运港	18	报关单类型
9	成交方式	19	离境口岸
10	包装种类	20	随附单据文件类别

3.4 同步状态 syncStatus 枚举

code	名称
0	待同步
1	已同步
2	无差异

四、接口详情

4.1 管理页分页查询

URL：POST /bc-param/page
请求格式：FORMDATA
说明：查询 bc_param 正式表，支持多条件筛选，按 sort ASC、id ASC 排序。

请求参数

字段	类型	必填	说明
type	Integer	否	参数类型编码（精准匹配）
nameCn	String	否	中文名称（模糊搜索）
code	String	否	编码1（精准匹配）
code2	String	否	编码2（精准匹配）
code3	String	否	编码3（精准匹配）
nameEn	String	否	英文名称（模糊搜索）
enable	Integer	否	是否启用（0:禁用 1:启用）
isExpired	Boolean	否	是否过期（true/false）
pageNum	Integer	否	当前页码，默认 1
pageSize	Integer	否	每页条数，默认 20

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "current": 1,
    "size": 20,
    "total": 150,
    "records": [
      {
        "id": 1,
        "type": 1,
        "code": "0100",
        "code2": null,
        "code3": null,
        "nameCn": "北京海关",
        "nameEn": "Beijing Customs",
        "fullNameCn": "中华人民共和国北京海关",
        "fullNameEn": "Beijing Customs of PRC",
        "enable": 1,
        "isExpired": false,
        "sort": 1,
        "createTime": "2025-01-01 10:00:00",
        "updateTime": "2025-01-15 14:30:00"
      }
    ]
  },
  "other": null
}

响应字段说明（records 数组元素）

字段	类型	说明
id	Long	主键
type	Integer	参数类型编码
code	String	编码1
code2	String	编码2
code3	String	编码3
nameCn	String	中文名称
nameEn	String	英文名称
fullNameCn	String	中文全称
fullNameEn	String	英文全称
enable	Integer	是否启用（0:禁用 1:启用）
isExpired	Boolean	是否过期
sort	Integer	排序值
createTime	String	创建时间（yyyy-MM-dd HH:mm:ss）
updateTime	String	更新时间（yyyy-MM-dd HH:mm:ss）

4.2 采集页分页查询

URL：POST /bc-param/collect-page
请求格式：FORMDATA
说明：查询 bc_param_collect 暂存表，按 syncStatus ASC（待同步优先）、id ASC 排序。

请求参数

字段	类型	必填	说明
type	Integer	否	参数类型编码（精准匹配）
nameCn	String	否	中文名称（模糊搜索）
code	String	否	编码1（精准匹配）
code2	String	否	编码2（精准匹配）
code3	String	否	编码3（精准匹配）
nameEn	String	否	英文名称（模糊搜索）
isExpired	Boolean	否	是否过期（true/false）
syncStatus	Integer	否	同步状态（0:待同步 1:已同步 2:无差异）
pageNum	Integer	否	当前页码，默认 1
pageSize	Integer	否	每页条数，默认 20

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "current": 1,
    "size": 20,
    "total": 80,
    "records": [
      {
        "id": 101,
        "type": 1,
        "code": "0100",
        "code2": null,
        "code3": null,
        "nameCn": "北京关区",
        "nameEn": "Beijing Customs",
        "fullNameCn": "中华人民共和国北京关区",
        "fullNameEn": "Beijing Customs District of PRC",
        "isExpired": false,
        "syncStatus": 0,
        "syncTime": null,
        "collectTime": "2025-05-15 09:30:00"
      }
    ]
  },
  "other": null
}

响应字段说明（records 数组元素）

字段	类型	说明
id	Long	采集记录 ID
type	Integer	参数类型编码
code	String	编码1
code2	String	编码2
code3	String	编码3
nameCn	String	中文名称
nameEn	String	英文名称
fullNameCn	String	中文全称
fullNameEn	String	英文全称
isExpired	Boolean	是否过期
syncStatus	Integer	同步状态（0:待同步 1:已同步 2:无差异）
syncTime	String	同步时间（yyyy-MM-dd HH:mm:ss），未同步时为 null
collectTime	String	采集时间（yyyy-MM-dd HH:mm:ss）

4.3 全量参数

URL：GET /bc-param/all
请求格式：无参数
说明：从 Redis 缓存读取全量参数数据，只返回 enable=1 且 isExpired=false 的有效数据。按 type 分组返回，供前端缓存。

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "1": [
      {
        "id": 1,
        "type": 1,
        "code": "0100",
        "code2": null,
        "code3": null,
        "nameCn": "北京海关",
        "nameEn": "Beijing Customs",
        "fullNameCn": "中华人民共和国北京海关",
        "fullNameEn": "Beijing Customs of PRC",
        "enable": 1,
        "isExpired": false,
        "sort": 1,
        "createTime": "2025-01-01 10:00:00",
        "updateTime": "2025-01-15 14:30:00"
      }
    ],
    "2": [
      {
        "id": 50,
        "type": 2,
        "code": "1",
        "code2": null,
        "code3": null,
        "nameCn": "监管仓库",
        "nameEn": "Bonded Warehouse",
        "fullNameCn": null,
        "fullNameEn": null,
        "enable": 1,
        "isExpired": false,
        "sort": 1,
        "createTime": "2025-01-01 10:00:00",
        "updateTime": null
      }
    ]
  },
  "other": null
}

响应字段说明

字段	类型	说明
data	Map<Integer, List<BcParamVO>>	key 为参数类型编码，value 为该类型下的参数列表

BcParamVO 字段同 4.1 响应字段。

4.4 获取采集时间

URL：GET /bc-param/collect-time
请求格式：无参数
说明：从 Redis 读取最近一次采集完成的时间，缓存不可用时返回 "-"。

响应示例

{
  "code": 200,
  "msg": "success",
  "data": "2025-05-15 09:30:00",
  "other": null
}

4.5 变更记录查询

URL：GET /bc-param/change-log/{id}
请求格式：路径参数
说明：查询指定 bc_param 记录的所有变更记录，按变更时间倒序。

请求参数

字段	类型	必填	说明
id	Long	是	bc_param 记录 ID（路径参数）

响应示例

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1001,
      "fieldName": "中文名称",
      "oldValue": "北京海关",
      "newValue": "北京关区",
      "createByName": "管理员",
      "createTime": "2025-05-10 15:20:00"
    },
    {
      "id": 1002,
      "fieldName": "是否启用",
      "oldValue": "1",
      "newValue": "0",
      "createByName": "管理员",
      "createTime": "2025-05-08 10:00:00"
    }
  ],
  "other": null
}

响应字段说明（data 数组元素）

字段	类型	说明
id	Long	日志 ID
fieldName	String	变更字段中文名称
oldValue	String	原值
newValue	String	新值
createByName	String	变更人名称
createTime	String	变更时间（yyyy-MM-dd HH:mm:ss）

4.6 同步差异对比

URL：GET /bc-param/collect-diff/{collectId}
请求格式：路径参数
说明：实时对比采集记录与 bc_param 正式记录的差异，用于同步弹窗展示。

请求参数

字段	类型	必填	说明
collectId	Long	是	bc_param_collect 记录 ID（路径参数）

响应示例

修改场景（正式表已有该编码记录）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "code": "0100",
    "nameCn": "北京关区",
    "diffs": [
      { "fieldName": "中文名称", "oldValue": "北京海关", "newValue": "北京关区" },
      { "fieldName": "英文全称", "oldValue": null, "newValue": "Beijing Customs District" }
    ]
  },
  "other": null
}

新增场景（正式表无该编码记录）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "code": "9999",
    "nameCn": "新增关区",
    "diffs": [
      { "fieldName": "编码1", "oldValue": null, "newValue": "9999" },
      { "fieldName": "中文名称", "oldValue": null, "newValue": "新增关区" },
      { "fieldName": "英文名称", "oldValue": null, "newValue": "New District" }
    ]
  },
  "other": null
}

过期场景（API 中已不存在该编码）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "code": "0200",
    "nameCn": "天津海关",
    "diffs": [
      { "fieldName": "是否过期", "oldValue": "否", "newValue": "是" }
    ]
  },
  "other": null
}

响应字段说明

字段	类型	说明
code	String	编码1
nameCn	String	中文名称
diffs	List<DiffItem>	差异字段列表

DiffItem 结构：

字段	类型	说明
fieldName	String	变更字段中文名称
oldValue	String	原值（bc_param 中的值，新增时为 null）
newValue	String	新值（采集表中的值）

4.7 新增/修改（暂未开放）

URL：POST /bc-param/save
请求格式：JSON（RequestBody）
说明：该接口当前暂未开放，调用将返回错误提示。

请求参数

字段	类型	必填	说明
id	Long	否	主键 ID（修改时必传，新增时不传）
type	Integer	是	参数类型编码
code	String	是	编码1
code2	String	否	编码2
code3	String	否	编码3
nameCn	String	是	中文名称
nameEn	String	否	英文名称
fullNameCn	String	否	中文全称
fullNameEn	String	否	英文全称
isExpired	Boolean	否	是否过期
sort	Integer	否	排序值，默认 1

请求示例

{
  "type": 1,
  "code": "0100",
  "nameCn": "北京海关",
  "nameEn": "Beijing Customs",
  "fullNameCn": "中华人民共和国北京海关",
  "fullNameEn": "Beijing Customs of PRC",
  "isExpired": false,
  "sort": 1
}

响应示例（当前固定返回）

{
  "code": 500,
  "msg": "暂未开放",
  "data": null,
  "other": null
}

4.8 启用/禁用

URL：POST /bc-param/enable-or-disable
请求格式：JSON（RequestBody）
说明：启用或禁用指定参数，操作后刷新缓存并记录变更日志。

请求参数

字段	类型	必填	说明
id	Long	是	参数 ID
enable	Integer	是	启用状态（0:禁用 1:启用）

请求示例

{
  "id": 1,
  "enable": 0
}

响应示例

成功：

{
  "code": 200,
  "msg": "success",
  "data": null,
  "other": null
}

失败：

{
  "code": 500,
  "msg": "基础参数不存在",
  "data": null,
  "other": null
}

校验规则

id 不能为空

enable 必须为 0 或 1

记录必须存在

4.9 批量保存排序

URL：POST /bc-param/save-sort
请求格式：JSON（RequestBody）
说明：批量更新指定类型下参数的排序值，操作后刷新缓存。

请求参数

字段	类型	必填	说明
type	Integer	否	参数类型编码（用于刷新缓存）
items	List<SortItem>	是	排序项列表

SortItem 结构：

字段	类型	必填	说明
id	Long	是	参数 ID
sort	Integer	否	排序值，默认 1

请求示例

{
  "type": 1,
  "items": [
    { "id": 1, "sort": 1 },
    { "id": 2, "sort": 2 },
    { "id": 3, "sort": 3 }
  ]
}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": null,
  "other": null
}

4.10 全量采集

URL：POST /bc-param/collect-all
请求格式：JSON（RequestBody）
说明：从外部 API 拉取指定类型的全量数据，写入 bc_param_collect 暂存表。不影响正式表和缓存。首次采集（正式表为空时）会自动同步到正式表。

请求参数

字段	类型	必填	说明
type	Integer	是	参数类型编码

请求示例

{
  "type": 1
}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": null,
  "other": null
}

4.11 批量同步

URL：POST /bc-param/batch-sync
请求格式：JSON（RequestBody）
说明：将采集暂存表中勾选的记录同步到 bc_param 正式表，记录变更日志，刷新 Redis 缓存。

请求参数

字段	类型	必填	说明
type	Integer	是	参数类型编码
ids	List<Long>	是	勾选的采集记录 ID 列表（bc_param_collect.id）

请求示例

{
  "type": 1,
  "ids": [101, 102, 103]
}

响应示例

成功：

{
  "code": 200,
  "msg": "success",
  "data": null,
  "other": null
}

失败：

{
  "code": 500,
  "msg": "请先选择基础参数",
  "data": null,
  "other": null
}

五、错误码

错误信息	触发场景
参数类型不能为空	type 为空时
参数ID不能为空	id 为空时
中文名称不能为空	nameCn 为空时（save 接口）
编码不能为空	code 为空时（save 接口）
基础参数不存在	根据 id 查不到记录时
该类型下编码已存在	同 type 下 code 重复时（save 接口）
请先选择基础参数	批量同步时 ids 为空
启用/禁用状态值不合法	enable 不为 0 或 1 时
暂未开放	调用 save 接口时（当前固定返回）

六、注意事项

缓存机制：/bc-param/all 接口从 Redis 缓存读取，管理端编辑或同步操作后后端会自动刷新缓存。

分页接口请求格式：分页查询接口使用 FORMDATA 格式（非 JSON），参数通过表单字段传递。

海关基础参数接口文档

基础参数管理 接口文档#

一、模块概述#

二、接口列表#

三、公共说明#

3.1 统一响应体 ResultResponse#

3.2 分页参数#

3.3 参数类型编码 type 枚举#

3.4 同步状态 syncStatus 枚举#

四、接口详情#

4.1 管理页分页查询#

请求参数#

响应示例#

响应字段说明（records 数组元素）#

4.2 采集页分页查询#

请求参数#

响应示例#

响应字段说明（records 数组元素）#

4.3 全量参数#

响应示例#

响应字段说明#

4.4 获取采集时间#

响应示例#

4.5 变更记录查询#

请求参数#

响应示例#

响应字段说明（data 数组元素）#

4.6 同步差异对比#

请求参数#

响应示例#

响应字段说明#

4.7 新增/修改（暂未开放）#

请求参数#

请求示例#

响应示例（当前固定返回）#

4.8 启用/禁用#

请求参数#

请求示例#

响应示例#

校验规则#

4.9 批量保存排序#

请求参数#

请求示例#

响应示例#

4.10 全量采集#

请求参数#

请求示例#

响应示例#

4.11 批量同步#

请求参数#

请求示例#

响应示例#

五、错误码#

六、注意事项#

基础参数管理接口文档

一、模块概述

二、接口列表

三、公共说明

3.1 统一响应体 ResultResponse

3.2 分页参数

3.3 参数类型编码 type 枚举

3.4 同步状态 syncStatus 枚举

四、接口详情

4.1 管理页分页查询

请求参数

响应示例

响应字段说明（records 数组元素）

4.2 采集页分页查询

请求参数

响应示例

响应字段说明（records 数组元素）

4.3 全量参数

响应示例

响应字段说明

4.4 获取采集时间

响应示例

4.5 变更记录查询

请求参数

响应示例

响应字段说明（data 数组元素）

4.6 同步差异对比

请求参数

响应示例

响应字段说明

4.7 新增/修改（暂未开放）

请求参数

请求示例

响应示例（当前固定返回）

4.8 启用/禁用

请求参数

请求示例

响应示例

校验规则

4.9 批量保存排序

请求参数

请求示例

响应示例

4.10 全量采集

请求参数

请求示例

响应示例

4.11 批量同步

请求参数

请求示例

响应示例

五、错误码

六、注意事项