个人开发接口文档

Appearance

字典管理 ​

概述 ​

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

主要功能 ​

  1. 字典列表展示

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

  2. 添加字典项

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

  3. 编辑字典项

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

  4. 删除字典项

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

  5. 字典类型管理

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

  6. 字典日志审计

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

技术实现 ​

数据库设计 ​

  • 字典项表 (dictionary_items)：

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

  • 字典类型表 (dictionary_types)：

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

前端实现 ​

技术栈 ​

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

页面结构 ​

  1. 字典列表页

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

  2. 字典详情页

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

  3. 字典类型管理页

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

接口列表 ​

1. 获取字典列表 ​

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

请求参数 ​

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

成功响应 ​

json
{
  "total": 100,
  "data": [
    {
      "id": 1,
      "typeId": 1,
      "code": "GENDER_MALE",
      "name": "男性",
      "description": "表示男性的字典项",
      "status": 1,
      "createdAt": "2023-09-01T08:00:00Z",
      "updatedAt": "2023-09-01T08:00:00Z"
    },
    ...
  ]
}

2. 添加字典项 ​

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

请求体 ​

json
{
  "typeId": 1,
  "code": "NEW_CODE",
  "name": "新字典项",
  "description": "新字典项的描述",
  "status": 1
}

成功响应 ​

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

3. 编辑字典项 ​

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

请求体 ​

json
{
  "name": "更新后的字典项",
  "description": "更新后的描述",
  "status": 1
}

成功响应 ​

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

4. 删除字典项 ​

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

成功响应 ​

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

5. 批量操作字典项 ​

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

请求体 ​

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

成功响应 ​

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

6. 导出字典数据 ​

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

成功响应 ​

  • 返回一个 Excel 文件流，文件名为 dictionary_export.xlsx

7. 获取字典类型列表 ​

  • URL：/api/dictionary/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/dictionary/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/dictionary/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/dictionary/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