gubersail-platform-ui/src/api/announcement/category.js

/**
 * 公告分类管理API
 * @description 提供公告分类的增删改查功能
 * @version 1.0.0
 */
import request from '@/router/axios';

/**
 * 分类状态枚举
 * @typedef {0|1} CategoryStatus
 * - 0: 禁用
 * - 1: 启用
 */

/**
 * 删除状态枚举
 * @typedef {0|1} DeleteStatus
 * - 0: 未删除
 * - 1: 已删除
 */

/**
 * 系统分类标识
 * @typedef {0|1} SystemFlag
 * - 0: 非系统分类
 * - 1: 系统分类
 */

/**
 * 分类数据类型定义
 * @typedef {Object} CategoryItem
 * @property {number} id - 分类ID（唯一标识）
 * @property {string} name - 分类名称（必填，最大长度50）
 * @property {number} sortOrder - 排序（数值越小越靠前，默认0）
 * @property {number} orgId - 组织ID（必填）
 * @property {string} orgCode - 组织编码（必填）
 * @property {string} orgName - 组织名称（只读）
 * @property {SystemFlag} isSystem - 是否系统分类（0-否 1-是）
 * @property {string} remark - 备注（可选，最大长度200）
 * @property {number} createUser - 创建用户ID
 * @property {number} createDept - 创建部门ID
 * @property {string|null} createTime - 创建时间（ISO格式）
 * @property {number|null} updateUser - 更新用户ID
 * @property {string|null} updateTime - 更新时间（ISO格式）
 * @property {CategoryStatus} status - 状态（0-禁用 1-启用）
 * @property {DeleteStatus} isDeleted - 是否删除（0-否 1-是）
 */

/**
 * 新增分类请求参数类型
 * @typedef {Object} AddCategoryParams
 * @property {number} createDept - 创建部门ID（必填）
 * @property {number} createUser - 创建用户ID（必填）
 * @property {string} name - 分类名称（必填，最大长度50）
 * @property {string} orgCode - 组织编码（必填）
 * @property {number} orgId - 组织ID（必填）
 * @property {string} orgName - 组织名称（必填）
 * @property {string} [remark=''] - 备注（可选，最大长度200）
 * @property {number} [sortOrder=0] - 排序（可选，默认0）
 */

/**
 * 更新分类请求参数类型
 * @typedef {Object} UpdateCategoryParams
 * @property {number} id - 分类ID（必填）
 * @property {string} name - 分类名称（必填，最大长度50）
 * @property {string} [remark] - 备注（可选，最大长度200）
 * @property {number} [sortOrder] - 排序（可选）
 * @property {number} [createDept] - 创建部门ID
 * @property {number} [createUser] - 创建用户ID
 * @property {string} [orgCode] - 组织编码
 * @property {number} [orgId] - 组织ID
 * @property {string} [orgName] - 组织名称
 */

/**
 * 通用API响应类型
 * @template T
 * @typedef {Object} ApiResponse
 * @property {number} code - 响应状态码
 * @property {boolean} success - 是否成功
 * @property {string} msg - 响应消息
 * @property {T} data - 响应数据
 */

/**
 * @template T
 * @typedef {ApiResponse<T>} ApiResponseGeneric
 */

/**
 * 获取分类列表
 * @returns {Promise<import('axios').AxiosResponse<ApiResponseGeneric<CategoryItem[]>>>} 分类列表响应
 * @throws {Error} 当请求失败时抛出错误
 * @example
 * // 获取所有分类
 * const response = await getCategoryList();
 * const categories = response.data.data;
 * console.log(categories.length);
 */
export const getCategoryList = () => {
  return request({
    url: '/api/blade-factory/api/factory/notice/category/list',
    method: 'get'
  })
}

