个人开发接口文档

Appearance

参数设置 ​

概述 ​

参数设置模块是系统中用于管理和维护各类全局参数的核心模块。通过该模块，管理员可以对系统中的参数项进行添加、编辑、删除等操作，并且可以配置参数的层级关系和状态。参数设置模块确保了系统的灵活性和可扩展性，使得不同角色的用户可以根据其权限访问相应的参数数据，从而提高系统的维护效率和数据一致性。

主要功能 ​

  1. 参数列表展示

    • 功能描述：以表格形式展示所有参数项的详细信息，包括参数类型、参数编码、参数名称、描述、创建时间、最后更新时间、状态（启用/禁用）等。
    • 操作按钮：
      • 搜索：支持按参数类型、参数编码、参数名称等关键字进行模糊查询。
      • 批量操作：支持批量启用、禁用、删除参数项。
      • 导出：将当前页面或全部参数数据导出为 Excel 文件。

  2. 添加参数项

    • 功能描述：提供表单用于创建新参数项，管理员可以填写字典项的详细信息并设置初始状态。
    • 字段说明：
      • 参数类型：必选，选择参数所属的类型（如系统配置、业务规则等）。
      • 参数编码：必填，唯一标识符。
      • 参数名称：必填，参数项的名称。
      • 描述：选填，简要描述参数项的用途。
      • 值：必填，参数的具体值。
      • 状态：默认启用，可以选择是否启用该参数项。

  3. 编辑参数项

    • 功能描述：管理员可以编辑现有参数项的详细信息，包括修改参数编码、参数名称、描述、值和状态。
    • 字段说明：
      • 参数编码：不可修改，作为唯一标识符。
      • 参数名称：可修改，确保唯一性。
      • 描述：可修改，更新参数项的描述。
      • 值：可修改，更新参数的具体值。
      • 状态：可修改，启用或禁用参数项。

  4. 删除参数项

    • 功能描述：管理员可以删除不再需要的参数项。为了防止误操作，删除操作会弹出确认框提示。
    • 注意事项：
      • 删除后无法恢复，请谨慎操作。
      • 如果参数项有未完成的任务或关联的数据，建议先处理这些数据再删除参数项。

  5. 参数类型管理

    • 功能描述：管理员可以对参数类型进行管理，包括添加、编辑和删除参数类型。
    • 字段说明：
      • 类型名称：必填，参数类型的名称。
      • 描述：选填，简要描述参数类型的用途。
      • 状态：默认启用，可以选择是否启用该参数类型。

  6. 参数日志审计

    • 功能描述：记录参数的操作日志，便于管理员审查参数的变更情况，确保系统的安全性和合规性。
    • 日志内容：
      • 操作时间：记录每次操作的具体时间。
      • 操作用户：记录执行操作的用户名。
      • 操作类型：记录具体操作（如添加参数项、编辑参数项、删除参数项等）。
      • 操作结果：记录操作是否成功及其相关信息。

技术实现 ​

数据库设计 ​

  • 参数项表 (parameter_items)：

    • id：主键，自增。
    • type_id：外键，关联参数类型表。
    • code：参数编码，唯一。
    • name：参数名称。
    • description：描述。
    • value：参数值。
    • status：参数项状态（0: 禁用, 1: 启用）。
    • created_at：创建时间。
    • updated_at：更新时间。

  • 参数类型表 (parameter_types)：

    • id：主键，自增。
    • name：类型名称，唯一。
    • description：描述。
    • status：类型状态（0: 禁用, 1: 启用）。
    • created_at：创建时间。
    • updated_at：更新时间。

前端实现 ​

技术栈 ​

  • 框架：Vue.js 3.x
  • UI库：Naive UI
  • 状态管理：Pinia
  • 路由管理：Vue Router
  • API请求：Axios

页面结构 ​

  1. 参数列表页

    • 组件：ParameterList.vue
    • 功能：
      • 使用 Naive UI 的 n-data-table 组件展示参数项列表。
      • 支持分页、排序和筛选功能。
      • 提供搜索栏，使用 n-input 和 n-button 组件实现模糊查询。
      • 提供批量操作按钮，使用 n-popconfirm 组件实现批量启用、禁用、删除参数项的确认框。
      • 提供导出按钮，调用后端 API 导出参数数据为 Excel 文件。

  2. 参数详情页

    • 组件：ParameterDetail.vue
    • 功能：
      • 使用 Naive UI 的 n-form 和 n-form-item 组件构建参数项信息表单。
      • 表单字段包括参数类型、参数编码、参数名称、描述、值、状态。
      • 使用 n-select 组件选择参数类型。
      • 使用 n-switch 组件切换参数项状态（启用/禁用）。
      • 提交表单时，调用后端 API 进行参数项信息的添加或编辑操作。

  3. 参数类型管理页

    • 组件：ParameterType.vue
    • 功能：
      • 使用 Naive UI 的 n-form 和 n-form-item 组件构建参数类型信息表单。
      • 表单字段包括类型名称、描述、状态。
      • 使用 n-switch 组件切换参数类型状态（启用/禁用）。
      • 提交表单时，调用后端 API 进行参数类型信息的添加或编辑操作。

接口列表 ​

1. 获取参数列表 ​

  • URL：/api/parameter/items
  • 方法：GET

请求参数 ​

