Module: JPSClient::API::Category

Included in:
Client
Defined in:
lib/jpsclient/api/category.rb

Overview

Category 相关 API 处理通用分类管理相关接口

Instance Method Summary collapse

Instance Method Details

#batch_create_categories(categories: []) ⇒ Array<Hash>

批量创建分类注意：此方法会逐个调用 API，返回结果数组

Parameters:

  • categories (Array<Hash>) (defaults to: []) —

    分类数组

Returns:

  • (Array<Hash>) —

    每个请求的响应结果



179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/jpsclient/api/category.rb', line 179

def batch_create_categories(categories: [])
  return [] if categories.empty?

  results = []
  categories.each do |category_params|
    result = create_category(params: category_params)
    results << result
  end

  results
end

#create_category(params: {}) ⇒ Hash

创建分类

Parameters:

  • params (Hash) (defaults to: {}) —

    分类信息参数

    • name: 分类名称（必需）

    • type: 分类类型（必需）

    • parent_id: 父分类ID（可选，根分类不需要）

    • icon: 分类图标（可选）

    • description: 分类描述（可选）

    • sort_order: 排序值（可选，默认1）

Returns:

  • (Hash) —

    API响应

Raises:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/jpsclient/api/category.rb', line 47

def create_category(params: {})
  config = @request_config && @request_config["category_create"]
  raise JPSClient::ExceptionError, "Missing config for category_create" unless config && config["url"]

  # 参数验证
  required_fields = [:name, :type]
  missing_fields = required_fields.select { |field| params[field].nil? || params[field].to_s.empty? }

  if missing_fields.any?
    raise JPSClient::ExceptionError, "Missing required fields: #{missing_fields.join(', ')}"
  end

  # 设置默认值
  params[:sort_order] ||= 1

  path = config["url"]

  return request_with_auth(:post, path, body: params)
end

#delete_category(id:) ⇒ Hash

删除分类

Parameters:

  • id (String, Integer) —

    分类ID（必需）

Returns:

  • (Hash) —

    API响应

Raises:



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/jpsclient/api/category.rb', line 93

def delete_category(id:)
  config = @request_config && @request_config["category_delete"]
  raise JPSClient::ExceptionError, "Missing config for category_delete" unless config && config["url"]

  path = config["url"]

  # POST请求，ID作为body参数
  params = { id: id }

  return request_with_auth(:post, path, body: params)
end

#disable_category(category_id:) ⇒ Hash

停用分类

Parameters:

  • category_id (String, Integer) —

    分类ID

Returns:

  • (Hash) —

    API响应



216
217
218
 
# File 'lib/jpsclient/api/category.rb', line 216

def disable_category(category_id:)
  update_category(params: { id: category_id, status: 0 })
end

#enable_category(category_id:) ⇒ Hash

启用分类

Parameters:

  • category_id (String, Integer) —

    分类ID

Returns:

  • (Hash) —

    API响应



208
209
210
 
# File 'lib/jpsclient/api/category.rb', line 208

def enable_category(category_id:)
  update_category(params: { id: category_id, status: 1 })
end

#get_categories_by_type(type:, parent_id: nil) ⇒ Hash

按类型获取分类列表（便捷方法）

Parameters:

  • type (String) —

    分类类型

    • application: 应用分类

    • resource: 资源分类

    • asset: 素材分类

    • requirement: 需求分类

    • sketch: 画板分类

    • tool: 工具分类

    • survey: 调研分类

    • publisher: 发行商分类

    • experience: 体验分类

  • parent_id (String, Integer, nil) (defaults to: nil) —

    父分类ID

Returns:

  • (Hash) —

    API响应



150
151
152
153
154
 
# File 'lib/jpsclient/api/category.rb', line 150

def get_categories_by_type(type:, parent_id: nil)
  params = { type: type }
  params[:parent_id] = parent_id if parent_id
  get_category_list(params: params)
end

#get_category_list(params: {}) ⇒ Hash

获取分类列表

Parameters:

  • params (Hash) (defaults to: {}) —

    查询参数

    • type: 分类类型（可选）

    • parent_id: 父分类ID（可选）

Returns:

  • (Hash) —

    API响应

Raises:



13
14
15
16
17
18
19
20
 
# File 'lib/jpsclient/api/category.rb', line 13

def get_category_list(params: {})
  config = @request_config && @request_config["category_list"]
  raise JPSClient::ExceptionError, "Missing config for category_list" unless config && config["url"]

  path = config["url"]

  return request_with_auth(:get, path, params: params)
end

#get_category_path(category_id:) ⇒ Array<Hash>

构建分类路径根据分类ID获取从根到该分类的完整路径

Parameters:

  • category_id (String, Integer) —

    分类ID

Returns:

  • (Array<Hash>) —

    分类路径数组，从根到目标分类



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/jpsclient/api/category.rb', line 225