/**
 * 新增分类
 * @param {AddCategoryParams} params - 分类信息
 * @param {number} params.createDept - 创建部门ID
 * @param {number} params.createUser - 创建用户ID
 * @param {string} params.name - 分类名称
 * @param {string} params.orgCode - 组织编码
 * @param {number} params.orgId - 组织ID
 * @param {string} params.orgName - 组织名称
 * @param {string} [params.remark=''] - 备注
 * @param {number} [params.sortOrder=0] - 排序
 * @returns {Promise<import('axios').AxiosResponse<ApiResponseGeneric<null>>>} 操作结果
 * @throws {Error} 当请求失败或参数验证失败时抛出错误
 * @example
 * // 新增分类
 * const params = {
 *   name: '重要公告',
 *   createDept: 1,
 *   createUser: 1,
 *   orgCode: 'ORG001',
 *   orgId: 1,
 *   orgName: '总部',
 *   remark: '重要公告分类'
 * };
 * await addCategory(params);
 */
export const addCategory = (params) => {
  return request({
    url: '/api/blade-factory/api/factory/notice/category/add',
    method: 'post',
    data: {
      sortOrder: 0,
      ...params
    }
  })
}

/**
 * 更新分类
 * @param {UpdateCategoryParams} params - 分类信息（包含id）
 * 修改分类
 * @param {Object} params - 分类参数
 * @param {number} params.id - 分类ID
 * @param {string} params.name - 分类名称
 * @param {string} [params.remark] - 备注
 * @param {number} [params.sortOrder] - 排序
 * @returns {Promise<import('axios').AxiosResponse<ApiResponse<null>>>} 操作结果
 * @throws {Error} 当请求失败、参数验证失败或分类不存在时抛出错误
 * @example
 * // 更新分类
 * const params = {
 *   id: 1,
 *   name: '更新后的分类名称',
 *   remark: '更新后的备注',
 *   sortOrder: 10
 * };
 * await updateCategory(params);
 */
export const updateCategory = (params) => {
  return request({
    url: '/api/blade-factory/api/factory/notice/category/update',
    method: 'post',
    data: params
  })
}

/**
 * 删除分类
 * @param {string|number} ids - 分类ID，多个用逗号分隔
 * @returns {Promise<import('axios').AxiosResponse<ApiResponse<null>>>} 操作结果
 * @throws {Error} 当请求失败或分类不存在时抛出错误
 * @example
 * // 删除单个分类
 * await removeCategory(1);
 * 
 * // 删除多个分类
 * await removeCategory('1,2,3');
 */
export const removeCategory = (ids) => {
  return request({
    url: '/api/blade-factory/api/notice/category/remove',
    method: 'post',
    params: {
      ids: String(ids)
    }
  })
}

/**
 * 获取分类详情
 * @param {number} id - 分类ID（必填）
 * @returns {Promise<import('axios').AxiosResponse<ApiResponseGeneric<CategoryItem>>>} 分类详情
 * @throws {Error} 当请求失败或分类不存在时抛出错误
 * @example
 * // 获取分类详情
 * const response = await getCategoryDetail(1);
 * const category = response.data.data;
 * console.log(category.name);
 */
export const getCategoryDetail = (id) => {
  return request({
    url: '/api/blade-factory/api/notice/category/detail',
    method: 'get',
    params: {
      id
    }
  })
}

/**
 * 更新分类状态
 * @param {number} id - 分类ID（必填）
 * @param {CategoryStatus} status - 状态（0-禁用 1-启用）
 * @returns {Promise<import('axios').AxiosResponse<ApiResponse<null>>>} 操作结果
 * @throws {Error} 当请求失败或分类不存在时抛出错误
 * @example
 * // 启用分类
 * await updateCategoryStatus(1, 1);
 * 
 * // 禁用分类
 * await updateCategoryStatus(1, 0);
 */
export const updateCategoryStatus = (id, status) => {
  return request({
    url: '/api/blade-factory/api/notice/category/status',
    method: 'post',
    params: {
      id,
      status
    }
  })
}