参数名类型是否必填默认值描述
pageint否1当前页码
pageSizeint否10每页显示条数
searchstring否搜索关键字（参数类型、编码、名称等）

成功响应 ​

json
{
  "total": 100,
  "data": [
    {
      "id": 1,
      "typeId": 1,
      "code": "SYSTEM_TIMEZONE",
      "name": "系统时区",
      "description": "系统默认时区配置",
      "value": "Asia/Shanghai",
      "status": 1,
      "createdAt": "2023-09-01T08:00:00Z",
      "updatedAt": "2023-09-01T08:00:00Z"
    },
    ...
  ]
}

2. 添加参数项 ​

  • URL：/api/parameter/items
  • 方法：POST
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "typeId": 1,
  "code": "NEW_CODE",
  "name": "新参数项",
  "description": "新参数项的描述",
  "value": "new_value",
  "status": 1
}

成功响应 ​

json
{
  "id": 101,
  "typeId": 1,
  "code": "NEW_CODE",
  "name": "新参数项",
  "description": "新参数项的描述",
  "value": "new_value",
  "status": 1,
  "createdAt": "2023-09-01T08:00:00Z",
  "updatedAt": "2023-09-01T08:00:00Z"
}

3. 编辑参数项 ​

  • URL：/api/parameter/items/{id}
  • 方法：PUT
  • 路径参数：
    • id：参数项ID
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "name": "更新后的参数项",
  "description": "更新后的描述",
  "value": "updated_value",
  "status": 1
}

成功响应 ​

json
{
  "id": 101,
  "typeId": 1,
  "code": "NEW_CODE",
  "name": "更新后的参数项",
  "description": "更新后的描述",
  "value": "updated_value",
  "status": 1,
  "updatedAt": "2023-09-01T08:00:00Z"
}

4. 删除参数项 ​

  • URL：/api/parameter/items/{id}
  • 方法：DELETE
  • 路径参数：
    • id：参数项ID

成功响应 ​

json
{
  "message": "删除成功"
}

5. 批量操作参数项 ​

  • URL：/api/parameter/items/batch
  • 方法：POST
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "ids": [1, 2, 3],
  "action": "enable" // 可选值：enable, disable, delete
}

成功响应 ​

json
{
  "message": "批量操作成功"
}

6. 导出参数数据 ​

  • URL：/api/parameter/items/export
  • 方法：GET
  • 请求参数：
    • typeId：参数类型ID（可选）
    • status：参数项状态（可选）

成功响应 ​

  • 返回一个 Excel 文件流，文件名为 parameter_export.xlsx
7. 获取参数类型列表 ​
  • URL：/api/parameter/types
  • 方法：GET

请求参数 ​

参数名类型是否必填默认值描述
pageint否1当前页码
pageSizeint否10每页显示条数
searchstring否搜索关键字（类型名称等）

成功响应 ​

json
{
  "total": 10,
  "data": [
    {
      "id": 1,
      "name": "系统配置",
      "description": "系统配置参数类型",
      "status": 1,
      "createdAt": "2023-09-01T08:00:00Z",
      "updatedAt": "2023-09-01T08:00:00Z"
    },
    ...
  ]
}

8. 添加参数类型 ​

  • URL：/api/parameter/types
  • 方法：POST
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "name": "新参数类型",
  "description": "新参数类型的描述",
  "status": 1
}

成功响应 ​

json
{
  "id": 11,
  "name": "新参数类型",
  "description": "新参数类型的描述",
  "status": 1,
  "createdAt": "2023-09-01T08:00:00Z",
  "updatedAt": "2023-09-01T08:00:00Z"
}

9. 编辑参数类型 ​

  • URL：/api/parameter/types/{id}
  • 方法：PUT
  • 路径参数：
    • id：参数类型ID
  • 请求头:
    • Content-Type: application/json

请求体 ​

json
{
  "name": "更新后的参数类型",
  "description": "更新后的描述",
  "status": 1
}

成功响应 ​

json
{
  "id": 11,
  "name": "更新后的参数类型",
  "description": "更新后的描述",
  "status": 1,
  "updatedAt": "2023-09-01T08:00:00Z"
}

10. 删除参数类型 ​

  • URL：/api/parameter/types/{id}
  • 方法：DELETE
  • 路径参数：
    • id：参数类型ID

成功响应 ​

json
{
  "message": "删除成功"
}

附录 ​

接口规范 ​

  • HTTP状态码：

    • 200 OK：请求成功。
    • 201 Created：资源创建成功。
    • 204 No Content：请求成功但无返回内容。
    • 400 Bad Request：客户端请求有误。
    • 404 Not Found：请求的资源不存在。
    • 409 Conflict：请求冲突，例如资源已存在。

  • 错误响应格式：

    json
    {
  "error": "Error message",
  "details": ["Detail 1", "Detail 2"]
}

  • 时间格式：

    • 使用 ISO 8601 标准格式，例如 2023-01-01T00:00:00Z。

总结 ​

参数设置模块是系统中不可或缺的一部分，它不仅提供了对参数数据的全面管理，还确保了系统的灵活性和可维护性。通过合理的参数配置和日志审计，管理员可以有效地管理和调整参数结构，保障系统的稳定运行和用户体验。如果有其他问题或需要进一步的帮助，请随时联系技术支持团队。

滇ICP备2024047254号-1
滇公网安备53011102001490