def get_category_path(category_id:)
  response = get_category_list

  # 如果请求失败，返回空数组
  return [] unless response && response['data']

  categories = response['data']['list'] || response['data'][:list] || []
  path = []

  current_id = category_id.to_s
  while current_id
    category = categories.find { |c|
      (c['id'] || c[:id]).to_s == current_id
    }
    break unless category

    path.unshift(category)
    current_id = (category['parent_id'] || category[:parent_id])&.to_s
    break if current_id == "0" || current_id.nil?
  end

  path
end

#get_category_statistics(category_id:) ⇒ Hash

获取分类统计信息统计某个分类下的直接子分类数量

Parameters:

  • category_id (String, Integer) —

    分类ID

Returns:

  • (Hash) —

    包含统计数据的哈希



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/jpsclient/api/category.rb', line 254

def get_category_statistics(category_id:)
  response = get_subcategories(parent_id: category_id)

  # 如果请求失败，返回空统计
  unless response && response['data']
    return {
      category_id: category_id,
      direct_children_count: 0,
      children: []
    }
  end

  child_list = response['data']['list'] || response['data'][:list] || []

  {
    category_id: category_id,
    direct_children_count: child_list.size,
    children: child_list
  }
end

#get_category_tree(params: {}) ⇒ Hash

获取分类树形结构

Parameters:

  • params (Hash) (defaults to: {}) —

    查询参数

    • type: 分类类型（可选）

    • max_level: 最大层级深度（可选）

Returns:

  • (Hash) —

    API响应，包含树形结构数据

Raises:



28
29
30
31
32
33
34
35
 
# File 'lib/jpsclient/api/category.rb', line 28

def get_category_tree(params: {})
  config = @request_config && @request_config["category_tree"]
  raise JPSClient::ExceptionError, "Missing config for category_tree" unless config && config["url"]

  path = config["url"]

  return request_with_auth(:get, path, params: params)
end

#get_root_categories(type: nil) ⇒ Hash

获取根分类列表

Parameters:

  • type (String, nil) (defaults to: nil) —

    分类类型（可选）

Returns:

  • (Hash) —

    API响应



168
169
170
171
172
 
# File 'lib/jpsclient/api/category.rb', line 168

def get_root_categories(type: nil)
  params = { parent_id: 0 }  # parent_id 为 0 或 null 表示根分类
  params[:type] = type if type
  get_category_list(params: params)
end

#get_subcategories(parent_id:) ⇒ Hash

获取某分类的所有子分类

Parameters:

  • parent_id (String, Integer) —

    父分类ID

Returns:

  • (Hash) —

    API响应



160
161
162
 
# File 'lib/jpsclient/api/category.rb', line 160

def get_subcategories(parent_id:)
  get_category_list(params: { parent_id: parent_id })
end

#move_category(category_id:, new_parent_id: nil) ⇒ Hash

移动分类到新的父分类

Parameters:

  • category_id (String, Integer) —

    要移动的分类ID

  • new_parent_id (String, Integer, nil) (defaults to: nil) —

    新的父分类ID（nil表示移到根级）

Returns:

  • (Hash) —

    API响应



196
197
198
199
200
201
202
 
# File 'lib/jpsclient/api/category.rb', line 196

def move_category(category_id:, new_parent_id: nil)
  params = {
    id: category_id,
    parent_id: new_parent_id || 0
  }
  update_category(params: params)
end

#sort_categories(items: []) ⇒ Hash

分类排序

Parameters:

  • items (Array<Hash>) (defaults to: []) —

    排序项数组每个项包含：

    • id: 分类ID

    • sort_order: 新的排序值

Returns:

  • (Hash) —

    API响应

Raises:



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/jpsclient/api/category.rb', line 112

def sort_categories(items: [])
  config = @request_config && @request_config["category_sort"]
  raise JPSClient::ExceptionError, "Missing config for category_sort" unless config && config["url"]

  if items.empty?
    raise JPSClient::ExceptionError, "Items array cannot be empty"
  end

  # 验证每个项都有必需的字段
  items.each_with_index do |item, index|
    unless item[:id] || item["id"]
      raise JPSClient::ExceptionError, "Item at index #{index} missing 'id'"
    end
    unless item[:sort_order] || item["sort_order"]
      raise JPSClient::ExceptionError, "Item at index #{index} missing 'sort_order'"
    end
  end

  path = config["url"]
  params = { items: items }

  return request_with_auth(:post, path, body: params)
end

#update_category(params: {}) ⇒ Hash

更新分类

Parameters:

  • params (Hash) (defaults to: {}) —

    更新参数

    • id: 分类ID（必需）

    • name: 分类名称

    • icon: 分类图标

    • description: 分类描述

    • sort_order: 排序值

    • status: 分类状态（1:启用, 0:停用）

Returns:

  • (Hash) —

    API响应

Raises:



77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/jpsclient/api/category.rb', line 77

def update_category(params: {})
  config = @request_config && @request_config["category_update"]
  raise JPSClient::ExceptionError, "Missing config for category_update" unless config && config["url"]

  # ID 是必需的
  raise JPSClient::ExceptionError, "Missing required field: id" unless params[:id]

  path = config["url"]

  return request_with_auth(:post, path, body: params)
end