{
  "system/system-alg.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "ALG应用层网关管理API",
      "version": "1.0.0",
      "summary": "ALG应用层网关的完整管理功能",
      "description": "提供ALG应用层网关的完整管理功能，包括：\n- FTP协议支持配置（默认端口21自动追加）\n- TFTP协议支持配置（默认端口69自动追加）\n- SIP协议支持配置（默认端口5060自动追加）\n- H323协议支持配置\n- 自定义端口配置（每种协议最多7个自定义端口，三种协议间端口不可重复）\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/alg": {
        "get": {
          "summary": "获取ALG配置",
          "description": "获取当前ALG应用层网关的配置信息，包括各协议的支持状态和自定义端口配置。\n",
          "operationId": "getAlgConfig",
          "tags": [
            "alg"
          ],
          "responses": {
            "200": {
              "description": "成功获取ALG配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AlgConfigResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "support_ftp": 1,
                          "support_tftp": 1,
                          "support_sip": 1,
                          "support_h323": 1,
                          "ftp_ports": "",
                          "sip_ports": "",
                          "tftp_ports": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新ALG配置",
          "description": "全量更新ALG应用层网关配置。所有字段均为必填，即使未修改也必须携带原值。\n端口约束：\n- 每种协议最多配置7个自定义端口\n- FTP、TFTP、SIP三种协议间的自定义端口不可重复\n- 默认端口（FTP:21、SIP:5060、TFTP:69）由系统自动追加，无需填入\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateAlgConfig",
          "tags": [
            "alg"
          ],
          "requestBody": {
            "required": true,
            "description": "ALG配置数据（全量更新，所有字段必填，未修改的字段须传原值）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlgConfigInput"
                },
                "example": {
                  "support_ftp": 1,
                  "support_tftp": 1,
                  "support_sip": 1,
                  "support_h323": 1,
                  "ftp_ports": "2121",
                  "sip_ports": "",
                  "tftp_ports": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AlgConfigResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AlgConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AlgConfig": {
          "type": "object",
          "required": [
            "id",
            "support_ftp",
            "support_tftp",
            "support_sip",
            "support_h323",
            "ftp_ports",
            "sip_ports",
            "tftp_ports"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "support_ftp": {
              "type": "integer",
              "description": "FTP协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "support_tftp": {
              "type": "integer",
              "description": "TFTP协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "support_sip": {
              "type": "integer",
              "description": "SIP协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "support_h323": {
              "type": "integer",
              "description": "H323协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "ftp_ports": {
              "type": "string",
              "description": "FTP自定义端口，逗号分隔，最多7个，不含默认端口21",
              "default": "",
              "example": ""
            },
            "sip_ports": {
              "type": "string",
              "description": "SIP自定义端口，逗号分隔，最多7个，不含默认端口5060",
              "default": "",
              "example": ""
            },
            "tftp_ports": {
              "type": "string",
              "description": "TFTP自定义端口，逗号分隔，最多7个，不含默认端口69",
              "default": "",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "AlgConfigInput": {
          "type": "object",
          "description": "ALG配置全量编辑输入。所有字段均为必填，未修改的字段须传原值。",
          "required": [
            "support_ftp",
            "support_tftp",
            "support_sip",
            "support_h323",
            "ftp_ports",
            "sip_ports",
            "tftp_ports"
          ],
          "properties": {
            "support_ftp": {
              "type": "integer",
              "description": "FTP协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "support_tftp": {
              "type": "integer",
              "description": "TFTP协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "support_sip": {
              "type": "integer",
              "description": "SIP协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "support_h323": {
              "type": "integer",
              "description": "H323协议ALG开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "ftp_ports": {
              "type": "string",
              "description": "FTP自定义端口，逗号分隔，最多7个，与SIP/TFTP端口不可重复，不含默认端口21",
              "default": "",
              "example": ""
            },
            "sip_ports": {
              "type": "string",
              "description": "SIP自定义端口，逗号分隔，最多7个，与FTP/TFTP端口不可重复，不含默认端口5060",
              "default": "",
              "example": ""
            },
            "tftp_ports": {
              "type": "string",
              "description": "TFTP自定义端口，逗号分隔，最多7个，与FTP/SIP端口不可重复，不含默认端口69",
              "default": "",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "alg",
        "x-displayName": "ALG应用层网关",
        "description": "ALG应用层网关配置管理，包括FTP、TFTP、SIP、H323协议支持"
      }
    ]
  },
  "system/system-backup.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统备份管理API",
      "version": "1.0.0",
      "summary": "系统配置备份与自动备份策略管理",
      "description": "提供系统配置备份的完整管理功能，包括：\n- 查询备份文件列表及磁盘使用情况\n- 查询/保存自动备份策略（执行周期、时间、文件保留天数）\n- 手动立即创建备份\n- 删除备份文件\n- 恢复指定备份\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/backup": {
        "get": {
          "summary": "获取备份信息",
          "description": "查询备份文件列表及磁盘使用情况。\n",
          "operationId": "getBackupSnapshots",
          "tags": [
            "backup"
          ],
          "responses": {
            "200": {
              "description": "成功获取备份信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SnapshotsResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "backup_info": [
                        {
                          "id": 1,
                          "timestamp": 1712500000,
                          "filename": "20240407120000.bak",
                          "backtype": 1,
                          "version": "4.0.100",
                          "filesize": 204800
                        },
                        {
                          "id": 2,
                          "timestamp": 1712600000,
                          "filename": "20240408100000.bak",
                          "backtype": 2,
                          "version": "4.0.100",
                          "filesize": 210000
                        }
                      ]
                    }
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "手动备份配置",
          "description": "立即将当前系统配置打包为备份文件（`.bak`）并保存。无需请求体。\n",
          "operationId": "createBackupSnapshot",
          "tags": [
            "backup"
          ],
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "comment",
                            "type": "format",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除备份文件",
          "description": "删除指定备份文件及其数据库记录。通过 query 参数 `srcfile` 指定要删除的备份文件，无需请求体。\n",
          "operationId": "deleteBackupSnapshot",
          "tags": [
            "backup"
          ],
          "parameters": [
            {
              "name": "srcfile",
              "in": "query",
              "required": true,
              "description": "要删除的备份文件名，格式为 `YYYYMMDDHHmmss.bak`",
              "schema": {
                "type": "string",
                "example": "20240407120000.bak"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "备份文件删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DeleteSuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/backup:restore": {
        "post": {
          "summary": "恢复备份",
          "description": "将系统配置恢复至指定备份文件。`srcfile` 需放在请求体中传入。操作成功后系统将自动重启（约 2 秒后）。\n\n**`restore_type` 说明：**\n- `0`（默认）：仅恢复配置，不切换固件版本\n- `1`：同时恢复固件版本（需从云端下载对应固件，耗时较长）\n\n**`sync_bind_cloud` 说明：**\n- `0`（默认）：不同步云平台绑定信息\n- `1`：同步导入云平台绑定信息，此时 `cloud_comment` 为必填\n\n**版本兼容限制：**\n- 4.0 配置不可恢复到 3.x 设备\n- 4.0 设备不可恢复 3.x 配置\n",
          "operationId": "restoreBackupSnapshot",
          "tags": [
            "backup"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestoreRequest"
                },
                "examples": {
                  "simple": {
                    "summary": "仅恢复配置",
                    "value": {
                      "srcfile": "20240407120000.bak",
                      "restore_type": 0,
                      "sync_bind_cloud": 0,
                      "cloud_comment": "branch-office-router"
                    }
                  },
                  "with_cloud": {
                    "summary": "恢复配置并同步云平台绑定信息",
                    "value": {
                      "srcfile": "20240407120000.bak",
                      "restore_type": 0,
                      "sync_bind_cloud": 1,
                      "cloud_comment": "branch-office-router"
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：恢复任务已触发\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "srcfile",
                            "type": "not_found",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/backup-auto": {
        "get": {
          "summary": "获取自动备份策略",
          "description": "查询当前自动备份策略配置。\n",
          "operationId": "getBackupSettings",
          "tags": [
            "backup"
          ],
          "responses": {
            "200": {
              "description": "成功获取自动备份策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/BackupSettingsResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "strategy": "week",
                          "time": "08:00",
                          "cycle_time": "1234567",
                          "valid_days": 30
                        }
                      ]
                    }
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "保存自动备份策略",
          "description": "更新自动备份策略配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n\n**`cycle_time` 格式说明（依 `strategy` 而定）：**\n- `strategy=one`（单次）：具体日期，格式 `YYYY-MM-DD`，如 `2024-04-07`\n- `strategy=week`（每天）：填 `all`\n- `strategy=week`（每周）：填星期组合串，如 `135`（周一三五），至少选 1 天\n- `strategy=month`（每月）：填月内执行日，范围 `1-31`，如 `15`\n",
          "operationId": "saveBackupSettings",
          "tags": [
            "backup"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackupSettingsRequest"
                },
                "examples": {
                  "weekly": {
                    "summary": "每周一三五 08:00 执行，保留 30 天",
                    "value": {
                      "id": 1,
                      "enabled": "yes",
                      "strategy": "week",
                      "time": "08:00",
                      "cycle_time": "135",
                      "valid_days": 30
                    }
                  },
                  "daily": {
                    "summary": "每天 02:00 执行，保留 7 天",
                    "value": {
                      "id": 1,
                      "enabled": "yes",
                      "strategy": "week",
                      "time": "02:00",
                      "cycle_time": "all",
                      "valid_days": 7
                    }
                  },
                  "monthly": {
                    "summary": "每月 15 号执行，不限期保留",
                    "value": {
                      "id": 1,
                      "enabled": "yes",
                      "strategy": "month",
                      "time": "00:00",
                      "cycle_time": "15",
                      "valid_days": 0
                    }
                  },
                  "once": {
                    "summary": "单次执行",
                    "value": {
                      "id": 1,
                      "enabled": "yes",
                      "strategy": "one",
                      "time": "10:00",
                      "cycle_time": "2024-04-07",
                      "valid_days": 1
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "cycle_time",
                            "type": "format",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DeleteSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示删除成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示创建成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "required": [
            "field",
            "type",
            "msg"
          ],
          "additionalProperties": false
        },
        "BackupSnapshot": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "description": "快照记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "description": "备份创建时间（Unix 时间戳，秒）",
              "example": 1712500000
            },
            "filename": {
              "type": "string",
              "description": "备份文件名（.bak 格式）",
              "example": "20240407120000.bak"
            },
            "backtype": {
              "type": "integer",
              "description": "备份类型：1=手动备份，2=自动备份",
              "enum": [
                1,
                2
              ],
              "example": 1
            },
            "version": {
              "type": "string",
              "description": "备份时的固件版本号",
              "example": "4.0.100"
            },
            "filesize": {
              "type": "integer",
              "description": "备份文件大小（字节）",
              "minimum": 0,
              "example": 204800
            }
          },
          "required": [
            "id",
            "timestamp",
            "filename",
            "backtype",
            "version",
            "filesize"
          ],
          "additionalProperties": false
        },
        "SnapshotsResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/SnapshotsResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "SnapshotsResults": {
          "type": "object",
          "properties": {
            "backup_info": {
              "type": "array",
              "description": "备份文件列表",
              "items": {
                "$ref": "#/components/schemas/BackupSnapshot"
              }
            }
          },
          "required": [
            "backup_info"
          ],
          "additionalProperties": false
        },
        "BackupSettings": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "description": "策略记录ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "是否启用自动备份",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "strategy": {
              "type": "string",
              "description": "备份周期类型：one=单次，week=每日/每周，month=每月",
              "enum": [
                "one",
                "week",
                "month"
              ],
              "example": "week"
            },
            "time": {
              "type": "string",
              "description": "执行时间，格式 HH:mm",
              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
              "example": "08:00"
            },
            "cycle_time": {
              "type": "string",
              "description": "执行周期值，含义依 strategy 而定：\n- one：具体日期（YYYY-MM-DD）\n- week：星期组合串（如 \"135\"）或 \"all\"（每天）\n- month：月内执行日（1-31 的数字字符串）\n",
              "example": "1234567"
            },
            "valid_days": {
              "type": "integer",
              "description": "自动备份文件保留天数，0 表示不限期",
              "minimum": 0,
              "maximum": 365,
              "example": 30
            }
          },
          "required": [
            "id",
            "enabled",
            "strategy",
            "time",
            "cycle_time",
            "valid_days"
          ],
          "additionalProperties": false
        },
        "BackupSettingsResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/BackupSettingsResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "BackupSettingsResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "自动备份策略列表",
              "items": {
                "$ref": "#/components/schemas/BackupSettings"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "BackupSettingsRequest": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "strategy",
            "time",
            "cycle_time",
            "valid_days"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "当前备份策略记录ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "是否启用自动备份",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "strategy": {
              "type": "string",
              "description": "备份周期类型：one=单次，week=每日/每周，month=每月",
              "enum": [
                "one",
                "week",
                "month"
              ],
              "example": "week"
            },
            "time": {
              "type": "string",
              "description": "执行时间，格式 HH:mm",
              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
              "example": "08:00"
            },
            "cycle_time": {
              "type": "string",
              "description": "执行周期值，格式依 strategy 而定（见接口描述）",
              "example": "135"
            },
            "valid_days": {
              "type": "integer",
              "description": "自动备份文件保留天数，0 表示不限期",
              "minimum": 0,
              "maximum": 365,
              "example": 30
            }
          },
          "additionalProperties": false
        },
        "RestoreRequest": {
          "type": "object",
          "required": [
            "srcfile"
          ],
          "properties": {
            "srcfile": {
              "type": "string",
              "description": "要恢复的备份文件名，格式为 `YYYYMMDDHHmmss.bak`",
              "example": "20240407120000.bak"
            },
            "restore_type": {
              "type": "integer",
              "description": "恢复类型：0=仅恢复配置，1=同时恢复固件版本",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "sync_bind_cloud": {
              "type": "integer",
              "description": "是否同步导入云平台绑定信息：0=否，1=是（此时 cloud_comment 必填）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "cloud_comment": {
              "type": "string",
              "description": "云端设备备注名称，sync_bind_cloud=1 时必填，长度 1-63 字符，支持 @ - _ + . 等特殊字符（不支持冒号）",
              "minLength": 1,
              "maxLength": 63,
              "example": "branch-office-router"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "backup",
        "x-displayName": "系统备份",
        "description": "系统配置备份文件管理及自动备份策略配置"
      }
    ]
  },
  "system/system-basic.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统基础设置API",
      "version": "1.0.0",
      "summary": "系统基础设置的完整管理功能",
      "description": "提供系统基础设置的完整管理功能，包括：\n- 主机名设置\n- 语言选择\n- 时区配置\n- 上网模式设置\n- NTP时间同步\n- 链路模式配置\n- 加速模式控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/basic/config": {
        "get": {
          "summary": "获取系统基础设置",
          "description": "获取当前系统的基础设置配置信息，包括主机名、语言、时区、\n上网模式、NTP配置、链路模式等所有基础设置项。\n",
          "operationId": "getSystemBasicConfig",
          "tags": [
            "system-basic"
          ],
          "responses": {
            "200": {
              "description": "成功获取系统基础设置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemBasicConfigResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新系统基础设置",
          "description": "更新系统的基础设置配置信息，包括主机名、语言、时区、\n上网模式、NTP配置、链路模式等设置。\n企业版功能设置在免费版上不生效。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateSystemBasicConfig",
          "tags": [
            "system-basic"
          ],
          "requestBody": {
            "required": true,
            "description": "系统基础设置配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemBasicConfigInput"
                },
                "example": {
                  "hostname": "Router",
                  "language": 1,
                  "time_zone": 8,
                  "time_zone_full": "0800",
                  "switch_nat": 1,
                  "switch_ntp": 1,
                  "switch_ntpd": 0,
                  "switch_ntpserver": 0,
                  "ntpserver_list": "",
                  "ntp_sync_cycle": 60,
                  "link_mode": 0,
                  "lan_nat": 1,
                  "backport": "wan1",
                  "listenport": "lan1",
                  "fast_nat": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/basic/ntp:sync": {
        "post": {
          "summary": "立即进行NTP同步",
          "description": "立即执行NTP时间同步，强制系统与NTP服务器进行时间校准。\n请确保NTP服务已启用且网络连接正常。\n",
          "operationId": "syncNtpTime",
          "tags": [
            "system-basic"
          ],
          "responses": {
            "200": {
              "description": "NTP时间同步成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "NTP时间同步异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemBasicErrorResponse"
                  },
                  "example": {
                    "message": "NTP时间同步异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SystemBasicErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "系统基础设置业务错误信息描述"
            }
          }
        },
        "SystemBasicConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SystemBasicConfig"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "SystemBasicConfig": {
          "type": "object",
          "required": [
            "id",
            "hostname",
            "language",
            "time_zone",
            "time_zone_full",
            "switch_nat",
            "switch_ntp",
            "switch_ntpd",
            "switch_ntpserver",
            "ntp_sync_cycle",
            "link_mode",
            "fast_nat",
            "lan_nat",
            "listenport",
            "backport"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "hostname": {
              "type": "string",
              "description": "主机名（1-21个字符，允许中文、字母、数字、`: @ - _ + .`）",
              "maxLength": 21,
              "example": "Router"
            },
            "language": {
              "type": "integer",
              "description": "选择语言，1-中文，2-英文；企业版功能，免费版设置不生效",
              "enum": [
                1,
                2
              ],
              "example": 1
            },
            "time_zone": {
              "type": "integer",
              "description": "时区偏移量（UTC），如东八区为8",
              "minimum": -12,
              "maximum": 14,
              "example": 8
            },
            "time_zone_full": {
              "type": "string",
              "description": "国际时区全格式（例 0800），默认值 '0800'",
              "pattern": "^[0-9]{4}$",
              "default": "0800",
              "example": "0800"
            },
            "switch_nat": {
              "type": "integer",
              "description": "上网模式，0=NONAT，1=对称NAT，2=全锥形NAT",
              "enum": [
                0,
                1,
                2
              ],
              "example": 1
            },
            "switch_ntp": {
              "type": "integer",
              "description": "自动更新时间开关，0-关 1-开",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "switch_ntpd": {
              "type": "integer",
              "description": "ntpd 服务开关，0-关 1-开",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "switch_ntpserver": {
              "type": "integer",
              "description": "NTP 服务器开关，0-关 1-开",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ntpserver_list": {
              "type": "string",
              "description": "自定义 NTP 服务器列表，最长253个字符，支持 IPv4/IPv6/域名",
              "maxLength": 253,
              "example": ""
            },
            "ntp_sync_cycle": {
              "type": "integer",
              "description": "NTP 同步间隔（分钟）",
              "minimum": 5,
              "maximum": 240,
              "example": 60
            },
            "link_mode": {
              "type": "integer",
              "description": "链路模式，0=主干模式，1=旁路模式，2=SDWAN 桥",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "lan_nat": {
              "type": "integer",
              "description": "路由模式(switch_nat=0)时是否启用 LAN 地址 NAT，0=关 1=开",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "backport": {
              "type": "string",
              "description": "旁路模式上网接口",
              "example": "wan1"
            },
            "listenport": {
              "type": "string",
              "description": "旁路模式监听接口",
              "example": "lan1"
            },
            "fast_nat": {
              "type": "integer",
              "description": "加速模式，0关闭，1开启软件模式，企业版功能，免费版设置不生效",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "SystemBasicConfigInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "hostname",
            "time_zone",
            "time_zone_full",
            "switch_nat",
            "switch_ntp",
            "switch_ntpd",
            "switch_ntpserver",
            "ntpserver_list",
            "ntp_sync_cycle",
            "link_mode",
            "lan_nat",
            "listenport",
            "backport",
            "language",
            "fast_nat"
          ],
          "properties": {
            "hostname": {
              "type": "string",
              "description": "主机名（1-21个字符，允许中文、字母、数字、`: @ - _ + .`）",
              "maxLength": 21,
              "example": "Router"
            },
            "language": {
              "type": "integer",
              "description": "选择语言，1-中文，2-英文；企业版功能，免费版设置不生效",
              "enum": [
                1,
                2
              ],
              "example": 1
            },
            "time_zone": {
              "type": "integer",
              "description": "时区偏移量（UTC），如东八区为8",
              "minimum": -12,
              "maximum": 14,
              "example": 8
            },
            "time_zone_full": {
              "type": "string",
              "description": "国际时区全格式（例 0800），默认值 '0800'",
              "pattern": "^[0-9]{4}$",
              "default": "0800",
              "example": "0800"
            },
            "switch_nat": {
              "type": "integer",
              "description": "上网模式，0=NONAT，1=对称NAT，2=全锥形NAT",
              "enum": [
                0,
                1,
                2
              ],
              "example": 1
            },
            "switch_ntp": {
              "type": "integer",
              "description": "自动更新时间开关，0-关 1-开",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "switch_ntpd": {
              "type": "integer",
              "description": "ntpd 服务开关，0-关 1-开",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "switch_ntpserver": {
              "type": "integer",
              "description": "NTP 服务器开关，0-关 1-开",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ntpserver_list": {
              "type": "string",
              "description": "自定义 NTP 服务器列表，最长253个字符，支持 IPv4/IPv6/域名",
              "maxLength": 253,
              "example": ""
            },
            "ntp_sync_cycle": {
              "type": "integer",
              "description": "NTP 同步间隔（分钟）",
              "minimum": 5,
              "maximum": 240,
              "example": 60
            },
            "link_mode": {
              "type": "integer",
              "description": "链路模式，0=主干模式，1=旁路模式，2=SDWAN 桥",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "lan_nat": {
              "type": "integer",
              "description": "路由模式(switch_nat=0)时是否启用 LAN 地址 NAT，0=关 1=开",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "backport": {
              "type": "string",
              "description": "旁路模式上网接口",
              "example": "wan1"
            },
            "listenport": {
              "type": "string",
              "description": "旁路模式监听接口",
              "example": "lan1"
            },
            "fast_nat": {
              "type": "integer",
              "description": "加速模式，0关闭，1开启软件模式，企业版功能，免费版设置不生效",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "system-basic",
        "x-displayName": "系统基础设置",
        "description": "系统基础设置配置管理，包括主机名、语言、时区、上网模式等"
      }
    ]
  },
  "system/system-cpufreq.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "CPU频率管理API",
      "version": "1.0.0",
      "summary": "CPU频率监控和管理的完整功能",
      "description": "提供CPU频率监控和管理的完整功能，包括：\n- CPU实时频率监控\n- CPU工作模式配置\n- 睿频模式控制\n- CPU使用率统计\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/cpufreq": {
        "get": {
          "summary": "获取CPU实时频率",
          "description": "获取所有CPU核心的实时频率信息、使用率、中断统计等数据。\n包含CPU ID、物理ID、核心ID、频率、使用率、软硬中断数等信息。\n",
          "operationId": "getCpuFrequency",
          "tags": [
            "cpu-freq-monitor"
          ],
          "responses": {
            "200": {
              "description": "成功获取CPU实时频率数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CpuFrequencyResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/cpufreq/mode": {
        "get": {
          "summary": "获取CPU工作模式",
          "description": "获取CPU的工作模式配置信息，包括当前调频模式、睿频状态、\n支持的模式列表等配置。\n",
          "operationId": "getCpuFrequencyMode",
          "tags": [
            "cpu-freq"
          ],
          "responses": {
            "200": {
              "description": "成功获取CPU工作模式",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CpuFrequencyModeResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "配置CPU工作模式",
          "description": "全量更新CPU工作模式配置。所有字段均为必填，即使未修改也必须携带原值。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateCpuFrequencyMode",
          "tags": [
            "cpu-freq"
          ],
          "requestBody": {
            "required": true,
            "description": "全量更新，所有字段必填，未修改的字段须传原值",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CpuFrequencyModeEditInput"
                },
                "example": {
                  "turbo": 1,
                  "mode": "performance"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "CPU工作模式配置更新成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CpuFrequencyResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "softirq_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CpuFrequencyData"
                  }
                }
              },
              "required": [
                "softirq_data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CpuFrequencyModeResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "cpufreq_support": {
                  "type": "integer",
                  "description": "是否支持调频，0为不支持，1为支持",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 1
                },
                "current_cpufreq": {
                  "type": "string",
                  "description": "当前的调频模式",
                  "enum": [
                    "off",
                    "conservative",
                    "ondemand",
                    "powersave",
                    "performance",
                    "schedutil"
                  ],
                  "example": "performance"
                },
                "current_turbo": {
                  "type": "integer",
                  "description": "当前的睿频模式，0为关闭，1为开启",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "cpufreq_list": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "off",
                      "conservative",
                      "ondemand",
                      "powersave",
                      "performance",
                      "schedutil"
                    ]
                  },
                  "description": "支持的调频模式列表",
                  "example": [
                    "conservative",
                    "ondemand",
                    "powersave",
                    "performance",
                    "schedutil"
                  ]
                },
                "turbo_support": {
                  "type": "integer",
                  "description": "是否支持睿频，0为不支持，1为支持",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                }
              },
              "required": [
                "cpufreq_support",
                "current_cpufreq",
                "current_turbo",
                "cpufreq_list",
                "turbo_support"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CpuFrequencyData": {
          "type": "object",
          "required": [
            "cpuid",
            "freq",
            "phyid",
            "coreid",
            "used",
            "softirq",
            "hardirq"
          ],
          "properties": {
            "cpuid": {
              "type": "string",
              "description": "CPU逻辑处理器ID",
              "example": "0"
            },
            "freq": {
              "type": "string",
              "description": "CPU频率（MHz）",
              "example": "2000"
            },
            "phyid": {
              "type": "string",
              "description": "物理CPU ID",
              "example": "0"
            },
            "coreid": {
              "type": "string",
              "description": "CPU核心ID",
              "example": "0"
            },
            "used": {
              "type": "string",
              "description": "CPU使用率百分比",
              "pattern": "^[0-9]+\\.[0-9]+%$",
              "example": "0.99%"
            },
            "softirq": {
              "type": "integer",
              "description": "软中断是否开启",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "hardirq": {
              "type": "integer",
              "description": "硬中断是否开启",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "CpuFrequencyModeEditInput": {
          "type": "object",
          "description": "CPU工作模式全量编辑。所有字段均为必填，未修改的字段须传原值。",
          "required": [
            "mode",
            "turbo"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "description": "CPU调频模式",
              "enum": [
                "off",
                "conservative",
                "ondemand",
                "powersave",
                "performance",
                "schedutil"
              ],
              "example": "performance"
            },
            "turbo": {
              "type": "integer",
              "description": "CPU睿频开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "cpu-freq-monitor",
        "x-displayName": "CPU频率监控",
        "description": "CPU实时频率、使用率和中断统计信息监控"
      },
      {
        "name": "cpu-freq",
        "x-displayName": "CPU频率管理",
        "description": "CPU工作模式和睿频配置管理"
      }
    ]
  },
  "system/system-disks.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统磁盘信息API",
      "version": "1.0.0",
      "summary": "查询系统磁盘、分区、文件系统与挂载信息",
      "description": "提供系统磁盘信息查询能力，包括：\n- 磁盘基础信息\n- 分区列表\n- 文件系统信息\n- 挂载用途与容量使用情况\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/disks": {
        "get": {
          "summary": "获取系统磁盘信息",
          "description": "获取当前系统的磁盘列表，以及每块磁盘下的分区、文件系统和挂载信息。\n",
          "operationId": "getSystemDisks",
          "tags": [
            "system-disks"
          ],
          "responses": {
            "200": {
              "description": "成功获取系统磁盘信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemDiskListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "type": "dos",
                          "disk": "sda",
                          "system": 0,
                          "block_size": 512,
                          "creating": 0,
                          "partition": [
                            {
                              "name": "sda1",
                              "type": 0,
                              "filesys": {
                                "fs_uuid": "b2f90854-8616-4c83-953f-caf8dfdf6866",
                                "fs_type": "ext4"
                              },
                              "size": 249108103168,
                              "mounted": {
                                "mt_purpose": "0",
                                "mt_total": "244062085120",
                                "mt_name": "",
                                "mt_used": "28672",
                                "mt_uses": "0",
                                "mt_avail": "231589875712"
                              },
                              "formating": 0
                            },
                            {
                              "name": "sda2",
                              "type": 0,
                              "filesys": {
                                "fs_uuid": "6b32b2eb-e04a-4020-aef6-6d4f3a2a03fa",
                                "fs_type": "ext4"
                              },
                              "size": 249108103168,
                              "mounted": {
                                "mt_purpose": "4",
                                "mt_total": "244062085120",
                                "mt_name": "",
                                "mt_used": "98304",
                                "mt_uses": "0",
                                "mt_avail": "231589806080"
                              },
                              "formating": 0
                            },
                            {
                              "name": "sda3",
                              "type": 0,
                              "filesys": {
                                "fs_uuid": "d31a6f82-ea6c-4c9c-a851-0e4a25d926fb",
                                "fs_type": "ext4"
                              },
                              "size": 249108103168,
                              "mounted": {
                                "mt_purpose": "1",
                                "mt_total": "244062085120",
                                "mt_name": "test-001",
                                "mt_used": "36864",
                                "mt_uses": "0",
                                "mt_avail": "231589867520"
                              },
                              "formating": 0
                            },
                            {
                              "name": "sda4",
                              "type": 0,
                              "filesys": {
                                "fs_uuid": "775cd0cb-f55e-40cc-ab2b-136f540bddab",
                                "fs_type": "ext4"
                              },
                              "size": 252879527936,
                              "mounted": {
                                "mt_purpose": "1",
                                "mt_total": "247772393472",
                                "mt_name": "test-002",
                                "mt_used": "28672",
                                "mt_uses": "0",
                                "mt_avail": "235111612416"
                              },
                              "formating": 0
                            }
                          ],
                          "model": "WDC  WDS100T2B0A",
                          "size": 1000204886016
                        },
                        {
                          "type": "dos",
                          "disk": "sdb",
                          "system": 1,
                          "block_size": 512,
                          "creating": 0,
                          "partition": [
                            {
                              "name": "sdb3",
                              "type": 0,
                              "filesys": {
                                "fs_uuid": "4cfe26af-180a-4692-8a96-50f3e6e70cbd",
                                "fs_type": "ext4"
                              },
                              "size": 52428800,
                              "mounted": {
                                "mt_purpose": "0",
                                "mt_total": "45520896",
                                "mt_name": "",
                                "mt_used": "1635328",
                                "mt_uses": "4",
                                "mt_avail": "40215552"
                              },
                              "formating": 0
                            },
                            {
                              "name": "sdb5",
                              "type": 2,
                              "filesys": {
                                "fs_uuid": "ff13e131-8192-4c49-a027-5ef217c2e277",
                                "fs_type": "ext4"
                              },
                              "size": 3899416576,
                              "mounted": {
                                "mt_purpose": "0",
                                "mt_total": "3755843584",
                                "mt_name": "",
                                "mt_used": "123707392",
                                "mt_uses": "3",
                                "mt_avail": "3420389376"
                              },
                              "formating": 0
                            }
                          ],
                          "model": "SanDisk SSD P4 4",
                          "size": 4011614208
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误状态码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求参数错误"
            }
          },
          "additionalProperties": false
        },
        "SystemDiskFilesystem": {
          "type": "object",
          "required": [
            "fs_uuid",
            "fs_type"
          ],
          "properties": {
            "fs_uuid": {
              "type": "string",
              "description": "文件系统 UUID",
              "example": "b2f90854-8616-4c83-953f-caf8dfdf6866"
            },
            "fs_type": {
              "type": "string",
              "description": "文件系统类型",
              "example": "ext4"
            }
          },
          "additionalProperties": false
        },
        "SystemDiskMountInfo": {
          "type": "object",
          "required": [
            "mt_purpose",
            "mt_total",
            "mt_name",
            "mt_used",
            "mt_uses",
            "mt_avail"
          ],
          "properties": {
            "mt_purpose": {
              "type": "string",
              "description": "挂载分区用途，`0` 未使用，`1` 普通存储，`2` 有余繁星，`3` 视频缓存，`4` 行为记录",
              "enum": [
                "0",
                "1",
                "2",
                "3",
                "4"
              ],
              "example": "0"
            },
            "mt_total": {
              "type": "string",
              "description": "分区总容量，单位 B",
              "example": "244062085120"
            },
            "mt_name": {
              "type": "string",
              "description": "挂载名称",
              "example": ""
            },
            "mt_used": {
              "type": "string",
              "description": "已使用容量，单位 B",
              "example": "28672"
            },
            "mt_uses": {
              "type": "string",
              "description": "使用率",
              "example": "0"
            },
            "mt_avail": {
              "type": "string",
              "description": "可用容量，单位 B",
              "example": "231589875712"
            }
          },
          "additionalProperties": false
        },
        "SystemDiskPartition": {
          "type": "object",
          "required": [
            "name",
            "type",
            "filesys",
            "size",
            "mounted",
            "formating"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "分区名称",
              "example": "sda1"
            },
            "type": {
              "type": "integer",
              "description": "分区类型，`0` 主分区，`1` 扩展分区，`2` 逻辑分区",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "filesys": {
              "$ref": "#/components/schemas/SystemDiskFilesystem"
            },
            "size": {
              "type": "integer",
              "format": "int64",
              "description": "分区大小，单位 B",
              "example": 249108103168
            },
            "mounted": {
              "$ref": "#/components/schemas/SystemDiskMountInfo"
            },
            "formating": {
              "type": "integer",
              "description": "分区是否正在格式化，`0` 否，`1` 是",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "SystemDiskDevice": {
          "type": "object",
          "required": [
            "type",
            "disk",
            "system",
            "block_size",
            "creating",
            "partition",
            "model",
            "size"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "磁盘分区表类型",
              "example": "dos"
            },
            "disk": {
              "type": "string",
              "description": "磁盘名，如 `sda`、`sdb`、`nda`、`mda`",
              "example": "sda"
            },
            "system": {
              "type": "integer",
              "description": "是否为系统磁盘，`0` 否，`1` 是",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "block_size": {
              "type": "integer",
              "description": "块大小",
              "example": 512
            },
            "creating": {
              "type": "integer",
              "description": "是否正在创建分区，`0` 否，`1` 是",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "partition": {
              "type": "array",
              "description": "分区列表",
              "items": {
                "$ref": "#/components/schemas/SystemDiskPartition"
              }
            },
            "model": {
              "type": "string",
              "description": "硬盘型号",
              "example": "WDC  WDS100T2B0A"
            },
            "size": {
              "type": "integer",
              "format": "int64",
              "description": "磁盘总大小，单位 B",
              "example": 1000204886016
            }
          },
          "additionalProperties": false
        },
        "SystemDiskListResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "results"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码，`0` 表示成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "data"
              ],
              "properties": {
                "data": {
                  "type": "array",
                  "description": "磁盘列表",
                  "items": {
                    "$ref": "#/components/schemas/SystemDiskDevice"
                  }
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用 JWT Bearer Token 进行认证。\n在请求头中添加：Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "system-disks",
        "x-displayName": "系统磁盘信息",
        "description": "查询系统磁盘、分区、文件系统与挂载使用情况"
      }
    ]
  },
  "system/system-files.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统文件管理API",
      "version": "1.0.0",
      "summary": "查询文件存储根目录与指定路径下的文件列表",
      "description": "提供文件管理查询能力，包括：\n- 查询系统中可用的文件存储根目录\n- 查询指定路径下的文件与目录列表\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/files": {
        "get": {
          "summary": "获取文件列表",
          "description": "根据 `path` 查询文件列表。\n\n常见用法：\n- `path=/`：获取系统中可用的文件存储根目录\n- `path=/test-001`：获取指定目录下的文件和子目录列表\n",
          "operationId": "getSystemFiles",
          "tags": [
            "system-files"
          ],
          "parameters": [
            {
              "name": "path",
              "in": "query",
              "required": true,
              "description": "要查询的文件路径",
              "schema": {
                "type": "string",
                "example": "/"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取文件列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemFileListResponse"
                  },
                  "examples": {
                    "storageRoots": {
                      "summary": "查询可用存储根目录",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "results": {
                          "data": [
                            {
                              "f_name": "test-001",
                              "st_mtime": 1776158091,
                              "st_type": 0,
                              "st_size": 244062085120,
                              "st_inode": 2
                            },
                            {
                              "f_name": "test-002",
                              "st_mtime": 1770200504,
                              "st_type": 0,
                              "st_size": 247772393472,
                              "st_inode": 2
                            }
                          ]
                        }
                      }
                    },
                    "directoryEntries": {
                      "summary": "查询指定目录下的文件与目录",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "results": {
                          "data": [
                            {
                              "st_size": 4096,
                              "st_inode": 12582913,
                              "f_name": "a",
                              "st_mtime": 1776158048,
                              "st_type": 1
                            },
                            {
                              "st_size": 6,
                              "st_inode": 12,
                              "f_name": "example",
                              "st_mtime": 1776158104,
                              "st_type": 2
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误状态码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求参数错误"
            }
          },
          "additionalProperties": false
        },
        "SystemFileEntry": {
          "type": "object",
          "required": [
            "f_name",
            "st_mtime",
            "st_type",
            "st_size",
            "st_inode"
          ],
          "properties": {
            "f_name": {
              "type": "string",
              "description": "文件或文件夹名称",
              "example": "test-001"
            },
            "st_mtime": {
              "type": "integer",
              "format": "int64",
              "description": "修改时间，Unix 时间戳",
              "example": 1776158091
            },
            "st_type": {
              "type": "integer",
              "description": "文件类型，`-1` 未知，`0` 磁盘，`1` 目录，`2` 文件，`3` 链接",
              "enum": [
                -1,
                0,
                1,
                2,
                3
              ],
              "example": 0
            },
            "st_size": {
              "type": "integer",
              "format": "int64",
              "description": "文件大小，单位 Byte",
              "example": 244062085120
            },
            "st_inode": {
              "type": "integer",
              "format": "int64",
              "description": "文件 inode 值",
              "example": 2
            }
          },
          "additionalProperties": false
        },
        "SystemFileListResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "results"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码，`0` 表示成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "data"
              ],
              "properties": {
                "data": {
                  "type": "array",
                  "description": "文件或目录列表",
                  "items": {
                    "$ref": "#/components/schemas/SystemFileEntry"
                  }
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用 JWT Bearer Token 进行认证。\n在请求头中添加：Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "system-files",
        "x-displayName": "系统文件管理",
        "description": "查询可用存储根目录与指定路径下的文件列表"
      }
    ]
  },
  "system/system-kernel-params.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "内核参数配置API",
      "version": "1.0.0",
      "summary": "内核网络参数的完整管理功能",
      "description": "提供内核网络参数的完整管理功能，包括：\n- BBR拥塞控制算法配置\n- TCP连接各阶段超时参数配置\n- UDP数据包超时参数配置\n- ICMP数据包超时参数配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/kernel-params": {
        "get": {
          "summary": "获取内核参数配置",
          "description": "获取当前内核网络参数配置，包括BBR、TCP/UDP/ICMP各超时时间。",
          "operationId": "getKernelParams",
          "tags": [
            "kernel-params"
          ],
          "responses": {
            "200": {
              "description": "成功获取内核参数配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/KernelParamsResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "bbr": 0,
                          "syn_recv_timeout": 5,
                          "syn_send_timeout": 5,
                          "established_timeout": 1800,
                          "fin_wait_timeout": 10,
                          "last_ack_timeout": 10,
                          "close_wait_timeout": 10,
                          "time_wait_timeout": 10,
                          "close_timeout": 5,
                          "udp_timeout": 10,
                          "udp_stream_timeout": 60,
                          "icmp_timeout": 10
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新内核参数配置",
          "description": "全量更新内核网络参数配置。所有字段均为必填，即使未修改也必须携带原值。",
          "operationId": "updateKernelParams",
          "tags": [
            "kernel-params"
          ],
          "requestBody": {
            "required": true,
            "description": "全量更新，所有字段必填，未修改的字段须传原值",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KernelParamsEditInput"
                },
                "example": {
                  "bbr": 0,
                  "syn_recv_timeout": 5,
                  "syn_send_timeout": 5,
                  "established_timeout": 1800,
                  "fin_wait_timeout": 10,
                  "last_ack_timeout": 10,
                  "close_wait_timeout": 10,
                  "time_wait_timeout": 10,
                  "close_timeout": 5,
                  "udp_timeout": 10,
                  "udp_stream_timeout": 60,
                  "icmp_timeout": 10
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "KernelParams": {
          "type": "object",
          "required": [
            "id",
            "bbr",
            "syn_recv_timeout",
            "syn_send_timeout",
            "established_timeout",
            "fin_wait_timeout",
            "last_ack_timeout",
            "close_wait_timeout",
            "time_wait_timeout",
            "close_timeout",
            "udp_timeout",
            "udp_stream_timeout",
            "icmp_timeout"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "bbr": {
              "type": "integer",
              "description": "BBR拥塞控制算法（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "syn_recv_timeout": {
              "type": "integer",
              "description": "SYN_RECV状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 5,
              "example": 5
            },
            "syn_send_timeout": {
              "type": "integer",
              "description": "SYN_SEND状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 5,
              "example": 5
            },
            "established_timeout": {
              "type": "integer",
              "description": "ESTABLISHED状态超时时间（秒）",
              "minimum": 600,
              "maximum": 86400,
              "default": 1800,
              "example": 1800
            },
            "fin_wait_timeout": {
              "type": "integer",
              "description": "FIN_WAIT状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "last_ack_timeout": {
              "type": "integer",
              "description": "LAST_ACK状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "close_wait_timeout": {
              "type": "integer",
              "description": "CLOSE_WAIT状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "time_wait_timeout": {
              "type": "integer",
              "description": "TIME_WAIT状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "close_timeout": {
              "type": "integer",
              "description": "CLOSE状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 5,
              "example": 5
            },
            "udp_timeout": {
              "type": "integer",
              "description": "UDP数据包超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "udp_stream_timeout": {
              "type": "integer",
              "description": "UDP流超时时间（秒）",
              "minimum": 30,
              "maximum": 1800,
              "default": 60,
              "example": 60
            },
            "icmp_timeout": {
              "type": "integer",
              "description": "ICMP数据包超时时间（秒）",
              "minimum": 5,
              "maximum": 100,
              "default": 10,
              "example": 10
            }
          },
          "additionalProperties": false
        },
        "KernelParamsEditInput": {
          "type": "object",
          "description": "内核参数全量编辑。所有字段均为必填，未修改的字段须传原值。",
          "required": [
            "bbr",
            "syn_recv_timeout",
            "syn_send_timeout",
            "established_timeout",
            "fin_wait_timeout",
            "last_ack_timeout",
            "close_wait_timeout",
            "time_wait_timeout",
            "close_timeout",
            "udp_timeout",
            "udp_stream_timeout",
            "icmp_timeout"
          ],
          "properties": {
            "bbr": {
              "type": "integer",
              "description": "BBR拥塞控制算法（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "syn_recv_timeout": {
              "type": "integer",
              "description": "SYN_RECV状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 5
            },
            "syn_send_timeout": {
              "type": "integer",
              "description": "SYN_SEND状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 5
            },
            "established_timeout": {
              "type": "integer",
              "description": "ESTABLISHED状态超时时间（秒）",
              "minimum": 600,
              "maximum": 86400,
              "example": 1800
            },
            "fin_wait_timeout": {
              "type": "integer",
              "description": "FIN_WAIT状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 10
            },
            "last_ack_timeout": {
              "type": "integer",
              "description": "LAST_ACK状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 10
            },
            "close_wait_timeout": {
              "type": "integer",
              "description": "CLOSE_WAIT状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 10
            },
            "time_wait_timeout": {
              "type": "integer",
              "description": "TIME_WAIT状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 10
            },
            "close_timeout": {
              "type": "integer",
              "description": "CLOSE状态超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 5
            },
            "udp_timeout": {
              "type": "integer",
              "description": "UDP数据包超时时间（秒）",
              "minimum": 5,
              "maximum": 60,
              "example": 10
            },
            "udp_stream_timeout": {
              "type": "integer",
              "description": "UDP流超时时间（秒）",
              "minimum": 30,
              "maximum": 1800,
              "example": 60
            },
            "icmp_timeout": {
              "type": "integer",
              "description": "ICMP数据包超时时间（秒）",
              "minimum": 5,
              "maximum": 100,
              "example": 10
            }
          },
          "additionalProperties": false
        },
        "KernelParamsResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/KernelParams"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "kernel-params",
        "x-displayName": "内核参数配置",
        "description": "内核网络参数配置管理，包括TCP超时、UDP超时、ICMP超时和BBR拥塞控制"
      }
    ]
  },
  "system/system-reboots.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统重启计划管理API",
      "version": "1.0.0",
      "summary": "系统重启计划的完整管理功能",
      "description": "提供系统重启计划的完整管理功能，包括：\n- 重启计划的创建、更新、删除\n- 重启计划的启用、停用控制\n- 支持一次性、每周、每月等多种周期策略\n- 重启和关机两种事件类型\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/reboot-schedules": {
        "get": {
          "summary": "获取重启计划列表",
          "description": "获取当前配置的所有重启计划列表，支持分页功能。\n包含计划状态、事件类型、周期策略、执行时间等信息。\n",
          "operationId": "listRebootSchedules",
          "tags": [
            "reboots"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取重启计划列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/RebootScheduleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加重启计划",
          "description": "添加新的重启计划，指定计划事件（重启/关机）、周期策略、\n执行时间和备注信息。支持一次性、每周、每月三种周期类型。\n",
          "operationId": "createRebootSchedule",
          "tags": [
            "reboots"
          ],
          "requestBody": {
            "required": true,
            "description": "重启计划配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RebootScheduleInput"
                },
                "example": {
                  "enabled": "yes",
                  "event": "reboot",
                  "strategy": "week",
                  "cycle_time": "7",
                  "time": "00:00",
                  "comment": "每周日重启计划"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/RebootScheduleErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/RebootScheduleErrorResponse"
                  },
                  "example": {
                    "message": "重启计划时间冲突"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/reboot-schedules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/rebootScheduleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定重启计划",
          "description": "根据计划ID获取单个重启计划的详细信息。\n",
          "operationId": "getRebootSchedule",
          "tags": [
            "reboots"
          ],
          "responses": {
            "200": {
              "description": "成功获取重启计划详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/RebootScheduleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新重启计划",
          "description": "完全更新现有的重启计划配置。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateRebootSchedule",
          "tags": [
            "reboots"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的重启计划配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RebootScheduleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用重启计划",
          "description": "部分更新重启计划配置，主要用于启用/停用计划状态。\n支持修改enabled字段来控制计划的执行状态。\n",
          "operationId": "patchRebootSchedule",
          "tags": [
            "reboots"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "计划启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除重启计划",
          "description": "删除指定的重启计划。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteRebootSchedule",
          "tags": [
            "reboots"
          ],
          "responses": {
            "200": {
              "description": "重启计划删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "rebootScheduleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "重启计划ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、time、strategy等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "RebootScheduleErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "重启计划业务错误信息描述"
            }
          }
        },
        "RebootScheduleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RebootSchedule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "RebootScheduleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RebootSchedule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "RebootSchedule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "event",
            "strategy",
            "cycle_time",
            "time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "计划ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 15,
              "example": "每周日重启"
            },
            "event": {
              "type": "string",
              "enum": [
                "reboot",
                "poweroff"
              ],
              "description": "计划事件，reboot为重启，poweroff为关机",
              "example": "reboot"
            },
            "strategy": {
              "type": "string",
              "enum": [
                "one",
                "day",
                "week",
                "month"
              ],
              "description": "计划周期：\n- one: 一次性执行\n- day: 每天执行\n- week: 每周执行\n- month: 每月执行\n",
              "example": "week"
            },
            "cycle_time": {
              "type": "string",
              "description": "计划日期，根据strategy字段有不同的含义：\n- strategy=one: 日期格式 YYYY-MM-DD\n- strategy=week: 星期数字(1-7)或字符串\"all\"表示每天\n- strategy=month: 月份中的日期数字(1-31)\n",
              "pattern": "^([0-9]{4}-[0-9]{2}-[0-9]{2}|[1-7]|all|[1-9]|[1-2][0-9]|3[0-1])$",
              "example": "7"
            },
            "time": {
              "type": "string",
              "description": "计划时间，格式为HH:MM",
              "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$",
              "example": "00:00"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "RebootScheduleInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "event",
            "strategy",
            "cycle_time",
            "time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "状态，yes为启用，no为停用",
              "example": "yes"
            },
            "event": {
              "type": "string",
              "enum": [
                "reboot",
                "poweroff"
              ],
              "description": "计划事件，reboot为重启，poweroff为关机",
              "example": "reboot"
            },
            "strategy": {
              "type": "string",
              "enum": [
                "one",
                "day",
                "week",
                "month"
              ],
              "description": "计划周期：\n- one: 一次性执行\n- day: 每天执行\n- week: 每周执行\n- month: 每月执行\n",
              "example": "week"
            },
            "cycle_time": {
              "type": "string",
              "description": "计划日期，根据strategy字段有不同的含义：\n- strategy=one: 日期格式 YYYY-MM-DD\n- strategy=week: 星期数字(1-7)或字符串\"all\"表示每天\n- strategy=month: 月份中的日期数字(1-31)\n",
              "pattern": "^([0-9]{4}-[0-9]{2}-[0-9]{2}|[1-7]|all|[1-9]|[1-2][0-9]|3[0-1])$",
              "example": "7"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 15,
              "example": "每周日重启"
            },
            "time": {
              "type": "string",
              "description": "计划时间，格式为HH:MM",
              "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$",
              "example": "00:00"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "reboots",
        "x-displayName": "重启计划管理",
        "description": "系统重启计划的管理，支持创建、更新、删除和启用/停用操作"
      }
    ]
  },
  "system/system-remote-access.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "远程访问配置API",
      "version": "1.0.0",
      "summary": "远程访问服务的完整管理功能",
      "description": "提供远程访问服务的完整管理功能，包括：\n- Telnet服务配置\n- SSH服务配置和端口管理\n- Web管理端口配置\n- 外网访问Web管理控制\n- HTTPS强制跳转配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/remote-access": {
        "get": {
          "summary": "获取远程访问配置",
          "description": "获取当前远程访问服务的配置信息，包括Telnet、SSH服务状态、\nWeb管理端口设置、外网访问权限、HTTPS强制跳转等配置。\n",
          "operationId": "getRemoteAccessConfig",
          "tags": [
            "remote-access"
          ],
          "responses": {
            "200": {
              "description": "成功获取远程访问配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/RemoteAccessConfigResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新远程访问配置",
          "description": "更新远程访问服务的配置信息，包括Telnet和SSH服务的启用状态、\n端口配置、Web管理端口设置、外网访问权限、HTTPS强制跳转等。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateRemoteAccessConfig",
          "tags": [
            "remote-access"
          ],
          "requestBody": {
            "required": true,
            "description": "远程访问配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RemoteAccessConfigInput"
                },
                "example": {
                  "open_telnetd": 0,
                  "open_wanweb": 1,
                  "open_sshd": 1,
                  "sshd_port": 22,
                  "sshd_passwd": "ikuai8.com",
                  "http_port": 80,
                  "https_port": 443,
                  "force_https": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "RemoteAccessConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RemoteAccessConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "RemoteAccessConfig": {
          "type": "object",
          "required": [
            "id",
            "open_telnetd",
            "open_wanweb",
            "open_sshd",
            "sshd_port",
            "sshd_passwd",
            "open_ftp",
            "ftp_port",
            "ftp_access",
            "http_port",
            "https_port",
            "force_https"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "open_telnetd": {
              "type": "integer",
              "description": "开启telnetd服务，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "open_wanweb": {
              "type": "integer",
              "description": "外网访问web管理权限，0为不允许访问，1为都允许，2为允许ipv4，3为允许ipv6",
              "enum": [
                0,
                1,
                2,
                3
              ],
              "default": 0,
              "example": 1
            },
            "open_sshd": {
              "type": "integer",
              "description": "开启SSHD服务，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "sshd_port": {
              "type": "integer",
              "description": "SSHD服务端口，0表示关闭。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 0,
              "maximum": 65535,
              "default": 22,
              "example": 22
            },
            "sshd_passwd": {
              "type": "string",
              "description": "SSHD登录密码",
              "minLength": 6,
              "maxLength": 64,
              "example": "ikuai8.com"
            },
            "open_ftp": {
              "type": "integer",
              "description": "FTP服务开关，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "ftp_port": {
              "type": "integer",
              "description": "FTP服务端口。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 10,
              "maximum": 65535,
              "default": 21,
              "example": 21
            },
            "ftp_access": {
              "type": "integer",
              "description": "是否允许外网访问FTP，0为不允许，1为允许",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "http_port": {
              "type": "integer",
              "description": "HTTP管理端口，0表示关闭HTTP。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 0,
              "maximum": 65535,
              "default": 80,
              "example": 80
            },
            "https_port": {
              "type": "integer",
              "description": "HTTPS管理端口，0表示关闭HTTPS。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 0,
              "maximum": 65535,
              "default": 443,
              "example": 443
            },
            "force_https": {
              "type": "integer",
              "description": "强制使用HTTPS访问，访问HTTP时强制跳转HTTPS，0为不强制，1为强制",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "RemoteAccessConfigInput": {
          "type": "object",
          "required": [
            "open_telnetd",
            "open_wanweb",
            "open_sshd",
            "sshd_port",
            "sshd_passwd",
            "http_port",
            "https_port",
            "force_https"
          ],
          "properties": {
            "open_telnetd": {
              "type": "integer",
              "description": "开启telnetd服务，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "open_wanweb": {
              "type": "integer",
              "description": "外网访问web管理权限，0为不允许访问，1为都允许，2为允许ipv4，3为允许ipv6",
              "enum": [
                0,
                1,
                2,
                3
              ],
              "default": 0,
              "example": 1
            },
            "open_sshd": {
              "type": "integer",
              "description": "开启SSHD服务，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "sshd_port": {
              "type": "integer",
              "description": "SSHD服务端口，0表示关闭。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 0,
              "maximum": 65535,
              "default": 22,
              "example": 22
            },
            "sshd_passwd": {
              "type": "string",
              "description": "SSHD登录密码",
              "minLength": 6,
              "maxLength": 64,
              "example": "ikuai8.com"
            },
            "http_port": {
              "type": "integer",
              "description": "HTTP管理端口，0表示关闭HTTP。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 0,
              "maximum": 65535,
              "default": 80,
              "example": 80
            },
            "https_port": {
              "type": "integer",
              "description": "HTTPS管理端口，0表示关闭HTTPS。允许范围10-599和800-65535，排除1234-1241、12345、34567",
              "minimum": 0,
              "maximum": 65535,
              "default": 443,
              "example": 443
            },
            "force_https": {
              "type": "integer",
              "description": "强制使用HTTPS访问，访问HTTP时强制跳转HTTPS，0为不强制，1为强制",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "remote-access",
        "x-displayName": "远程访问配置",
        "description": "远程访问服务配置管理，包括Telnet、SSH、Web管理端口和外网访问权限"
      }
    ]
  },
  "system/system-upgrade.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统固件升级API",
      "version": "1.0.0",
      "summary": "系统固件版本检测、信息查询及升级流程管理",
      "description": "提供系统固件升级的完整流程，按以下顺序调用：\n\n1. **版本检测** — 触发向云端检测是否有新版本\n2. **获取版本信息** — 查询当前版本与最新版本信息\n3. **立即升级** — 触发固件下载并安装\n4. **获取升级状态** — 轮询升级进度与结果\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/upgrade:check": {
        "post": {
          "summary": "版本检测",
          "description": "向云端发起版本检测请求，拉取最新版本信息并缓存到本地。无需请求体。\n\n检测完成后，调用「获取版本信息」接口获取最新版本详情。\n",
          "operationId": "checkUpgradeVersion",
          "tags": [
            "upgrade"
          ],
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：检测请求已发起\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "firmware_channel",
                            "type": "unsupported",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/upgrade": {
        "get": {
          "summary": "获取版本信息",
          "description": "查询当前固件版本与云端最新版本信息，用于判断是否需要升级。\n\n`new_system_ver` 为空或与 `system_ver` 相同时表示已是最新版本。\n",
          "operationId": "getUpgradeInfo",
          "tags": [
            "upgrade"
          ],
          "responses": {
            "200": {
              "description": "成功获取版本信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpgradeInfoResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": {
                        "auto_upgrade_lib_dpi": 1,
                        "auto_upgrade_lib_im": 1,
                        "auto_upgrade_lib_domain": 1,
                        "auto_upgrade_sec": 1,
                        "libproto_ver": "3.0.8",
                        "libaudit_ver": "3.0.1",
                        "libdomain_ver": "2.1.0",
                        "system_ver": "4.0.200",
                        "version_type": "alpha",
                        "build_date": "202604081742",
                        "new_libproto_ver": "3.0.8",
                        "new_libaudit_ver": "3.0.1",
                        "new_libdomain_ver": "2.1.0",
                        "new_system_ver": "3.7.21",
                        "new_build_date": "202509221910",
                        "update_content": "修复：\n1. 内外网设置：部分环境网卡无法显示的bug\n2. 系统概况：MLO开启时，AC状态中2.4G和5G终端连接数错误\n",
                        "ignore_upgrade_ver": "",
                        "bootguide": "flash",
                        "firmware_channel": 0
                      }
                    }
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/upgrade:start": {
        "post": {
          "summary": "立即升级",
          "description": "触发系统固件升级，从云端下载最新固件并安装。升级过程为后台异步执行。\n\n请求体必须传入 `type`，且值固定为 `system`。\n\n触发后请轮询「获取升级状态」接口跟踪进度。\n",
          "operationId": "startUpgrade",
          "tags": [
            "upgrade"
          ],
          "requestBody": {
            "required": true,
            "description": "升级请求参数",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartUpgradeRequest"
                },
                "example": {
                  "type": "system"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：升级任务已触发\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "new_system_ver",
                            "type": "missing",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/upgrade:status": {
        "get": {
          "summary": "获取升级状态",
          "description": "查询当前固件升级任务的执行状态与进度。\n\n**`status` 状态码说明：**\n- `0`：无升级任务（空闲或升级成功完成）\n- `1`：正在下载固件（`status_msg` 包含下载进度百分比）\n- `2`：正在安装固件\n- `-1`：固件信息获取失败\n- `-2`：固件下载失败\n- `-3`：固件文件解析失败\n- `-4`：固件安装失败\n\n**轮询建议：** 每 2 秒轮询一次，直到 `status <= 0` 为止。\n",
          "operationId": "getUpgradeStatus",
          "tags": [
            "upgrade"
          ],
          "responses": {
            "200": {
              "description": "成功获取升级状态",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpgradeStatusResponse"
                  },
                  "examples": {
                    "idle": {
                      "summary": "空闲",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "results": {
                          "auto_upgrade": {
                            "status": 0,
                            "status_msg": ""
                          }
                        }
                      }
                    },
                    "downloading": {
                      "summary": "正在下载",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "results": {
                          "auto_upgrade": {
                            "status": 1,
                            "status_msg": "正在下载 45%"
                          }
                        }
                      }
                    },
                    "installing": {
                      "summary": "正在安装",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "results": {
                          "auto_upgrade": {
                            "status": 2,
                            "status_msg": "正在升级固件"
                          }
                        }
                      }
                    },
                    "failed": {
                      "summary": "下载失败",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "results": {
                          "auto_upgrade": {
                            "status": -2,
                            "status_msg": "下载失败，请检查网络连接"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "required": [
            "field",
            "type",
            "msg"
          ],
          "additionalProperties": false
        },
        "StartUpgradeRequest": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "description": "升级类型，固定传 `system`",
              "const": "system",
              "example": "system"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        "UpgradeInfoResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/UpgradeInfoResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpgradeInfoResults": {
          "type": "object",
          "properties": {
            "data": {
              "$ref": "#/components/schemas/UpgradeInfo"
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "UpgradeInfo": {
          "type": "object",
          "properties": {
            "auto_upgrade_lib_dpi": {
              "type": "integer",
              "description": "DPI 特征库自动升级开关，1=开启，0=关闭",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "auto_upgrade_lib_im": {
              "type": "integer",
              "description": "即时通讯特征库自动升级开关，1=开启，0=关闭",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "auto_upgrade_lib_domain": {
              "type": "integer",
              "description": "域名特征库自动升级开关，1=开启，0=关闭",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "auto_upgrade_sec": {
              "type": "integer",
              "description": "安全规则自动升级开关，1=开启，0=关闭",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "libproto_ver": {
              "type": "string",
              "description": "当前协议特征库版本",
              "example": "3.0.8"
            },
            "libaudit_ver": {
              "type": "string",
              "description": "当前审计特征库版本",
              "example": "3.0.1"
            },
            "libdomain_ver": {
              "type": "string",
              "description": "当前域名特征库版本",
              "example": "2.1.0"
            },
            "system_ver": {
              "type": "string",
              "description": "当前系统固件版本号",
              "example": "4.0.200"
            },
            "build_date": {
              "type": "string",
              "description": "当前固件编译日期，格式 YYYYMMDDHHmm",
              "example": "202604081742"
            },
            "version_type": {
              "type": "string",
              "description": "当前版本类型（如 release、beta、alpha）",
              "example": "alpha"
            },
            "new_libproto_ver": {
              "type": "string",
              "description": "可升级的协议特征库版本，无新版本时为空字符串",
              "example": "3.0.8"
            },
            "new_libaudit_ver": {
              "type": "string",
              "description": "可升级的审计特征库版本，无新版本时为空字符串",
              "example": "3.0.1"
            },
            "new_libdomain_ver": {
              "type": "string",
              "description": "可升级的域名特征库版本，无新版本时为空字符串",
              "example": "2.1.0"
            },
            "new_system_ver": {
              "type": "string",
              "description": "最新系统固件版本号，无新版本时为空字符串",
              "example": "3.7.21"
            },
            "new_build_date": {
              "type": "string",
              "description": "最新固件编译日期，格式 YYYYMMDDHHmm，无新版本时为空字符串",
              "example": "202509221910"
            },
            "update_content": {
              "type": "string",
              "description": "最新版本更新说明，无新版本时为空字符串",
              "example": "修复：\n1. 内外网设置：部分环境网卡无法显示的bug"
            },
            "ignore_upgrade_ver": {
              "type": "string",
              "description": "忽略升级的版本号，未设置时为空字符串",
              "example": ""
            },
            "bootguide": {
              "type": "string",
              "description": "升级引导方式",
              "example": "flash"
            },
            "firmware_channel": {
              "type": "integer",
              "description": "固件渠道：0=正式版，1=体验版，2=Alpha版",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            }
          },
          "required": [
            "auto_upgrade_lib_dpi",
            "auto_upgrade_lib_im",
            "auto_upgrade_lib_domain",
            "auto_upgrade_sec",
            "libproto_ver",
            "libaudit_ver",
            "libdomain_ver",
            "system_ver",
            "build_date",
            "version_type",
            "new_libproto_ver",
            "new_libaudit_ver",
            "new_libdomain_ver",
            "new_system_ver",
            "new_build_date",
            "update_content",
            "ignore_upgrade_ver",
            "bootguide",
            "firmware_channel"
          ],
          "additionalProperties": false
        },
        "UpgradeStatusResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/UpgradeStatusResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpgradeStatusResults": {
          "type": "object",
          "properties": {
            "auto_upgrade": {
              "$ref": "#/components/schemas/UpgradeStatus"
            }
          },
          "required": [
            "auto_upgrade"
          ],
          "additionalProperties": false
        },
        "UpgradeStatus": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "description": "升级状态码：\n- `0`：空闲 / 升级成功完成\n- `1`：正在下载固件\n- `2`：正在安装固件\n- `-1`：固件信息获取失败\n- `-2`：固件下载失败\n- `-3`：固件文件解析失败\n- `-4`：固件安装失败\n",
              "enum": [
                0,
                1,
                2,
                -1,
                -2,
                -3,
                -4
              ],
              "example": 0
            },
            "status_msg": {
              "type": "string",
              "description": "状态描述信息；status=1 时包含下载进度（如 '正在下载 45%'）；失败时包含错误信息",
              "example": ""
            }
          },
          "required": [
            "status",
            "status_msg"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "upgrade",
        "x-displayName": "系统升级",
        "description": "固件版本检测、信息查询与升级流程管理"
      }
    ]
  },
  "system/system-vrrp.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "VRRP热备管理API",
      "version": "1.0.0",
      "summary": "VRRP热备的完整管理功能",
      "description": "提供VRRP热备的完整管理功能，包括：\n- 热备配置管理\n- 热备服务启停控制\n- 主从模式设置\n- 心跳接口配置\n- 虚拟IP管理\n- 配置同步控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/vrrp/config": {
        "get": {
          "summary": "获取热备配置",
          "description": "获取当前VRRP热备的配置信息，包括启用状态、工作模式、\n优先级、心跳接口、虚拟IP等配置。不支持filter和limit。\n",
          "operationId": "getVrrpConfig",
          "tags": [
            "vrrp-config"
          ],
          "responses": {
            "200": {
              "description": "成功获取VRRP热备配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/VrrpConfigResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "设置热备配置",
          "description": "配置VRRP热备的各项参数，包括工作模式、优先级、心跳接口、\n虚拟IP、配置同步等设置。支持主模式、备份模式、负载模式。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateVrrpConfig",
          "tags": [
            "vrrp-config"
          ],
          "requestBody": {
            "required": true,
            "description": "VRRP热备配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VrrpConfigInput"
                },
                "example": {
                  "enabled": "yes",
                  "type": 1,
                  "prio": 150,
                  "gateway": "8.8.8.8",
                  "ifnames": "wan1,wan2",
                  "auto_sync": 0,
                  "single_line": 0,
                  "ignore_wanstatus": 1,
                  "interfaces": "wan1,wan2",
                  "virtual_ips": "192.168.1.254,10.0.0.254",
                  "ht_iface": "eth0",
                  "remote_addr": "192.168.1.100"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "VRRP热备配置更新成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/vrrp:start": {
        "post": {
          "summary": "开启热备配置",
          "description": "启动VRRP热备服务，使热备配置生效。\n启动前请确保热备参数配置正确。\n",
          "operationId": "startVrrpService",
          "tags": [
            "vrrp-control"
          ],
          "responses": {
            "200": {
              "description": "VRRP热备服务启动成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "VRRP热备服务启动异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/VrrpErrorResponse"
                  },
                  "example": {
                    "message": "VRRP热备服务启动异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/vrrp:stop": {
        "post": {
          "summary": "关闭热备配置",
          "description": "停止VRRP热备服务，停止热备功能。\n停止前请确认不会影响现有业务的高可用性。\n",
          "operationId": "stopVrrpService",
          "tags": [
            "vrrp-control"
          ],
          "responses": {
            "200": {
              "description": "VRRP热备服务停止成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "VRRP热备服务停止异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/VrrpErrorResponse"
                  },
                  "example": {
                    "message": "VRRP热备服务停止异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "VrrpErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "VRRP业务错误信息描述"
            }
          }
        },
        "VrrpConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/VrrpConfig"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "VrrpConfig": {
          "type": "object",
          "required": [
            "enabled",
            "type",
            "prio",
            "gateway",
            "ifnames",
            "auto_sync",
            "single_line",
            "ignore_wanstatus",
            "interfaces",
            "virtual_ips",
            "ht_iface",
            "remote_addr"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "no"
            },
            "type": {
              "type": "integer",
              "description": "工作模式，1=主备模式，3=负载模式",
              "enum": [
                1,
                3
              ],
              "example": 1
            },
            "prio": {
              "type": "integer",
              "description": "优先级",
              "minimum": 0,
              "maximum": 255,
              "example": 150
            },
            "gateway": {
              "type": "string",
              "description": "PING 探测的目标 IP 地址",
              "format": "ipv4",
              "example": "8.8.8.8"
            },
            "ifnames": {
              "type": "string",
              "description": "外网接口探测列表，逗号分隔的 WAN 接口名（如 wan1,wan2）",
              "example": "wan1,wan2"
            },
            "auto_sync": {
              "type": "integer",
              "description": "是否开启配置的自动同步（0=否，1=是），仅企业版支持",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "single_line": {
              "type": "integer",
              "description": "是否开启单线环境（0=否，1=是）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ignore_wanstatus": {
              "type": "integer",
              "description": "是否开启外网检测（0=否，1=是）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "interfaces": {
              "type": "string",
              "description": "传输链路接口列表",
              "example": ""
            },
            "virtual_ips": {
              "type": "string",
              "description": "传输链路对应接口的虚拟IP",
              "example": ""
            },
            "ht_iface": {
              "type": "string",
              "description": "心跳接口",
              "example": ""
            },
            "remote_addr": {
              "type": "string",
              "description": "对端的 IP 地址（心跳线）",
              "format": "ipv4",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "VrrpConfigInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "enabled",
            "type",
            "prio",
            "gateway",
            "ifnames",
            "auto_sync",
            "single_line",
            "ignore_wanstatus",
            "interfaces",
            "virtual_ips",
            "ht_iface",
            "remote_addr"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "type": {
              "type": "integer",
              "description": "工作模式，1=主备模式，3=负载模式",
              "enum": [
                1,
                3
              ],
              "example": 1
            },
            "prio": {
              "type": "integer",
              "description": "优先级",
              "minimum": 0,
              "maximum": 255,
              "example": 150
            },
            "method": {
              "type": "integer",
              "description": "探测方式，0=DNS+PING，1=DNS，2=PING",
              "enum": [
                0,
                1,
                2
              ],
              "default": 2,
              "example": 2
            },
            "domain": {
              "type": "string",
              "description": "DNS探测域名",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "dns": {
              "type": "string",
              "description": "DNS服务地址",
              "default": "114.114.114.114",
              "example": "114.114.114.114"
            },
            "gateway": {
              "type": "string",
              "description": "PING 探测的目标 IP 地址",
              "format": "ipv4",
              "example": "8.8.8.8"
            },
            "interval": {
              "type": "integer",
              "description": "心跳间隔（秒）",
              "minimum": 1,
              "maximum": 255,
              "default": 3,
              "example": 3
            },
            "ifnames": {
              "type": "string",
              "description": "外网接口探测列表",
              "example": "wan1,wan2"
            },
            "auto_sync": {
              "type": "integer",
              "description": "是否开启配置的自动同步（0=否，1=是），仅企业版支持",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "single_line": {
              "type": "integer",
              "description": "是否开启单线环境（0=否，1=是）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ignore_wanstatus": {
              "type": "integer",
              "description": "是否开启外网检测（0=否，1=是）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "interfaces": {
              "type": "string",
              "description": "传输链路接口列表",
              "example": "wan1,wan2"
            },
            "virtual_ips": {
              "type": "string",
              "description": "传输链路对应接口的虚拟IP",
              "example": "192.168.1.254,10.0.0.254"
            },
            "ht_iface": {
              "type": "string",
              "description": "心跳接口",
              "example": "eth0"
            },
            "remote_addr": {
              "type": "string",
              "description": "对端的 IP 地址（心跳线）",
              "format": "ipv4",
              "example": "192.168.1.100"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "vrrp-config",
        "x-displayName": "VRRP热备配置",
        "description": "VRRP热备配置管理，包括工作模式、优先级、心跳接口等设置"
      },
      {
        "name": "vrrp-control",
        "x-displayName": "VRRP热备控制",
        "description": "VRRP热备服务的启动和停止控制"
      }
    ]
  },
  "system/system-web-admin-accounts.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "WEB登录账号与用户组管理API",
      "version": "1.0.0",
      "summary": "WEB管理后台登录账号与权限组的查询和管理功能",
      "description": "提供 WEB 管理后台登录账号与权限组的查询和管理能力，包括：\n- 用户组列表、详情、新增、修改、删除\n- 登录账号列表、详情、新增、修改、删除\n- 指定账号是否需要修改密码查询\n\n推荐使用流程：\n1. 先创建用户组，定义组权限和允许登录源地址\n2. 再创建登录账号，并通过 `group_id` 绑定到对应用户组\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/system/web-admin/groups": {
        "get": {
          "summary": "获取WEB登录用户组列表",
          "description": "获取 WEB 管理后台登录用户组列表。\n",
          "operationId": "listWebAdminGroups",
          "tags": [
            "web-admin-groups"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码，从 1 开始",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1,
                "example": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页返回记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 50,
                "example": 50
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取 WEB 登录用户组列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebAdminGroupListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "groups_total": 3,
                      "groups_data": [
                        {
                          "id": 1,
                          "group_name": "admin",
                          "perm_config": "",
                          "ip_addr": "0.0.0.0/0"
                        },
                        {
                          "id": 2,
                          "group_name": "test001",
                          "perm_config": "monitoring_center:r,monitor_iface:r,ipv6_stream:r",
                          "ip_addr": "0.0.0.0/0"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "新增WEB登录用户组",
          "description": "新增一个 WEB 管理后台登录用户组。\n\n用户组是账号权限的载体，建议先创建组，再创建账号。\n",
          "operationId": "createWebAdminGroup",
          "tags": [
            "web-admin-groups"
          ],
          "requestBody": {
            "required": true,
            "description": "WEB 登录用户组创建数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAdminGroupCreateInput"
                },
                "example": {
                  "group_name": "readonly",
                  "ip_addr": "0.0.0.0/0",
                  "perm_config": "monitoring_center:r,network_configuration:r"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 3
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/web-admin/groups/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "WEB 登录用户组 ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取单个WEB登录用户组详情",
          "description": "根据 ID 获取单个 WEB 登录用户组详情。\n",
          "operationId": "getWebAdminGroup",
          "tags": [
            "web-admin-groups"
          ],
          "responses": {
            "200": {
              "description": "成功获取 WEB 登录用户组详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebAdminGroupResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "groups_total": 1,
                      "groups_data": [
                        {
                          "id": 1,
                          "group_name": "admin",
                          "perm_config": "",
                          "ip_addr": "0.0.0.0/0"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "全量修改WEB登录用户组",
          "description": "全量修改指定 ID 的 WEB 登录用户组。\n\n注意：\n- 用户组 `id = 1` 为超级管理员组\n- 该组除名称外，其它属性不应修改\n",
          "operationId": "updateWebAdminGroup",
          "tags": [
            "web-admin-groups"
          ],
          "requestBody": {
            "required": true,
            "description": "WEB 登录用户组更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAdminGroupUpdateInput"
                },
                "example": {
                  "group_name": "readonly",
                  "ip_addr": "192.168.3.0/24",
                  "perm_config": "monitoring_center:r,network_configuration:r"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除WEB登录用户组",
          "description": "删除指定 ID 的 WEB 登录用户组。\n使用前建议确认没有账号仍在引用该组。\n",
          "operationId": "deleteWebAdminGroup",
          "tags": [
            "web-admin-groups"
          ],
          "responses": {
            "200": {
              "description": "WEB 登录用户组删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/web-admin/password-status": {
        "get": {
          "summary": "查询账号是否需要修改密码",
          "description": "查询指定 WEB 登录账号当前是否需要修改密码。\n\n返回说明：\n- `mod_passwd = 0`：当前不需要修改密码\n- `mod_passwd = 1`：当前密码为默认密码，需要修改\n",
          "operationId": "getWebAdminAccountPasswdStatus",
          "tags": [
            "web-admin-accounts"
          ],
          "parameters": [
            {
              "name": "username",
              "in": "query",
              "required": true,
              "description": "要查询的 WEB 登录账号用户名",
              "schema": {
                "type": "string",
                "example": "admin"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定账号的修改密码状态",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ModPasswdResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "mod_passwd": 0
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/web-admin/password": {
        "put": {
          "summary": "修改WEB登录账号密码",
          "description": "修改当前 WEB 登录账号的密码。\n",
          "operationId": "updateWebAdminPassword",
          "tags": [
            "web-admin-accounts"
          ],
          "requestBody": {
            "required": true,
            "description": "WEB 登录账号密码更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAdminPasswordInput"
                },
                "example": {
                  "passwd": "0192023a7bbd73250516f069df18b500"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/web-admin/accounts": {
        "get": {
          "summary": "获取WEB登录账号列表",
          "description": "获取 WEB 管理后台登录账号列表。\n",
          "operationId": "listWebAdminAccounts",
          "tags": [
            "web-admin-accounts"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码，从 1 开始",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1,
                "example": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页返回记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 50,
                "example": 50
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取 WEB 登录账号列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebAdminAccountListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "accounts_total": 3,
                      "accounts_data": [
                        {
                          "id": 1,
                          "username": "admin",
                          "enabled": "yes",
                          "group_id": 1,
                          "passwd": "0192023a7bbd73250516f069df18b500",
                          "force": 0,
                          "interval": 30,
                          "sesstimeout": 120,
                          "comment": ""
                        },
                        {
                          "id": 2,
                          "username": "test001",
                          "enabled": "yes",
                          "group_id": 2,
                          "passwd": "fa820cc1ad39a4e99283e9fa555035ec",
                          "force": 0,
                          "interval": 30,
                          "sesstimeout": 120,
                          "comment": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "新增WEB登录账号",
          "description": "新增一个 WEB 管理后台登录账号。\n\n建议先调用 `/api/v4.0/system/web-admin/groups` 创建用户组，再新增账号。\n",
          "operationId": "createWebAdminAccount",
          "tags": [
            "web-admin-accounts"
          ],
          "requestBody": {
            "required": true,
            "description": "WEB 登录账号创建数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAdminAccountCreateInput"
                },
                "example": {
                  "username": "ops_admin",
                  "passwd": "0192023a7bbd73250516f069df18b500",
                  "enabled": "yes",
                  "group_id": 1,
                  "force": 0,
                  "interval": 30,
                  "sesstimeout": 120,
                  "comment": "运维管理员账号"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 3
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/system/web-admin/accounts/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "WEB 登录账号 ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取单个WEB登录账号详情",
          "description": "根据 ID 获取单个 WEB 登录账号详情。\n",
          "operationId": "getWebAdminAccount",
          "tags": [
            "web-admin-accounts"
          ],
          "responses": {
            "200": {
              "description": "成功获取 WEB 登录账号详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebAdminAccountResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "accounts_total": 1,
                      "accounts_data": [
                        {
                          "id": 1,
                          "username": "admin",
                          "enabled": "yes",
                          "group_id": 1,
                          "passwd": "0192023a7bbd73250516f069df18b500",
                          "force": 0,
                          "interval": 30,
                          "sesstimeout": 120,
                          "comment": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "全量修改WEB登录账号",
          "description": "全量修改指定 ID 的 WEB 登录账号。\n\n账号权限与安全地址范围由 `group_id` 关联的用户组统一定义。\n",
          "operationId": "updateWebAdminAccount",
          "tags": [
            "web-admin-accounts"
          ],
          "requestBody": {
            "required": true,
            "description": "WEB 登录账号更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAdminAccountUpdateInput"
                },
                "example": {
                  "username": "ops_admin",
                  "passwd": "0192023a7bbd73250516f069df18b500",
                  "enabled": "yes",
                  "group_id": 1,
                  "force": 0,
                  "interval": 30,
                  "sesstimeout": 120,
                  "comment": "更新后的备注"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除WEB登录账号",
          "description": "删除指定 ID 的 WEB 登录账号。\n",
          "operationId": "deleteWebAdminAccount",
          "tags": [
            "web-admin-accounts"
          ],
          "responses": {
            "200": {
              "description": "WEB 登录账号删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问 WEB 登录账号管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 404,
                "message": "WEB 登录账号不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误状态码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求参数错误"
            }
          },
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n`details` 数组中可出现多条记录，表示多个字段或多组唯一性校验同时失败。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示创建成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            },
            "rowid": {
              "type": "integer",
              "format": "int64",
              "description": "新建记录 ID",
              "example": 3
            }
          },
          "additionalProperties": false
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非 0 表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非 0 表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "WebAdminAccount": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "username",
            "passwd",
            "group_id",
            "sesstimeout",
            "force",
            "interval"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "账号 ID",
              "minimum": 1,
              "example": 1
            },
            "comment": {
              "type": "string",
              "description": "备注信息",
              "maxLength": 255,
              "example": ""
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "example": "admin"
            },
            "enabled": {
              "type": "string",
              "description": "账号状态，`yes` 为启用，`no` 为停用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "passwd": {
              "type": "string",
              "description": "密码 MD5 值",
              "pattern": "^[a-fA-F0-9]{32}$",
              "example": "0192023a7bbd73250516f069df18b500"
            },
            "group_id": {
              "type": "integer",
              "description": "所属用户组 ID，对应 `usergroup.id`",
              "minimum": 1,
              "example": 1
            },
            "sesstimeout": {
              "type": "integer",
              "description": "会话超时时间，单位分钟，最小值 5",
              "minimum": 5,
              "example": 120
            },
            "force": {
              "type": "integer",
              "description": "定期修改密码开关，0 为关闭，1 为开启",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "interval": {
              "type": "integer",
              "description": "定期修改密码周期，单位天，最小值 1，默认 30",
              "minimum": 1,
              "example": 30
            }
          },
          "additionalProperties": false
        },
        "WebAdminGroup": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "perm_config",
            "ip_addr"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "用户组 ID",
              "minimum": 1,
              "example": 1
            },
            "group_name": {
              "type": "string",
              "description": "用户组名称",
              "example": "admin"
            },
            "perm_config": {
              "type": "string",
              "description": "权限配置字符串，菜单 key 对应设备侧 `menu.json`",
              "example": "monitoring_center:r,network_configuration:r"
            },
            "ip_addr": {
              "type": "string",
              "description": "安全 IP 地址范围，支持如 `0.0.0.0/0`、`192.168.1.1/255.255.255.0`、`192.168.1.1-192.168.1.200`",
              "example": "0.0.0.0/0"
            }
          },
          "additionalProperties": false
        },
        "WebAdminGroupCreateInput": {
          "type": "object",
          "required": [
            "group_name",
            "ip_addr",
            "perm_config"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "用户组名称",
              "example": "readonly"
            },
            "ip_addr": {
              "type": "string",
              "description": "安全 IP 地址范围",
              "example": "0.0.0.0/0"
            },
            "perm_config": {
              "type": "string",
              "description": "权限配置字符串，菜单 key 对应设备侧 `menu.json`",
              "example": "monitoring_center:r,network_configuration:r"
            }
          },
          "additionalProperties": false
        },
        "WebAdminGroupUpdateInput": {
          "type": "object",
          "description": "WEB 登录用户组全量更新输入。\n当目标组 `id = 1` 时，建议仅修改 `group_name`。\n",
          "required": [
            "group_name",
            "ip_addr",
            "perm_config"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "用户组名称",
              "example": "readonly"
            },
            "ip_addr": {
              "type": "string",
              "description": "安全 IP 地址范围",
              "example": "192.168.3.0/24"
            },
            "perm_config": {
              "type": "string",
              "description": "权限配置字符串，菜单 key 对应设备侧 `menu.json`",
              "example": "monitoring_center:r,network_configuration:r"
            }
          },
          "additionalProperties": false
        },
        "WebAdminPasswordInput": {
          "type": "object",
          "required": [
            "passwd"
          ],
          "properties": {
            "passwd": {
              "type": "string",
              "description": "新密码的 MD5 值",
              "pattern": "^[a-fA-F0-9]{32}$",
              "example": "0192023a7bbd73250516f069df18b500"
            }
          },
          "additionalProperties": false
        },
        "WebAdminAccountCreateInput": {
          "type": "object",
          "required": [
            "username",
            "passwd",
            "enabled",
            "group_id",
            "force",
            "interval",
            "sesstimeout"
          ],
          "properties": {
            "username": {
              "type": "string",
              "description": "用户名",
              "example": "ops_admin"
            },
            "passwd": {
              "type": "string",
              "description": "登录密码的 MD5 值",
              "pattern": "^[a-fA-F0-9]{32}$",
              "example": "0192023a7bbd73250516f069df18b500"
            },
            "enabled": {
              "type": "string",
              "description": "账号状态，`yes` 为启用，`no` 为停用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "group_id": {
              "type": "integer",
              "description": "所属用户组 ID。账号权限由该用户组提供，应先创建用户组再新增账号",
              "minimum": 1,
              "example": 1
            },
            "force": {
              "type": "integer",
              "description": "定期修改密码开关",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "interval": {
              "type": "integer",
              "description": "定期修改密码周期，单位天，最小值 1，默认 30",
              "minimum": 1,
              "example": 30
            },
            "sesstimeout": {
              "type": "integer",
              "description": "会话超时时间，单位分钟，最小值 5",
              "minimum": 5,
              "example": 120
            },
            "comment": {
              "type": "string",
              "description": "备注信息",
              "maxLength": 255,
              "example": "运维管理员账号"
            }
          },
          "additionalProperties": false
        },
        "WebAdminAccountUpdateInput": {
          "type": "object",
          "required": [
            "username",
            "passwd",
            "enabled",
            "group_id",
            "force",
            "interval",
            "sesstimeout"
          ],
          "properties": {
            "username": {
              "type": "string",
              "description": "用户名",
              "example": "ops_admin"
            },
            "passwd": {
              "type": "string",
              "description": "登录密码的 MD5 值",
              "pattern": "^[a-fA-F0-9]{32}$",
              "example": "0192023a7bbd73250516f069df18b500"
            },
            "enabled": {
              "type": "string",
              "description": "账号状态，`yes` 为启用，`no` 为停用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "group_id": {
              "type": "integer",
              "description": "所属用户组 ID。账号权限由该用户组提供",
              "minimum": 1,
              "example": 1
            },
            "force": {
              "type": "integer",
              "description": "定期修改密码开关",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "interval": {
              "type": "integer",
              "description": "定期修改密码周期，单位天，最小值 1，默认 30",
              "minimum": 1,
              "example": 30
            },
            "sesstimeout": {
              "type": "integer",
              "description": "会话超时时间，单位分钟，最小值 5",
              "minimum": 5,
              "example": 120
            },
            "comment": {
              "type": "string",
              "description": "备注信息",
              "maxLength": 255,
              "example": "更新后的备注"
            }
          },
          "additionalProperties": false
        },
        "ModPasswdResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "mod_passwd": {
                  "type": "integer",
                  "description": "是否需要修改密码，`0` 为不需要，`1` 表示当前密码为默认密码，需要修改",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                }
              },
              "required": [
                "mod_passwd"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WebAdminAccountResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "accounts_total": {
                  "type": "integer",
                  "example": 1
                },
                "accounts_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WebAdminAccount"
                  }
                }
              },
              "required": [
                "accounts_total",
                "accounts_data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WebAdminAccountListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "accounts_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 3
                },
                "accounts_data": {
                  "type": "array",
                  "description": "WEB 登录账号列表",
                  "items": {
                    "$ref": "#/components/schemas/WebAdminAccount"
                  }
                }
              },
              "required": [
                "accounts_total",
                "accounts_data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WebAdminGroupResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "groups_total": {
                  "type": "integer",
                  "example": 1
                },
                "groups_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WebAdminGroup"
                  }
                }
              },
              "required": [
                "groups_total",
                "groups_data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WebAdminGroupListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "groups_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 3
                },
                "groups_data": {
                  "type": "array",
                  "description": "WEB 登录用户组列表",
                  "items": {
                    "$ref": "#/components/schemas/WebAdminGroup"
                  }
                }
              },
              "required": [
                "groups_total",
                "groups_data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用 JWT Bearer Token 进行认证。\n在请求头中添加：Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "web-admin-groups",
        "x-displayName": "WEB登录用户组管理",
        "description": "WEB 管理后台登录用户组与权限配置管理"
      },
      {
        "name": "web-admin-accounts",
        "x-displayName": "WEB登录账号管理",
        "description": "WEB 管理后台登录账号的查询与维护，账号通过 `group_id` 绑定用户组"
      }
    ]
  },
  "monitor/monitor-cameras.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "摄像头监控API",
      "version": "1.0.0",
      "summary": "摄像头设备监控查询",
      "description": "提供摄像头设备的监控查询功能，包括：\n- 摄像头设备列表查询\n- 设备在线状态监控\n- NVR（网络录像机）及其下属摄像头查询\n\n**注意：** 此模块仅提供查询功能，摄像头设备通过自动发现添加。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/cameras": {
        "get": {
          "summary": "查询摄像头设备列表",
          "description": "查询摄像头设备列表，支持分页和过滤。\n",
          "operationId": "getCameras",
          "tags": [
            "monitor-cameras"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 设备类型过滤：filter=flag==1\n- 在线状态过滤：filter=status==0\n- IP地址过滤：filter=ip_addr==192.168.1.100\n",
              "schema": {
                "type": "string"
              },
              "example": "status==0"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 tagname, name, ip_addr, vendor, version, comment",
              "schema": {
                "type": "string"
              },
              "example": "name,ip_addr,vendor"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "Hikvision"
            }
          ],
          "responses": {
            "200": {
              "description": "成功返回摄像头列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CameraResponse"
                  },
                  "examples": {
                    "success": {
                      "value": {
                        "results": {
                          "data": [
                            {
                              "id": 1,
                              "tagname": "一楼大厅摄像头",
                              "name": "Hikvision Camera",
                              "vendor": "HIKVISION",
                              "ip_addr": "192.168.1.100",
                              "port": 80,
                              "mac": "aa:bb:cc:dd:ee:ff",
                              "status": 0,
                              "flag": 1,
                              "enabled": "yes",
                              "comment": "安装在1楼大厅",
                              "passwd_flag": 1
                            },
                            {
                              "id": 2,
                              "tagname": "NVR主机",
                              "name": "Hikvision NVR",
                              "vendor": "HIKVISION",
                              "ip_addr": "192.168.1.200",
                              "port": 80,
                              "mac": "11:22:33:44:55:66",
                              "status": 0,
                              "flag": 2,
                              "enabled": "yes",
                              "camera_count": 4
                            }
                          ],
                          "total": 2
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、name、ip_addr、vendor、status等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "schemas": {
        "CameraDevice": {
          "type": "object",
          "description": "摄像头设备信息",
          "required": [
            "id",
            "tagname"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "设备ID"
            },
            "enabled": {
              "type": "string",
              "description": "启用状态",
              "enum": [
                "yes",
                "no"
              ]
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）"
            },
            "name": {
              "type": "string",
              "description": "设备名称"
            },
            "vendor": {
              "type": "string",
              "description": "设备厂商"
            },
            "ip_addr": {
              "type": "string",
              "description": "设备IP地址",
              "format": "ipv4"
            },
            "port": {
              "type": "integer",
              "description": "HTTP端口号",
              "minimum": 1,
              "maximum": 65535
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"
            },
            "status": {
              "type": "integer",
              "description": "设备在线状态（0: 在线, 1: 离线）",
              "enum": [
                0,
                1
              ]
            },
            "serialno": {
              "type": "string",
              "description": "设备序列号"
            },
            "last_time": {
              "type": "integer",
              "description": "最近离线时间戳",
              "format": "int64"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符"
            },
            "version": {
              "type": "string",
              "description": "固件版本号"
            },
            "flag": {
              "type": "integer",
              "description": "设备类型标识（1: 摄像头, 2: NVR）",
              "enum": [
                1,
                2
              ]
            },
            "nvr": {
              "type": "string",
              "description": "所属NVR设备"
            },
            "camera_count": {
              "type": "integer",
              "description": "NVR下的摄像头数量（flag=2时有效）"
            },
            "passwd_flag": {
              "type": "integer",
              "description": "密码正确性标识（0: 无密码, 1: 密码正确, 2: 密码错误）",
              "enum": [
                0,
                1,
                2
              ]
            }
          }
        },
        "CameraResponse": {
          "type": "object",
          "properties": {
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "摄像头列表",
                  "items": {
                    "$ref": "#/components/schemas/CameraDevice"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数"
                }
              }
            }
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求参数错误",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 400
                  },
                  "message": {
                    "type": "string",
                    "example": "参数错误"
                  }
                }
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 401
                  },
                  "message": {
                    "type": "string",
                    "example": "未认证或凭证无效"
                  }
                }
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-cameras",
        "x-displayName": "摄像头监控",
        "description": "摄像头设备监控查询"
      }
    ]
  },
  "monitor/monitor-clients.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "终端监控管理API",
      "version": "1.0.0",
      "summary": "终端状态和流量监控的完整功能",
      "description": "提供终端监控的完整功能，包括：\n- IPv4/IPv6终端在线状态监控\n- IPv4/IPv6终端离线状态监控\n- 终端当日流量统计\n- 终端5分钟实时流量负载（5秒一个数据点）\n- 指定终端最近24小时协议分类流量统计\n- 指定终端最近24小时协议分类速率负载\n- 指定终端当前访问的应用协议速率统计\n- 支持分页、过滤和模糊匹配\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/clients-online": {
        "get": {
          "summary": "获取IPv4终端在线统计",
          "description": "获取当前IPv4在线终端的统计信息，包括MAC地址、SSID、IP地址、\n上下行速率、连接数、厂商型号等详细信息。支持分页、过滤和模糊匹配。\n",
          "operationId": "getOnlineClients",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 ssid, mac, ip_addr, termname, client_vendor, client_model",
              "schema": {
                "type": "string"
              },
              "example": "mac,ip_addr"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "08:9b:4b"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n- \"：（包含）\"\n- \"!：（不包含）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=mac==08:9b:4b:01:7e:7c\n- AND条件：filter=interface==lan1&filter=connect_num>1\n- OR条件：filter=mac==08:9b:4b:01:7e:7c,mac==08:9b:4b:13:35:6f\n- 包含过滤：filter=client_vendor:Apple\n- 时间范围：filter=timestamp>1763804000&filter=timestamp<1763805000\n",
              "schema": {
                "type": "string"
              },
              "example": "mac==08:9b:4b:01:7e:7c"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取在线终端统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/OnlineClientsResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "mac": "08:9b:4b:01:7e:7c",
                          "ip_addr": "192.168.9.199",
                          "ip_addr_int": 3232238023,
                          "ssid": "",
                          "uplink_dev": "iKuai-lpx",
                          "uplink_addr": "08:9b:4b:13:35:6f",
                          "webid": 0,
                          "connect_num": 3,
                          "total_up": 3929392,
                          "total_down": 77762748,
                          "upload": 0,
                          "download": 0,
                          "today_total": 57775943,
                          "apname": "",
                          "ac_gid": 0,
                          "device_icon": "1_107",
                          "vendor_icon": "2_998",
                          "timestamp": 1763804867,
                          "termname": "未知123",
                          "ipv4_gnames": "",
                          "ipv6_gnames": "",
                          "mac_gnames": "11",
                          "dtalk_name": "",
                          "link_addr": "",
                          "client_vendor": "路由器",
                          "client_model": "test",
                          "client_type": "iKuaiOS",
                          "client_typeid": 107998000,
                          "reject": 0,
                          "comment": "123",
                          "bssid": "",
                          "uprate": "",
                          "downrate": "",
                          "enc": "",
                          "static_status": 0,
                          "interface": "lan1",
                          "signal": "",
                          "auth_type": 0,
                          "vlan_id": 0,
                          "uptime": "2025-11-22 17:47:47",
                          "username": "",
                          "ppptype": "",
                          "apmac": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients-ip6-online": {
        "get": {
          "summary": "获取IPv6终端在线统计",
          "description": "获取当前IPv6在线终端的统计信息，包括MAC地址、SSID、IP地址、\n上下行速率、连接数、厂商型号等详细信息。支持分页、过滤和模糊匹配。\n",
          "operationId": "getIp6OnlineClients",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 ssid, mac, ip_addr, termname, client_vendor, client_model",
              "schema": {
                "type": "string"
              },
              "example": "mac,ip_addr"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "08:9b:4b"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n- \"：（包含）\"\n- \"!：（不包含）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=mac==08:9b:4b:01:7e:7c\n- AND条件：filter=interface==lan1&filter=connect_num>1\n- OR条件：filter=mac==08:9b:4b:01:7e:7c,mac==08:9b:4b:13:35:6f\n- 包含过滤：filter=client_vendor:Apple\n- 时间范围：filter=timestamp>1763804000&filter=timestamp<1763805000\n",
              "schema": {
                "type": "string"
              },
              "example": "mac==08:9b:4b:01:7e:7c"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IPv6在线终端统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ip6OnlineClientsResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "mac": "1a:00:9c:10:f1:5c",
                          "ip_addr": "2408:8207:3053:bc21:1800:9cff:fe10:f15c",
                          "ip_addr_int": 0,
                          "ssid": "",
                          "uplink_dev": "1.253",
                          "uplink_addr": "00:e2:59:00:68:4e",
                          "webid": 0,
                          "connect_num": 0,
                          "total_up": 96,
                          "total_down": 110,
                          "upload": 0,
                          "download": 0,
                          "today_total": 24514,
                          "apname": "",
                          "ac_gid": 0,
                          "device_icon": "",
                          "vendor_icon": "",
                          "timestamp": 1773394260,
                          "termname": "测试部Ubuntu",
                          "ipv4_gnames": "",
                          "ipv6_gnames": "",
                          "mac_gnames": "",
                          "dtalk_name": "",
                          "link_addr": "fe80::1800:9cff:fe10:f15c",
                          "client_vendor": "Unknown",
                          "client_model": "",
                          "client_type": "Unknown",
                          "client_typeid": 0,
                          "device_type": "",
                          "reject": 0,
                          "comment": "测试部Ubuntu",
                          "bssid": "",
                          "uprate": "",
                          "downrate": "",
                          "enc": "",
                          "static_status": 0,
                          "interface": "vlan5",
                          "signal": 0,
                          "channel": "--",
                          "auth_type": 0,
                          "vlan_id": 0,
                          "uptime": "2026-03-13 17:31:00",
                          "username": "",
                          "ppptype": "",
                          "apmac": "",
                          "frequencies": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients-offline": {
        "get": {
          "summary": "获取IPv4终端离线统计",
          "description": "获取IPv4离线终端的统计信息，包括MAC地址、IP地址、下线时间、\n总流量统计、认证类型等详细信息。支持分页、过滤和模糊匹配。\n",
          "operationId": "getOfflineClients",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 mac, ip_addr, termname, client_vendor, client_model",
              "schema": {
                "type": "string"
              },
              "example": "mac,ip_addr"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "52:83:56"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n- \"：（包含）\"\n- \"!：（不包含）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=mac==52:83:56:ef:f2:4b\n- AND条件：filter=logout_time>1763814000&filter=total_up>0\n- OR条件：filter=mac==52:83:56:ef:f2:4b,mac==08:9b:4b:01:7e:7c\n- 包含过滤：filter=client_vendor:Apple\n- 时间范围：filter=logout_time>1763814000&filter=logout_time<1763815000\n",
              "schema": {
                "type": "string"
              },
              "example": "mac==52:83:56:ef:f2:4b"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取离线终端统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/OfflineClientsResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "offline_data": [
                        {
                          "id": 1,
                          "mac": "52:83:56:ef:f2:4b",
                          "ip_addr": "192.168.9.105",
                          "username": "",
                          "client_typeid": 101000299,
                          "client_vendor": "Apple",
                          "client_model": "",
                          "static_status": 0,
                          "termname": "",
                          "comment": "",
                          "ipv6_gnames": "",
                          "today_total": 0,
                          "logout_time": 1763814180,
                          "total_up": 4105104,
                          "total_down": 27465719,
                          "client_type": "iOS",
                          "ipv4_gnames": "",
                          "auth": 0,
                          "mac_gnames": "",
                          "dtalk_name": "",
                          "vlan_id": 0
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients-ip6-offline": {
        "get": {
          "summary": "获取IPv6终端离线统计",
          "description": "获取IPv6离线终端的统计信息，包括MAC地址、IP地址、下线时间、\n总流量统计、认证类型等详细信息。支持分页、过滤和模糊匹配。\n",
          "operationId": "getIp6OfflineClients",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 mac, ip_addr, termname, client_vendor, client_model",
              "schema": {
                "type": "string"
              },
              "example": "mac,ip_addr"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "00:71:6f"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n- \":（包含）\"\n- \"!：（不包含）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=mac==00:71:6f:a6:0c:2d\n- AND条件：filter=logout_time>1773390000&filter=total_up>0\n- OR条件：filter=mac==00:71:6f:a6:0c:2d,mac==08:9b:4b:01:7e:7c\n- 包含过滤：filter=client_vendor:iKuai\n- 时间范围：filter=logout_time>1773390000&filter=logout_time<1773391000\n",
              "schema": {
                "type": "string"
              },
              "example": "mac==00:71:6f:a6:0c:2d"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IPv6离线终端统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ip6OfflineClientsResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "offline_data": [
                        {
                          "id": 1,
                          "mac": "00:71:6f:a6:0c:2d",
                          "ip_addr": "2408:8207:3053:bb90:0271:6fff:fea6:0c2d",
                          "username": "",
                          "client_typeid": 107998006,
                          "client_vendor": "iKuai",
                          "client_model": "iKuai路由器",
                          "device_type": "",
                          "today_total": 8370425,
                          "logout_time": 1773390540,
                          "total_up": 4769559,
                          "total_down": 21154347,
                          "client_type": "iKuaiOS",
                          "ipv4_gnames": "",
                          "ipv6_gnames": "",
                          "mac_gnames": "",
                          "auth": 0,
                          "dtalk_name": "",
                          "vlan_id": 0,
                          "termname": "",
                          "comment": "",
                          "device_icon": "1_107"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients-traffic-summary": {
        "get": {
          "summary": "获取终端当日流量统计",
          "description": "获取所有终端的当日流量统计信息，包括总流量、上行流量、\n下行流量等汇总数据。支持分页功能，不支持key、pattern、filter。\n",
          "operationId": "getClientTrafficSummary",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取终端当日流量统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ClientTrafficSummaryResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "terminal": [
                        {
                          "id": 1,
                          "mac": "08:9b:4b:01:7e:7c",
                          "ip_addr": "192.168.9.199",
                          "username": "testuser",
                          "comment": "我的电脑",
                          "icon": "1_107",
                          "sum_total": 7006058917,
                          "sum_total_up": 4546140370,
                          "sum_total_down": 2459918547
                        },
                        {
                          "id": 2,
                          "mac": "1a:f8:62:e6:ca:49",
                          "ip_addr": "192.168.9.105",
                          "username": "",
                          "comment": "",
                          "icon": "",
                          "sum_total": 114884,
                          "sum_total_up": 44004,
                          "sum_total_down": 70880
                        }
                      ],
                      "terminal_total": 2,
                      "terminal_total_flow": 7006173801
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients-traffic-load": {
        "get": {
          "summary": "获取指定终端的5分钟流量负载",
          "description": "获取指定终端的5分钟流量负载，包含上行速率和下行速率，\n5秒一个数据点，共300个数据点。ip和mac均必须输入。\n",
          "operationId": "getClientTrafficLoad",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "name": "mac",
              "in": "query",
              "required": true,
              "description": "终端MAC地址",
              "schema": {
                "type": "string",
                "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                "example": "08:9b:4b:01:7e:7c"
              }
            },
            {
              "name": "ip",
              "in": "query",
              "required": true,
              "description": "终端IP地址",
              "schema": {
                "type": "string",
                "format": "ipv4",
                "example": "192.168.9.199"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取终端5分钟流量负载数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ClientStreamResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "terminal_stream_collect": [
                        {
                          "download": 78335,
                          "conn_num": "177",
                          "timestamp": 1773304236,
                          "upload": 7402
                        },
                        {
                          "download": 49133,
                          "conn_num": "258",
                          "timestamp": 1773304241,
                          "upload": 87372
                        },
                        {
                          "download": 45746,
                          "conn_num": "242",
                          "timestamp": 1773304246,
                          "upload": 280816
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients/protocols": {
        "get": {
          "summary": "获取指定终端的协议分类流量统计",
          "description": "获取指定终端最近24小时的协议分类流量统计。\n协议大类包括：网络协议、传输下载、休闲娱乐、生活服务、办公协作、\n社交通讯、效率工具、网络游戏、金融理财、学习教育等。\nmac和ip必须输入，不支持limit、page、key、pattern、filter。\n",
          "operationId": "getClientProtocols",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "name": "mac",
              "in": "query",
              "required": true,
              "description": "终端MAC地址",
              "schema": {
                "type": "string",
                "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                "example": "08:9b:4b:01:7e:7c"
              }
            },
            {
              "name": "ip",
              "in": "query",
              "required": true,
              "description": "终端IP地址",
              "schema": {
                "type": "string",
                "example": "192.168.9.199"
              }
            },
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "开始时间戳",
              "schema": {
                "type": "integer",
                "example": 1773304236
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "结束时间戳",
              "schema": {
                "type": "integer",
                "example": 1773304246
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定终端协议分类流量统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ClientProtocolsResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "total": 2635725,
                          "proto": "4:7",
                          "proto_name": "未知应用"
                        },
                        {
                          "id": 2,
                          "total": 3439230,
                          "proto": "3500000:3999999",
                          "proto_name": "效率工具"
                        },
                        {
                          "id": 3,
                          "total": 69668994,
                          "proto": "2500000:2999999",
                          "proto_name": "传输下载"
                        },
                        {
                          "id": 5,
                          "total": 267252162,
                          "proto": "4000000:4499999",
                          "proto_name": "办公协作"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients/protocols/history-load": {
        "get": {
          "summary": "获取指定终端的协议分类历史速率",
          "description": "获取指定终端最近24小时的协议分类速率负载，每5分钟一个数据点，\n包含各协议分类的上下行速率信息，单位字节/秒。\nmac和ip必须输入，不支持limit、page、key、pattern、filter。\n",
          "operationId": "getClientProtocolsHistoryLoad",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "name": "mac",
              "in": "query",
              "required": true,
              "description": "终端MAC地址",
              "schema": {
                "type": "string",
                "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                "example": "08:9b:4b:01:7e:7c"
              }
            },
            {
              "name": "ip",
              "in": "query",
              "required": true,
              "description": "终端IP地址",
              "schema": {
                "type": "string",
                "example": "192.168.9.199"
              }
            },
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "开始时间戳",
              "schema": {
                "type": "integer",
                "example": 1773304236
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "结束时间戳",
              "schema": {
                "type": "integer",
                "example": 1773304246
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定终端协议分类历史速率数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ClientProtocolHistoryLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "upload": 1899,
                          "proto": "1000000:1499999",
                          "proto_name": "网络协议",
                          "timestamp": 1773287100,
                          "download": 2683,
                          "id": 1
                        },
                        {
                          "upload": 0,
                          "proto": "2500000:2999999",
                          "timestamp": 1773287100,
                          "download": 0,
                          "id": 2
                        },
                        {
                          "upload": 80,
                          "proto": "4000000:4499999",
                          "timestamp": 1773287100,
                          "download": 123,
                          "id": 3
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/clients/app-protocols/load": {
        "get": {
          "summary": "获取指定终端当前应用协议速率统计",
          "description": "查询指定终端当前访问的所有应用协议的速率和流量信息，\n包括连接数、上下行速率、总流量及协议分类信息。\nmac 和 ip 必须输入，支持分页。\n",
          "operationId": "getClientAppProtocolsLoad",
          "tags": [
            "monitor-clients"
          ],
          "parameters": [
            {
              "name": "mac",
              "in": "query",
              "description": "终端MAC地址",
              "required": true,
              "schema": {
                "type": "string"
              },
              "example": "08:9b:4b:01:7e:7c"
            },
            {
              "name": "ip",
              "in": "query",
              "description": "终端IP地址",
              "required": true,
              "schema": {
                "type": "string",
                "format": "ipv4"
              },
              "example": "192.168.9.199"
            },
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页返回数量",
              "required": false,
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              },
              "example": 20
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定终端当前应用协议速率统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ClientAppProtocolsLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "conn_cnt": 0,
                          "upload": 0,
                          "download": 0,
                          "appid": 5030009,
                          "app_name": "今日头条",
                          "id": 1,
                          "total": 170,
                          "total_up": 100,
                          "total_down": 70,
                          "proto2_name": "5030001:5040000",
                          "proto1_name": "5000000:5499999",
                          "rules": {}
                        },
                        {
                          "conn_cnt": 0,
                          "upload": 0,
                          "download": 0,
                          "appid": 5060190,
                          "app_name": "谷歌通用账号",
                          "id": 2,
                          "total": 190,
                          "total_up": 80,
                          "total_down": 110,
                          "proto2_name": "5060001:5070000",
                          "proto1_name": "5000000:5499999",
                          "rules": {}
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 10,
            "example": 10
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、mac、ip_addr等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "OnlineClientsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/OnlineClientsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "OnlineClientsResults": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            },
            "data": {
              "type": "array",
              "description": "在线终端列表",
              "items": {
                "$ref": "#/components/schemas/OnlineClient"
              }
            }
          },
          "required": [
            "total",
            "data"
          ],
          "additionalProperties": false
        },
        "OnlineClient": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ip_addr",
            "timestamp",
            "total_up",
            "total_down",
            "connect_num",
            "upload",
            "download",
            "uplink_dev",
            "uplink_addr",
            "apname",
            "bssid",
            "termname",
            "comment",
            "static_status",
            "client_type",
            "client_typeid",
            "interface",
            "auth_type",
            "vlan_id",
            "uptime",
            "username",
            "ppptype",
            "apmac",
            "today_total",
            "client_vendor",
            "client_model",
            "reject",
            "frequencies",
            "uprate",
            "downrate",
            "enc",
            "ipv4_gnames",
            "ipv6_gnames",
            "mac_gnames",
            "dtalk_name",
            "link_addr",
            "webid",
            "device_icon",
            "vendor_icon",
            "ac_gid"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "终端ID",
              "minimum": 1,
              "example": 1
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:01:7e:7c"
            },
            "ssid": {
              "type": "string",
              "description": "SSID名称（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "ip_addr_int": {
              "type": "integer",
              "format": "int64",
              "description": "终端IP地址（整数格式）",
              "minimum": 0,
              "example": 3232238023
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IP地址",
              "format": "ipv4",
              "example": "192.168.9.199"
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763804867
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "总上传字节数",
              "minimum": 0,
              "example": 3929392
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "总下载字节数",
              "minimum": 0,
              "example": 77762748
            },
            "connect_num": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 3
            },
            "upload": {
              "type": "integer",
              "description": "实时上传速率（B/s）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "实时下载速率（B/s）",
              "minimum": 0,
              "example": 0
            },
            "uplink_dev": {
              "type": "string",
              "description": "上行设备名称",
              "maxLength": 100,
              "example": "iKuai-lpx"
            },
            "uplink_addr": {
              "type": "string",
              "description": "上行设备MAC地址",
              "maxLength": 100,
              "example": "08:9b:4b:13:35:6f"
            },
            "apname": {
              "type": "string",
              "description": "AP名称（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "bssid": {
              "type": "string",
              "description": "AP的BSSID（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 200,
              "example": "未知123"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "123"
            },
            "static_status": {
              "type": "integer",
              "description": "静态状态 (0=动态, 1=静态)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "client_type": {
              "type": "string",
              "description": "终端类型",
              "maxLength": 50,
              "example": "iKuaiOS"
            },
            "client_typeid": {
              "type": "integer",
              "format": "int64",
              "description": "终端类型ID",
              "minimum": 0,
              "example": 107998000
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "lan1"
            },
            "signal": {
              "type": "string",
              "description": "信号强度（无线连接时有效）",
              "maxLength": 50,
              "example": ""
            },
            "auth_type": {
              "type": "integer",
              "description": "认证类型",
              "minimum": 0,
              "example": 0
            },
            "vlan_id": {
              "type": "integer",
              "description": "VLAN ID",
              "minimum": 0,
              "example": 0
            },
            "uptime": {
              "type": "string",
              "description": "上线时间",
              "maxLength": 50,
              "example": "2025-11-22 17:47:47"
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "maxLength": 100,
              "example": ""
            },
            "ppptype": {
              "type": "string",
              "description": "PPPoE类型或IP获取方式",
              "maxLength": 50,
              "example": ""
            },
            "apmac": {
              "type": "string",
              "description": "AP的MAC地址（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "today_total": {
              "type": "integer",
              "format": "int64",
              "description": "今日总流量（字节）",
              "minimum": 0,
              "example": 57775943
            },
            "client_vendor": {
              "type": "string",
              "description": "客户端厂商",
              "maxLength": 100,
              "example": "路由器"
            },
            "client_model": {
              "type": "string",
              "description": "客户端型号",
              "maxLength": 100,
              "example": "test"
            },
            "reject": {
              "type": "integer",
              "description": "拒绝状态 (0=不拒绝, 1=拒绝)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "frequencies": {
              "type": "string",
              "description": "频率信息（无线连接时有效）",
              "maxLength": 50,
              "example": ""
            },
            "uprate": {
              "type": "string",
              "description": "上行速率信息",
              "maxLength": 50,
              "example": ""
            },
            "downrate": {
              "type": "string",
              "description": "下行速率信息",
              "maxLength": 50,
              "example": ""
            },
            "enc": {
              "type": "string",
              "description": "加密信息（无线连接时有效）",
              "maxLength": 50,
              "example": ""
            },
            "ipv4_gnames": {
              "type": "string",
              "description": "IPv4组名称",
              "maxLength": 200,
              "example": ""
            },
            "ipv6_gnames": {
              "type": "string",
              "description": "IPv6组名称",
              "maxLength": 200,
              "example": ""
            },
            "mac_gnames": {
              "type": "string",
              "description": "MAC组名称",
              "maxLength": 200,
              "example": "11"
            },
            "dtalk_name": {
              "type": "string",
              "description": "D-Talk名称",
              "maxLength": 100,
              "example": ""
            },
            "link_addr": {
              "type": "string",
              "description": "链路地址",
              "maxLength": 100,
              "example": ""
            },
            "webid": {
              "type": "integer",
              "description": "Web认证ID",
              "minimum": 0,
              "example": 0
            },
            "device_icon": {
              "type": "string",
              "description": "设备图标标识",
              "maxLength": 50,
              "example": "1_107"
            },
            "vendor_icon": {
              "type": "string",
              "description": "厂商图标标识",
              "maxLength": 50,
              "example": "2_998"
            },
            "ac_gid": {
              "type": "integer",
              "description": "AC组ID",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "OfflineClientsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/OfflineClientsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "OfflineClientsResults": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            },
            "offline_data": {
              "type": "array",
              "description": "离线终端列表",
              "items": {
                "$ref": "#/components/schemas/OfflineClient"
              }
            }
          },
          "required": [
            "total",
            "offline_data"
          ],
          "additionalProperties": false
        },
        "OfflineClient": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ip_addr",
            "logout_time",
            "total_up",
            "total_down",
            "today_total",
            "client_type",
            "client_typeid",
            "static_status",
            "auth",
            "ipv4_gnames",
            "ipv6_gnames",
            "mac_gnames",
            "dtalk_name",
            "termname",
            "comment",
            "username",
            "client_vendor",
            "client_model",
            "vlan_id"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "终端ID",
              "minimum": 1,
              "example": 1
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "52:83:56:ef:f2:4b"
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IP地址",
              "format": "ipv4",
              "example": "192.168.9.105"
            },
            "logout_time": {
              "type": "integer",
              "format": "int64",
              "description": "下线时间戳（Unix时间戳）",
              "example": 1763814180
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "总上传字节数",
              "minimum": 0,
              "example": 4105104
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "总下载字节数",
              "minimum": 0,
              "example": 27465719
            },
            "today_total": {
              "type": "integer",
              "format": "int64",
              "description": "今日总流量（字节）",
              "minimum": 0,
              "example": 0
            },
            "client_type": {
              "type": "string",
              "description": "终端类型",
              "maxLength": 50,
              "example": "iOS"
            },
            "client_typeid": {
              "type": "integer",
              "format": "int64",
              "description": "终端类型ID",
              "minimum": 0,
              "example": 101000299
            },
            "static_status": {
              "type": "integer",
              "description": "静态状态 (0=动态, 1=静态)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "auth": {
              "type": "integer",
              "description": "认证状态 (0=未认证, 1=已认证)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ipv4_gnames": {
              "type": "string",
              "description": "IPv4组名称",
              "maxLength": 200,
              "example": ""
            },
            "ipv6_gnames": {
              "type": "string",
              "description": "IPv6组名称",
              "maxLength": 200,
              "example": ""
            },
            "mac_gnames": {
              "type": "string",
              "description": "MAC组名称",
              "maxLength": 200,
              "example": ""
            },
            "dtalk_name": {
              "type": "string",
              "description": "D-Talk名称",
              "maxLength": 100,
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 200,
              "example": ""
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "maxLength": 100,
              "example": ""
            },
            "client_vendor": {
              "type": "string",
              "description": "客户端厂商",
              "maxLength": 100,
              "example": "Apple"
            },
            "client_model": {
              "type": "string",
              "description": "客户端型号",
              "maxLength": 100,
              "example": ""
            },
            "vlan_id": {
              "type": "integer",
              "description": "VLAN ID",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "ClientTrafficSummaryResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ClientTrafficSummaryResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ClientTrafficSummaryResults": {
          "type": "object",
          "properties": {
            "terminal": {
              "type": "array",
              "description": "终端流量统计列表",
              "items": {
                "$ref": "#/components/schemas/TerminalTraffic"
              }
            },
            "terminal_total": {
              "type": "integer",
              "description": "终端总数量",
              "minimum": 0,
              "example": 10
            },
            "terminal_total_flow": {
              "type": "integer",
              "format": "int64",
              "description": "所有终端当日总流量（字节）",
              "minimum": 0,
              "example": 7006058917
            }
          },
          "required": [
            "terminal"
          ],
          "additionalProperties": false
        },
        "TerminalTraffic": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ip_addr",
            "sum_total",
            "sum_total_up",
            "sum_total_down"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "终端ID",
              "minimum": 1,
              "example": 1
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:01:7e:7c"
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IP地址",
              "format": "ipv4",
              "example": "192.168.9.199"
            },
            "username": {
              "type": "string",
              "description": "终端绑定用户名",
              "example": "testuser"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "我的电脑"
            },
            "icon": {
              "type": "string",
              "description": "终端图标标识",
              "maxLength": 50,
              "example": "1_107"
            },
            "sum_total": {
              "type": "integer",
              "format": "int64",
              "description": "当日总流量（字节）",
              "minimum": 0,
              "example": 7006058917
            },
            "sum_total_up": {
              "type": "integer",
              "format": "int64",
              "description": "当日上行流量（字节）",
              "minimum": 0,
              "example": 4546140370
            },
            "sum_total_down": {
              "type": "integer",
              "format": "int64",
              "description": "当日下行流量（字节）",
              "minimum": 0,
              "example": 2459918547
            }
          },
          "additionalProperties": false
        },
        "ClientStreamResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ClientStreamResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ClientStreamResults": {
          "type": "object",
          "properties": {
            "terminal_stream_collect": {
              "type": "array",
              "description": "终端流量监控数据列表（5秒一个数据点，共300个）",
              "items": {
                "$ref": "#/components/schemas/ClientStream"
              }
            }
          },
          "required": [
            "terminal_stream_collect"
          ],
          "additionalProperties": false
        },
        "ClientStream": {
          "type": "object",
          "required": [
            "timestamp",
            "upload",
            "download",
            "conn_num"
          ],
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1773304236
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上传速率（字节/秒）",
              "minimum": 0,
              "example": 7402
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下载速率（字节/秒）",
              "minimum": 0,
              "example": 78335
            },
            "conn_num": {
              "type": "string",
              "description": "连接数",
              "pattern": "^[0-9]*$",
              "example": "177"
            }
          },
          "additionalProperties": false
        },
        "ClientProtocolsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ClientProtocolsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ClientProtocolsResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "终端协议分类流量列表",
              "items": {
                "$ref": "#/components/schemas/ClientProtocolItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "ClientProtocolItem": {
          "type": "object",
          "required": [
            "id",
            "total",
            "proto",
            "proto_name"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "总流量（字节）",
              "minimum": 0,
              "example": 2635725
            },
            "proto": {
              "type": "string",
              "description": "协议分类ID范围",
              "example": "4:7"
            },
            "proto_name": {
              "type": "string",
              "description": "协议分类名称",
              "maxLength": 100,
              "example": "未知应用"
            }
          },
          "additionalProperties": false
        },
        "ClientProtocolHistoryLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ClientProtocolHistoryLoadResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ClientProtocolHistoryLoadResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "终端协议分类历史速率数据列表",
              "items": {
                "$ref": "#/components/schemas/ClientProtocolHistoryLoadItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "ClientProtocolHistoryLoadItem": {
          "type": "object",
          "required": [
            "id",
            "proto",
            "timestamp",
            "upload",
            "download"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "proto": {
              "type": "string",
              "description": "协议分类ID范围",
              "example": "1000000:1499999"
            },
            "proto_name": {
              "type": "string",
              "description": "协议分类名称",
              "maxLength": 100,
              "example": "网络协议"
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1773287100
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上行速率（字节/秒）",
              "minimum": 0,
              "example": 1899
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下行速率（字节/秒）",
              "minimum": 0,
              "example": 2683
            }
          },
          "additionalProperties": false
        },
        "ClientAppProtocolsLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ClientAppProtocolsLoadResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ClientAppProtocolsLoadResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "终端当前应用协议速率列表",
              "items": {
                "$ref": "#/components/schemas/ClientAppProtocolLoadItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "ClientAppProtocolLoadItem": {
          "type": "object",
          "required": [
            "id",
            "appid",
            "app_name",
            "proto1_name",
            "proto2_name",
            "conn_cnt",
            "upload",
            "download",
            "total",
            "total_up",
            "total_down",
            "rules"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "appid": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议ID",
              "minimum": 1,
              "example": 5030009
            },
            "app_name": {
              "type": "string",
              "description": "应用协议名称",
              "maxLength": 100,
              "example": "今日头条"
            },
            "proto1_name": {
              "type": "string",
              "description": "一级协议分类ID范围",
              "example": "5000000:5499999"
            },
            "proto2_name": {
              "type": "string",
              "description": "二级协议分类ID范围",
              "example": "5030001:5040000"
            },
            "conn_cnt": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上行速率（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下行速率（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "总流量（字节）",
              "minimum": 0,
              "example": 170
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "上行流量（字节）",
              "minimum": 0,
              "example": 100
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "下行流量（字节）",
              "minimum": 0,
              "example": 70
            },
            "rules": {
              "type": "object",
              "description": "规则信息",
              "additionalProperties": true,
              "example": {}
            }
          },
          "additionalProperties": false
        },
        "Ip6OnlineClientsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/Ip6OnlineClientsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Ip6OnlineClientsResults": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            },
            "data": {
              "type": "array",
              "description": "IPv6在线终端列表",
              "items": {
                "$ref": "#/components/schemas/Ip6OnlineClient"
              }
            }
          },
          "required": [
            "total",
            "data"
          ],
          "additionalProperties": false
        },
        "Ip6OnlineClient": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ip_addr",
            "timestamp",
            "total_up",
            "total_down",
            "connect_num",
            "upload",
            "download",
            "uplink_dev",
            "uplink_addr",
            "apname",
            "bssid",
            "termname",
            "comment",
            "static_status",
            "client_type",
            "client_typeid",
            "interface",
            "auth_type",
            "vlan_id",
            "uptime",
            "username",
            "ppptype",
            "apmac",
            "today_total",
            "client_vendor",
            "client_model",
            "device_type",
            "reject",
            "frequencies",
            "uprate",
            "downrate",
            "enc",
            "ipv4_gnames",
            "ipv6_gnames",
            "mac_gnames",
            "dtalk_name",
            "link_addr",
            "webid",
            "device_icon",
            "vendor_icon",
            "ac_gid",
            "signal",
            "channel"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "终端ID",
              "minimum": 1,
              "example": 1
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "1a:00:9c:10:f1:5c"
            },
            "ssid": {
              "type": "string",
              "description": "SSID名称（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "ip_addr_int": {
              "type": "integer",
              "format": "int64",
              "description": "终端IP地址（整数格式，IPv6时为0）",
              "minimum": 0,
              "example": 0
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IPv6地址",
              "example": "2408:8207:3053:bc21:1800:9cff:fe10:f15c"
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1773394260
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "总上传字节数",
              "minimum": 0,
              "example": 96
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "总下载字节数",
              "minimum": 0,
              "example": 110
            },
            "connect_num": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "description": "实时上传速率（B/s）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "实时下载速率（B/s）",
              "minimum": 0,
              "example": 0
            },
            "uplink_dev": {
              "type": "string",
              "description": "上行设备名称",
              "maxLength": 100,
              "example": "1.253"
            },
            "uplink_addr": {
              "type": "string",
              "description": "上行设备MAC地址",
              "maxLength": 100,
              "example": "00:e2:59:00:68:4e"
            },
            "apname": {
              "type": "string",
              "description": "AP名称（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "bssid": {
              "type": "string",
              "description": "AP的BSSID（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 200,
              "example": "测试部Ubuntu"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "测试部Ubuntu"
            },
            "static_status": {
              "type": "integer",
              "description": "静态状态 (0=动态, 1=静态)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "client_type": {
              "type": "string",
              "description": "终端类型",
              "maxLength": 50,
              "example": "Unknown"
            },
            "client_typeid": {
              "type": "integer",
              "format": "int64",
              "description": "终端类型ID",
              "minimum": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "vlan5"
            },
            "signal": {
              "type": "integer",
              "description": "信号强度（无线连接时有效，0表示无信号）",
              "example": 0
            },
            "channel": {
              "type": "string",
              "description": "无线信道（无线连接时有效，有线终端显示\"--\"）",
              "maxLength": 20,
              "example": "--"
            },
            "auth_type": {
              "type": "integer",
              "description": "认证类型",
              "minimum": 0,
              "example": 0
            },
            "vlan_id": {
              "type": "integer",
              "description": "VLAN ID",
              "minimum": 0,
              "example": 0
            },
            "uptime": {
              "type": "string",
              "description": "上线时间",
              "maxLength": 50,
              "example": "2026-03-13 17:31:00"
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "maxLength": 100,
              "example": ""
            },
            "ppptype": {
              "type": "string",
              "description": "PPPoE类型或IP获取方式",
              "maxLength": 50,
              "example": ""
            },
            "apmac": {
              "type": "string",
              "description": "AP的MAC地址（无线连接时有效）",
              "maxLength": 100,
              "example": ""
            },
            "today_total": {
              "type": "integer",
              "format": "int64",
              "description": "今日总流量（字节）",
              "minimum": 0,
              "example": 24514
            },
            "client_vendor": {
              "type": "string",
              "description": "客户端厂商",
              "maxLength": 100,
              "example": "Unknown"
            },
            "client_model": {
              "type": "string",
              "description": "客户端型号",
              "maxLength": 100,
              "example": ""
            },
            "device_type": {
              "type": "string",
              "description": "设备类型",
              "maxLength": 100,
              "example": ""
            },
            "reject": {
              "type": "integer",
              "description": "拒绝状态 (0=不拒绝, 1=拒绝)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "frequencies": {
              "type": "string",
              "description": "频率信息（无线连接时有效）",
              "maxLength": 50,
              "example": ""
            },
            "uprate": {
              "type": "string",
              "description": "上行速率信息",
              "maxLength": 50,
              "example": ""
            },
            "downrate": {
              "type": "string",
              "description": "下行速率信息",
              "maxLength": 50,
              "example": ""
            },
            "enc": {
              "type": "string",
              "description": "加密信息（无线连接时有效）",
              "maxLength": 50,
              "example": ""
            },
            "ipv4_gnames": {
              "type": "string",
              "description": "IPv4组名称",
              "maxLength": 200,
              "example": ""
            },
            "ipv6_gnames": {
              "type": "string",
              "description": "IPv6组名称",
              "maxLength": 200,
              "example": ""
            },
            "mac_gnames": {
              "type": "string",
              "description": "MAC组名称",
              "maxLength": 200,
              "example": ""
            },
            "dtalk_name": {
              "type": "string",
              "description": "D-Talk名称",
              "maxLength": 100,
              "example": ""
            },
            "link_addr": {
              "type": "string",
              "description": "链路本地地址",
              "maxLength": 100,
              "example": "fe80::1800:9cff:fe10:f15c"
            },
            "webid": {
              "type": "integer",
              "description": "Web认证ID",
              "minimum": 0,
              "example": 0
            },
            "device_icon": {
              "type": "string",
              "description": "设备图标标识",
              "maxLength": 50,
              "example": ""
            },
            "vendor_icon": {
              "type": "string",
              "description": "厂商图标标识",
              "maxLength": 50,
              "example": ""
            },
            "ac_gid": {
              "type": "integer",
              "description": "AC组ID",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "Ip6OfflineClientsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/Ip6OfflineClientsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Ip6OfflineClientsResults": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            },
            "offline_data": {
              "type": "array",
              "description": "IPv6离线终端列表",
              "items": {
                "$ref": "#/components/schemas/Ip6OfflineClient"
              }
            }
          },
          "required": [
            "total",
            "offline_data"
          ],
          "additionalProperties": false
        },
        "Ip6OfflineClient": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ip_addr",
            "logout_time",
            "total_up",
            "total_down",
            "today_total",
            "client_type",
            "client_typeid",
            "device_type",
            "device_icon",
            "auth",
            "ipv4_gnames",
            "ipv6_gnames",
            "mac_gnames",
            "dtalk_name",
            "termname",
            "comment",
            "username",
            "client_vendor",
            "client_model",
            "vlan_id"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "终端ID",
              "minimum": 1,
              "example": 1
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "00:71:6f:a6:0c:2d"
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IPv6地址",
              "example": "2408:8207:3053:bb90:0271:6fff:fea6:0c2d"
            },
            "logout_time": {
              "type": "integer",
              "format": "int64",
              "description": "下线时间戳（Unix时间戳）",
              "example": 1773390540
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "总上传字节数",
              "minimum": 0,
              "example": 4769559
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "总下载字节数",
              "minimum": 0,
              "example": 21154347
            },
            "today_total": {
              "type": "integer",
              "format": "int64",
              "description": "今日总流量（字节）",
              "minimum": 0,
              "example": 8370425
            },
            "client_type": {
              "type": "string",
              "description": "终端类型",
              "maxLength": 50,
              "example": "iKuaiOS"
            },
            "client_typeid": {
              "type": "integer",
              "format": "int64",
              "description": "终端类型ID",
              "minimum": 0,
              "example": 107998006
            },
            "device_type": {
              "type": "string",
              "description": "设备类型",
              "maxLength": 100,
              "example": ""
            },
            "device_icon": {
              "type": "string",
              "description": "设备图标标识",
              "maxLength": 50,
              "example": "1_107"
            },
            "auth": {
              "type": "integer",
              "description": "认证状态 (0=未认证, 1=已认证)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ipv4_gnames": {
              "type": "string",
              "description": "IPv4组名称",
              "maxLength": 200,
              "example": ""
            },
            "ipv6_gnames": {
              "type": "string",
              "description": "IPv6组名称",
              "maxLength": 200,
              "example": ""
            },
            "mac_gnames": {
              "type": "string",
              "description": "MAC组名称",
              "maxLength": 200,
              "example": ""
            },
            "dtalk_name": {
              "type": "string",
              "description": "D-Talk名称",
              "maxLength": 100,
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 200,
              "example": ""
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "maxLength": 100,
              "example": ""
            },
            "client_vendor": {
              "type": "string",
              "description": "客户端厂商",
              "maxLength": 100,
              "example": "iKuai"
            },
            "client_model": {
              "type": "string",
              "description": "客户端型号",
              "maxLength": 100,
              "example": "iKuai路由器"
            },
            "vlan_id": {
              "type": "integer",
              "description": "VLAN ID",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-clients",
        "x-displayName": "终端监控",
        "description": "终端状态和流量监控，包括在线/离线统计、实时速率、协议分类流量及应用协议速率查询"
      }
    ]
  },
  "monitor/monitor-flow-shunting.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "分流监控API",
      "version": "1.0.0",
      "summary": "分流监控统计查询",
      "description": "提供分流监控的统计查询功能，包括：\n- 端口分流连接数统计\n- 协议分流连接数统计\n- 域名分流连接数统计\n- 多时间维度数据（今日、昨日、最近7天）\n\n**分流类型说明：**\n- 端口分流：基于端口的流量分流\n- 协议分流：基于L7协议识别的流量分流\n- 域名分流：基于域名的流量分流\n- 未分流：未被任何分流策略匹配的连接\n\n**数据更新：** 每3分钟自动更新\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/flow-shunting": {
        "get": {
          "summary": "查询分流统计数据",
          "description": "查询分流监控统计数据，包含今日、昨日、最近7天的连接数统计。\n\n**TYPE 参数：**\n- `data`: 统计数据（默认）\n",
          "operationId": "getFlowShuntingStats",
          "tags": [
            "monitor-flow-shunting"
          ],
          "parameters": [
            {
              "name": "TYPE",
              "in": "query",
              "description": "返回数据类型",
              "schema": {
                "type": "string",
                "enum": [
                  "data"
                ],
                "default": "data"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功返回统计数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/FlowShuntingResponse"
                  },
                  "examples": {
                    "success": {
                      "value": {
                        "results": {
                          "data": {
                            "today": {
                              "llb_cnt": 100,
                              "port_cnt": 50,
                              "proto_cnt": 30,
                              "domain_cnt": 20,
                              "conn_cnt": 200
                            },
                            "yesterday": {
                              "llb_cnt": 120,
                              "port_cnt": 60,
                              "proto_cnt": 35,
                              "domain_cnt": 25,
                              "conn_cnt": 240
                            },
                            "week": {
                              "llb_cnt": 700,
                              "port_cnt": 350,
                              "proto_cnt": 210,
                              "domain_cnt": 140,
                              "conn_cnt": 1400
                            }
                          },
                          "clean_time": 1646822400
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            }
          }
        }
      }
    },
    "components": {
      "schemas": {
        "FlowShuntingStats": {
          "type": "object",
          "description": "分流统计数据",
          "properties": {
            "llb_cnt": {
              "type": "integer",
              "description": "负载均衡连接数"
            },
            "port_cnt": {
              "type": "integer",
              "description": "端口分流连接数"
            },
            "proto_cnt": {
              "type": "integer",
              "description": "协议分流连接数"
            },
            "domain_cnt": {
              "type": "integer",
              "description": "域名分流连接数"
            },
            "conn_cnt": {
              "type": "integer",
              "description": "总连接数"
            }
          }
        },
        "FlowShuntingResponse": {
          "type": "object",
          "properties": {
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "object",
                  "description": "统计数据",
                  "properties": {
                    "today": {
                      "$ref": "#/components/schemas/FlowShuntingStats"
                    },
                    "yesterday": {
                      "$ref": "#/components/schemas/FlowShuntingStats"
                    },
                    "week": {
                      "$ref": "#/components/schemas/FlowShuntingStats"
                    }
                  }
                },
                "clean_time": {
                  "type": "integer",
                  "description": "上次清空时间戳",
                  "format": "int64"
                }
              }
            }
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求参数错误",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 400
                  },
                  "message": {
                    "type": "string",
                    "example": "参数错误"
                  }
                }
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 401
                  },
                  "message": {
                    "type": "string",
                    "example": "未认证或凭证无效"
                  }
                }
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-flow-shunting",
        "x-displayName": "分流监控",
        "description": "分流监控统计查询"
      }
    ]
  },
  "monitor/monitor-interfaces.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "接口监控管理API",
      "version": "1.0.0",
      "summary": "接口状态和流量监控的完整功能",
      "description": "提供网络接口监控的完整功能，包括：\n- 线路状态监控\n- 线路最近24小时流量负载监控\n- 内外网接口（wan/lan）配置监控\n- 物理网卡列表及属性信息查询\n- IPv6线路详情查询\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/interfaces-status": {
        "get": {
          "summary": "获取线路状态监控",
          "description": "获取所有网络接口的线路状态信息，包括线路检查结果（iface_check）和\n流量统计信息（iface_stream）。包含连接状态、IP地址、网关、\n线路检测结果、自动切换状态、实时流量等详细信息。\n不支持query参数。\n",
          "operationId": "getInterfaceStatus",
          "tags": [
            "monitor-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取接口状态监控数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/InterfaceStatusResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "iface_check": [
                        {
                          "id": 1,
                          "interface": "wan1",
                          "parent_interface": "wan1",
                          "ip_addr": "192.168.99.102",
                          "gateway": "192.168.99.1",
                          "internet": "DHCP",
                          "updatetime": "1763805119",
                          "auto_switch": "已启用",
                          "result": "success",
                          "errmsg": "线路检测成功",
                          "comment": ""
                        },
                        {
                          "id": 2,
                          "interface": "wan2",
                          "parent_interface": "wan2",
                          "ip_addr": "192.168.33.2",
                          "gateway": "192.168.33.1",
                          "internet": "DHCP",
                          "updatetime": "1763804872",
                          "auto_switch": "已启用",
                          "result": "success",
                          "errmsg": "线路检测成功",
                          "comment": ""
                        }
                      ],
                      "iface_stream": [
                        {
                          "interface": "lan1",
                          "comment": "",
                          "ip_addr": "192.168.9.1",
                          "connect_num": "--",
                          "upload": 41,
                          "download": 0,
                          "total_up": 18937856,
                          "total_down": 99567308,
                          "updropped": 0,
                          "downdropped": 0,
                          "uppacked": 107050,
                          "downpacked": 58957
                        },
                        {
                          "interface": "wan1",
                          "comment": "",
                          "ip_addr": "192.168.99.102",
                          "connect_num": "1",
                          "upload": 2406,
                          "download": 2017,
                          "total_up": 52160182,
                          "total_down": 198655160,
                          "updropped": 0,
                          "downdropped": 0,
                          "uppacked": 118002,
                          "downpacked": 142353
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/interfaces-traffic": {
        "get": {
          "summary": "获取线路最近24小时流量负载监控",
          "description": "获取线路最近24小时的流量统计数据，包括最大/平均上传下载速率、\n丢包率、往返时延等网络质量指标。支持多线路汇总数据。\n不支持limit、page、order、key、pattern、filter参数。\n",
          "operationId": "getInterfacesTraffic",
          "tags": [
            "monitor-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取线路流量监控数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/InterfacesTrafficResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "wans_stat_history": [
                        {
                          "max_upload": "1.22",
                          "max_download": "1.08",
                          "drop_rate": "0.00",
                          "avg_rtt": 6.64,
                          "max_rtt": 8.64,
                          "id": 828,
                          "timestamp": 1764152100,
                          "interface": "all",
                          "avg_upload": "0.95",
                          "min_rtt": 5.95,
                          "avg_download": "0.85"
                        },
                        {
                          "max_upload": "1.22",
                          "max_download": "1.08",
                          "drop_rate": "0.00",
                          "avg_rtt": 6.35,
                          "max_rtt": 6.69,
                          "id": 826,
                          "timestamp": 1764152100,
                          "interface": "wan1",
                          "avg_upload": "0.95",
                          "min_rtt": 5.95,
                          "avg_download": "0.85"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/interfaces-config": {
        "get": {
          "summary": "获取内外网接口配置监控",
          "description": "获取内网（LAN）和外网（WAN）接口的配置快照信息，包括接口名称、\nMAC地址、IP地址、子网掩码、网关、DNS、接入模式、绑定模式等详细配置。\n",
          "operationId": "getInterfacesConfig",
          "tags": [
            "monitor-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取内外网接口配置监控数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/InterfacesConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "snapshoot_lan": [
                        {
                          "id": 1,
                          "comment": "",
                          "interface": "lan1",
                          "bandmode": 0,
                          "linkmode": 4,
                          "mac": "00:e2:59:00:68:4e",
                          "member": [
                            "eth0"
                          ],
                          "ip_addr": "192.168.1.253",
                          "netmask": "255.255.254.0"
                        },
                        {
                          "id": 2,
                          "comment": "",
                          "interface": "lan2",
                          "bandmode": 0,
                          "linkmode": 4,
                          "mac": "00:e2:59:00:68:4f",
                          "member": [
                            "eth1",
                            "eth2"
                          ],
                          "ip_addr": "192.168.29.253",
                          "netmask": "255.255.255.0"
                        }
                      ],
                      "snapshoot_wan": [
                        {
                          "id": 1,
                          "comment": "wan1",
                          "interface": "wan1",
                          "mac": "00:e2:59:00:68:53",
                          "member": [
                            "eth5"
                          ],
                          "bandmode": 0,
                          "linkmode": 4,
                          "default_route": 1,
                          "internet": 2,
                          "ip_addr": "114.241.221.239",
                          "netmask": "255.255.255.255",
                          "gateway": "114.241.208.1",
                          "dns1": "202.106.46.151",
                          "dns2": "202.106.195.68",
                          "count_static": 0,
                          "count_dhcp": 0,
                          "count_pppoe": 0,
                          "count_check_fail": 0,
                          "updatetime": 1773147772,
                          "check_res": 0,
                          "errmsg": "线路检测成功",
                          "power": "",
                          "isp": "",
                          "imei": "",
                          "qnw": "",
                          "ccid": "",
                          "isnr": "",
                          "pcid": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/interfaces-physical": {
        "get": {
          "summary": "获取物理网卡列表",
          "description": "查询物理网卡列表和网卡对应的属性信息，包括驱动、网卡类型、\nMAC地址、连接状态、协商速率、双工模式、网卡型号及所属接口等。\n",
          "operationId": "listPhysicalInterfaces",
          "tags": [
            "monitor-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取物理网卡列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PhysicalInterfacesResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "ether_info": {
                        "eth0": {
                          "driver": "igb",
                          "type": "TP",
                          "mac": "00:e2:69:00:89:e5",
                          "link": 1,
                          "speed": 100,
                          "duplex": 1,
                          "model": "Intel Corporation I211 Gigabit Network Connection",
                          "interface": "lan1",
                          "lock": 0,
                          "bindmod": 0
                        },
                        "eth1": {
                          "driver": "igb",
                          "type": "TP",
                          "mac": "00:e2:69:00:89:e6",
                          "link": 1,
                          "speed": 1000,
                          "duplex": 1,
                          "model": "Intel Corporation I211 Gigabit Network Connection",
                          "interface": "lan1",
                          "lock": 0,
                          "bindmod": 0
                        },
                        "vnet": {
                          "driver": "kvm",
                          "type": "TP",
                          "mac": "00:00:00:00:00:00",
                          "link": 1,
                          "speed": 1000,
                          "duplex": 1,
                          "model": "Kvm Virtual Bridge Enternet Controller",
                          "interface": "Null",
                          "lock": 0,
                          "bindmod": 0
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/interfaces-traffic-v6": {
        "get": {
          "summary": "获取IPv6线路详情",
          "description": "查询IPv6线路详情，包括wan线路IPv6的转发流量负载，\n包含连接数、上行速率、下行速率、总上行流量、总下行流量等信息。\n",
          "operationId": "getInterfacesTrafficV6",
          "tags": [
            "monitor-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取IPv6线路详情数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/InterfacesTrafficV6Response"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "download": 0,
                          "interface": "vwan666",
                          "conn": 0,
                          "upload": 0,
                          "id": 1,
                          "total_upload": "0",
                          "total_download": "0"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "InterfaceStatusResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/InterfaceStatusResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "InterfaceStatusResults": {
          "type": "object",
          "properties": {
            "iface_check": {
              "type": "array",
              "description": "接口状态检查列表",
              "items": {
                "$ref": "#/components/schemas/InterfaceCheck"
              }
            },
            "iface_stream": {
              "type": "array",
              "description": "接口流量统计列表",
              "items": {
                "$ref": "#/components/schemas/InterfaceStream"
              }
            }
          },
          "required": [
            "iface_check",
            "iface_stream"
          ],
          "additionalProperties": false
        },
        "InterfaceCheck": {
          "type": "object",
          "required": [
            "id",
            "interface",
            "parent_interface",
            "ip_addr",
            "gateway",
            "internet",
            "updatetime",
            "auto_switch",
            "result",
            "errmsg",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "接口ID",
              "minimum": 1,
              "example": 1
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "wan1"
            },
            "parent_interface": {
              "type": "string",
              "description": "父接口名称",
              "maxLength": 50,
              "example": "wan1"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.99.102"
            },
            "gateway": {
              "type": "string",
              "description": "网关地址",
              "format": "ipv4",
              "example": "192.168.99.1"
            },
            "internet": {
              "type": "string",
              "description": "接入方式",
              "enum": [
                "DHCP",
                "PPPoE",
                "Static",
                "--"
              ],
              "example": "DHCP"
            },
            "updatetime": {
              "type": "string",
              "description": "更新时间戳（Unix时间戳字符串）",
              "example": "1763805119"
            },
            "auto_switch": {
              "type": "string",
              "description": "线路自动切换开关状态",
              "enum": [
                "已启用",
                "已停用"
              ],
              "example": "已启用"
            },
            "result": {
              "type": "string",
              "description": "检测结果",
              "enum": [
                "success",
                "failed"
              ],
              "example": "success"
            },
            "errmsg": {
              "type": "string",
              "description": "错误消息或检测信息",
              "maxLength": 200,
              "example": "线路检测成功"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "InterfaceStream": {
          "type": "object",
          "required": [
            "interface",
            "ip_addr",
            "connect_num",
            "upload",
            "download",
            "total_up",
            "total_down",
            "updropped",
            "downdropped",
            "uppacked",
            "downpacked",
            "comment"
          ],
          "properties": {
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "lan1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.9.1"
            },
            "connect_num": {
              "type": "string",
              "description": "连接数（lan接口为--）",
              "example": "1"
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "实时上传速率（B/s）",
              "minimum": 0,
              "example": 2406
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "实时下载速率（B/s）",
              "minimum": 0,
              "example": 2017
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "总上传字节数",
              "minimum": 0,
              "example": 52160182
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "总下载字节数",
              "minimum": 0,
              "example": 198655160
            },
            "updropped": {
              "type": "integer",
              "format": "int64",
              "description": "上行丢弃包数",
              "minimum": 0,
              "example": 0
            },
            "downdropped": {
              "type": "integer",
              "format": "int64",
              "description": "下行丢弃包数",
              "minimum": 0,
              "example": 0
            },
            "uppacked": {
              "type": "integer",
              "format": "int64",
              "description": "上行包数",
              "minimum": 0,
              "example": 118002
            },
            "downpacked": {
              "type": "integer",
              "format": "int64",
              "description": "下行包数",
              "minimum": 0,
              "example": 142353
            }
          },
          "additionalProperties": false
        },
        "InterfacesTrafficResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/InterfacesTrafficResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "InterfacesTrafficResults": {
          "type": "object",
          "properties": {
            "wans_stat_history": {
              "type": "array",
              "description": "线路流量历史数据列表",
              "items": {
                "$ref": "#/components/schemas/WanStatHistory"
              }
            }
          },
          "required": [
            "wans_stat_history"
          ],
          "additionalProperties": false
        },
        "WanStatHistory": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "interface",
            "avg_upload",
            "max_upload",
            "avg_download",
            "max_download",
            "drop_rate",
            "avg_rtt",
            "min_rtt",
            "max_rtt"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 828
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1764152100
            },
            "interface": {
              "type": "string",
              "description": "接口名称，all代表所有线路的统计",
              "maxLength": 50,
              "example": "all"
            },
            "avg_upload": {
              "type": "string",
              "description": "平均上行速率（KB/s）",
              "pattern": "^[0-9]+(\\.[0-9]+)?$",
              "example": "0.95"
            },
            "max_upload": {
              "type": "string",
              "description": "最大上行速率（KB/s）",
              "pattern": "^[0-9]+(\\.[0-9]+)?$",
              "example": "1.22"
            },
            "avg_download": {
              "type": "string",
              "description": "平均下行速率（KB/s）",
              "pattern": "^[0-9]+(\\.[0-9]+)?$",
              "example": "0.85"
            },
            "max_download": {
              "type": "string",
              "description": "最大下行速率（KB/s）",
              "pattern": "^[0-9]+(\\.[0-9]+)?$",
              "example": "1.08"
            },
            "drop_rate": {
              "type": "string",
              "description": "丢包率",
              "pattern": "^[0-9]+(\\.[0-9]+)?$",
              "example": "0.00"
            },
            "avg_rtt": {
              "type": "number",
              "format": "float",
              "description": "平均往返时延（ms）",
              "minimum": 0,
              "example": 6.64
            },
            "min_rtt": {
              "type": "number",
              "format": "float",
              "description": "最小往返时延（ms）",
              "minimum": 0,
              "example": 5.95
            },
            "max_rtt": {
              "type": "number",
              "format": "float",
              "description": "最大往返时延（ms）",
              "minimum": 0,
              "example": 8.64
            }
          },
          "additionalProperties": false
        },
        "InterfacesConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/InterfacesConfigResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "InterfacesConfigResults": {
          "type": "object",
          "properties": {
            "snapshoot_lan": {
              "type": "array",
              "description": "LAN接口配置快照列表",
              "items": {
                "$ref": "#/components/schemas/LanInterfaceConfig"
              }
            },
            "snapshoot_wan": {
              "type": "array",
              "description": "WAN接口配置快照列表",
              "items": {
                "$ref": "#/components/schemas/WanInterfaceConfig"
              }
            }
          },
          "required": [
            "snapshoot_lan",
            "snapshoot_wan"
          ],
          "additionalProperties": false
        },
        "LanInterfaceConfig": {
          "type": "object",
          "required": [
            "id",
            "comment",
            "interface",
            "bandmode",
            "linkmode",
            "mac",
            "member",
            "ip_addr",
            "netmask"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "接口ID",
              "minimum": 1,
              "example": 1
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "lan1"
            },
            "bandmode": {
              "type": "integer",
              "description": "绑定模式 (0=网桥, 1=汇聚)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "linkmode": {
              "type": "integer",
              "description": "链路聚合模式，bandmode=1时有效 (2=手工链路聚合, 4=LACP链路聚合)",
              "enum": [
                2,
                4
              ],
              "example": 4
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$",
              "example": "00:e2:59:00:68:4e"
            },
            "member": {
              "type": "array",
              "description": "网卡成员列表",
              "items": {
                "type": "string",
                "example": "eth0"
              },
              "example": [
                "eth0"
              ]
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.1.253"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.254.0"
            }
          },
          "additionalProperties": false
        },
        "WanInterfaceConfig": {
          "type": "object",
          "required": [
            "id",
            "comment",
            "interface",
            "mac",
            "member",
            "bandmode",
            "default_route",
            "internet",
            "ip_addr",
            "netmask",
            "gateway",
            "dns1",
            "dns2",
            "count_static",
            "count_dhcp",
            "count_pppoe",
            "count_check_fail",
            "updatetime",
            "check_res",
            "errmsg"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "接口ID",
              "minimum": 1,
              "example": 1
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "wan1"
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "wan1"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$",
              "example": "00:e2:59:00:68:53"
            },
            "member": {
              "type": "array",
              "description": "网卡成员列表",
              "items": {
                "type": "string",
                "example": "eth5"
              },
              "example": [
                "eth5"
              ]
            },
            "bandmode": {
              "type": "integer",
              "description": "绑定模式 (0=网桥, 1=汇聚)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "linkmode": {
              "type": "integer",
              "description": "链路聚合模式，bandmode=1时有效 (2=手工链路聚合, 4=LACP链路聚合)",
              "enum": [
                2,
                4
              ],
              "example": 4
            },
            "default_route": {
              "type": "integer",
              "description": "当前接口是否为默认路由 (0=否, 1=是)",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "internet": {
              "type": "integer",
              "description": "接入模式 (0=静态IP, 1=DHCP, 2=ADSL/PPPoE, 3=基于物理网卡的混合模式, 4=基于vlan的混合模式)",
              "enum": [
                0,
                1,
                2,
                3,
                4
              ],
              "example": 2
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "114.241.221.239"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.255.255"
            },
            "gateway": {
              "type": "string",
              "description": "网关",
              "format": "ipv4",
              "example": "114.241.208.1"
            },
            "dns1": {
              "type": "string",
              "description": "DNS1",
              "format": "ipv4",
              "example": "202.106.46.151"
            },
            "dns2": {
              "type": "string",
              "description": "DNS2",
              "format": "ipv4",
              "example": "202.106.195.68"
            },
            "count_static": {
              "type": "integer",
              "description": "静态IP数量（接入模式为3或4时有效）",
              "minimum": 0,
              "example": 0
            },
            "count_dhcp": {
              "type": "integer",
              "description": "DHCP数量（接入模式为3或4时有效）",
              "minimum": 0,
              "example": 0
            },
            "count_pppoe": {
              "type": "integer",
              "description": "ADSL/PPPoE数量（接入模式为3或4时有效）",
              "minimum": 0,
              "example": 0
            },
            "count_check_fail": {
              "type": "integer",
              "description": "线路检测失败次数",
              "minimum": 0,
              "example": 0
            },
            "updatetime": {
              "type": "integer",
              "format": "int64",
              "description": "更新时间戳（Unix时间戳）",
              "example": 1773147772
            },
            "check_res": {
              "type": "integer",
              "description": "线路检测结果码",
              "example": 0
            },
            "errmsg": {
              "type": "string",
              "description": "线路连通性检测信息",
              "maxLength": 200,
              "example": "线路检测成功"
            },
            "power": {
              "type": "string",
              "description": "信号强度（4G模块有效）",
              "example": ""
            },
            "isp": {
              "type": "string",
              "description": "运营商信息（4G模块有效）",
              "example": ""
            },
            "imei": {
              "type": "string",
              "description": "IMEI号（4G模块有效）",
              "example": ""
            },
            "qnw": {
              "type": "string",
              "description": "网络制式（4G模块有效）",
              "example": ""
            },
            "ccid": {
              "type": "string",
              "description": "SIM卡CCID（4G模块有效）",
              "example": ""
            },
            "isnr": {
              "type": "string",
              "description": "信噪比（4G模块有效）",
              "example": ""
            },
            "pcid": {
              "type": "string",
              "description": "小区ID（4G模块有效）",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "PhysicalInterfacesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/PhysicalInterfacesResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PhysicalInterfacesResults": {
          "type": "object",
          "properties": {
            "ether_info": {
              "type": "object",
              "description": "物理网卡信息，key为网卡名称（如eth0、eth1、vnet等）",
              "additionalProperties": {
                "$ref": "#/components/schemas/EtherInfo"
              }
            }
          },
          "required": [
            "ether_info"
          ],
          "additionalProperties": false
        },
        "EtherInfo": {
          "type": "object",
          "required": [
            "driver",
            "type",
            "mac",
            "link",
            "speed",
            "duplex",
            "model",
            "interface",
            "lock",
            "bindmod"
          ],
          "properties": {
            "driver": {
              "type": "string",
              "description": "网卡驱动",
              "example": "igb"
            },
            "type": {
              "type": "string",
              "description": "网卡类型 (TP=电口, FIBRE=光口, USB, LTE, KVM, WIFI)",
              "enum": [
                "TP",
                "FIBRE",
                "USB",
                "LTE",
                "KVM",
                "WIFI"
              ],
              "example": "TP"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$",
              "example": "00:e2:69:00:89:e5"
            },
            "link": {
              "type": "integer",
              "description": "网卡状态 (0=离线, 1=在线)",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "speed": {
              "type": "integer",
              "description": "网卡协商速率（Mbps）",
              "minimum": 0,
              "example": 1000
            },
            "duplex": {
              "type": "integer",
              "description": "网卡双工模式 (0=半双工, 1=全双工)",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "model": {
              "type": "string",
              "description": "网卡型号",
              "example": "Intel Corporation I211 Gigabit Network Connection"
            },
            "interface": {
              "type": "string",
              "description": "网卡所属接口名称",
              "maxLength": 50,
              "example": "lan1"
            },
            "lock": {
              "type": "integer",
              "description": "网卡锁定状态",
              "example": 0
            },
            "bindmod": {
              "type": "integer",
              "description": "网卡绑定模式 (0=网桥, 1=汇聚)",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "InterfacesTrafficV6Response": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/InterfacesTrafficV6Results"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "InterfacesTrafficV6Results": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "总记录数",
              "minimum": 0,
              "example": 1
            },
            "data": {
              "type": "array",
              "description": "IPv6线路流量数据列表",
              "items": {
                "$ref": "#/components/schemas/InterfaceTrafficV6"
              }
            }
          },
          "required": [
            "total",
            "data"
          ],
          "additionalProperties": false
        },
        "InterfaceTrafficV6": {
          "type": "object",
          "required": [
            "id",
            "interface",
            "conn",
            "upload",
            "download",
            "total_upload",
            "total_download"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "vwan666"
            },
            "conn": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上行速率（B/s）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下行速率（B/s）",
              "minimum": 0,
              "example": 0
            },
            "total_upload": {
              "type": "string",
              "description": "总上行流量",
              "example": "0"
            },
            "total_download": {
              "type": "string",
              "description": "总下行流量",
              "example": "0"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-interfaces",
        "x-displayName": "接口监控",
        "description": "网络接口状态和流量监控，支持线路状态、流量统计、接口配置及物理网卡查询"
      }
    ]
  },
  "monitor/monitor-load.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "负载监控API",
      "version": "1.0.0",
      "summary": "系统负载监控数据查询",
      "description": "提供系统负载监控功能，包括：\n- 系统实时状态监控\n- CPU负载监控\n- 内存使用监控\n- 磁盘空间监控\n- 在线终端数监控\n- 连接数监控\n- 系统温度监控\n- 网络负载监控\n- 支持时间范围和数据聚合\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/system": {
        "get": {
          "summary": "获取系统实时状态信息",
          "description": "获取路由系统的实时状态信息，包括CPU、内存、连接数、流量、版本等。\n无需传入参数。\n",
          "operationId": "getSystemInfo",
          "tags": [
            "monitor-load"
          ],
          "responses": {
            "200": {
              "description": "成功获取系统实时状态",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemInfoResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "sysinfo": {
                        "cpu": [
                          "12.78%",
                          "15.15%",
                          "12.87%",
                          "12.87%",
                          "12.87%"
                        ],
                        "cputemp": [
                          62
                        ],
                        "freq": [
                          "2000",
                          "2000",
                          "2000",
                          "2000"
                        ],
                        "gwid": "dc345846a78aa2521afe00916af191d7",
                        "hostname": "iKuai",
                        "ip_addr": "192.168.99.1",
                        "link_status": 0,
                        "memory": {
                          "total": 1774768,
                          "available": 919360,
                          "free": 966748,
                          "cached": 323988,
                          "buffers": 15668,
                          "used": "48%"
                        },
                        "online_user": {
                          "count": 0,
                          "count_2g": 0,
                          "count_5g": 0,
                          "count_wired": 0,
                          "count_wireless": 0
                        },
                        "stream": {
                          "connect_num": 78,
                          "tcp_connect_num": 48,
                          "udp_connect_num": 28,
                          "icmp_connect_num": 2,
                          "upload": 0,
                          "download": 0,
                          "total_up": 22867423,
                          "total_down": 180169006
                        },
                        "uptime": 9837,
                        "verinfo": {
                          "modelname": "",
                          "verstring": "4.0.111-beta x64 Enterprise Build202603131338",
                          "version": "4.0.111",
                          "build_date": 202603131338,
                          "arch": "x86",
                          "sysbit": "x64"
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/cpu": {
        "get": {
          "summary": "获取CPU负载监控数据",
          "description": "获取指定时间范围内的CPU负载监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getCpuLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取CPU负载数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CpuLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "cpu": [
                        {
                          "cpu": 0,
                          "timestamp": 1763532960
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/memory": {
        "get": {
          "summary": "获取内存使用监控数据",
          "description": "获取指定时间范围内的内存使用监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getMemoryLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取内存使用数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MemoryLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "memory": [
                        {
                          "timestamp": 1763532960,
                          "memory": 1067964,
                          "memory_use": 60
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/disk": {
        "get": {
          "summary": "获取磁盘空间使用监控数据",
          "description": "获取指定时间范围内的磁盘空间使用监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getDiskSpaceLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取磁盘空间使用数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DiskSpaceLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "disk_space_used": [
                        {
                          "timestamp": 1763532960,
                          "disk_space_use": 75,
                          "disk_space_used": 2543
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/terminals": {
        "get": {
          "summary": "获取在线终端数监控数据",
          "description": "获取指定时间范围内的在线终端数监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getOnTerminalLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取在线终端数数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/OnTerminalLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "on_terminal": [
                        {
                          "on_terminal": 1,
                          "timestamp": 1763532960
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/connections": {
        "get": {
          "summary": "获取连接数监控数据",
          "description": "获取指定时间范围内的连接数监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getConnNumLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取连接数数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ConnNumLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "conn_num": [
                        {
                          "conn_num": 6,
                          "timestamp": 1763532960
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/cputemp": {
        "get": {
          "summary": "获取系统温度监控数据",
          "description": "获取指定时间范围内的系统温度监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getCpuTempLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取系统温度数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CpuTempLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "cputemp1": [
                        {
                          "cputemp1": 56,
                          "timestamp": 1763532960
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/network": {
        "get": {
          "summary": "获取网络负载监控数据",
          "description": "获取指定时间范围内的网络负载监控数据。\n支持按小时、天、周、月进行数据聚合，可选择平均值或最大值。\n",
          "operationId": "getNetworkLoad",
          "tags": [
            "monitor-load"
          ],
          "parameters": [
            {
              "name": "datetype",
              "in": "query",
              "description": "数据聚合类型",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "hour",
                  "day",
                  "week",
                  "month"
                ],
                "example": "hour"
              }
            },
            {
              "name": "start_time",
              "in": "query",
              "description": "开始时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763532000
              }
            },
            {
              "name": "end_time",
              "in": "query",
              "description": "结束时间戳",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1763536500
              }
            },
            {
              "name": "math",
              "in": "query",
              "description": "数学计算方式",
              "required": true,
              "schema": {
                "type": "string",
                "enum": [
                  "avg",
                  "max"
                ],
                "example": "avg"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取网络负载数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NetworkLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "rate_stat": [
                        {
                          "timestamp": 1764152520,
                          "max_upload": 0,
                          "max_download": 0,
                          "rx_packages": 1534,
                          "tx_packages": 752
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CpuLoad": {
          "type": "object",
          "required": [
            "cpu",
            "timestamp"
          ],
          "properties": {
            "cpu": {
              "type": "integer",
              "description": "CPU使用率百分比",
              "minimum": 0,
              "maximum": 100,
              "example": 15
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763532960
            }
          },
          "additionalProperties": false
        },
        "CpuLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "cpu": {
                  "type": "array",
                  "description": "CPU负载数据列表",
                  "items": {
                    "$ref": "#/components/schemas/CpuLoad"
                  }
                }
              },
              "required": [
                "cpu"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MemoryLoad": {
          "type": "object",
          "required": [
            "timestamp",
            "memory",
            "memory_use"
          ],
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763532960
            },
            "memory": {
              "type": "integer",
              "description": "内存使用量（KB）",
              "minimum": 0,
              "example": 1067964
            },
            "memory_use": {
              "type": "integer",
              "description": "内存使用率百分比",
              "minimum": 0,
              "maximum": 100,
              "example": 60
            }
          },
          "additionalProperties": false
        },
        "MemoryLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "memory": {
                  "type": "array",
                  "description": "内存使用数据列表",
                  "items": {
                    "$ref": "#/components/schemas/MemoryLoad"
                  }
                }
              },
              "required": [
                "memory"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DiskSpaceLoad": {
          "type": "object",
          "required": [
            "timestamp",
            "disk_space_use",
            "disk_space_used"
          ],
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763532960
            },
            "disk_space_use": {
              "type": "integer",
              "description": "磁盘空间使用率百分比",
              "minimum": 0,
              "maximum": 100,
              "example": 75
            },
            "disk_space_used": {
              "type": "integer",
              "description": "已使用磁盘空间（MB）",
              "minimum": 0,
              "example": 2543
            }
          },
          "additionalProperties": false
        },
        "DiskSpaceLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "disk_space_used": {
                  "type": "array",
                  "description": "磁盘空间使用数据列表",
                  "items": {
                    "$ref": "#/components/schemas/DiskSpaceLoad"
                  }
                }
              },
              "required": [
                "disk_space_used"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "OnTerminalLoad": {
          "type": "object",
          "required": [
            "on_terminal",
            "timestamp"
          ],
          "properties": {
            "on_terminal": {
              "type": "integer",
              "description": "在线终端数量",
              "minimum": 0,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763532960
            }
          },
          "additionalProperties": false
        },
        "OnTerminalLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "on_terminal": {
                  "type": "array",
                  "description": "在线终端数数据列表",
                  "items": {
                    "$ref": "#/components/schemas/OnTerminalLoad"
                  }
                }
              },
              "required": [
                "on_terminal"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ConnNumLoad": {
          "type": "object",
          "required": [
            "conn_num",
            "timestamp"
          ],
          "properties": {
            "conn_num": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 6
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763532960
            }
          },
          "additionalProperties": false
        },
        "ConnNumLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "conn_num": {
                  "type": "array",
                  "description": "连接数数据列表",
                  "items": {
                    "$ref": "#/components/schemas/ConnNumLoad"
                  }
                }
              },
              "required": [
                "conn_num"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CpuTempLoad": {
          "type": "object",
          "required": [
            "cputemp1",
            "timestamp"
          ],
          "properties": {
            "cputemp1": {
              "type": "integer",
              "description": "CPU温度（摄氏度）",
              "minimum": 0,
              "maximum": 100,
              "example": 56
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763532960
            }
          },
          "additionalProperties": false
        },
        "CpuTempLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "cputemp1": {
                  "type": "array",
                  "description": "CPU温度数据列表",
                  "items": {
                    "$ref": "#/components/schemas/CpuTempLoad"
                  }
                }
              },
              "required": [
                "cputemp1"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "NetworkLoad": {
          "type": "object",
          "required": [
            "timestamp",
            "max_upload",
            "max_download",
            "rx_packages",
            "tx_packages"
          ],
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1764152520
            },
            "max_upload": {
              "type": "integer",
              "description": "最大上传速度（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "max_download": {
              "type": "integer",
              "description": "最大下载速度（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "rx_packages": {
              "type": "integer",
              "description": "接收包数量",
              "minimum": 0,
              "example": 1534
            },
            "tx_packages": {
              "type": "integer",
              "description": "发送包数量",
              "minimum": 0,
              "example": 752
            }
          },
          "additionalProperties": false
        },
        "NetworkLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rate_stat": {
                  "type": "array",
                  "description": "网络负载数据列表",
                  "items": {
                    "$ref": "#/components/schemas/NetworkLoad"
                  }
                }
              },
              "required": [
                "rate_stat"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "SysMemory": {
          "type": "object",
          "required": [
            "total",
            "available",
            "free",
            "cached",
            "buffers",
            "used"
          ],
          "properties": {
            "total": {
              "type": "integer",
              "description": "总内存（KB）",
              "example": 1774768
            },
            "available": {
              "type": "integer",
              "description": "可用内存（KB）",
              "example": 919360
            },
            "free": {
              "type": "integer",
              "description": "空闲内存（KB）",
              "example": 966748
            },
            "cached": {
              "type": "integer",
              "description": "缓存内存（KB）",
              "example": 323988
            },
            "buffers": {
              "type": "integer",
              "description": "缓冲内存（KB）",
              "example": 15668
            },
            "used": {
              "type": "string",
              "description": "已用内存百分比",
              "example": "48%"
            }
          },
          "additionalProperties": false
        },
        "SysOnlineUser": {
          "type": "object",
          "required": [
            "count",
            "count_2g",
            "count_5g",
            "count_wired",
            "count_wireless"
          ],
          "properties": {
            "count": {
              "type": "integer",
              "description": "在线用户总数",
              "example": 0
            },
            "count_2g": {
              "type": "integer",
              "description": "2G在线用户数",
              "example": 0
            },
            "count_5g": {
              "type": "integer",
              "description": "5G在线用户数",
              "example": 0
            },
            "count_wired": {
              "type": "integer",
              "description": "有线在线用户数",
              "example": 0
            },
            "count_wireless": {
              "type": "integer",
              "description": "无线在线用户数",
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "SysStream": {
          "type": "object",
          "required": [
            "connect_num",
            "tcp_connect_num",
            "udp_connect_num",
            "icmp_connect_num",
            "upload",
            "download",
            "total_up",
            "total_down"
          ],
          "properties": {
            "connect_num": {
              "type": "integer",
              "description": "当前连接数",
              "example": 78
            },
            "tcp_connect_num": {
              "type": "integer",
              "description": "当前TCP连接数",
              "example": 48
            },
            "udp_connect_num": {
              "type": "integer",
              "description": "当前UDP连接数",
              "example": 28
            },
            "icmp_connect_num": {
              "type": "integer",
              "description": "当前ICMP连接数",
              "example": 2
            },
            "upload": {
              "type": "integer",
              "description": "当前上行速率（B/S）",
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "当前下行速率（B/S）",
              "example": 0
            },
            "total_up": {
              "type": "integer",
              "description": "总上行流量（B）",
              "example": 22867423
            },
            "total_down": {
              "type": "integer",
              "description": "总下行流量（B）",
              "example": 180169006
            }
          },
          "additionalProperties": false
        },
        "SysVerinfo": {
          "type": "object",
          "required": [
            "modelname",
            "verstring",
            "version",
            "build_date",
            "arch",
            "sysbit"
          ],
          "properties": {
            "modelname": {
              "type": "string",
              "description": "设备型号名称",
              "example": ""
            },
            "verstring": {
              "type": "string",
              "description": "版本信息字符串",
              "example": "4.0.111-beta x64 Enterprise Build202603131338"
            },
            "version": {
              "type": "string",
              "description": "版本号",
              "example": "4.0.111"
            },
            "build_date": {
              "type": "integer",
              "format": "int64",
              "description": "构建时间",
              "example": 202603131338
            },
            "arch": {
              "type": "string",
              "description": "系统架构",
              "example": "x86"
            },
            "sysbit": {
              "type": "string",
              "description": "系统位数",
              "example": "x64"
            }
          },
          "additionalProperties": false
        },
        "SysInfo": {
          "type": "object",
          "required": [
            "cpu",
            "cputemp",
            "freq",
            "gwid",
            "hostname",
            "ip_addr",
            "link_status",
            "memory",
            "online_user",
            "stream",
            "uptime",
            "verinfo"
          ],
          "properties": {
            "cpu": {
              "type": "array",
              "description": "CPU使用率列表，第一项为所有核心平均值，后续依次为各核心使用率",
              "items": {
                "type": "string"
              },
              "example": [
                "12.78%",
                "15.15%",
                "12.87%"
              ]
            },
            "cputemp": {
              "type": "array",
              "description": "CPU温度列表（摄氏度）",
              "items": {
                "type": "integer"
              },
              "example": [
                62
              ]
            },
            "freq": {
              "type": "array",
              "description": "各CPU核心频率列表（MHz）",
              "items": {
                "type": "string"
              },
              "example": [
                "2000",
                "2000",
                "2000",
                "2000"
              ]
            },
            "gwid": {
              "type": "string",
              "description": "路由ID",
              "example": "dc345846a78aa2521afe00916af191d7"
            },
            "hostname": {
              "type": "string",
              "description": "路由主机名称",
              "example": "iKuai"
            },
            "ip_addr": {
              "type": "string",
              "description": "路由LAN1 IP地址",
              "example": "192.168.99.1"
            },
            "link_status": {
              "type": "integer",
              "description": "链路状态",
              "example": 0
            },
            "memory": {
              "$ref": "#/components/schemas/SysMemory"
            },
            "online_user": {
              "$ref": "#/components/schemas/SysOnlineUser"
            },
            "stream": {
              "$ref": "#/components/schemas/SysStream"
            },
            "uptime": {
              "type": "integer",
              "description": "运行时间（秒）",
              "example": 9837
            },
            "verinfo": {
              "$ref": "#/components/schemas/SysVerinfo"
            }
          },
          "additionalProperties": false
        },
        "SystemInfoResponse": {
          "type": "object",
          "required": [
            "message",
            "results"
          ],
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "sysinfo"
              ],
              "properties": {
                "sysinfo": {
                  "$ref": "#/components/schemas/SysInfo"
                }
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-load",
        "x-displayName": "负载监控",
        "description": "系统负载监控数据查询，包括CPU、内存、磁盘、终端、连接数、温度和网络监控"
      }
    ]
  },
  "monitor/monitor-peripheral-devices.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "周边设备监控API",
      "version": "1.0.0",
      "summary": "周边设备监控查询",
      "description": "提供周边设备的监控查询功能，包括：\n- 设备列表查询\n- 设备在线状态监控（ICMP/端口扫描）\n- 自动端口转发状态查询\n\n**支持的设备类型：**\n- 路由器、交换机、防火墙、服务器\n- 摄像头、打印机、智能设备、无线AP\n- 其他网络设备\n\n**注意：** 此模块仅提供查询功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/downstream": {
        "get": {
          "summary": "查询周边设备列表",
          "description": "查询周边设备列表，支持分页、过滤和设备类型筛选。\n\n**设备类型筛选（device参数）：**\n- router: 路由器\n- switches: 交换机\n- firewall: 防火墙\n- server: 服务器\n- camera: 摄像头\n- printer: 打印机\n- SmartDevices: 智能设备\n- ap: 无线AP\n- other: 其他\n",
          "operationId": "getPeripheralDevices",
          "tags": [
            "monitor-peripheral"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 设备类型过滤：filter=device==camera\n- 在线状态过滤：filter=status==1\n- IP地址过滤：filter=ip_addr==192.168.1.100\n",
              "schema": {
                "type": "string"
              },
              "example": "device==camera"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 name, tagname, ip_addr, mac, device, access",
              "schema": {
                "type": "string"
              },
              "example": "name,ip_addr"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "192.168"
            }
          ],
          "responses": {
            "200": {
              "description": "成功返回设备列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PeripheralDeviceResponse"
                  },
                  "examples": {
                    "success": {
                      "value": {
                        "results": {
                          "total": 15,
                          "data": [
                            {
                              "id": 1,
                              "enabled": "yes",
                              "name": "核心交换机",
                              "tagname": "核心交换机",
                              "type": 0,
                              "ip_addr": "192.168.1.1",
                              "mac": "",
                              "port": "80",
                              "protocol": "tcp",
                              "autonat": 0,
                              "eport": "",
                              "access": "http",
                              "method": "icmp",
                              "device": "switches",
                              "shell_port": 22,
                              "last_time": 0,
                              "status": 1
                            },
                            {
                              "id": 2,
                              "enabled": "yes",
                              "name": "监控摄像头01",
                              "tagname": "监控摄像头01",
                              "type": 0,
                              "ip_addr": "192.168.1.100",
                              "mac": "",
                              "port": "554",
                              "protocol": "tcp",
                              "autonat": 1,
                              "eport": "8554",
                              "access": "",
                              "method": "portscan",
                              "device": "camera",
                              "shell_port": 0,
                              "last_time": 1678867200,
                              "status": 0
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、ip_addr、status、last_time等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "schemas": {
        "PeripheralDevice": {
          "type": "object",
          "description": "周边设备信息",
          "required": [
            "id",
            "enabled",
            "name",
            "type",
            "device",
            "method"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "设备ID"
            },
            "enabled": {
              "type": "string",
              "description": "启用状态",
              "enum": [
                "yes",
                "no"
              ]
            },
            "name": {
              "type": "string",
              "description": "设备名称"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）"
            },
            "type": {
              "type": "integer",
              "description": "地址类型（0: IP地址, 1: MAC地址）",
              "enum": [
                0,
                1
              ]
            },
            "ip_addr": {
              "type": "string",
              "description": "设备IP地址",
              "format": "ipv4"
            },
            "mac": {
              "type": "string",
              "description": "设备MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"
            },
            "port": {
              "type": "string",
              "description": "设备管理端口"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "tcp",
                "udp"
              ]
            },
            "autonat": {
              "type": "integer",
              "description": "自动端口转发（0: 关闭, 1: 开启）",
              "enum": [
                0,
                1
              ]
            },
            "eport": {
              "type": "string",
              "description": "外部端口"
            },
            "access": {
              "type": "string",
              "description": "访问方式",
              "enum": [
                "",
                "http",
                "https"
              ]
            },
            "method": {
              "type": "string",
              "description": "在线检测方法",
              "enum": [
                "icmp",
                "portscan"
              ]
            },
            "device": {
              "type": "string",
              "description": "设备类型",
              "enum": [
                "router",
                "switches",
                "firewall",
                "server",
                "camera",
                "printer",
                "SmartDevices",
                "ap",
                "other"
              ]
            },
            "shell_port": {
              "type": "integer",
              "description": "Shell管理端口"
            },
            "last_time": {
              "type": "integer",
              "description": "最近离线时间戳",
              "format": "int64"
            },
            "status": {
              "type": "integer",
              "description": "设备在线状态（0: 离线, 1: 在线）",
              "enum": [
                0,
                1
              ]
            }
          }
        },
        "PeripheralDeviceResponse": {
          "type": "object",
          "properties": {
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "设备列表",
                  "items": {
                    "$ref": "#/components/schemas/PeripheralDevice"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数"
                }
              }
            }
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求参数错误",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 400
                  },
                  "message": {
                    "type": "string",
                    "example": "参数错误"
                  }
                }
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 401
                  },
                  "message": {
                    "type": "string",
                    "example": "未认证或凭证无效"
                  }
                }
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-peripheral",
        "x-displayName": "周边设备监控",
        "description": "周边设备监控查询"
      }
    ]
  },
  "monitor/monitor-proto.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "应用协议监控管理API",
      "version": "1.0.0",
      "summary": "应用协议流量监控和统计分析功能",
      "description": "提供应用协议监控的完整功能，包括：\n- 最近24小时应用协议流量统计\n- 协议分类流量汇总\n- 协议分类历史速率（每5分钟一个数据点）\n- 当前应用协议速率使用详情\n- 应用协议历史速率使用详情\n- 访问指定应用协议的终端列表\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/app-traffic-summary": {
        "get": {
          "summary": "获取最近24小时应用协议流量统计",
          "description": "获取最近24小时的应用协议流量统计信息，包括应用名称、分类、\n总流量、上下行流量等详细数据。支持分页查询，不支持key、pattern、filter。\n",
          "operationId": "getAppTrafficSummary",
          "tags": [
            "monitor-app-traffic"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取最近24小时应用协议流量统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppTrafficSummaryResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "proto3_day": [
                        {
                          "appname": "阿里云",
                          "appname_level1": "云服务",
                          "appname_level2": "传输下载",
                          "total": 95062858,
                          "id": 2,
                          "total_down": 47258077,
                          "total_up": 47804781,
                          "appid": 2540017
                        },
                        {
                          "appname": "HTTPS",
                          "appname_level1": "基础协议",
                          "appname_level2": "网络协议",
                          "total": 80009645,
                          "id": 3,
                          "total_down": 71440106,
                          "total_up": 8569539,
                          "appid": 1000020
                        }
                      ],
                      "proto3_day_total": 56,
                      "proto3_day_total_flow": 733339966
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/protocols": {
        "get": {
          "summary": "获取最近24小时协议分类流量汇总",
          "description": "查询最近24小时协议分类的流量使用详情，返回各协议大类的流量汇总。\n协议大类包括：网络协议、传输下载、休闲娱乐、生活服务、办公协作、\n社交通讯、效率工具、网络游戏、金融理财、学习教育等。\n支持时间段范围查询，不支持limit、page、key、pattern、filter。\n",
          "operationId": "listProtocolsTraffic",
          "tags": [
            "monitor-app-traffic"
          ],
          "parameters": [
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "查询起始时间戳（Unix时间戳）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1773215100
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "查询结束时间戳（Unix时间戳）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1773215100
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取应用协议分类流量汇总",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ProtocolsTrafficResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "proto": "1000000:1499999",
                          "proto_name": "网络协议",
                          "total": 256535748864
                        },
                        {
                          "proto": "2500000:2999999",
                          "proto_name": "传输下载",
                          "total": 171852275684
                        },
                        {
                          "proto": "3000000:3499999",
                          "proto_name": "休闲娱乐",
                          "total": 52848833471
                        },
                        {
                          "proto": "4:7",
                          "proto_name": "未知应用",
                          "total": 25864048498
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/protocols/history-load": {
        "get": {
          "summary": "获取协议分类历史速率",
          "description": "查询最近24小时协议分类的速率使用详情，每5分钟一个数据点。\n返回各协议分类的上下行速率、总流量、连接数等信息。\n支持时间段范围查询（可选），不支持limit、page、key、pattern、filter。\n",
          "operationId": "getProtocolsHistoryLoad",
          "tags": [
            "monitor-app-traffic"
          ],
          "parameters": [
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "查询起始时间戳（Unix时间戳，可选）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1773215100
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "查询结束时间戳（Unix时间戳，可选）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1773215100
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取应用协议分类历史速率数据",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ProtocolsHistoryLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "proto": "3500000:3999999",
                          "proto_name": "效率工具",
                          "id": 112451,
                          "timestamp": 1773215100,
                          "conn_cnt": 59,
                          "upload": 40033,
                          "download": 309602,
                          "total_up": 5975668,
                          "total_down": 8691312,
                          "total": 14666980
                        },
                        {
                          "proto": "4:7",
                          "proto_name": "未知应用",
                          "id": 112452,
                          "timestamp": 1773215100,
                          "conn_cnt": 240,
                          "upload": 4678,
                          "download": 4911,
                          "total_up": 2313328,
                          "total_down": 18727212,
                          "total": 21040540
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/app-protocols/load": {
        "get": {
          "summary": "获取当前应用协议速率使用详情",
          "description": "查询当前各应用协议的速率使用详情，包括当前连接数、上下行速率、总流量等。\n支持分页查询，支持按上下行流量进行排序，不支持key、pattern、filter。\n",
          "operationId": "listAppProtocolsLoad",
          "tags": [
            "monitor-app-traffic"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取当前应用协议速率使用详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolsLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "appid": 2580003,
                          "appname": "IOS更新",
                          "proto1_name": "2500000:2999999",
                          "total_up": 814625315,
                          "total_down": 112532061362,
                          "conn_cnt": 0,
                          "upload": 0,
                          "download": 0,
                          "id": 1,
                          "total": 113346686677,
                          "proto2_name": "2580001:2590000"
                        },
                        {
                          "appid": 1000024,
                          "appname": "IOS更新",
                          "proto1_name": "1000000:1499999",
                          "total_up": 4293602113,
                          "total_down": 80956644079,
                          "conn_cnt": 61,
                          "upload": 20077,
                          "download": 434711,
                          "id": 2,
                          "total": 85250246192,
                          "proto2_name": "1000001:1010000"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/app-protocols/history-load": {
        "get": {
          "summary": "获取应用协议历史速率使用详情",
          "description": "查询指定应用协议的最近24小时历史速率使用详情，每5分钟一个数据点。\n例如可查询微信、QQ的最近24小时历史速率负载。\n支持时间段范围查询，必须指定应用协议ID（appids），支持多个ID以逗号分隔。\n不支持limit、page、key、pattern、filter。\n",
          "operationId": "getAppProtocolsHistoryLoad",
          "tags": [
            "monitor-app-traffic"
          ],
          "parameters": [
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "查询起始时间戳（Unix时间戳，可选）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1773215100
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "查询结束时间戳（Unix时间戳，可选）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1773215100
              }
            },
            {
              "name": "appids",
              "in": "query",
              "required": true,
              "description": "应用协议ID，必须指定，支持多个ID以逗号分隔（如 2580003,2580004）",
              "schema": {
                "type": "string",
                "example": "2580003,2580004"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取应用协议历史速率使用详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolsHistoryLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 2148885,
                          "timestamp": 1773216900,
                          "appid": 2580003,
                          "appname": "微信",
                          "conn_cnt": 16,
                          "upload": 1294,
                          "download": 2838,
                          "total_up": 2418577,
                          "total_down": 216010661,
                          "total": 218429238
                        },
                        {
                          "id": 2149034,
                          "timestamp": 1773217200,
                          "appid": 2580003,
                          "appname": "微信",
                          "conn_cnt": 5,
                          "upload": 0,
                          "download": 0,
                          "total_up": 2290568,
                          "total_down": 209349430,
                          "total": 211639998
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/app-protocols/terminal-load": {
        "get": {
          "summary": "获取访问指定应用协议的终端列表",
          "description": "查询有哪些终端访问过指定的应用协议，列出终端当前的上下行速率、\n总流量、连接数、主机名、MAC地址等信息。\n必须指定应用协议ID（appid）。\n不支持limit、page、key、pattern、filter。\n",
          "operationId": "getAppProtocolTerminalLoad",
          "tags": [
            "monitor-app-traffic"
          ],
          "parameters": [
            {
              "name": "appid",
              "in": "query",
              "required": true,
              "description": "应用协议ID，必须指定",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 2580003
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取访问指定应用协议的终端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolTerminalLoadResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "conn_cnt": 0,
                          "upload": 0,
                          "download": 0,
                          "comment": "",
                          "ipaddr_int": 3232236433,
                          "hostname": "ghuadeMBP",
                          "client_model": "",
                          "client_type": "MacOS",
                          "mac": "00:e0:4c:78:a8:06",
                          "ipaddr": "192.168.3.145",
                          "termname": "",
                          "id": 1,
                          "uptime": 1773147773,
                          "total_up": 53352,
                          "total_down": 138375
                        },
                        {
                          "conn_cnt": 0,
                          "upload": 0,
                          "download": 0,
                          "comment": "",
                          "ipaddr_int": 3232236548,
                          "hostname": "iKuaigaideiMac2",
                          "client_model": "iQOO%20Neo5%20SE",
                          "client_type": "Android",
                          "mac": "04:9d:05:53:46:33",
                          "ipaddr": "192.168.4.4",
                          "termname": "",
                          "id": 2,
                          "uptime": 1773147773,
                          "total_up": 560,
                          "total_down": 720
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "desc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持按上行（upload、total_up）或下行（download、total_down）流量排序",
          "schema": {
            "type": "string",
            "enum": [
              "upload",
              "download",
              "total_up",
              "total_down"
            ],
            "default": "total_down",
            "example": "total_down"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AppTrafficSummaryResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/AppTrafficSummaryResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppTrafficSummaryResults": {
          "type": "object",
          "properties": {
            "proto3_day": {
              "type": "array",
              "description": "应用协议流量统计列表",
              "items": {
                "$ref": "#/components/schemas/AppTrafficItem"
              }
            },
            "proto3_day_total": {
              "type": "integer",
              "description": "总应用数量",
              "example": 56
            },
            "proto3_day_total_flow": {
              "type": "integer",
              "format": "int64",
              "description": "总应用流量（字节）",
              "example": 733339966
            }
          },
          "required": [
            "proto3_day",
            "proto3_day_total",
            "proto3_day_total_flow"
          ],
          "additionalProperties": false
        },
        "AppTrafficItem": {
          "type": "object",
          "required": [
            "appname",
            "appname_level1",
            "appname_level2",
            "total",
            "total_down",
            "total_up",
            "appid",
            "id"
          ],
          "properties": {
            "appname": {
              "type": "string",
              "description": "应用名称",
              "maxLength": 100,
              "example": "阿里云"
            },
            "appname_level1": {
              "type": "string",
              "description": "应用一级分类",
              "maxLength": 100,
              "example": "云服务"
            },
            "appname_level2": {
              "type": "string",
              "description": "应用二级分类",
              "maxLength": 100,
              "example": "传输下载"
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "应用总流量（字节）",
              "minimum": 0,
              "example": 95062858
            },
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 2
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "应用下行总流量（字节）",
              "minimum": 0,
              "example": 47258077
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "应用上行总流量（字节）",
              "minimum": 0,
              "example": 47804781
            },
            "appid": {
              "type": "integer",
              "format": "int64",
              "description": "应用ID",
              "minimum": 1,
              "example": 2540017
            }
          },
          "additionalProperties": false
        },
        "ProtocolsTrafficResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ProtocolsTrafficResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ProtocolsTrafficResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "应用协议分类流量列表",
              "items": {
                "$ref": "#/components/schemas/ProtocolTrafficItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "ProtocolTrafficItem": {
          "type": "object",
          "required": [
            "proto",
            "proto_name",
            "total"
          ],
          "properties": {
            "proto": {
              "type": "string",
              "description": "应用协议ID范围",
              "example": "1000000:1499999"
            },
            "proto_name": {
              "type": "string",
              "description": "应用协议分类名称",
              "maxLength": 100,
              "example": "网络协议"
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议分类总流量（字节）",
              "minimum": 0,
              "example": 256535748864
            }
          },
          "additionalProperties": false
        },
        "ProtocolsHistoryLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/ProtocolsHistoryLoadResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ProtocolsHistoryLoadResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "应用协议分类历史速率数据列表",
              "items": {
                "$ref": "#/components/schemas/ProtocolHistoryLoadItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "ProtocolHistoryLoadItem": {
          "type": "object",
          "required": [
            "proto",
            "proto_name",
            "id",
            "timestamp",
            "conn_cnt",
            "upload",
            "download",
            "total_up",
            "total_down",
            "total"
          ],
          "properties": {
            "proto": {
              "type": "string",
              "description": "应用协议ID范围",
              "example": "3500000:3999999"
            },
            "proto_name": {
              "type": "string",
              "description": "应用协议分类名称",
              "maxLength": 100,
              "example": "效率工具"
            },
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 112451
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1773215100
            },
            "conn_cnt": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 59
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上行速率（字节/秒）",
              "minimum": 0,
              "example": 40033
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下行速率（字节/秒）",
              "minimum": 0,
              "example": 309602
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "上行总流量（字节）",
              "minimum": 0,
              "example": 5975668
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "下行总流量（字节）",
              "minimum": 0,
              "example": 8691312
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "总流量（字节）",
              "minimum": 0,
              "example": 14666980
            }
          },
          "additionalProperties": false
        },
        "AppProtocolsLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/AppProtocolsLoadResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocolsLoadResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "当前应用协议速率使用详情列表",
              "items": {
                "$ref": "#/components/schemas/AppProtocolLoadItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "AppProtocolLoadItem": {
          "type": "object",
          "required": [
            "appid",
            "appname",
            "proto1_name",
            "proto2_name",
            "total_up",
            "total_down",
            "conn_cnt",
            "upload",
            "download",
            "id",
            "total"
          ],
          "properties": {
            "appid": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议ID",
              "minimum": 1,
              "example": 2580003
            },
            "appname": {
              "type": "string",
              "description": "应用协议名称",
              "maxLength": 100,
              "example": "IOS更新"
            },
            "proto1_name": {
              "type": "string",
              "description": "应用协议一级分类ID范围",
              "example": "2500000:2999999"
            },
            "proto2_name": {
              "type": "string",
              "description": "应用协议二级分类ID范围",
              "example": "2580001:2590000"
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议上行总流量（字节）",
              "minimum": 0,
              "example": 814625315
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议下行总流量（字节）",
              "minimum": 0,
              "example": 112532061362
            },
            "conn_cnt": {
              "type": "integer",
              "description": "应用协议当前连接数",
              "minimum": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议当前上行速率（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议当前下行速率（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议总流量（字节）",
              "minimum": 0,
              "example": 113346686677
            }
          },
          "additionalProperties": false
        },
        "AppProtocolsHistoryLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/AppProtocolsHistoryLoadResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocolsHistoryLoadResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "应用协议历史速率数据列表",
              "items": {
                "$ref": "#/components/schemas/AppProtocolHistoryLoadItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "AppProtocolHistoryLoadItem": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "appid",
            "appname",
            "conn_cnt",
            "upload",
            "download",
            "total_up",
            "total_down",
            "total"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 2148885
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1773216900
            },
            "appid": {
              "type": "integer",
              "format": "int64",
              "description": "应用协议ID",
              "minimum": 1,
              "example": 2580003
            },
            "appname": {
              "type": "string",
              "description": "应用协议名称",
              "maxLength": 100,
              "example": "微信"
            },
            "conn_cnt": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 16
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上行速率（字节/秒）",
              "minimum": 0,
              "example": 1294
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下行速率（字节/秒）",
              "minimum": 0,
              "example": 2838
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "上行总流量（字节）",
              "minimum": 0,
              "example": 2418577
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "下行总流量（字节）",
              "minimum": 0,
              "example": 216010661
            },
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "总流量（字节）",
              "minimum": 0,
              "example": 218429238
            }
          },
          "additionalProperties": false
        },
        "AppProtocolTerminalLoadResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/AppProtocolTerminalLoadResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocolTerminalLoadResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "访问指定应用协议的终端列表",
              "items": {
                "$ref": "#/components/schemas/AppProtocolTerminalItem"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "AppProtocolTerminalItem": {
          "type": "object",
          "required": [
            "id",
            "ipaddr",
            "ipaddr_int",
            "mac",
            "hostname",
            "client_type",
            "conn_cnt",
            "upload",
            "download",
            "total_up",
            "total_down",
            "uptime",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "ipaddr": {
              "type": "string",
              "description": "终端IP地址",
              "format": "ipv4",
              "example": "192.168.3.145"
            },
            "ipaddr_int": {
              "type": "integer",
              "format": "int64",
              "description": "终端IP地址（整数形式）",
              "example": 3232236433
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$",
              "example": "00:e0:4c:78:a8:06"
            },
            "hostname": {
              "type": "string",
              "description": "主机名",
              "maxLength": 200,
              "example": "ghuadeMBP"
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 200,
              "example": ""
            },
            "client_type": {
              "type": "string",
              "description": "终端类型",
              "maxLength": 100,
              "example": "MacOS"
            },
            "client_model": {
              "type": "string",
              "description": "终端型号",
              "maxLength": 200,
              "example": ""
            },
            "conn_cnt": {
              "type": "integer",
              "description": "连接数",
              "minimum": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "format": "int64",
              "description": "上行速率（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "format": "int64",
              "description": "下行速率（字节/秒）",
              "minimum": 0,
              "example": 0
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "上行总流量（字节）",
              "minimum": 0,
              "example": 53352
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "下行总流量（字节）",
              "minimum": 0,
              "example": 138375
            },
            "uptime": {
              "type": "integer",
              "format": "int64",
              "description": "上线时间戳（Unix时间戳）",
              "example": 1773147773
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-app-traffic",
        "x-displayName": "应用协议监控",
        "description": "应用协议流量监控和统计分析，支持流量汇总、历史速率、终端访问查询"
      }
    ]
  },
  "monitor/monitor-switch.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "云管交换机监控API",
      "version": "1.0.0",
      "summary": "云管交换机设备监控查询",
      "description": "提供云管交换机的设备列表查询功能。\n\n**支持的设备类型：**\n- IK_J7052: 爱快J7052系列\n- 3ndlevel: 三级交换机\n- 2ndlevel: 二级交换机\n\n**注意：** 此模块仅提供查询功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/switch": {
        "get": {
          "summary": "查询云管交换机设备列表",
          "description": "查询云管交换机设备列表，支持分页和过滤。\n",
          "operationId": "getSwitchDevices",
          "tags": [
            "cloud-switch"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 在线状态过滤：filter=status==1\n- 设备类型过滤：filter=type==IK_J7052\n- IP地址过滤：filter=ip_addr==192.168.1.100\n",
              "schema": {
                "type": "string"
              },
              "example": "status==1"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 name, tagname, ip_addr, mac, device, oemname",
              "schema": {
                "type": "string"
              },
              "example": "name,ip_addr,mac"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "交换机"
            }
          ],
          "responses": {
            "200": {
              "description": "成功返回设备列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SwitchResponse"
                  },
                  "examples": {
                    "success": {
                      "value": {
                        "results": {
                          "data": [
                            {
                              "id": 1,
                              "name": "核心交换机",
                              "tagname": "核心交换机",
                              "oemname": "IK-J7052",
                              "mac": "aa:bb:cc:dd:ee:ff",
                              "ip_addr": "192.168.1.100",
                              "netmask": "255.255.255.0",
                              "version": "v1.0.0",
                              "device": "IK-J7052",
                              "connect_time": 1678886400,
                              "type": "IK_J7052",
                              "snmp_version": "v2c",
                              "status": 1
                            }
                          ],
                          "total": 5
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、ip_addr、status、connect_time等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "schemas": {
        "SwitchDevice": {
          "type": "object",
          "description": "云管交换机设备信息",
          "required": [
            "id",
            "name",
            "ip_addr",
            "type"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "设备ID"
            },
            "name": {
              "type": "string",
              "description": "设备名称"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）"
            },
            "oemname": {
              "type": "string",
              "description": "设备OEM名称"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4"
            },
            "version": {
              "type": "string",
              "description": "固件版本"
            },
            "device": {
              "type": "string",
              "description": "设备型号"
            },
            "connect_time": {
              "type": "integer",
              "description": "设备上线时间戳",
              "format": "int64"
            },
            "type": {
              "type": "string",
              "description": "设备类型（对应oidset标识）",
              "enum": [
                "IK_J7052",
                "3ndlevel",
                "2ndlevel"
              ]
            },
            "snmp_version": {
              "type": "string",
              "description": "SNMP版本",
              "enum": [
                "v2c",
                "v3"
              ]
            },
            "community": {
              "type": "string",
              "description": "SNMP v2c 团体名"
            },
            "username": {
              "type": "string",
              "description": "SNMP v3 用户名"
            },
            "security": {
              "type": "string",
              "description": "SNMP v3 安全级别"
            },
            "auth_proto": {
              "type": "string",
              "description": "SNMP v3 认证协议"
            },
            "auth_pass": {
              "type": "string",
              "description": "SNMP v3 认证密码"
            },
            "priv_proto": {
              "type": "string",
              "description": "SNMP v3 加密协议"
            },
            "priv_pass": {
              "type": "string",
              "description": "SNMP v3 加密密码"
            },
            "status": {
              "type": "integer",
              "description": "设备在线状态（0: 离线, 1: SNMP在线, 2: Ping在线）",
              "enum": [
                0,
                1,
                2
              ]
            }
          }
        },
        "SwitchResponse": {
          "type": "object",
          "properties": {
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "设备列表",
                  "items": {
                    "$ref": "#/components/schemas/SwitchDevice"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数"
                }
              }
            }
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求参数错误",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 400
                  },
                  "message": {
                    "type": "string",
                    "example": "参数错误"
                  }
                }
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "example": 401
                  },
                  "message": {
                    "type": "string",
                    "example": "未认证或凭证无效"
                  }
                }
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "cloud-switch",
        "x-displayName": "云管交换机",
        "description": "云管交换机设备监控查询"
      }
    ]
  },
  "monitor/monitor-traffic-audit.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "流量审计监控API",
      "version": "1.0.0",
      "summary": "终端与账号流量审计查询",
      "description": "提供流量审计查询功能，包括：\n- MAC 终端流量审计列表\n- MAC 终端流量趋势详情\n- MAC 终端应用流量详情\n- 认证账号流量审计列表\n- 认证账号流量趋势详情\n- 认证账号应用流量详情\n\n本模块仅提供查询能力，不包含导出、清空等数据维护操作。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "monitor-traffic-audit",
        "x-displayName": "流量审计",
        "description": "终端与认证账号流量审计查询"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/traffic-audit/terminals": {
        "get": {
          "tags": [
            "monitor-traffic-audit"
          ],
          "summary": "查询 MAC 流量审计列表",
          "description": "查询 MAC 终端维度的流量审计统计列表。\n数据按 MAC 聚合，返回累计上行、累计下行等信息，可按时间范围查询。\n",
          "operationId": "listMacTrafficAudit",
          "parameters": [
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/starttimeParam"
            },
            {
              "$ref": "#/components/parameters/stoptimeParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取 MAC 流量审计列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacTrafficAuditListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "daytime": [
                        {
                          "mac": "68:da:73:a1:d9:01",
                          "comment": "",
                          "sum_total_up": 1928782910,
                          "sum_total_down": 7899352962
                        },
                        {
                          "mac": "fe:74:26:af:a4:09",
                          "comment": "test001",
                          "sum_total_up": 18983257,
                          "sum_total_down": 759188865
                        }
                      ],
                      "daytime_total": 9
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/traffic-audit/terminals/trend": {
        "get": {
          "tags": [
            "monitor-traffic-audit"
          ],
          "summary": "查询指定 MAC 流量趋势详情",
          "description": "查询指定 MAC 终端的流量趋势详情。\n返回 IPv4 日流量统计数据，并在存在 IPv6 统计数据时同步返回 IPv6 日流量统计数据。\n终端身份由查询参数 mac 确定，结果默认按统计日期升序返回。\n",
          "operationId": "getMacTrafficAuditTrend",
          "parameters": [
            {
              "$ref": "#/components/parameters/macQueryParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定 MAC 流量趋势详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacTrafficAuditTrendResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "daytime": [
                        {
                          "mac": "68:da:73:a1:d9:01",
                          "base_total_up": 0,
                          "base_total_down": 0,
                          "total_up": 219189326,
                          "total_down": 649378079,
                          "auth": 0,
                          "systype": "MacOS",
                          "devtype": "Apple",
                          "comment": "",
                          "sum_total_up": 219189326,
                          "sum_total_down": 649378079,
                          "sum_online": 43799,
                          "termname": "",
                          "id": 6,
                          "timestamp": 1776397741,
                          "logout_time": 1776441540,
                          "daytime": 1776355200,
                          "online_time": 43799,
                          "ip_addr": "192.168.99.102"
                        }
                      ],
                      "daytime6": [
                        {
                          "auth": 0,
                          "systype": "MacOS",
                          "devtype": "Apple",
                          "comment": "",
                          "sum_total_up": 828568,
                          "sum_total_down": 2772487,
                          "sum_online": 13140,
                          "id": 69,
                          "timestamp": 1777305531,
                          "logout_time": 1777305540,
                          "daytime": 1777219200,
                          "online_time": 9,
                          "ip_addr": "fc00:78aa:2521:0001:14d7:9c58:4fc2:a58e",
                          "mac": "68:da:73:a1:d9:01",
                          "base_total_up": 0,
                          "base_total_down": 0,
                          "total_up": 1199,
                          "total_down": 729
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/traffic-audit/terminals/applications": {
        "get": {
          "tags": [
            "monitor-traffic-audit"
          ],
          "summary": "查询指定 MAC 应用流量详情",
          "description": "查询指定 MAC 终端的应用流量明细。\n- method=day（默认）：返回最近 7 天数据，无需传 starttime/stoptime\n- method=hour：可选传入 starttime/stoptime，未传时默认返回最近 1 小时数据\n返回格式为时间戳到应用流量映射，每条记录按时间升序排列。\n",
          "operationId": "getMacTrafficAuditApplications",
          "parameters": [
            {
              "$ref": "#/components/parameters/macQueryParam"
            },
            {
              "$ref": "#/components/parameters/methodParam"
            },
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "查询起始时间戳（仅 method=hour 时有效，不传默认为当前时间前 1 小时）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1778083200
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "查询结束时间戳（仅 method=hour 时有效，不传默认为当前时间）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1778169600
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定 MAC 应用流量详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacTrafficAuditApplicationsResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "app_data": [
                        {
                          "timestamp": 1778083200,
                          "apps": {
                            "网页浏览": "1275244107",
                            "谷歌通用协议": "2182276",
                            "钉钉": "1701224",
                            "腾讯私有协议": "1467689"
                          }
                        },
                        {
                          "timestamp": 1778169600,
                          "apps": {
                            "HTTPS": "858993459",
                            "企业微信": "419430400"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/traffic-audit/accounts": {
        "get": {
          "tags": [
            "monitor-traffic-audit"
          ],
          "summary": "查询账号流量审计列表",
          "description": "查询认证账号维度的流量审计统计列表。\n数据按账号聚合，返回累计上行、累计下行等信息，可按时间范围查询。\n",
          "operationId": "listAccountTrafficAudit",
          "parameters": [
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/starttimeParam"
            },
            {
              "$ref": "#/components/parameters/stoptimeParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取账号流量审计列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AccountTrafficAuditListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "daytime_vpn": [
                        {
                          "mac": "vpn_user01",
                          "comment": "远程办公",
                          "sum_total_up": 1928782910,
                          "sum_total_down": 7899352962
                        }
                      ],
                      "daytime_vpn_total": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/traffic-audit/accounts/trend": {
        "get": {
          "tags": [
            "monitor-traffic-audit"
          ],
          "summary": "查询指定账号流量趋势详情",
          "description": "查询指定认证账号的流量趋势详情，返回账号维度的日流量统计数据，结果默认按统计日期升序返回。",
          "operationId": "getAccountTrafficAuditTrend",
          "parameters": [
            {
              "$ref": "#/components/parameters/usernameQueryParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定账号流量趋势详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AccountTrafficAuditTrendResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "daytime_vpn": [
                        {
                          "id": 2,
                          "timestamp": 1778116236,
                          "logout_time": 1778125080,
                          "daytime": 1778083200,
                          "online_time": 8844,
                          "ip_addr": "10.10.10.2",
                          "mac": "vpn_user01",
                          "mac_addr": "68:da:73:a1:d9:01",
                          "base_total_up": 0,
                          "base_total_down": 0,
                          "total_up": 73861576,
                          "total_down": 1320258077,
                          "auth": 1,
                          "systype": "Windows",
                          "devtype": "PC",
                          "comment": "远程办公",
                          "sum_total_up": 73861576,
                          "sum_total_down": 1320258077,
                          "sum_online": 8844
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/traffic-audit/accounts/applications": {
        "get": {
          "tags": [
            "monitor-traffic-audit"
          ],
          "summary": "查询指定账号应用流量详情",
          "description": "查询指定认证账号的应用流量明细。\n- method=day（默认）：返回最近 7 天数据，无需传 starttime/stoptime\n- method=hour：可选传入 starttime/stoptime，未传时默认返回最近 1 小时数据\n返回格式为时间戳到应用流量映射，每条记录按时间升序排列。\n",
          "operationId": "getAccountTrafficAuditApplications",
          "parameters": [
            {
              "$ref": "#/components/parameters/usernameQueryParam"
            },
            {
              "$ref": "#/components/parameters/methodParam"
            },
            {
              "name": "starttime",
              "in": "query",
              "required": false,
              "description": "查询起始时间戳（仅 method=hour 时有效，不传默认为当前时间前 1 小时）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1778083200
              }
            },
            {
              "name": "stoptime",
              "in": "query",
              "required": false,
              "description": "查询结束时间戳（仅 method=hour 时有效，不传默认为当前时间）",
              "schema": {
                "type": "integer",
                "format": "int64",
                "example": 1778169600
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取指定账号应用流量详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AccountTrafficAuditApplicationsResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "app_username_data": [
                        {
                          "timestamp": 1778083200,
                          "apps": {
                            "HTTPS": "209715200",
                            "企业微信": "83886080",
                            "远程桌面": "41943040"
                          }
                        },
                        {
                          "timestamp": 1778169600,
                          "apps": {
                            "网页浏览": "536870912",
                            "钉钉": "268435456"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "分页参数，格式为 offset,count",
          "schema": {
            "type": "string",
            "pattern": "^\\\\d+,\\\\d+$",
            "default": "0,50",
            "example": "0,50"
          }
        },
        "starttimeParam": {
          "name": "starttime",
          "in": "query",
          "required": false,
          "description": "查询起始时间戳",
          "schema": {
            "type": "integer",
            "format": "int64",
            "example": 1778121610
          }
        },
        "stoptimeParam": {
          "name": "stoptime",
          "in": "query",
          "required": false,
          "description": "查询结束时间戳",
          "schema": {
            "type": "integer",
            "format": "int64",
            "example": 1778125210
          }
        },
        "methodParam": {
          "name": "method",
          "in": "query",
          "description": "应用流量统计粒度，不传时按日统计",
          "schema": {
            "type": "string",
            "enum": [
              "hour",
              "day"
            ],
            "default": "day",
            "example": "hour"
          }
        },
        "macQueryParam": {
          "name": "mac",
          "in": "query",
          "required": true,
          "description": "MAC 地址",
          "schema": {
            "type": "string",
            "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
            "example": "68:da:73:a1:d9:01"
          }
        },
        "usernameQueryParam": {
          "name": "username",
          "in": "query",
          "required": true,
          "description": "认证账号名称",
          "schema": {
            "type": "string",
            "example": "vpn_user01"
          }
        }
      },
      "schemas": {
        "TrafficAuditDayItem": {
          "type": "object",
          "description": "流量审计日统计记录",
          "properties": {
            "id": {
              "type": "integer",
              "description": "记录 ID"
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "上线时间戳"
            },
            "logout_time": {
              "type": "integer",
              "format": "int64",
              "description": "下线时间戳"
            },
            "daytime": {
              "type": "integer",
              "format": "int64",
              "description": "统计日期对应的零点时间戳"
            },
            "online_time": {
              "type": "integer",
              "description": "本条记录在线时长，单位秒"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP 地址"
            },
            "mac": {
              "type": "string",
              "description": "MAC 地址或认证账号"
            },
            "mac_addr": {
              "type": "string",
              "description": "账号对应的终端 MAC 地址"
            },
            "base_total_up": {
              "type": "integer",
              "format": "int64",
              "description": "当日基准上行流量，单位字节"
            },
            "base_total_down": {
              "type": "integer",
              "format": "int64",
              "description": "当日基准下行流量，单位字节"
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "当前累计上行流量，单位字节"
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "当前累计下行流量，单位字节"
            },
            "auth": {
              "type": "integer",
              "description": "认证方式"
            },
            "systype": {
              "type": "string",
              "description": "系统类型"
            },
            "devtype": {
              "type": "string",
              "description": "设备类型"
            },
            "comment": {
              "type": "string",
              "description": "备注"
            },
            "termname": {
              "type": "string",
              "description": "终端名称"
            },
            "sum_total_up": {
              "type": "integer",
              "format": "int64",
              "description": "聚合上行流量，单位字节"
            },
            "sum_total_down": {
              "type": "integer",
              "format": "int64",
              "description": "聚合下行流量，单位字节"
            },
            "sum_online": {
              "type": "integer",
              "description": "聚合在线时长，单位秒"
            }
          }
        },
        "TrafficAuditAppItem": {
          "type": "object",
          "description": "应用流量明细记录",
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "统计时间戳（method=day 时为当日零点，method=hour 时为整点）"
            },
            "apps": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "应用名称到流量的映射，流量单位为字节",
              "example": {
                "网页浏览": "1275244107",
                "钉钉": "1701224"
              }
            }
          }
        },
        "TrafficAuditListItem": {
          "type": "object",
          "description": "流量审计列表记录",
          "properties": {
            "mac": {
              "type": "string",
              "description": "MAC 地址或认证账号"
            },
            "comment": {
              "type": "string",
              "description": "备注"
            },
            "sum_total_down": {
              "type": "integer",
              "format": "int64",
              "description": "聚合下行流量，单位字节"
            },
            "sum_total_up": {
              "type": "integer",
              "format": "int64",
              "description": "聚合上行流量，单位字节"
            }
          }
        },
        "MacTrafficAuditListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功"
            },
            "message": {
              "type": "string",
              "description": "响应消息"
            },
            "results": {
              "type": "object",
              "properties": {
                "daytime": {
                  "type": "array",
                  "description": "MAC 终端流量审计列表",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditListItem"
                  }
                },
                "daytime_total": {
                  "type": "integer",
                  "description": "MAC 终端统计总数"
                }
              }
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ]
        },
        "MacTrafficAuditTrendResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功"
            },
            "message": {
              "type": "string",
              "description": "响应消息"
            },
            "results": {
              "type": "object",
              "properties": {
                "daytime": {
                  "type": "array",
                  "description": "MAC 终端 IPv4 日流量统计",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditDayItem"
                  }
                },
                "daytime6": {
                  "type": "array",
                  "description": "MAC 终端 IPv6 日流量统计",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditDayItem"
                  }
                }
              }
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ]
        },
        "MacTrafficAuditApplicationsResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功"
            },
            "message": {
              "type": "string",
              "description": "响应消息"
            },
            "results": {
              "type": "object",
              "properties": {
                "app_data": {
                  "type": "array",
                  "description": "MAC 终端应用流量明细",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditAppItem"
                  }
                }
              }
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ]
        },
        "AccountTrafficAuditListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功"
            },
            "message": {
              "type": "string",
              "description": "响应消息"
            },
            "results": {
              "type": "object",
              "properties": {
                "daytime_vpn": {
                  "type": "array",
                  "description": "账号流量审计列表",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditListItem"
                  }
                },
                "daytime_vpn_total": {
                  "type": "integer",
                  "description": "账号统计总数"
                }
              }
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ]
        },
        "AccountTrafficAuditTrendResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功"
            },
            "message": {
              "type": "string",
              "description": "响应消息"
            },
            "results": {
              "type": "object",
              "properties": {
                "daytime_vpn": {
                  "type": "array",
                  "description": "账号日流量趋势数据",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditDayItem"
                  }
                }
              }
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ]
        },
        "AccountTrafficAuditApplicationsResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0 表示成功"
            },
            "message": {
              "type": "string",
              "description": "响应消息"
            },
            "results": {
              "type": "object",
              "properties": {
                "app_username_data": {
                  "type": "array",
                  "description": "账号应用流量明细",
                  "items": {
                    "$ref": "#/components/schemas/TrafficAuditAppItem"
                  }
                }
              }
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ]
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误码"
            },
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ]
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求语法错误或参数不合法"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用 JWT Bearer Token 进行认证"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "monitor/monitor-wireless.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "无线监控管理API",
      "version": "1.0.0",
      "summary": "无线网络监控的完整功能",
      "description": "提供无线网络监控的完整功能，包括：\n- 无线AP和终端统计信息\n- 无线流量统计监控\n- 无线网络评分分析\n- SSID终端数量统计\n- 信道占用情况统计\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/monitoring/wireless-statistics": {
        "get": {
          "summary": "获取无线监控统计信息",
          "description": "获取无线网络的统计数据，包括AP状态统计和客户端状态统计，\n如AP在线数量、终端数量、频段分布等信息。\n",
          "operationId": "getWirelessStatistics",
          "tags": [
            "monitor-wireless"
          ],
          "responses": {
            "200": {
              "description": "成功获取无线统计信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessStatisticsResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/wireless-traffic": {
        "get": {
          "summary": "获取无线流量统计",
          "description": "获取最近24小时内AP设备的无线流量统计数据，包括五分钟累计流量和实时上下行速率。\n可通过apmac参数过滤指定AP的数据，不提供则汇总所有AP数据。\n",
          "operationId": "getWirelessTraffic",
          "tags": [
            "monitor-wireless"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/apmacParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取无线流量统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessTrafficResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/wireless-score": {
        "get": {
          "summary": "获取无线网络评分",
          "description": "获取最近24小时内无线网络质量评分，包括用户活跃度、空口健康度、信道负载、\n关联稳定度、延迟、信号覆盖度、丢包率等评分指标。\n",
          "operationId": "getWirelessScore",
          "tags": [
            "monitor-wireless"
          ],
          "responses": {
            "200": {
              "description": "成功获取无线网络评分",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessScoreResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/ssid-clients": {
        "get": {
          "summary": "获取SSID终端统计",
          "description": "获取各SSID的终端连接历史统计信息，按每小时汇总。\n可通过ssid参数过滤指定SSID的数据，不提供则返回所有SSID数据。\n",
          "operationId": "getWirelessSsidClients",
          "tags": [
            "monitor-wireless"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/ssidParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取SSID终端统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessSsidClientsResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/monitoring/channel-clients": {
        "get": {
          "summary": "获取信道终端统计",
          "description": "获取各信道的终端连接历史统计信息，按每小时汇总。\n可通过channel参数过滤指定信道的数据，不提供则返回所有信道数据。\n",
          "operationId": "getWirelessChannelClients",
          "tags": [
            "monitor-wireless"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/channelParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取信道终端统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessChannelClientsResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "apmacParam": {
          "name": "apmac",
          "in": "query",
          "description": "AP设备MAC地址，不提供则汇总所有AP数据",
          "required": false,
          "schema": {
            "type": "string",
            "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
            "example": "00:00:00:00:00:00"
          }
        },
        "ssidParam": {
          "name": "ssid",
          "in": "query",
          "description": "SSID名称，不提供则返回所有SSID数据",
          "required": false,
          "schema": {
            "type": "string",
            "maxLength": 100,
            "example": "iKuai01_2G"
          }
        },
        "channelParam": {
          "name": "channel",
          "in": "query",
          "description": "无线信道号，不提供则返回所有信道数据",
          "required": false,
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 165,
            "example": 1
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WirelessStatisticsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WirelessStatisticsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessStatisticsResults": {
          "type": "object",
          "required": [
            "ap_status",
            "clt_status"
          ],
          "properties": {
            "ap_status": {
              "$ref": "#/components/schemas/ApStatus"
            },
            "clt_status": {
              "$ref": "#/components/schemas/CltStatus"
            }
          },
          "additionalProperties": false
        },
        "ApStatus": {
          "type": "object",
          "required": [
            "ap_count",
            "ap_online",
            "ap_offline",
            "ap_perfer_5g",
            "ap_roaming"
          ],
          "properties": {
            "ap_count": {
              "type": "integer",
              "description": "AP总数",
              "minimum": 0,
              "example": 3
            },
            "ap_online": {
              "type": "integer",
              "description": "在线AP数量",
              "minimum": 0,
              "example": 3
            },
            "ap_offline": {
              "type": "integer",
              "description": "离线AP数量",
              "minimum": 0,
              "example": 0
            },
            "ap_perfer_5g": {
              "type": "integer",
              "description": "偏好5G的AP数量",
              "minimum": 0,
              "example": 3
            },
            "ap_roaming": {
              "type": "integer",
              "description": "支持漫游的AP数量",
              "minimum": 0,
              "example": 3
            }
          },
          "additionalProperties": false
        },
        "CltStatus": {
          "type": "object",
          "required": [
            "clt_count",
            "clt_count_2g",
            "clt_count_5g",
            "clt_max_online",
            "clt_active",
            "clt_inactive"
          ],
          "properties": {
            "clt_count": {
              "type": "integer",
              "description": "终端总数",
              "minimum": 0,
              "example": 1
            },
            "clt_count_2g": {
              "type": "integer",
              "description": "2G终端数量",
              "minimum": 0,
              "example": 0
            },
            "clt_count_5g": {
              "type": "integer",
              "description": "5G终端数量",
              "minimum": 0,
              "example": 1
            },
            "clt_max_online": {
              "type": "integer",
              "description": "最近24小时最大在线终端数",
              "minimum": 0,
              "example": 3
            },
            "clt_active": {
              "type": "integer",
              "description": "活跃终端数",
              "minimum": 0,
              "example": 0
            },
            "clt_inactive": {
              "type": "integer",
              "description": "非活跃终端数",
              "minimum": 0,
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "WirelessTrafficResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WirelessTrafficResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessTrafficResults": {
          "type": "object",
          "properties": {
            "total_count_flow": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/WirelessTrafficFlow"
              },
              "description": "最近24小时流量统计数据列表（按时间戳分组）"
            }
          },
          "required": [
            "total_count_flow"
          ],
          "additionalProperties": false
        },
        "WirelessTrafficFlow": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "upload",
            "download",
            "count5m_up",
            "count5m_down"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763804700
            },
            "upload": {
              "type": "integer",
              "description": "上行速率汇总（bps）",
              "minimum": 0,
              "example": 1024
            },
            "download": {
              "type": "integer",
              "description": "下行速率汇总（bps）",
              "minimum": 0,
              "example": 2048
            },
            "count5m_up": {
              "type": "integer",
              "format": "int64",
              "description": "五分钟上行累计流量（字节）",
              "minimum": 0,
              "example": 0
            },
            "count5m_down": {
              "type": "integer",
              "format": "int64",
              "description": "五分钟下行累计流量（字节）",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "WirelessScoreResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WirelessScoreResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessScoreResults": {
          "type": "object",
          "properties": {
            "total_count_net_status": {
              "$ref": "#/components/schemas/WirelessNetworkScore"
            }
          },
          "required": [
            "total_count_net_status"
          ],
          "additionalProperties": false
        },
        "WirelessNetworkScore": {
          "type": "object",
          "required": [
            "score_active_user",
            "score_chutil_load",
            "score_channf_load",
            "score_conn_sta",
            "delay",
            "coverage",
            "dropptk"
          ],
          "properties": {
            "score_active_user": {
              "type": "integer",
              "description": "用户活跃度评分",
              "minimum": 0,
              "example": 74
            },
            "score_chutil_load": {
              "type": "integer",
              "description": "空口健康度评分",
              "minimum": 0,
              "example": 95
            },
            "score_channf_load": {
              "type": "integer",
              "description": "信道负载评分",
              "minimum": 0,
              "example": 100
            },
            "score_conn_sta": {
              "type": "integer",
              "description": "关联稳定度评分",
              "minimum": 0,
              "example": 98
            },
            "delay": {
              "type": "integer",
              "description": "延迟（毫秒）",
              "minimum": 0,
              "example": 0
            },
            "coverage": {
              "type": "integer",
              "description": "信号覆盖度",
              "minimum": 0,
              "example": 100
            },
            "dropptk": {
              "type": "integer",
              "description": "丢包率（2G+5G合计均值）",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "WirelessSsidClientsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WirelessSsidClientsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessSsidClientsResults": {
          "type": "object",
          "properties": {
            "ssid_sta_history": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SsidStaHistory"
              },
              "description": "SSID终端历史数据（每小时汇总）"
            }
          },
          "required": [
            "ssid_sta_history"
          ],
          "additionalProperties": false
        },
        "SsidStaHistory": {
          "type": "object",
          "required": [
            "total",
            "timestamp",
            "ssid"
          ],
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳，整点）",
              "example": 1763784900
            },
            "ssid": {
              "type": "string",
              "description": "SSID名称",
              "maxLength": 100,
              "example": "iKuai01_2G"
            },
            "total": {
              "type": "integer",
              "description": "终端总数（inactive+active之和）",
              "minimum": 0,
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "WirelessChannelClientsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WirelessChannelClientsResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessChannelClientsResults": {
          "type": "object",
          "properties": {
            "channel_sta_history": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ChannelStaHistory"
              },
              "description": "信道终端历史数据（每小时汇总）"
            }
          },
          "required": [
            "channel_sta_history"
          ],
          "additionalProperties": false
        },
        "ChannelStaHistory": {
          "type": "object",
          "required": [
            "apnum",
            "timestamp",
            "channel",
            "online"
          ],
          "properties": {
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳，整点）",
              "example": 1763784900
            },
            "channel": {
              "type": "integer",
              "description": "信道号",
              "minimum": 1,
              "maximum": 165,
              "example": 1
            },
            "online": {
              "type": "integer",
              "description": "在线终端数",
              "minimum": 0,
              "example": 0
            },
            "apnum": {
              "type": "integer",
              "description": "使用该信道的AP个数",
              "minimum": 0,
              "example": 1
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "monitor-wireless",
        "x-displayName": "无线监控",
        "description": "无线网络监控，包括AP状态、流量统计、网络评分、SSID和信道监控"
      }
    ]
  },
  "network/network-advanced-protocols.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "高级自定义协议管理API",
      "version": "1.0.0",
      "summary": "高级自定义协议管理完整功能",
      "description": "提供高级自定义协议的完整管理功能，包括：\n- 协议的创建、查询、更新、删除\n- 协议启用/停用状态控制\n- 支持9种协议分类：网络协议、网络游戏、社交通讯等\n- 支持自定义语法规则（Base64编码）\n- 自动生成应用ID\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/app-protocols/advanced/rules": {
        "get": {
          "summary": "获取高级自定义协议列表",
          "description": "获取所有高级自定义协议列表。\n支持分页功能。\n",
          "operationId": "listAdvancedProtocols",
          "tags": [
            "advanced-protocols"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取高级自定义协议列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AdvancedProtocolListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "comment": "test",
                          "rule": "UHJvdG9jb2w9SFRUUA==",
                          "name": "test",
                          "class": 2,
                          "appid": 2910001
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建高级自定义协议",
          "description": "创建新的高级自定义协议策略。\n支持选择协议分类和自定义语法规则（Base64编码）。\n",
          "operationId": "createAdvancedProtocol",
          "tags": [
            "advanced-protocols"
          ],
          "requestBody": {
            "required": true,
            "description": "高级自定义协议配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdvancedProtocolInput"
                },
                "example": {
                  "class": "0",
                  "comment": "aa",
                  "name": "aa",
                  "rule": "UHJvdG9jb2w9SFRUUA==",
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/app-protocols/advanced/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/advancedProtocolIdParam"
          }
        ],
        "get": {
          "summary": "获取指定高级自定义协议详情",
          "description": "根据ID获取单个高级自定义协议策略的详细信息。\n需要提供有效的策略ID。\n",
          "operationId": "getAdvancedProtocol",
          "tags": [
            "advanced-protocols"
          ],
          "responses": {
            "200": {
              "description": "成功获取高级自定义协议详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AdvancedProtocolResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "comment": "test",
                          "rule": "UHJvdG9jb2w9SFRUUA==",
                          "name": "test",
                          "class": 2,
                          "appid": 2910001
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新高级自定义协议",
          "description": "完全更新指定高级自定义协议策略的配置信息。\n需要提供所有字段。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateAdvancedProtocol",
          "tags": [
            "advanced-protocols"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的高级自定义协议配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdvancedProtocolEditInput"
                },
                "example": {
                  "class": 0,
                  "appid": 2910001,
                  "comment": "updated",
                  "name": "aa",
                  "rule": "UHJvdG9jb2w9SFRUUA==",
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用高级自定义协议",
          "description": "部分更新指定高级自定义协议策略。\n主要用于启用/停用状态切换。\n",
          "operationId": "patchAdvancedProtocol",
          "tags": [
            "advanced-protocols"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "启用状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "required": [
                    "enabled"
                  ]
                },
                "example": {
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除高级自定义协议",
          "description": "删除指定的高级自定义协议策略。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteAdvancedProtocol",
          "tags": [
            "advanced-protocols"
          ],
          "responses": {
            "200": {
              "description": "高级自定义协议删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "advancedProtocolIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "高级自定义协议ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AdvancedProtocol": {
          "type": "object",
          "required": [
            "id",
            "class",
            "appid"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态（启用/禁用）",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "test"
            },
            "name": {
              "type": "string",
              "description": "协议名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9]+$",
              "example": "test"
            },
            "class": {
              "type": "integer",
              "description": "协议分类（0-8）：\n- 0: 网络协议自定义\n- 1: 网络游戏自定义\n- 2: 社交通讯自定义\n- 3: 传输下载自定义\n- 4: 休闲娱乐自定义\n- 5: 效率工具自定义\n- 6: 办公协作自定义\n- 7: 学习教育自定义\n- 8: 生活服务自定义\n",
              "minimum": 0,
              "maximum": 8,
              "example": 2
            },
            "appid": {
              "type": "integer",
              "description": "应用ID（自动生成，不需要输入）",
              "readOnly": true,
              "example": 2910001
            },
            "rule": {
              "type": "string",
              "description": "语法规则（Base64编码）",
              "example": "UHJvdG9jb2w9SFRUUA=="
            }
          },
          "additionalProperties": false
        },
        "AdvancedProtocolInput": {
          "type": "object",
          "required": [
            "class",
            "name",
            "rule",
            "enabled"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态（启用/禁用）",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "aa"
            },
            "name": {
              "type": "string",
              "description": "协议名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9]+$",
              "example": "aa"
            },
            "class": {
              "type": "integer",
              "description": "协议分类（0-8）：\n- 0: 网络协议自定义\n- 1: 网络游戏自定义\n- 2: 社交通讯自定义\n- 3: 传输下载自定义\n- 4: 休闲娱乐自定义\n- 5: 效率工具自定义\n- 6: 办公协作自定义\n- 7: 学习教育自定义\n- 8: 生活服务自定义\n",
              "minimum": 0,
              "maximum": 8,
              "example": 0
            },
            "rule": {
              "type": "string",
              "description": "语法规则（Base64编码）",
              "example": "UHJvdG9jb2w9SFRUUA=="
            }
          },
          "additionalProperties": false
        },
        "AdvancedProtocolEditInput": {
          "type": "object",
          "description": "PUT全量修改，所有字段均为required；不修改的字段请保持原值或传空值，未传入的字段可能被重置。",
          "required": [
            "class",
            "appid",
            "enabled",
            "comment",
            "name",
            "rule"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态（启用/禁用）",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "aa"
            },
            "name": {
              "type": "string",
              "description": "协议名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9]+$",
              "example": "aa"
            },
            "class": {
              "type": "integer",
              "description": "协议分类（0-8）：\n- 0: 网络协议自定义\n- 1: 网络游戏自定义\n- 2: 社交通讯自定义\n- 3: 传输下载自定义\n- 4: 休闲娱乐自定义\n- 5: 效率工具自定义\n- 6: 办公协作自定义\n- 7: 学习教育自定义\n- 8: 生活服务自定义\n",
              "minimum": 0,
              "maximum": 8,
              "example": 0
            },
            "appid": {
              "type": "integer",
              "description": "应用ID（由系统根据协议名和分类自动生成，需从查询接口获取后传入）",
              "example": 2910001
            },
            "rule": {
              "type": "string",
              "description": "语法规则（Base64编码）",
              "example": "UHJvdG9jb2w9SFRUUA=="
            }
          },
          "additionalProperties": false
        },
        "AdvancedProtocolResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AdvancedProtocol"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AdvancedProtocolListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AdvancedProtocol"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "advanced-protocols",
        "x-displayName": "高级协议管理",
        "description": "高级自定义协议管理，支持9种协议分类和自定义语法规则（Base64编码）"
      }
    ]
  },
  "network/network-dhcp-access.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DHCP访问控制管理API",
      "version": "1.0.0",
      "summary": "DHCP黑名单和白名单模式的完整管理功能",
      "description": "提供DHCP访问控制的完整管理功能，包括：\n- 黑名单和白名单模式切换\n- 访问控制规则的创建和管理\n- 基于MAC地址的访问控制\n- 规则的启用/停用管理\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dhcp/access-control/mode": {
        "get": {
          "summary": "获取访问控制模式",
          "description": "获取当前DHCP访问控制的工作模式。\n返回黑名单模式或白名单模式。\n",
          "operationId": "getDhcpAccessMode",
          "tags": [
            "dhcp-access-mode"
          ],
          "responses": {
            "200": {
              "description": "成功获取访问控制模式",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpAccessModeResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "mode": 0
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "设置访问控制模式",
          "description": "设置DHCP访问控制的工作模式。\n可以在黑名单模式和白名单模式之间切换。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "setDhcpAccessMode",
          "tags": [
            "dhcp-access-mode"
          ],
          "requestBody": {
            "required": true,
            "description": "访问控制模式配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DhcpAccessModeInput"
                },
                "example": {
                  "mode": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "访问控制模式设置成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpAccessModeResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp/access-control/rules": {
        "get": {
          "summary": "获取访问控制规则列表",
          "description": "获取当前配置的所有DHCP访问控制规则列表。\n根据当前模式，这些规则可能是黑名单或白名单。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDhcpAccessRules",
          "tags": [
            "dhcp-access-rules"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=mac==11:22:33:44:55:66\n- OR条件：filter=tagname==test001,tagname==test007\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取访问控制规则列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpAccessRulesListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "tagname": "test001",
                          "mac": "11:22:33:44:55:66",
                          "ip_type": "4",
                          "comment": "test001"
                        },
                        {
                          "id": 2,
                          "enabled": "yes",
                          "tagname": "test007",
                          "mac": "11:22:33:44:55:67",
                          "ip_type": "4",
                          "comment": "test007-comment"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建访问控制规则",
          "description": "添加新的DHCP访问控制规则。\n根据当前模式，该规则将被添加到黑名单或白名单中。\nenabled、mac、tagname 为必需字段，comment 可选。\n",
          "operationId": "createDhcpAccessRule",
          "tags": [
            "dhcp-access-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "访问控制规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DhcpAccessRuleCreateInput"
                },
                "example": {
                  "enabled": "yes",
                  "mac": "11:22:33:44:55:68",
                  "tagname": "test008"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 3
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（MAC地址已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  "example": {
                    "message": "MAC地址已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp/access-control/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/accessRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定访问控制规则",
          "description": "根据规则ID获取单个DHCP访问控制规则的详细信息。\n需要提供有效的规则ID。\n",
          "operationId": "getDhcpAccessRule",
          "tags": [
            "dhcp-access-rules"
          ],
          "responses": {
            "200": {
              "description": "成功获取访问控制规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpAccessRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新访问控制规则",
          "description": "完全更新现有的DHCP访问控制规则配置。\n需要提供所有字段。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDhcpAccessRule",
          "tags": [
            "dhcp-access-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的访问控制规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DhcpAccessRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用访问控制规则",
          "description": "部分更新现有的DHCP访问控制规则配置。\n主要用于启用/停用规则状态。\n",
          "operationId": "patchDhcpAccessRule",
          "tags": [
            "dhcp-access-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除访问控制规则",
          "description": "删除指定的DHCP访问控制规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDhcpAccessRule",
          "tags": [
            "dhcp-access-rules"
          ],
          "responses": {
            "200": {
              "description": "访问控制规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "accessRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "访问控制规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、mac、tagname等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DhcpAccessModeResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "mode": {
              "type": "integer",
              "description": "访问控制模式，0:黑名单模式 1:白名单模式 2:同步安全中心MAC访问控制",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            }
          },
          "required": [
            "code",
            "message",
            "mode"
          ],
          "additionalProperties": false
        },
        "DhcpAccessModeInput": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "integer",
              "description": "访问控制模式，0:黑名单模式 1:白名单模式 2:同步安全中心MAC访问控制",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            }
          },
          "required": [
            "mode"
          ],
          "additionalProperties": false
        },
        "DhcpAccessRuleCreateResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建的规则ID",
              "example": 3
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "DhcpAccessRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DhcpAccessRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpAccessRulesListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DhcpAccessRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpAccessRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "mac",
            "ip_type"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "11:22:33:44:55:66"
            },
            "ip_type": {
              "type": "string",
              "description": "IP类型",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "DhcpAccessRuleCreateInput": {
          "type": "object",
          "required": [
            "enabled",
            "mac",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "11:22:33:44:55:68"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test008"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test008-comment"
            }
          },
          "additionalProperties": false
        },
        "DhcpAccessRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "mac",
            "tagname",
            "comment"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "11:22:33:44:55:68"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test008"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test008-comment"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/DhcpAccessRuleCreateResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dhcp-access-mode",
        "x-displayName": "DHCP访问控制模式",
        "description": "DHCP黑名单和白名单模式的设置和切换"
      },
      {
        "name": "dhcp-access-rules",
        "x-displayName": "DHCP访问控制规则",
        "description": "DHCP访问控制规则的管理和配置"
      }
    ]
  },
  "network/network-dhcp-clients.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DHCP客户端管理API",
      "version": "1.0.0",
      "summary": "DHCP和DHCPv6客户端终端列表的查询功能",
      "description": "提供DHCP客户端信息的查询功能，包括：\n- DHCPv4客户端列表查询\n- DHCPv6客户端列表查询\n- 客户端租约信息查看\n- 客户端连接状态监控\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dhcp/clients": {
        "get": {
          "summary": "获取DHCP客户端列表",
          "description": "获取当前通过DHCPv4服务器分配IP地址的所有客户端信息。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDhcpClients",
          "tags": [
            "dhcp-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=interface==lan1\n- AND条件：filter=interface==lan1&filter=status==0\n- OR条件：filter=mac==7a:38:7a:39:95:71,mac==11:22:33:44:55:66\n",
              "schema": {
                "type": "string",
                "example": "interface==lan1"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取DHCP客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpClientsListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "mac": "7a:38:7a:39:95:71",
                          "start_time": 1767087726,
                          "end_time": 1767094926,
                          "timeout": 4630,
                          "termname": "",
                          "hostname": "",
                          "status": 0,
                          "id": 24,
                          "interface": "lan1",
                          "ip_addr_int": 3232260968,
                          "ip_addr": "192.168.99.104"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp6/clients": {
        "get": {
          "summary": "获取DHCPv6客户端列表",
          "description": "获取当前通过DHCPv6服务器分配IPv6地址的所有客户端信息。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDhcp6Clients",
          "tags": [
            "dhcpv6-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=interface==lan1\n- AND条件：filter=interface==lan1&filter=timeout>1000\n- OR条件：filter=mac==a6:28:e6:a1:23:5d,mac==11:22:33:44:55:66\n",
              "schema": {
                "type": "string",
                "example": "interface==lan1"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取DHCPv6客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Dhcp6ClientsListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "client_total": 1,
                      "client_data": [
                        {
                          "id": 2,
                          "interface": "lan1",
                          "link_addr": "fe80::ef:8645:497a:db87",
                          "duid": "00030001a628e6a1235d",
                          "hostname": "",
                          "start_time": 1767089750,
                          "expires": 1767096950,
                          "timeout": 6656,
                          "termname": "",
                          "ipv6_addr": "fc00:78aa:2521:1::cd1",
                          "mac": "a6:28:e6:a1:23:5d"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、interface、mac、ip_addr、start_time等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DhcpClientsListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DhcpClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Dhcp6ClientsListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "client_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "client_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Dhcp6Client"
                  }
                }
              },
              "required": [
                "client_total",
                "client_data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpClient": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ip_addr",
            "interface",
            "start_time",
            "end_time",
            "timeout",
            "status"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端记录ID",
              "minimum": 1,
              "example": 24
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "7a:38:7a:39:95:71"
            },
            "ip_addr": {
              "type": "string",
              "description": "IPv4地址",
              "format": "ipv4",
              "example": "192.168.99.104"
            },
            "ip_addr_int": {
              "type": "integer",
              "description": "IP地址的整数表示",
              "format": "int64",
              "example": 3232260968
            },
            "interface": {
              "type": "string",
              "description": "网络接口",
              "pattern": "^[a-zA-Z0-9]+$",
              "example": "lan1"
            },
            "hostname": {
              "type": "string",
              "description": "主机名",
              "maxLength": 255,
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 100,
              "example": ""
            },
            "start_time": {
              "type": "integer",
              "description": "租约开始时间（Unix时间戳）",
              "format": "int64",
              "example": 1767087726
            },
            "end_time": {
              "type": "integer",
              "description": "租约结束时间（Unix时间戳）",
              "format": "int64",
              "example": 1767094926
            },
            "timeout": {
              "type": "integer",
              "description": "过期时间（秒）",
              "minimum": 0,
              "example": 4630
            },
            "status": {
              "type": "integer",
              "description": "客户端状态",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "Dhcp6Client": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "ipv6_addr",
            "interface",
            "duid",
            "start_time",
            "expires",
            "timeout"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端记录ID",
              "minimum": 1,
              "example": 2
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "a6:28:e6:a1:23:5d"
            },
            "ipv6_addr": {
              "type": "string",
              "description": "IPv6地址",
              "format": "ipv6",
              "example": "fc00:78aa:2521:1::cd1"
            },
            "link_addr": {
              "type": "string",
              "description": "链路本地地址",
              "format": "ipv6",
              "example": "fe80::ef:8645:497a:db87"
            },
            "interface": {
              "type": "string",
              "description": "网络接口",
              "pattern": "^[a-zA-Z0-9]+$",
              "example": "lan1"
            },
            "duid": {
              "type": "string",
              "description": "DHCP唯一标识符",
              "pattern": "^[0-9a-fA-F]+$",
              "maxLength": 128,
              "example": "00030001a628e6a1235d"
            },
            "hostname": {
              "type": "string",
              "description": "主机名",
              "maxLength": 255,
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "maxLength": 100,
              "example": ""
            },
            "start_time": {
              "type": "integer",
              "description": "租约开始时间（Unix时间戳）",
              "format": "int64",
              "example": 1767089750
            },
            "expires": {
              "type": "integer",
              "description": "租约过期时间（Unix时间戳）",
              "format": "int64",
              "example": 1767096950
            },
            "timeout": {
              "type": "integer",
              "description": "过期时间（秒）",
              "minimum": 0,
              "example": 6656
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dhcp-clients",
        "x-displayName": "DHCP客户端",
        "description": "DHCPv4客户端信息查询"
      },
      {
        "name": "dhcpv6-clients",
        "x-displayName": "DHCPv6客户端",
        "description": "DHCPv6客户端信息查询"
      }
    ]
  },
  "network/network-dhcp-server.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DHCP服务管理API",
      "version": "1.0.0",
      "summary": "DHCP服务的完整管理功能",
      "description": "提供DHCP服务的完整管理功能，包括：\n- 策略配置和更新\n- 地址池管理\n- 服务状态控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dhcp/services": {
        "get": {
          "summary": "获取所有DHCP策略",
          "description": "获取当前配置的所有DHCP服务策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDhcpServices",
          "tags": [
            "dhcp-service"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=lease>3600&filter=interface==eth0\n- OR条件：filter=dns1==8.8.8.8,filter=dns2==8.8.4.4\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取DHCP策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpServiceListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建DHCP策略",
          "description": "添加新的DHCP服务策略，包括地址池、DNS、WINS等配置。\n所有必需字段必须提供。\n",
          "operationId": "createDhcpService",
          "tags": [
            "dhcp-service"
          ],
          "requestBody": {
            "required": true,
            "description": "DHCP服务配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DHCPServiceInput"
                },
                "example": {
                  "enabled": "yes",
                  "interface": "eth0",
                  "phy_ifnames": "eth0,veth0",
                  "addr_pool": "192.168.1.100-192.168.1.200",
                  "exclude_pool": "192.168.1.101,192.168.1.102",
                  "netmask": "255.255.255.0",
                  "gateway": "192.168.1.1",
                  "dns1": "8.8.8.8",
                  "dns2": "8.8.4.4",
                  "wins1": "192.168.1.10",
                  "wins2": "192.168.1.11",
                  "domain": "example.com",
                  "next_server": "192.168.1.2",
                  "lease": 3600,
                  "delay": 600,
                  "opt_type15": 0,
                  "opt15": "example.local",
                  "opt_type28": 1,
                  "opt28": "192.168.1.255",
                  "opt_type43": 2,
                  "opt43": "vendor-specific-data",
                  "opt_type60": 0,
                  "opt60": "PXEClient",
                  "opt_type66": 2,
                  "opt66": "tftp.example.com",
                  "opt_type67": 2,
                  "opt67": "pxelinux.0",
                  "opt_type80": 1,
                  "opt80": "client-identifier",
                  "opt_type119": 2,
                  "opt119": "example.com,corp.com",
                  "opt_type125": 0,
                  "opt125": "",
                  "opt_type128": 1,
                  "opt128": "192.168.1.100",
                  "opt_type138": 1,
                  "opt138": "192.168.1.100",
                  "opt_type121": 1,
                  "opt121": "192.168.1.0,255.255.255.0,192.168.1.1",
                  "check_addr_valid": 1,
                  "check_relay_only": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（名称已存在或地址池冲突）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpErrorResponse"
                  },
                  "example": {
                    "message": "名称已存在或地址池冲突"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp/services/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/dhcpServiceIdParam"
          }
        ],
        "get": {
          "summary": "获取指定DHCP策略",
          "description": "根据策略ID获取单个DHCP服务策略的详细信息。\n需要提供有效的策略ID。\n",
          "operationId": "getDhcpService",
          "tags": [
            "dhcp-service"
          ],
          "responses": {
            "200": {
              "description": "成功获取DHCP策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpServiceResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新DHCP策略",
          "description": "完全更新现有的DHCP服务策略配置。\n需要提供所有字段。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDhcpService",
          "tags": [
            "dhcp-service"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的DHCP服务配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DHCPServiceInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用DHCP策略",
          "description": "部分更新现有的DHCP服务策略配置。\n主要用于启用/停用策略状态。\n",
          "operationId": "patchDhcpService",
          "tags": [
            "dhcp-service"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "服务启用状态",
                      "example": "yes"
                    }
                  }
                },
                "example": {
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除DHCP策略",
          "description": "删除指定的DHCP服务策略。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDhcpService",
          "tags": [
            "dhcp-service"
          ],
          "responses": {
            "200": {
              "description": "DHCP策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp/services:restart": {
        "post": {
          "summary": "重启DHCP服务",
          "description": "重启DHCP服务，所有配置更改将生效。\n服务重启期间可能会有短暂的服务中断。\n",
          "operationId": "restartDhcpService",
          "tags": [
            "dhcp-service-control"
          ],
          "responses": {
            "200": {
              "description": "DHCP服务重启成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "服务重启异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpErrorResponse"
                  },
                  "example": {
                    "message": "服务重新启动异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "dhcpServiceIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "DHCP策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、interface、lease等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DhcpServiceResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DHCPService"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpServiceListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DHCPService"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "DHCP业务错误信息描述"
            }
          }
        },
        "DHCPService": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "interface",
            "phy_ifnames",
            "addr_pool",
            "netmask",
            "gateway"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "服务启用状态，yes为启用（默认），no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "iKuai-DHCP"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口名称",
              "pattern": "^[a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "lan1"
            },
            "phy_ifnames": {
              "type": "string",
              "description": "绑定的物理网卡名称，多个用逗号分隔",
              "pattern": "^[a-zA-Z0-9,]+$",
              "minLength": 1,
              "example": "eth0,veth0"
            },
            "addr_pool": {
              "type": "string",
              "description": "DHCP地址池范围，格式为起始IP-结束IP",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)-((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$",
              "example": "192.168.1.100-192.168.1.200"
            },
            "exclude_pool": {
              "type": "string",
              "description": "排除的地址范围，在地址池中不分配的IP，多个用逗号分隔",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(,((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))*$",
              "example": "192.168.1.101,192.168.1.102"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.255.0"
            },
            "gateway": {
              "type": "string",
              "description": "默认网关地址",
              "format": "ipv4",
              "example": "192.168.1.1"
            },
            "dns1": {
              "type": "string",
              "description": "主DNS服务器地址，默认为223.5.5.5",
              "format": "ipv4",
              "default": "223.5.5.5",
              "example": "8.8.8.8"
            },
            "dns2": {
              "type": "string",
              "description": "次DNS服务器地址，默认为223.6.6.6",
              "format": "ipv4",
              "default": "223.6.6.6",
              "example": "8.8.4.4"
            },
            "wins1": {
              "type": "string",
              "description": "主WINS服务器地址，用于Windows客户端",
              "format": "ipv4",
              "example": "192.168.1.10"
            },
            "wins2": {
              "type": "string",
              "description": "次WINS服务器地址，用于Windows客户端",
              "format": "ipv4",
              "example": "192.168.1.11"
            },
            "domain": {
              "type": "string",
              "description": "DNS域名",
              "format": "hostname",
              "example": "example.com"
            },
            "next_server": {
              "type": "string",
              "description": "下一跳服务器IP地址，通常用于PXE启动",
              "format": "ipv4",
              "example": "192.168.1.2"
            },
            "lease": {
              "type": "integer",
              "description": "IP地址租赁时间（秒），默认为3600（1小时）",
              "minimum": 1,
              "maximum": 525600,
              "default": 3600,
              "example": 3600
            },
            "delay": {
              "type": "integer",
              "description": "过期地址保留时间（秒），默认为600（10分钟）",
              "minimum": 0,
              "maximum": 2160,
              "default": 600,
              "example": 600
            },
            "opt_type15": {
              "type": "integer",
              "description": "Option type 15类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type28": {
              "type": "integer",
              "description": "Option type 28类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type43": {
              "type": "integer",
              "description": "Option type 43类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type60": {
              "type": "integer",
              "description": "Option type 60类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type66": {
              "type": "integer",
              "description": "Option type 66类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type67": {
              "type": "integer",
              "description": "Option type 67类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type80": {
              "type": "integer",
              "description": "Option type 80类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type119": {
              "type": "integer",
              "description": "Option type 119类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type125": {
              "type": "integer",
              "description": "Option type 125类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type128": {
              "type": "integer",
              "description": "Option type 128类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type138": {
              "type": "integer",
              "description": "Option type 138类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type121": {
              "type": "integer",
              "description": "Option type 121类型，0: 16进制 2: 路由列表（IP/掩码 网关）",
              "enum": [
                0,
                2
              ],
              "default": 2,
              "example": 2
            },
            "opt15": {
              "type": "string",
              "description": "Option 15内容，用于指定用户的DNS域名",
              "default": "",
              "example": ""
            },
            "opt28": {
              "type": "string",
              "description": "Option 28内容，广播地址配置",
              "default": "",
              "example": ""
            },
            "opt43": {
              "type": "string",
              "description": "Option 43内容，供应商特定信息的配置内容",
              "default": "",
              "example": ""
            },
            "opt60": {
              "type": "string",
              "description": "Option 60内容，供应商类别标识符，用于标识设备厂商类型",
              "default": "",
              "example": ""
            },
            "opt66": {
              "type": "string",
              "description": "Option 66内容，TFTP服务器名称，用于PXE启动",
              "default": "",
              "example": ""
            },
            "opt67": {
              "type": "string",
              "description": "Option 67内容，PXE启动文件名配置",
              "default": "",
              "example": ""
            },
            "opt80": {
              "type": "string",
              "description": "Option 80内容，客户端标识符用于唯一识别客户端",
              "default": "",
              "example": ""
            },
            "opt119": {
              "type": "string",
              "description": "Option 119内容，域名搜索列表，指定DNS搜索域",
              "default": "",
              "example": ""
            },
            "opt125": {
              "type": "string",
              "description": "Option 125内容，供应商标识符，用于识别DHCP供应商设备",
              "default": "",
              "example": ""
            },
            "opt128": {
              "type": "string",
              "description": "Option 128内容，微软PXE启动相关配置",
              "default": "",
              "example": ""
            },
            "opt138": {
              "type": "string",
              "description": "Option 138内容，微软特定选项用于远程启动",
              "default": "",
              "example": ""
            },
            "opt121": {
              "type": "string",
              "description": "Option 121内容，静态路由配置，指定客户端应添加到路由表的路由",
              "default": "",
              "example": ""
            },
            "check_addr_valid": {
              "type": "integer",
              "description": "是否检查IP地址有效性，1为检查，0为不检查",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "check_relay_only": {
              "type": "integer",
              "description": "是否只能使用与中继请求，1为是，0为否",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "DHCPServiceInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "interface",
            "phy_ifnames",
            "addr_pool",
            "netmask",
            "gateway",
            "lease",
            "delay",
            "check_addr_valid",
            "check_relay_only"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "服务启用状态，yes为启用（默认），no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "iKuai-DHCP"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口名称",
              "pattern": "^[a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "lan1"
            },
            "phy_ifnames": {
              "type": "string",
              "description": "绑定的物理网卡名称，多个用逗号分隔",
              "pattern": "^[a-zA-Z0-9,]+$",
              "minLength": 1,
              "example": "eth0,veth0"
            },
            "addr_pool": {
              "type": "string",
              "description": "DHCP地址池范围，格式为起始IP-结束IP",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)-((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$",
              "example": "192.168.1.100-192.168.1.200"
            },
            "exclude_pool": {
              "type": "string",
              "description": "排除的地址范围，在地址池中不分配的IP，多个用逗号分隔",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(,((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))*$",
              "example": "192.168.1.101,192.168.1.102"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.255.0"
            },
            "gateway": {
              "type": "string",
              "description": "默认网关地址",
              "format": "ipv4",
              "example": "192.168.1.1"
            },
            "dns1": {
              "type": "string",
              "description": "主DNS服务器地址，默认为223.5.5.5",
              "format": "ipv4",
              "default": "223.5.5.5",
              "example": "8.8.8.8"
            },
            "dns2": {
              "type": "string",
              "description": "次DNS服务器地址，默认为223.6.6.6",
              "format": "ipv4",
              "default": "223.6.6.6",
              "example": "8.8.4.4"
            },
            "wins1": {
              "type": "string",
              "description": "主WINS服务器地址，用于Windows客户端",
              "format": "ipv4",
              "example": "192.168.1.10"
            },
            "wins2": {
              "type": "string",
              "description": "次WINS服务器地址，用于Windows客户端",
              "format": "ipv4",
              "example": "192.168.1.11"
            },
            "domain": {
              "type": "string",
              "description": "DNS域名",
              "format": "hostname",
              "example": "example.com"
            },
            "next_server": {
              "type": "string",
              "description": "下一跳服务器IP地址，通常用于PXE启动",
              "format": "ipv4",
              "example": "192.168.1.2"
            },
            "lease": {
              "type": "integer",
              "description": "IP地址租赁时间（秒），默认为3600（1小时）",
              "minimum": 1,
              "maximum": 525600,
              "default": 3600,
              "example": 3600
            },
            "delay": {
              "type": "integer",
              "description": "过期地址保留时间（秒），默认为600（10分钟）",
              "minimum": 0,
              "maximum": 2160,
              "default": 600,
              "example": 600
            },
            "opt_type15": {
              "type": "integer",
              "description": "Option type 15类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type28": {
              "type": "integer",
              "description": "Option type 28类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type43": {
              "type": "integer",
              "description": "Option type 43类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type60": {
              "type": "integer",
              "description": "Option type 60类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type66": {
              "type": "integer",
              "description": "Option type 66类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type67": {
              "type": "integer",
              "description": "Option type 67类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type80": {
              "type": "integer",
              "description": "Option type 80类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type119": {
              "type": "integer",
              "description": "Option type 119类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type125": {
              "type": "integer",
              "description": "Option type 125类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type128": {
              "type": "integer",
              "description": "Option type 128类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type138": {
              "type": "integer",
              "description": "Option type 138类型，0: 16进制 1: IP地址 2: 字符串",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "opt_type121": {
              "type": "integer",
              "description": "Option type 121类型，0: 16进制 2: 路由列表（IP/掩码 网关）",
              "enum": [
                0,
                2
              ],
              "default": 2,
              "example": 2
            },
            "opt15": {
              "type": "string",
              "description": "Option 15内容，用于指定用户的DNS域名",
              "default": "",
              "example": ""
            },
            "opt28": {
              "type": "string",
              "description": "Option 28内容，广播地址配置",
              "default": "",
              "example": ""
            },
            "opt43": {
              "type": "string",
              "description": "Option 43内容，供应商特定信息的配置内容",
              "default": "",
              "example": ""
            },
            "opt60": {
              "type": "string",
              "description": "Option 60内容，供应商类别标识符，用于标识设备厂商类型",
              "default": "",
              "example": ""
            },
            "opt66": {
              "type": "string",
              "description": "Option 66内容，TFTP服务器名称，用于PXE启动",
              "default": "",
              "example": ""
            },
            "opt67": {
              "type": "string",
              "description": "Option 67内容，PXE启动文件名配置",
              "default": "",
              "example": ""
            },
            "opt80": {
              "type": "string",
              "description": "Option 80内容，客户端标识符用于唯一识别客户端",
              "default": "",
              "example": ""
            },
            "opt119": {
              "type": "string",
              "description": "Option 119内容，域名搜索列表，指定DNS搜索域",
              "default": "",
              "example": ""
            },
            "opt125": {
              "type": "string",
              "description": "Option 125内容，供应商标识符，用于识别DHCP供应商设备",
              "default": "",
              "example": ""
            },
            "opt128": {
              "type": "string",
              "description": "Option 128内容，微软PXE启动相关配置",
              "default": "",
              "example": ""
            },
            "opt138": {
              "type": "string",
              "description": "Option 138内容，微软特定选项用于远程启动",
              "default": "",
              "example": ""
            },
            "opt121": {
              "type": "string",
              "description": "Option 121内容，静态路由配置，指定客户端应添加到路由表的路由",
              "default": "",
              "example": ""
            },
            "check_addr_valid": {
              "type": "integer",
              "description": "是否检查IP地址有效性，1为检查，0为不检查",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "check_relay_only": {
              "type": "integer",
              "description": "是否只能使用与中继请求，1为是，0为否",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dhcp-service",
        "x-displayName": "DHCP服务",
        "description": "DHCP服务策略的管理和配置"
      },
      {
        "name": "dhcp-service-control",
        "x-displayName": "DHCP服务控制",
        "description": "DHCP服务的重启控制"
      }
    ]
  },
  "network/network-dhcp-static.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DHCP静态分配管理API",
      "version": "1.0.0",
      "summary": "DHCP静态IP地址分配的完整管理功能",
      "description": "提供DHCP静态分配的完整管理功能，包括：\n- 静态分配规则创建和管理\n- 为特定MAC地址分配固定IP\n- 支持自定义网关和DNS配置\n- 规则的启用/停用管理\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dhcp/static": {
        "get": {
          "summary": "获取静态分配列表",
          "description": "获取当前配置的所有DHCP静态分配规则列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDhcpStatic",
          "tags": [
            "dhcp-static"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==lan1\n- OR条件：filter=mac==11:22:33:44:55:66,mac==11:22:33:44:55:77\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取静态分配列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpStaticListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "static_total": 2,
                      "static_data": [
                        {
                          "mac": "11:22:33:44:55:66",
                          "gateway": "192.168.9.1",
                          "dns1": "223.5.5.5",
                          "dns2": "223.6.6.6",
                          "ip_addr": "192.168.9.120",
                          "ip_addr_int": 3232237944,
                          "comment": "test001",
                          "id": 1,
                          "enabled": "yes",
                          "hostname": "",
                          "tagname": "term001",
                          "interface": "lan1"
                        },
                        {
                          "mac": "11:22:33:44:55:77",
                          "gateway": "192.168.9.1",
                          "dns1": "223.5.5.5",
                          "dns2": "119.29.29.29",
                          "ip_addr": "192.168.9.111",
                          "ip_addr_int": 3232237935,
                          "comment": "test003",
                          "id": 2,
                          "enabled": "yes",
                          "hostname": "",
                          "tagname": "test002",
                          "interface": "lan1"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建静态分配规则",
          "description": "添加新的DHCP静态分配规则，为特定MAC地址分配固定IP地址。\n所有必需字段必须提供。\n",
          "operationId": "createDhcpStatic",
          "tags": [
            "dhcp-static"
          ],
          "requestBody": {
            "required": true,
            "description": "静态分配规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DhcpStaticInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "备注",
                  "interface": "lan1",
                  "ip_addr": "192.168.1.100",
                  "mac": "xx:xx:xx:xx:xx:xx",
                  "gateway": "192.168.1.1",
                  "dns1": "8.8.8.8",
                  "dns2": "8.8.4.4",
                  "tagname": "test",
                  "hostname": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（MAC地址或IP地址已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  "example": {
                    "message": "MAC地址或IP地址已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp/static/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/staticIdParam"
          }
        ],
        "get": {
          "summary": "获取指定静态分配规则",
          "description": "根据规则ID获取单个DHCP静态分配规则的详细信息。\n需要提供有效的规则ID。\n",
          "operationId": "getDhcpStatic",
          "tags": [
            "dhcp-static"
          ],
          "responses": {
            "200": {
              "description": "成功获取静态分配规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpStaticResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新静态分配规则",
          "description": "完全更新现有的DHCP静态分配规则配置。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDhcpStatic",
          "tags": [
            "dhcp-static"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的静态分配规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DhcpStaticInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用静态分配规则",
          "description": "部分更新现有的DHCP静态分配规则配置。\n主要用于启用/停用规则状态。\n",
          "operationId": "patchDhcpStatic",
          "tags": [
            "dhcp-static"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除静态分配规则",
          "description": "删除指定的DHCP静态分配规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDhcpStatic",
          "tags": [
            "dhcp-static"
          ],
          "responses": {
            "200": {
              "description": "静态分配规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "staticIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "静态分配规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、interface、ip_addr、mac等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DhcpStaticCreateResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建的规则ID",
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "DhcpStaticResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DhcpStatic"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpStaticListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "static_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 2
                },
                "static_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DhcpStatic"
                  }
                }
              },
              "required": [
                "static_total",
                "static_data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpStatic": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "mac",
            "ip_addr",
            "interface",
            "tagname"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用（默认），no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$|^([0-9A-Fa-f]{2}-){5}[0-9A-Fa-f]{2}$|^[0-9A-Fa-f]{12}$",
              "example": "11:22:33:44:55:66"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.9.120"
            },
            "ip_addr_int": {
              "type": "integer",
              "description": "IP地址的整数表示",
              "format": "int64",
              "example": 3232237944
            },
            "interface": {
              "type": "string",
              "description": "接口名称，支持 auto、lan* 或 vlan* 格式，最大15个字符",
              "pattern": "^(auto|lan[a-zA-Z0-9]*|vlan[a-zA-Z0-9]*)$",
              "maxLength": 15,
              "example": "lan1"
            },
            "gateway": {
              "type": "string",
              "description": "网关地址",
              "example": "192.168.9.1"
            },
            "dns1": {
              "type": "string",
              "description": "DNS1服务器地址",
              "example": "223.5.5.5"
            },
            "dns2": {
              "type": "string",
              "description": "DNS2服务器地址",
              "example": "223.6.6.6"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "term001"
            },
            "hostname": {
              "type": "string",
              "description": "主机名",
              "maxLength": 255,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "DhcpStaticInput": {
          "type": "object",
          "required": [
            "enabled",
            "mac",
            "ip_addr",
            "interface",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用（默认），no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$|^([0-9A-Fa-f]{2}-){5}[0-9A-Fa-f]{2}$|^[0-9A-Fa-f]{12}$",
              "example": "11:22:33:44:55:66"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.1.100"
            },
            "interface": {
              "type": "string",
              "description": "接口名称，支持 auto、lan* 或 vlan* 格式，最大15个字符",
              "pattern": "^(auto|lan[a-zA-Z0-9]*|vlan[a-zA-Z0-9]*)$",
              "maxLength": 15,
              "example": "lan1"
            },
            "gateway": {
              "type": "string",
              "description": "网关地址，不填则为空",
              "example": "192.168.1.1"
            },
            "dns1": {
              "type": "string",
              "description": "DNS1服务器地址",
              "example": "8.8.8.8"
            },
            "dns2": {
              "type": "string",
              "description": "DNS2服务器地址",
              "example": "8.8.4.4"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "备注"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test"
            },
            "hostname": {
              "type": "string",
              "description": "主机名",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/DhcpStaticCreateResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dhcp-static",
        "x-displayName": "DHCP静态分配",
        "description": "DHCP静态IP地址分配规则的管理和配置"
      }
    ]
  },
  "network/network-dhcp6-access.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DHCPv6访问控制管理API",
      "version": "1.0.0",
      "summary": "DHCPv6黑名单和白名单模式的完整管理功能",
      "description": "提供DHCPv6访问控制的完整管理功能，包括：\n- 黑名单和白名单模式切换\n- 访问控制规则的创建和管理\n- 基于MAC地址的访问控制\n- 规则的启用/停用管理\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dhcp6/access-control/mode": {
        "get": {
          "summary": "获取DHCPv6访问控制模式",
          "description": "获取当前DHCPv6访问控制的工作模式。\n返回黑名单模式或白名单模式。\n",
          "operationId": "getDhcp6AccessMode",
          "tags": [
            "dhcpv6-access-mode"
          ],
          "responses": {
            "200": {
              "description": "成功获取访问控制模式",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Dhcp6AccessModeResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "mode": 0
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "设置DHCPv6访问控制模式",
          "description": "设置DHCPv6访问控制的工作模式。\n可以在黑名单模式和白名单模式之间切换。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "setDhcp6AccessMode",
          "tags": [
            "dhcpv6-access-mode"
          ],
          "requestBody": {
            "required": true,
            "description": "访问控制模式配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dhcp6AccessModeInput"
                },
                "example": {
                  "mode": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "访问控制模式设置成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Dhcp6AccessModeResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp6/access-control/rules": {
        "get": {
          "summary": "获取DHCPv6访问控制规则列表",
          "description": "获取当前配置的所有DHCPv6访问控制规则列表。\n根据当前模式，这些规则可能是黑名单或白名单。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDhcp6AccessRules",
          "tags": [
            "dhcpv6-access-rules"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=mac==11:22:33:44:55:66\n- OR条件：filter=tagname==test001,tagname==test007\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取访问控制规则列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Dhcp6AccessRulesListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "tagname": "test001",
                          "mac": "11:22:33:44:55:66",
                          "comment": "test001"
                        },
                        {
                          "id": 2,
                          "enabled": "yes",
                          "tagname": "test007",
                          "mac": "11:22:33:44:55:67",
                          "comment": "test007-comment"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建DHCPv6访问控制规则",
          "description": "添加新的DHCPv6访问控制规则。\n根据当前模式，该规则将被添加到黑名单或白名单中。\n所有必需字段必须提供。\n",
          "operationId": "createDhcp6AccessRule",
          "tags": [
            "dhcpv6-access-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "访问控制规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dhcp6AccessRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "mac": "11:22:33:44:55:68",
                  "tagname": "test008",
                  "comment": "test008-comment"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 3
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（MAC地址已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  "example": {
                    "message": "MAC地址已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dhcp6/access-control/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/dhcp6AccessRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定DHCPv6访问控制规则",
          "description": "根据规则ID获取单个DHCPv6访问控制规则的详细信息。\n需要提供有效的规则ID。\n",
          "operationId": "getDhcp6AccessRule",
          "tags": [
            "dhcpv6-access-rules"
          ],
          "responses": {
            "200": {
              "description": "成功获取访问控制规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Dhcp6AccessRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新DHCPv6访问控制规则",
          "description": "完全更新现有的DHCPv6访问控制规则配置。\n需要提供所有字段。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDhcp6AccessRule",
          "tags": [
            "dhcpv6-access-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的访问控制规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dhcp6AccessRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用DHCPv6访问控制规则",
          "description": "部分更新现有的DHCPv6访问控制规则配置。\n主要用于启用/停用规则状态。\n",
          "operationId": "patchDhcp6AccessRule",
          "tags": [
            "dhcpv6-access-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除DHCPv6访问控制规则",
          "description": "删除指定的DHCPv6访问控制规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDhcp6AccessRule",
          "tags": [
            "dhcpv6-access-rules"
          ],
          "responses": {
            "200": {
              "description": "访问控制规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "dhcp6AccessRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "DHCPv6访问控制规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、mac、tagname等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "Dhcp6AccessModeResponse": {
          "type": "object",
          "required": [
            "message",
            "results"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "mode"
              ],
              "properties": {
                "mode": {
                  "type": "integer",
                  "description": "访问控制模式，0:黑名单模式 1:白名单模式",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                }
              }
            }
          },
          "additionalProperties": false
        },
        "Dhcp6AccessModeInput": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "integer",
              "description": "访问控制模式，0:黑名单模式 1:白名单模式",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "required": [
            "mode"
          ],
          "additionalProperties": false
        },
        "Dhcp6AccessRuleCreateResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建的规则ID",
              "example": 3
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "Dhcp6AccessRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Dhcp6AccessRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Dhcp6AccessRulesListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Dhcp6AccessRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Dhcp6AccessRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "mac"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "11:22:33:44:55:66"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "Dhcp6AccessRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "mac",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$",
              "example": "11:22:33:44:55:68"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test008"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test008-comment"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Dhcp6AccessRuleCreateResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dhcpv6-access-mode",
        "x-displayName": "DHCPv6访问控制模式",
        "description": "DHCPv6黑名单和白名单模式的设置和切换"
      },
      {
        "name": "dhcpv6-access-rules",
        "x-displayName": "DHCPv6访问控制规则",
        "description": "DHCPv6访问控制规则的管理和配置"
      }
    ]
  },
  "network/network-dmz.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DMZ策略管理API",
      "version": "1.0.0",
      "summary": "DMZ策略的完整管理功能",
      "description": "提供DMZ策略的完整管理功能，包括：\n- DMZ策略的增删改查\n- 支持外网接口配置\n- 支持内网地址映射\n- 支持协议和端口排除配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dmz/rules": {
        "get": {
          "summary": "获取DMZ策略列表",
          "description": "获取当前配置的DMZ策略列表，支持分页功能。\n包含策略名称、外网接口、内网地址、排除协议、排除端口等信息。\n",
          "operationId": "listDmzRules",
          "tags": [
            "dmz"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取DMZ策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DmzRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加DMZ策略",
          "description": "添加新的DMZ策略，将外网接口的所有流量映射到指定的内网地址。\n可配置排除的协议和端口。\n",
          "operationId": "createDmzRule",
          "tags": [
            "dmz"
          ],
          "requestBody": {
            "required": true,
            "description": "DMZ策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmzRuleInput"
                },
                "example": {
                  "tagname": "test001",
                  "enabled": "yes",
                  "interface": "192.168.100.1",
                  "lan_addr": "192.168.10.10",
                  "protocol": "tcp",
                  "comment": "test001"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DmzErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（策略名称已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DmzErrorResponse"
                  },
                  "example": {
                    "message": "DMZ策略已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dmz/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/dmzRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定DMZ策略详情",
          "description": "根据策略ID获取单个DMZ策略的详细信息。\n",
          "operationId": "getDmzRule",
          "tags": [
            "dmz"
          ],
          "responses": {
            "200": {
              "description": "成功获取DMZ策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DmzRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新DMZ策略",
          "description": "完全更新现有的DMZ策略配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDmzRule",
          "tags": [
            "dmz"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的DMZ策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmzRuleEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用DMZ策略",
          "description": "部分更新现有的DMZ策略配置。\n主要用于启用/停用策略状态。\n",
          "operationId": "patchDmzRule",
          "tags": [
            "dmz"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除DMZ策略",
          "description": "删除指定的DMZ策略。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDmzRule",
          "tags": [
            "dmz"
          ],
          "responses": {
            "200": {
              "description": "DMZ策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "dmzRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "DMZ策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DmzErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "DMZ业务错误信息描述"
            }
          }
        },
        "DmzRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 5
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DmzRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DmzRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DmzRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DmzRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "interface",
            "lan_addr",
            "lan_addr_int",
            "protocol",
            "excl_port",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "interface": {
              "type": "string",
              "description": "外网接口名称或外网IP地址",
              "example": "192.168.100.1"
            },
            "lan_addr": {
              "type": "string",
              "description": "内网地址（DMZ主机地址）",
              "format": "ipv4",
              "example": "192.168.10.10"
            },
            "lan_addr_int": {
              "type": "integer",
              "description": "内网地址整数表示（系统自动计算）",
              "readOnly": true,
              "example": 3232238090
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "排除的协议类型：\n- any: 所有协议\n- tcp: TCP协议\n- udp: UDP协议\n- tcp+udp: TCP和UDP协议\n",
              "example": "tcp"
            },
            "excl_port": {
              "type": "string",
              "description": "排除的端口，多个端口用逗号分隔，支持范围输入（如：80,443,1000-2000）",
              "example": "80"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "DmzRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "interface",
            "lan_addr",
            "protocol",
            "excl_port"
          ],
          "properties": {
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "interface": {
              "type": "string",
              "description": "外网接口名称或外网IP地址",
              "example": "192.168.100.1"
            },
            "lan_addr": {
              "type": "string",
              "description": "内网地址（DMZ主机地址）",
              "format": "ipv4",
              "example": "192.168.10.10"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "排除的协议类型：\n- any: 所有协议\n- tcp: TCP协议\n- udp: UDP协议\n- tcp+udp: TCP和UDP协议\n",
              "example": "tcp"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            },
            "excl_port": {
              "type": "string",
              "description": "排除的端口，多个端口用逗号分隔，支持范围输入（如：80,443,1000-2000）。当 protocol 为 tcp 或 udp 时必填",
              "example": "80"
            }
          },
          "additionalProperties": false
        },
        "DmzRuleEditInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "id",
            "tagname",
            "enabled",
            "interface",
            "lan_addr",
            "protocol",
            "excl_port",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态",
              "example": "yes"
            },
            "interface": {
              "type": "string",
              "description": "外网接口名称或外网IP地址，或'all'",
              "example": "192.168.100.1"
            },
            "lan_addr": {
              "type": "string",
              "description": "内网地址（DMZ主机地址）",
              "format": "ipv4",
              "example": "192.168.10.10"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "排除的协议类型",
              "example": "tcp"
            },
            "excl_port": {
              "type": "string",
              "description": "排除的端口，多个端口用逗号分隔，支持范围输入（如：80,443,1000-2000）。当 protocol 为 tcp 或 udp 时必填",
              "example": "80"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dmz",
        "x-displayName": "DMZ策略管理",
        "description": "DMZ策略的增删改查操作，支持协议和端口排除配置"
      }
    ]
  },
  "network/network-dnat.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "端口映射规则管理API",
      "version": "1.0.0",
      "summary": "DNAT端口映射规则的完整管理功能",
      "description": "提供DNAT端口映射规则的完整管理功能，包括：\n- 端口映射规则的增删改查\n- 支持TCP/UDP协议配置\n- 支持外网端口到内网端口的映射\n- 支持源地址访问控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dnat/rules": {
        "get": {
          "summary": "获取所有DNAT规则",
          "description": "获取当前配置的端口映射规则列表，支持分页功能。\n包含规则名称、内外网端口、协议、启用状态等信息。\n",
          "operationId": "listDnatRules",
          "tags": [
            "dnat"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取端口映射规则列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnatRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加DNAT规则",
          "description": "添加新的端口映射规则，将外网端口映射到内网地址的端口。\n支持TCP、UDP或TCP+UDP协议，支持端口范围配置。\n",
          "operationId": "createDnatRule",
          "tags": [
            "dnat"
          ],
          "requestBody": {
            "required": true,
            "description": "端口映射规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DnatRuleInput"
                },
                "example": {
                  "tagname": "test001",
                  "enabled": "yes",
                  "lan_addr": "192.168.177.100",
                  "lan_port": "90,9090-9099",
                  "protocol": "tcp",
                  "interface": "wan1",
                  "wan_port": "90,9090-9099",
                  "src_addr": {
                    "custom": [
                      "192.168.1.2"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gid": "IPGP1",
                        "gp_name": "test001"
                      }
                    ]
                  },
                  "comment": "test001"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnatErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（端口或规则名称已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnatErrorResponse"
                  },
                  "example": {
                    "message": "端口映射规则已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dnat/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/dnatRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定DNAT规则详情",
          "description": "根据规则ID获取单个端口映射规则的详细信息。\n",
          "operationId": "getDnatRule",
          "tags": [
            "dnat"
          ],
          "responses": {
            "200": {
              "description": "成功获取端口映射规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnatRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新DNAT规则",
          "description": "完全更新现有的端口映射规则配置。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDnatRule",
          "tags": [
            "dnat"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的端口映射规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DnatRuleEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用DNAT规则",
          "description": "部分更新现有的端口映射规则配置。\n主要用于启用/停用规则状态。\n",
          "operationId": "patchDnatRule",
          "tags": [
            "dnat"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除DNAT规则",
          "description": "删除指定的端口映射规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDnatRule",
          "tags": [
            "dnat"
          ],
          "responses": {
            "200": {
              "description": "端口映射规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "dnatRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "端口映射规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 2
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DnatErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "DNAT业务错误信息描述"
            }
          }
        },
        "DnatRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnatRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnatRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnatRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnatRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "lan_addr",
            "lan_port",
            "protocol",
            "interface",
            "wan_port",
            "src_addr",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 2
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "lan_addr": {
              "type": "string",
              "description": "内网地址",
              "format": "ipv4",
              "example": "192.168.177.100"
            },
            "lan_addr_int": {
              "type": "integer",
              "description": "内网地址整数表示（系统自动计算）",
              "readOnly": true,
              "example": 3232280932
            },
            "lan_port": {
              "type": "string",
              "description": "内网端口，支持单个端口或端口范围，多个端口用逗号分隔",
              "example": "90,9090-9099"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "传输协议类型",
              "example": "tcp"
            },
            "interface": {
              "type": "string",
              "description": "外网接口名称或外网IP地址",
              "example": "wan1"
            },
            "wan_port": {
              "type": "string",
              "description": "外网端口，支持单个端口或端口范围，多个端口用逗号分隔",
              "example": "90,9090-9099"
            },
            "src_addr": {
              "type": "object",
              "description": "允许访问的源地址",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.1.2"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "IPGP1"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test001"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [
                  "192.168.1.2"
                ],
                "object": [
                  {
                    "type": 0,
                    "gid": "IPGP1",
                    "gp_name": "test001"
                  }
                ]
              }
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "DnatRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "lan_addr",
            "lan_port",
            "protocol",
            "interface",
            "wan_port"
          ],
          "properties": {
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "lan_addr": {
              "type": "string",
              "description": "内网地址",
              "format": "ipv4",
              "example": "192.168.177.100"
            },
            "lan_port": {
              "type": "string",
              "description": "内网端口，支持单个端口或端口范围，多个端口用逗号分隔",
              "example": "90,9090-9099"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "传输协议类型",
              "example": "tcp"
            },
            "interface": {
              "type": "string",
              "description": "外网接口名称或外网IP地址",
              "example": "wan1"
            },
            "wan_port": {
              "type": "string",
              "description": "外网端口，支持单个端口或端口范围，多个端口用逗号分隔",
              "example": "90,9090-9099"
            },
            "src_addr": {
              "type": "object",
              "description": "允许访问的源地址",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.1.2"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "IPGP1"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test001"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [
                  "192.168.1.2"
                ],
                "object": [
                  {
                    "type": 0,
                    "gid": "IPGP1",
                    "gp_name": "test001"
                  }
                ]
              }
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "DnatRuleEditInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "id",
            "tagname",
            "enabled",
            "lan_addr",
            "lan_port",
            "protocol",
            "interface",
            "wan_port",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 2
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态",
              "example": "yes"
            },
            "lan_addr": {
              "type": "string",
              "description": "内网地址",
              "format": "ipv4",
              "example": "192.168.177.100"
            },
            "lan_port": {
              "type": "string",
              "description": "内网端口",
              "example": "90,9090-9099"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "传输协议类型",
              "example": "tcp"
            },
            "interface": {
              "type": "string",
              "description": "外网接口名称或外网IP地址",
              "example": "wan1"
            },
            "wan_port": {
              "type": "string",
              "description": "外网端口",
              "example": "90,9090-9099"
            },
            "src_addr": {
              "type": "object",
              "description": "允许访问的源地址",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              }
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "test001"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dnat",
        "x-displayName": "端口映射规则管理",
        "description": "DNAT端口映射规则的增删改查操作"
      }
    ]
  },
  "network/network-dns.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DNS服务管理API",
      "version": "1.0.0",
      "summary": "DNS服务的完整管理功能",
      "description": "提供DNS服务的完整管理功能，包括：\n- DNS缓存状态监控\n- DNS配置管理\n- DNS代理规则管理\n- 解析类型控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/dns/stats": {
        "get": {
          "summary": "获取DNS缓存状态",
          "description": "获取DNS缓存的统计信息，包括请求数、命中数、未命中数等。\n支持按日期维度查看缓存性能。\n",
          "operationId": "getDnsCacheStats",
          "tags": [
            "dns-cache"
          ],
          "responses": {
            "200": {
              "description": "成功获取DNS缓存统计",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsCacheStatsListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 7,
                      "data": [
                        {
                          "id": 1,
                          "request": 1388762,
                          "hit": 1010261,
                          "miss": 378501,
                          "date": "2025-11-12",
                          "save_time": "2025-11-12 10:30:00"
                        },
                        {
                          "id": 2,
                          "request": 5000,
                          "hit": 0,
                          "miss": 0,
                          "date": 0,
                          "save_time": "2025-11-12 10:30:00"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dns/config": {
        "get": {
          "summary": "获取DNS配置",
          "description": "获取当前DNS服务的配置信息，包括代理服务启用状态、\n缓存TTL、DNS工作模式、主备DNS服务器等配置。\n",
          "operationId": "getDnsConfig",
          "tags": [
            "dns-config"
          ],
          "responses": {
            "200": {
              "description": "成功获取DNS配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsConfigResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新DNS配置",
          "description": "更新DNS服务的配置信息，包括启用DNS代理服务、\n设置缓存TTL、配置DNS工作模式等。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDnsConfig",
          "tags": [
            "dns-config"
          ],
          "requestBody": {
            "required": true,
            "description": "DNS配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DnsConfigInput"
                },
                "example": {
                  "enabled": "yes",
                  "forbid_dns_4a": 0,
                  "cache_ttl": 300,
                  "cachemode": 0,
                  "proxy_force": 0,
                  "proxy_force_dns": "",
                  "query": "https://doh.pub/dns-query",
                  "dns1": "114.114.114.114",
                  "dns2": "119.29.29.29",
                  "defense": "",
                  "network": "",
                  "query_args_ip": "",
                  "query_head_ip": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dns/proxy/rules": {
        "get": {
          "summary": "获取DNS代理规则列表",
          "description": "获取当前配置的DNS代理规则列表，支持分页和过滤功能。\n包含域名、解析IP地址、启用状态、备注等信息。\n",
          "operationId": "listDnsProxyRules",
          "tags": [
            "dns-proxy"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取DNS代理规则列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsProxyRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加DNS代理规则",
          "description": "添加新的DNS代理规则，指定域名和对应的解析IP地址。\n支持IPv4和IPv6解析类型。\n",
          "operationId": "createDnsProxyRule",
          "tags": [
            "dns-proxy"
          ],
          "requestBody": {
            "required": true,
            "description": "DNS代理规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DnsProxyRuleInput"
                },
                "example": {
                  "domain": "example.com",
                  "dns_addr": "192.168.1.100",
                  "enabled": "yes",
                  "comment": "示例域名解析规则",
                  "src_addr": "192.168.1.0/24",
                  "is_ipv6": 0,
                  "parse_type": "ipv4"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（域名已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsErrorResponse"
                  },
                  "example": {
                    "message": "域名解析规则已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/dns/proxy/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/dnsProxyRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定DNS代理规则",
          "description": "根据规则ID获取单个DNS代理规则的详细信息。\n",
          "operationId": "getDnsProxyRule",
          "tags": [
            "dns-proxy"
          ],
          "responses": {
            "200": {
              "description": "成功获取DNS代理规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsProxyRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新DNS代理规则",
          "description": "完全更新现有的DNS代理规则配置。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDnsProxyRule",
          "tags": [
            "dns-proxy"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的DNS代理规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DnsProxyRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用DNS代理规则",
          "description": "部分更新现有的DNS代理规则配置。\n主要用于启用/停用规则状态。\n",
          "operationId": "patchDnsProxyRule",
          "tags": [
            "dns-proxy"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除DNS代理规则",
          "description": "删除指定的DNS代理规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteDnsProxyRule",
          "tags": [
            "dns-proxy"
          ],
          "responses": {
            "200": {
              "description": "DNS代理规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/multi-dns/rules": {
        "get": {
          "summary": "获取多线DNS策略列表",
          "description": "获取当前配置的多线DNS策略列表，支持分页功能。\n每个WAN口线路可以自定义上级DNS服务器地址。\n",
          "operationId": "listMultiDnsRules",
          "tags": [
            "multi-dns"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取多线DNS策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MultiDnsRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加多线DNS策略",
          "description": "添加新的多线DNS策略，为WAN口线路配置自定义DNS服务器地址。\n每个WAN口可以配置不同的上级DNS服务器。\n",
          "operationId": "createMultiDnsRule",
          "tags": [
            "multi-dns"
          ],
          "requestBody": {
            "required": true,
            "description": "多线DNS策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MultiDnsRuleInput"
                },
                "example": {
                  "interface": "wan1",
                  "tagname": "线路1",
                  "dns1": "8.8.8.8",
                  "dns2": "8.8.4.4",
                  "enabled": "yes",
                  "comment": "主线路DNS配置"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（网卡或名称已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DnsErrorResponse"
                  },
                  "example": {
                    "message": "网卡接口或策略名称已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/multi-dns/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/multiDnsRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定多线DNS策略",
          "description": "根据策略ID获取单个多线DNS策略的详细信息。\n",
          "operationId": "getMultiDnsRule",
          "tags": [
            "multi-dns"
          ],
          "responses": {
            "200": {
              "description": "成功获取多线DNS策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MultiDnsRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新多线DNS策略",
          "description": "完全更新现有的多线DNS策略配置。\n需要提供所有字段。\n",
          "operationId": "updateMultiDnsRule",
          "tags": [
            "multi-dns"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的多线DNS策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MultiDnsRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用多线DNS策略",
          "description": "部分更新现有的多线DNS策略配置。\n主要用于启用/停用策略状态。\n",
          "operationId": "patchMultiDnsRule",
          "tags": [
            "multi-dns"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除多线DNS策略",
          "description": "删除指定的多线DNS策略。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteMultiDnsRule",
          "tags": [
            "multi-dns"
          ],
          "responses": {
            "200": {
              "description": "多线DNS策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "dnsProxyRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "DNS代理规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "multiDnsRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "多线DNS策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            },
            "code": {
              "type": "integer",
              "description": "状态码",
              "example": 0
            },
            "rowid": {
              "type": "integer",
              "description": "新创建记录ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "code",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DnsCacheStatsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnsCacheStats"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnsCacheStatsListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 7
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnsCacheStats"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnsErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "DNS业务错误信息描述"
            }
          }
        },
        "DnsConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnsConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnsProxyRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnsProxyRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnsProxyRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DnsProxyRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MultiDnsRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MultiDnsRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MultiDnsRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MultiDnsRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DnsCacheStats": {
          "type": "object",
          "required": [
            "id",
            "request",
            "hit",
            "miss",
            "date",
            "save_time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "统计ID",
              "minimum": 1,
              "example": 1
            },
            "request": {
              "type": "integer",
              "description": "总请求数",
              "minimum": 0,
              "example": 1388762
            },
            "hit": {
              "type": "integer",
              "description": "缓存命中数",
              "minimum": 0,
              "example": 1010261
            },
            "miss": {
              "type": "integer",
              "description": "缓存未命中数",
              "minimum": 0,
              "example": 378501
            },
            "date": {
              "oneOf": [
                {
                  "type": "string",
                  "format": "date",
                  "description": "统计日期（YYYY-MM-DD格式）",
                  "example": "2025-11-12"
                },
                {
                  "type": "integer",
                  "description": "累计统计标志（date为0时表示累计统计）",
                  "example": 0
                }
              ]
            },
            "save_time": {
              "type": "string",
              "description": "缓存保存时间",
              "readOnly": true,
              "example": "2025-11-12 10:30:00"
            }
          },
          "additionalProperties": false
        },
        "DnsConfig": {
          "type": "object",
          "required": [
            "enabled",
            "forbid_dns_4a",
            "cache_ttl",
            "cachemode",
            "proxy_force",
            "proxy_force_dns",
            "query",
            "dns1",
            "dns2",
            "network",
            "defense",
            "query_args_ip",
            "query_head_ip"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "启用DNS代理服务，yes为启用，no为停用",
              "example": "yes"
            },
            "forbid_dns_4a": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "忽略DNS 4A记录，0为允许，1为忽略",
              "example": 0
            },
            "cache_ttl": {
              "type": "integer",
              "description": "缓存的最大TTL（秒），范围 60-3600",
              "minimum": 60,
              "maximum": 3600,
              "default": 300,
              "example": 300
            },
            "cachemode": {
              "type": "integer",
              "enum": [
                0,
                1,
                2,
                3
              ],
              "description": "DNS工作模式：\n- 0: UDP代理\n- 1: 多线缓存\n- 2: 第三方代理\n- 3: DoH (DNS over HTTPS)\n",
              "example": 0
            },
            "proxy_force": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "强制客户端启用DNS代理（只针对dnsmasq），0为否，1为是",
              "example": 0
            },
            "proxy_force_dns": {
              "type": "string",
              "description": "第三方代理的DNS服务器IP列表，多个以逗号分隔，当 cachemode=2 时必填",
              "example": ""
            },
            "query": {
              "type": "string",
              "description": "解析URL地址（DoH模式使用）",
              "format": "uri",
              "default": "https://doh.pub/dns-query",
              "example": "https://doh.pub/dns-query"
            },
            "dns1": {
              "type": "string",
              "description": "主DNS服务器地址",
              "format": "ipv4",
              "default": "114.114.114.114",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "备DNS服务器地址",
              "format": "ipv4",
              "default": "119.29.29.29",
              "example": "119.29.29.29"
            },
            "network": {
              "type": "string",
              "description": "网络接口",
              "readOnly": true,
              "example": ""
            },
            "defense": {
              "type": "string",
              "description": "DNS防御",
              "readOnly": true,
              "example": ""
            },
            "query_args_ip": {
              "type": "string",
              "description": "查询参数IP",
              "readOnly": true,
              "example": ""
            },
            "query_head_ip": {
              "type": "string",
              "description": "查询头部IP",
              "readOnly": true,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "DnsConfigInput": {
          "type": "object",
          "required": [
            "enabled",
            "forbid_dns_4a",
            "cache_ttl",
            "cachemode",
            "proxy_force",
            "proxy_force_dns",
            "dns1",
            "dns2",
            "query",
            "defense",
            "network",
            "query_args_ip",
            "query_head_ip"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "启用DNS代理服务，yes为启用，no为停用",
              "example": "yes"
            },
            "forbid_dns_4a": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "忽略DNS 4A记录，0为允许，1为忽略",
              "example": 0
            },
            "cache_ttl": {
              "type": "integer",
              "description": "缓存的最大TTL（秒），范围 60-3600",
              "minimum": 60,
              "maximum": 3600,
              "default": 300,
              "example": 300
            },
            "cachemode": {
              "type": "integer",
              "enum": [
                0,
                1,
                2,
                3
              ],
              "description": "DNS工作模式：\n- 0: UDP代理\n- 1: 多线缓存\n- 2: 第三方代理\n- 3: DoH (DNS over HTTPS)\n",
              "example": 0
            },
            "proxy_force": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "强制客户端启用DNS代理（只针对dnsmasq），0为否，1为是",
              "example": 0
            },
            "proxy_force_dns": {
              "type": "string",
              "description": "第三方代理的DNS服务器IP列表，多个以逗号分隔，当 cachemode=2 时必填",
              "example": ""
            },
            "query": {
              "type": "string",
              "description": "DoH解析URL地址，当 cachemode=3（DoH模式）时必填",
              "format": "uri",
              "default": "https://doh.pub/dns-query",
              "example": "https://doh.pub/dns-query"
            },
            "dns1": {
              "type": "string",
              "description": "主DNS服务器地址",
              "format": "ipv4",
              "default": "114.114.114.114",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "备DNS服务器地址",
              "format": "ipv4",
              "default": "119.29.29.29",
              "example": "119.29.29.29"
            },
            "defense": {
              "type": "string",
              "description": "DNS防御配置，详情回填后保存原值",
              "example": ""
            },
            "network": {
              "type": "string",
              "description": "网络接口配置，详情回填后保存原值",
              "example": ""
            },
            "query_args_ip": {
              "type": "string",
              "description": "查询参数IP，详情回填后保存原值",
              "example": ""
            },
            "query_head_ip": {
              "type": "string",
              "description": "查询头部IP，详情回填后保存原值",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "DnsProxyRule": {
          "type": "object",
          "required": [
            "id",
            "domain",
            "dns_addr",
            "enabled",
            "comment",
            "src_addr",
            "is_ipv6",
            "parse_type"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "domain": {
              "type": "string",
              "description": "域名",
              "pattern": "^[a-zA-Z0-9.-]+$",
              "minLength": 1,
              "maxLength": 255,
              "example": "example.com"
            },
            "dns_addr": {
              "type": "string",
              "description": "解析的IP地址",
              "format": "ipv4",
              "example": "192.168.1.100"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "示例域名解析规则"
            },
            "src_addr": {
              "type": "string",
              "description": "生效的IP段范围，多个以逗号隔开，支持固定IP、带掩码格式、范围格式",
              "example": "192.168.1.0/24,192.168.1.1,192.168.1.10-192.168.1.20"
            },
            "is_ipv6": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "是否为IPv6，0为IPv4，1为IPv6",
              "example": 0
            },
            "parse_type": {
              "type": "string",
              "enum": [
                "ipv4",
                "ipv6",
                "proxy",
                "proxy6"
              ],
              "description": "解析类型：\n- ipv4: IPv4解析\n- ipv6: IPv6解析\n- proxy: 代理解析\n- proxy6: IPv6代理解析\n",
              "example": "ipv4"
            }
          },
          "additionalProperties": false
        },
        "DnsProxyRuleInput": {
          "type": "object",
          "required": [
            "domain",
            "dns_addr",
            "enabled",
            "parse_type"
          ],
          "properties": {
            "domain": {
              "type": "string",
              "description": "域名，不能为空",
              "minLength": 1,
              "maxLength": 255,
              "example": "example.com"
            },
            "dns_addr": {
              "type": "string",
              "description": "解析的IP地址，不能为空；parse_type=ipv4 时须为合法 IPv4，parse_type=ipv6 时须为合法 IPv6",
              "example": "192.168.1.100"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "示例域名解析规则"
            },
            "src_addr": {
              "type": "string",
              "description": "限制来源IP范围，多个以逗号隔开，支持固定IP、带掩码格式、范围格式（可不传，不填表示不限制来源）",
              "example": "192.168.1.0/24,192.168.1.1,192.168.1.10-192.168.1.20"
            },
            "is_ipv6": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "是否为IPv6，0为IPv4，1为IPv6",
              "example": 0
            },
            "parse_type": {
              "type": "string",
              "enum": [
                "ipv4",
                "ipv6",
                "proxy",
                "proxy6"
              ],
              "description": "解析类型：\n- ipv4: IPv4解析\n- ipv6: IPv6解析\n- proxy: 代理解析\n- proxy6: IPv6代理解析\n",
              "example": "ipv4"
            }
          },
          "additionalProperties": false
        },
        "MultiDnsRule": {
          "type": "object",
          "required": [
            "id",
            "interface",
            "tagname",
            "dns1",
            "dns2",
            "enabled",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "interface": {
              "type": "string",
              "description": "网卡接口名称",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 50,
              "example": "线路1"
            },
            "dns1": {
              "type": "string",
              "description": "主DNS服务器地址",
              "format": "ipv4",
              "example": "8.8.8.8"
            },
            "dns2": {
              "type": "string",
              "description": "备DNS服务器地址",
              "format": "ipv4",
              "example": "8.8.4.4"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "策略启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "主线路DNS配置"
            }
          },
          "additionalProperties": false
        },
        "MultiDnsRuleInput": {
          "type": "object",
          "required": [
            "interface",
            "tagname",
            "dns1",
            "dns2",
            "enabled",
            "comment"
          ],
          "properties": {
            "interface": {
              "type": "string",
              "description": "网卡接口名称",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 50,
              "example": "线路1"
            },
            "dns1": {
              "type": "string",
              "description": "主DNS服务器地址",
              "format": "ipv4",
              "example": "8.8.8.8"
            },
            "dns2": {
              "type": "string",
              "description": "备DNS服务器地址",
              "format": "ipv4",
              "example": "8.8.4.4"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "策略启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "主线路DNS配置"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "dns-cache",
        "x-displayName": "DNS缓存",
        "description": "DNS缓存状态监控和统计信息"
      },
      {
        "name": "dns-config",
        "x-displayName": "DNS配置",
        "description": "DNS服务配置管理"
      },
      {
        "name": "dns-proxy",
        "x-displayName": "DNS代理规则",
        "description": "DNS代理规则管理"
      },
      {
        "name": "multi-dns",
        "x-displayName": "多线DNS管理",
        "description": "多线路DNS策略管理，为每个WAN口配置自定义DNS服务器"
      }
    ]
  },
  "network/network-lan.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "LAN接口管理API",
      "version": "1.0.0",
      "summary": "LAN接口及物理网卡信息查询",
      "description": "提供LAN接口的完整管理功能，包括：\n- LAN接口配置查询\n- LAN接口配置更新\n- 物理网卡列表及属性信息查询\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/interfaces/lan-config": {
        "get": {
          "summary": "获取LAN接口配置",
          "description": "查询所有LAN接口的配置信息，包括接口名称、绑定网卡、IP地址/掩码、\nDHCP服务器状态、VLAN绑定、链路聚合模式等详细信息。\n",
          "operationId": "getLanConfig",
          "tags": [
            "lan-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取LAN接口配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/LanConfigResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "name": "lan1",
                          "tagname": "lan1",
                          "comment": "",
                          "mac": "",
                          "speed": 0,
                          "duplex": 0,
                          "lan_visit": 1,
                          "bandmode": 0,
                          "linkmode": 4,
                          "policy": 0,
                          "ip_mask": "192.168.99.1/255.255.255.0",
                          "bandif": "00:e2:69:00:89:e5,00:e2:69:00:89:e6",
                          "bandeth": "eth0,eth1,eth2",
                          "bandflag": "0,0",
                          "vlan": "vlan1001",
                          "dhcp_server": 1
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/interfaces/lan-config/{id}": {
        "put": {
          "summary": "更新LAN接口配置",
          "description": "更新指定LAN接口的网卡配置。本接口为全量修改，请求时需传入所有字段，\n未传入的字段可能被重置。\n",
          "operationId": "updateLanConfig",
          "tags": [
            "lan-interfaces"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "LAN接口ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1,
                "example": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanConfigUpdateRequest"
                },
                "example": {
                  "bandif": "00:e2:69:00:89:e5,00:e2:69:00:89:e6",
                  "bandmode": 0,
                  "speed": 0,
                  "duplex": 0,
                  "lan_visit": 1,
                  "ip_mask": "192.168.99.1/255.255.255.0",
                  "mac": "",
                  "comment": "",
                  "linkmode": 4,
                  "policy": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/interfaces/physical": {
        "get": {
          "summary": "获取物理网卡列表",
          "description": "查询所有物理网卡的列表及属性信息，包括驱动类型、网卡类型、\nMAC地址、链路状态、协商速率、双工模式和所属接口名称。\n返回结果以网卡名称（如eth0、eth1）为键的对象格式。\n",
          "operationId": "getPhysicalInterfaces",
          "tags": [
            "lan-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取物理网卡列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/InterfacesPhysicalResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "ether_info": {
                        "eth0": {
                          "driver": "igb",
                          "type": "TP",
                          "mac": "00:e2:69:00:89:e5",
                          "link": 1,
                          "speed": 100,
                          "duplex": 1,
                          "model": "Intel Corporation I211 Gigabit Network Connection",
                          "interface": "lan1",
                          "lock": 0,
                          "bindmod": 0
                        },
                        "eth1": {
                          "driver": "igb",
                          "type": "TP",
                          "mac": "00:e2:69:00:89:e6",
                          "link": 1,
                          "speed": 1000,
                          "duplex": 1,
                          "model": "Intel Corporation I211 Gigabit Network Connection",
                          "interface": "lan1",
                          "lock": 0,
                          "bindmod": 0
                        },
                        "eth2": {
                          "driver": "igb",
                          "type": "TP",
                          "mac": "00:e2:69:00:89:e7",
                          "link": 0,
                          "speed": 0,
                          "duplex": 0,
                          "model": "Intel Corporation I211 Gigabit Network Connection",
                          "interface": "lan1",
                          "lock": 0,
                          "bindmod": 0
                        },
                        "eth3": {
                          "driver": "igb",
                          "type": "TP",
                          "mac": "00:e2:69:00:89:e8",
                          "link": 1,
                          "speed": 1000,
                          "duplex": 1,
                          "model": "Intel Corporation I211 Gigabit Network Connection",
                          "interface": "wan1",
                          "lock": 0,
                          "bindmod": 0
                        },
                        "vnet": {
                          "driver": "kvm",
                          "type": "TP",
                          "mac": "00:00:00:00:00:00",
                          "link": 1,
                          "speed": 1000,
                          "duplex": 1,
                          "model": "Kvm Virtual Bridge Enternet Controller",
                          "interface": "Null",
                          "lock": 0,
                          "bindmod": 0
                        }
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "LanConfigResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/LanConfigResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "LanConfigResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "LAN接口配置列表",
              "items": {
                "$ref": "#/components/schemas/LanInterface"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "LanInterface": {
          "type": "object",
          "required": [
            "id",
            "name",
            "tagname",
            "comment",
            "mac",
            "speed",
            "duplex",
            "lan_visit",
            "bandmode",
            "linkmode",
            "policy",
            "ip_mask",
            "bandif",
            "bandeth",
            "bandflag",
            "vlan",
            "dhcp_server"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "接口ID",
              "minimum": 1,
              "example": 1
            },
            "name": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "lan1"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 50,
              "example": "lan1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "mac": {
              "type": "string",
              "description": "网卡MAC地址（空字符串表示未设置）",
              "maxLength": 17,
              "example": ""
            },
            "speed": {
              "type": "integer",
              "description": "网卡速率（0=自动, 10/100/1000/10000 Mbps）",
              "enum": [
                0,
                10,
                100,
                1000,
                10000
              ],
              "example": 0
            },
            "duplex": {
              "type": "integer",
              "description": "工作模式（0=自动, 1=全双工, 2=半双工）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "lan_visit": {
              "type": "integer",
              "description": "是否允许其他LAN访问（0=不允许, 1=允许）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "bandmode": {
              "type": "integer",
              "description": "绑定模式（0=网桥, 1=汇聚）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "linkmode": {
              "type": "integer",
              "description": "链路聚合模式，bandmode=1时有效（2=手工链路聚合, 4=LACP链路聚合）",
              "enum": [
                2,
                4
              ],
              "example": 4
            },
            "policy": {
              "type": "integer",
              "description": "汇聚负载方式（0=layer2, 1=layer3+4, 2=layer2+3）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "ip_mask": {
              "type": "string",
              "description": "网卡IP地址和子网掩码，格式：IP地址/子网掩码",
              "example": "192.168.99.1/255.255.255.0"
            },
            "bandif": {
              "type": "string",
              "description": "绑定网卡MAC地址列表（逗号分隔）",
              "example": "00:e2:69:00:89:e5,00:e2:69:00:89:e6"
            },
            "bandeth": {
              "type": "string",
              "description": "绑定网卡名称列表（逗号分隔）",
              "example": "eth0,eth1,eth2"
            },
            "bandflag": {
              "type": "string",
              "description": "绑定模式列表，bandmode=1时有效（逗号分隔，每项0=网桥/1=汇聚）",
              "example": "0,0"
            },
            "vlan": {
              "type": "string",
              "description": "绑定的VLAN接口名称（空字符串表示未绑定VLAN）",
              "maxLength": 50,
              "example": "vlan1001"
            },
            "dhcp_server": {
              "type": "integer",
              "description": "是否启用DHCP服务器（0=不启用, 1=启用）",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "InterfacesPhysicalResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/InterfacesPhysicalResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "InterfacesPhysicalResults": {
          "type": "object",
          "properties": {
            "ether_info": {
              "type": "object",
              "description": "物理网卡信息，key为网卡名称（如eth0、eth1、vnet等）",
              "additionalProperties": {
                "$ref": "#/components/schemas/PhysicalNic"
              },
              "example": {
                "eth0": {
                  "driver": "igb",
                  "type": "TP",
                  "mac": "00:e2:69:00:89:e5",
                  "link": 1,
                  "speed": 100,
                  "duplex": 1,
                  "model": "Intel Corporation I211 Gigabit Network Connection",
                  "interface": "lan1",
                  "lock": 0,
                  "bindmod": 0
                }
              }
            }
          },
          "required": [
            "ether_info"
          ],
          "additionalProperties": false
        },
        "PhysicalNic": {
          "type": "object",
          "required": [
            "driver",
            "type",
            "mac",
            "link",
            "speed",
            "duplex",
            "model",
            "interface",
            "lock",
            "bindmod"
          ],
          "properties": {
            "driver": {
              "type": "string",
              "description": "网卡驱动名称",
              "maxLength": 50,
              "example": "igb"
            },
            "type": {
              "type": "string",
              "description": "网卡类型",
              "enum": [
                "TP",
                "FIBRE",
                "USB",
                "LTE",
                "KVM",
                "WIFI"
              ],
              "example": "TP"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "00:e2:69:00:89:e5"
            },
            "link": {
              "type": "integer",
              "description": "网卡链路状态（0=离线, 1=在线）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "speed": {
              "type": "integer",
              "description": "网卡协商速率（Mbps，0表示未协商）",
              "minimum": 0,
              "example": 1000
            },
            "duplex": {
              "type": "integer",
              "description": "双工模式（0=半双工, 1=全双工）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "model": {
              "type": "string",
              "description": "网卡型号描述",
              "maxLength": 200,
              "example": "Intel Corporation I211 Gigabit Network Connection"
            },
            "interface": {
              "type": "string",
              "description": "网卡所属接口名称（未分配时为\"Null\"）",
              "maxLength": 50,
              "example": "lan1"
            },
            "lock": {
              "type": "integer",
              "description": "锁定状态",
              "minimum": 0,
              "example": 0
            },
            "bindmod": {
              "type": "integer",
              "description": "网卡绑定模式（0=网桥, 1=汇聚）",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果信息",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "LanConfigUpdateRequest": {
          "type": "object",
          "required": [
            "bandif",
            "bandmode",
            "speed",
            "duplex",
            "lan_visit",
            "ip_mask"
          ],
          "properties": {
            "bandif": {
              "type": "string",
              "description": "绑定网卡MAC地址，多个以逗号分隔",
              "example": "00:e2:69:00:89:e5,00:e2:69:00:89:e6"
            },
            "bandmode": {
              "type": "integer",
              "description": "绑定模式（0=网桥, 1=汇聚）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "speed": {
              "type": "integer",
              "description": "网卡速率（0=自动, 10/100/1000/10000 Mbps）",
              "enum": [
                0,
                10,
                100,
                1000,
                10000
              ],
              "example": 0
            },
            "duplex": {
              "type": "integer",
              "description": "工作模式（0=自动, 1=全双工, 2=半双工）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "lan_visit": {
              "type": "integer",
              "description": "是否允许其他LAN访问（0=不允许, 1=允许）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "ip_mask": {
              "type": "string",
              "description": "IP地址和子网掩码，格式：IP/掩码，如 192.168.1.1/255.255.255.0",
              "example": "192.168.99.1/255.255.255.0"
            },
            "mac": {
              "type": "string",
              "description": "克隆MAC地址，空字符串表示不克隆",
              "maxLength": 17,
              "example": ""
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64字符",
              "maxLength": 64,
              "example": ""
            },
            "linkmode": {
              "type": "integer",
              "description": "链路聚合模式，bandmode=1时有效（2=手工链路聚合, 4=LACP链路聚合）",
              "enum": [
                2,
                4
              ],
              "example": 4
            },
            "policy": {
              "type": "integer",
              "description": "汇聚负载方式（0=layer2, 1=layer3+4, 2=layer2+3）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "lan-interfaces",
        "x-displayName": "网络接口",
        "description": "LAN接口配置及物理网卡信息查询"
      }
    ]
  },
  "network/network-nat-rule.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "NAT规则策略管理API",
      "version": "1.0.0",
      "summary": "NAT规则策略的完整管理功能",
      "description": "提供NAT规则策略的完整管理功能，包括：\n- NAT规则的增删改查\n- 支持过滤、DNAT、SNAT三种动作类型\n- 支持源地址、目标地址、端口配置\n- 支持内网接口和外网接口配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/nat/rules": {
        "get": {
          "summary": "获取NAT规则列表",
          "description": "获取当前配置的NAT规则列表，支持分页功能。\n包含规则名称、动作类型、接口配置、地址配置、端口配置等信息。\n",
          "operationId": "listNatRules",
          "tags": [
            "nat-rules"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取NAT规则列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NatRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建NAT规则",
          "description": "添加新的NAT规则，支持过滤(filter)、DNAT、SNAT三种动作类型。\n可配置源地址、目标地址、端口、接口等参数。\n",
          "operationId": "createNatRule",
          "tags": [
            "nat-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "NAT规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatRuleInput"
                },
                "example": {
                  "tagname": "test001",
                  "enabled": "yes",
                  "action": "filter",
                  "iinterface": "lan1",
                  "ointerface": "wan1",
                  "src_addr": {
                    "custom": [
                      "192.168.1.1"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gid": "IPGP1",
                        "gp_name": "test001"
                      }
                    ]
                  },
                  "dst_addr": {
                    "custom": [
                      "192.168.2.2"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gid": "IPGP5",
                        "gp_name": "test002"
                      }
                    ]
                  },
                  "nat_addr": "",
                  "nat_port": "",
                  "protocol": "tcp",
                  "comment": "test002",
                  "src_port": {
                    "custom": [],
                    "object": [
                      {
                        "type": 3,
                        "gid": "PORTGP3",
                        "gp_name": "test999"
                      }
                    ]
                  },
                  "dst_port": {
                    "custom": [],
                    "object": [
                      {
                        "type": 3,
                        "gid": "PORTGP4",
                        "gp_name": "test1000"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NatErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（规则名称已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NatErrorResponse"
                  },
                  "example": {
                    "message": "NAT规则已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/nat/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/natRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定NAT规则详情",
          "description": "根据规则ID获取单个NAT规则的详细信息。\n",
          "operationId": "getNatRule",
          "tags": [
            "nat-rules"
          ],
          "responses": {
            "200": {
              "description": "成功获取NAT规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NatRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新NAT规则",
          "description": "完全更新现有的NAT规则配置。\n需要提供所有字段。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateNatRule",
          "tags": [
            "nat-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的NAT规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NatRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用NAT规则",
          "description": "部分更新现有的NAT规则配置。\n主要用于启用/停用规则状态。\n",
          "operationId": "patchNatRule",
          "tags": [
            "nat-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除NAT规则",
          "description": "删除指定的NAT规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteNatRule",
          "tags": [
            "nat-rules"
          ],
          "responses": {
            "200": {
              "description": "NAT规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "natRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "NAT规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "NatErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "NAT业务错误信息描述"
            }
          }
        },
        "NatRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 10
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NatRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "NatRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NatRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "NatRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "action",
            "iinterface",
            "ointerface",
            "src_addr",
            "dst_addr",
            "nat_addr",
            "nat_port",
            "protocol",
            "comment",
            "src_port",
            "dst_port",
            "src_addr_inv",
            "dst_addr_inv"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "action": {
              "type": "string",
              "enum": [
                "filter",
                "dnat",
                "snat"
              ],
              "description": "NAT动作类型：\n- filter: 过滤规则\n- dnat: 目标地址转换\n- snat: 源地址转换\n",
              "example": "filter"
            },
            "iinterface": {
              "type": "string",
              "description": "进接口，多个接口以逗号分隔，any表示任意接口",
              "example": "lan1"
            },
            "ointerface": {
              "type": "string",
              "description": "出接口，多个接口以逗号分隔，any表示任意接口",
              "example": "wan1"
            },
            "src_addr": {
              "type": "object",
              "description": "源地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.1.1"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "IPGP1"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test001"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [
                  "192.168.1.1"
                ],
                "object": [
                  {
                    "type": 0,
                    "gid": "IPGP1",
                    "gp_name": "test001"
                  }
                ]
              }
            },
            "dst_addr": {
              "type": "object",
              "description": "目标地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.2.2"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "IPGP5"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test002"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [
                  "192.168.2.2"
                ],
                "object": [
                  {
                    "type": 0,
                    "gid": "IPGP5",
                    "gp_name": "test002"
                  }
                ]
              }
            },
            "nat_addr": {
              "type": "string",
              "description": "NAT地址（action为snat或dnat时使用）",
              "format": "ipv4",
              "example": ""
            },
            "nat_port": {
              "type": "string",
              "description": "NAT端口（action为dnat时使用）",
              "example": ""
            },
            "protocol": {
              "type": "string",
              "enum": [
                "",
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "传输协议类型，空字符串或any表示不限制",
              "example": "tcp"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "test002"
            },
            "src_port": {
              "type": "object",
              "description": "源端口配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "description": "端口对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 3
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "PORTGP3"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test999"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [],
                "object": [
                  {
                    "type": 3,
                    "gid": "PORTGP3",
                    "gp_name": "test999"
                  }
                ]
              }
            },
            "dst_port": {
              "type": "object",
              "description": "目标端口配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "description": "端口对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 3
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "PORTGP4"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test1000"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [],
                "object": [
                  {
                    "type": 3,
                    "gid": "PORTGP4",
                    "gp_name": "test1000"
                  }
                ]
              }
            },
            "src_addr_inv": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "源地址取反(0:不取反, 1:取反)",
              "example": 0
            },
            "dst_addr_inv": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "目的地址取反(0:不取反, 1:取反)",
              "example": 0
            },
            "src_addr_int": {
              "type": "integer",
              "description": "源地址整数值",
              "readOnly": true,
              "example": 0
            },
            "dst_addr_int": {
              "type": "integer",
              "description": "目的地址整数值",
              "readOnly": true,
              "example": 0
            },
            "nat_addr_int": {
              "type": "integer",
              "description": "NAT地址整数值",
              "readOnly": true,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "NatRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "action",
            "iinterface",
            "ointerface",
            "src_addr_inv",
            "dst_addr_inv"
          ],
          "properties": {
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "开启状态，yes为启用，no为停用",
              "example": "yes"
            },
            "action": {
              "type": "string",
              "enum": [
                "filter",
                "dnat",
                "snat"
              ],
              "description": "NAT动作类型：\n- filter: 过滤规则\n- dnat: 目标地址转换\n- snat: 源地址转换\n",
              "example": "filter"
            },
            "iinterface": {
              "type": "string",
              "description": "进接口，多个接口以逗号分隔，any表示任意接口",
              "example": "lan1"
            },
            "ointerface": {
              "type": "string",
              "description": "出接口，多个接口以逗号分隔，any表示任意接口",
              "example": "wan1"
            },
            "src_addr": {
              "type": "object",
              "description": "源地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.1.1"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "IPGP1"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test001"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [
                  "192.168.1.1"
                ],
                "object": [
                  {
                    "type": 0,
                    "gid": "IPGP1",
                    "gp_name": "test001"
                  }
                ]
              }
            },
            "dst_addr": {
              "type": "object",
              "description": "目标地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.2.2"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "IPGP5"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test002"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [
                  "192.168.2.2"
                ],
                "object": [
                  {
                    "type": 0,
                    "gid": "IPGP5",
                    "gp_name": "test002"
                  }
                ]
              }
            },
            "nat_addr": {
              "type": "string",
              "description": "NAT地址（action为snat或dnat时使用）",
              "format": "ipv4",
              "example": ""
            },
            "nat_port": {
              "type": "string",
              "description": "NAT端口（action为dnat时使用）",
              "example": ""
            },
            "protocol": {
              "type": "string",
              "enum": [
                "",
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "description": "传输协议类型，空字符串或any表示不限制",
              "example": "tcp"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test002"
            },
            "src_addr_inv": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "源地址取反(0:不取反, 1:取反)",
              "default": 0,
              "example": 0
            },
            "dst_addr_inv": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "目的地址取反(0:不取反, 1:取反)",
              "default": 0,
              "example": 0
            },
            "src_port": {
              "type": "object",
              "description": "源端口配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "description": "端口对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 3
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "PORTGP3"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test999"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [],
                "object": [
                  {
                    "type": 3,
                    "gid": "PORTGP3",
                    "gp_name": "test999"
                  }
                ]
              }
            },
            "dst_port": {
              "type": "object",
              "description": "目标端口配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "description": "端口对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "example": 3
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象组ID",
                        "example": "PORTGP4"
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象组名称",
                        "example": "test1000"
                      }
                    },
                    "required": [
                      "type",
                      "gid",
                      "gp_name"
                    ]
                  }
                }
              },
              "required": [
                "custom",
                "object"
              ],
              "example": {
                "custom": [],
                "object": [
                  {
                    "type": 3,
                    "gid": "PORTGP4",
                    "gp_name": "test1000"
                  }
                ]
              }
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "nat-rules",
        "x-displayName": "NAT规则策略管理",
        "description": "NAT规则策略的增删改查操作，支持filter、dnat、snat三种动作类型"
      }
    ]
  },
  "network/network-protocols.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "自定义协议策略管理API",
      "version": "1.0.0",
      "summary": "自定义协议策略管理完整功能",
      "description": "提供自定义协议策略的完整管理功能，包括：\n- 协议策略的创建、查询、更新、删除\n- 策略启用/停用状态控制\n- 支持9种协议分类：网络协议、网络游戏、社交通讯等\n- 支持源地址、目的地址、协议类型、端口配置\n- 支持对象引用配置（IP对象、端口对象等）\n- 自动生成应用ID\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/app-protocols/custom/rules": {
        "get": {
          "summary": "获取自定义协议策略列表",
          "description": "获取所有自定义协议策略列表。\n支持分页功能。\n",
          "operationId": "listCustomProtocols",
          "tags": [
            "custom-proto"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取自定义协议策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CustomProtocolListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "comment": "",
                          "name": "11",
                          "class": 0,
                          "appid": 1900001,
                          "protocol": "udp",
                          "src_addr": {
                            "custom": [
                              "192.168.9.168"
                            ],
                            "object": [
                              {
                                "type": 0,
                                "gp_name": "11",
                                "gid": "GPIP1"
                              }
                            ]
                          },
                          "dst_addr": {
                            "custom": [
                              "192.168.10.168"
                            ],
                            "object": [
                              {
                                "type": 0,
                                "gp_name": "11",
                                "gid": "GPIP1"
                              }
                            ]
                          },
                          "src_port": "",
                          "dst_port": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建自定义协议策略",
          "description": "创建新的自定义协议策略。\n支持配置源/目的地址、协议类型和端口，可引用IP/端口对象组。\n",
          "operationId": "createCustomProtocol",
          "tags": [
            "custom-proto"
          ],
          "requestBody": {
            "required": true,
            "description": "自定义协议策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomProtocolInput"
                },
                "example": {
                  "class": "0",
                  "comment": "",
                  "name": "11",
                  "src_addr": {
                    "custom": [
                      "192.168.9.168"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "dst_addr": {
                    "custom": [
                      "192.168.10.168"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "protocol": "udp",
                  "dst_port": {
                    "custom": [
                      "9000",
                      "10000-20000"
                    ],
                    "object": [
                      {
                        "gid": "PORTGP26",
                        "gp_name": "ip55",
                        "type": 3
                      }
                    ]
                  },
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/app-protocols/custom/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/customProtocolIdParam"
          }
        ],
        "get": {
          "summary": "获取指定自定义协议策略详情",
          "description": "根据ID获取单个自定义协议策略的详细信息。\n需要提供有效的策略ID。\n",
          "operationId": "getCustomProtocol",
          "tags": [
            "custom-proto"
          ],
          "responses": {
            "200": {
              "description": "成功获取自定义协议策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CustomProtocolResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "comment": "",
                          "name": "11",
                          "class": 0,
                          "appid": 1900001,
                          "protocol": "udp",
                          "src_addr": {
                            "custom": [
                              "192.168.9.168"
                            ],
                            "object": [
                              {
                                "type": 0,
                                "gp_name": "11",
                                "gid": "GPIP1"
                              }
                            ]
                          },
                          "dst_addr": {
                            "custom": [
                              "192.168.10.168"
                            ],
                            "object": [
                              {
                                "type": 0,
                                "gp_name": "11",
                                "gid": "GPIP1"
                              }
                            ]
                          },
                          "src_port": "",
                          "dst_port": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新自定义协议策略",
          "description": "完全更新指定自定义协议策略的配置信息。\n需要提供所有字段。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateCustomProtocol",
          "tags": [
            "custom-proto"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的自定义协议策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomProtocolEditInput"
                },
                "example": {
                  "class": 0,
                  "appid": 1900001,
                  "comment": "updated",
                  "name": "11",
                  "protocol": "tcp",
                  "src_addr": {
                    "custom": [
                      "192.168.9.168"
                    ],
                    "object": []
                  },
                  "dst_addr": {
                    "custom": [],
                    "object": []
                  },
                  "src_port": "",
                  "dst_port": {
                    "custom": [
                      "80"
                    ],
                    "object": []
                  },
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用自定义协议策略",
          "description": "部分更新指定自定义协议策略。\n主要用于启用/停用状态切换。\n",
          "operationId": "patchCustomProtocol",
          "tags": [
            "custom-proto"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "启用状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "required": [
                    "enabled"
                  ]
                },
                "example": {
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除自定义协议策略",
          "description": "删除指定的自定义协议策略。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteCustomProtocol",
          "tags": [
            "custom-proto"
          ],
          "responses": {
            "200": {
              "description": "自定义协议策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "customProtocolIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "自定义协议策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象组名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象组ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "PortObject": {
          "type": "object",
          "properties": {
            "gid": {
              "type": "string",
              "description": "端口对象组ID",
              "example": "PORTGP26"
            },
            "gp_name": {
              "type": "string",
              "description": "端口对象组名称",
              "example": "ip55"
            },
            "type": {
              "type": "integer",
              "description": "对象类型",
              "example": 3
            }
          },
          "additionalProperties": false
        },
        "AddressFilter": {
          "description": "地址过滤条件，可为空字符串或包含自定义地址/对象引用的对象",
          "oneOf": [
            {
              "type": "string",
              "description": "空字符串表示不过滤",
              "example": ""
            },
            {
              "type": "object",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "192.168.9.168"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "IP对象引用列表",
                  "items": {
                    "$ref": "#/components/schemas/AddressObject"
                  }
                }
              },
              "additionalProperties": false
            }
          ]
        },
        "PortFilter": {
          "description": "端口过滤条件，可为空字符串或包含自定义端口/对象引用的对象",
          "oneOf": [
            {
              "type": "string",
              "description": "空字符串表示不过滤",
              "example": ""
            },
            {
              "type": "object",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表（支持单端口如 '9000' 或范围如 '10000-20000'，范围1-65535）",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "9000",
                    "10000-20000"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "端口对象引用列表",
                  "items": {
                    "$ref": "#/components/schemas/PortObject"
                  }
                }
              },
              "additionalProperties": false
            }
          ]
        },
        "CustomProtocol": {
          "type": "object",
          "required": [
            "id",
            "class",
            "appid"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态（启用/禁用）",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "name": {
              "type": "string",
              "description": "协议名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9]+$",
              "example": "11"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressFilter"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressFilter"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp",
                "icmp",
                "any"
              ],
              "example": "udp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortFilter"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortFilter"
            },
            "class": {
              "type": "integer",
              "description": "协议分类（0-8）：\n- 0: 网络协议自定义\n- 1: 网络游戏自定义\n- 2: 社交通讯自定义\n- 3: 传输下载自定义\n- 4: 休闲娱乐自定义\n- 5: 效率工具自定义\n- 6: 办公协作自定义\n- 7: 学习教育自定义\n- 8: 生活服务自定义\n",
              "minimum": 0,
              "maximum": 8,
              "example": 0
            },
            "appid": {
              "type": "integer",
              "description": "应用ID（自动生成，不需要输入）",
              "readOnly": true,
              "example": 1900001
            }
          },
          "additionalProperties": false
        },
        "CustomProtocolInput": {
          "type": "object",
          "required": [
            "class",
            "name",
            "protocol",
            "enabled"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态（启用/禁用）",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "name": {
              "type": "string",
              "description": "协议名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9]+$",
              "example": "11"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressFilter"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressFilter"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp",
                "icmp",
                "any"
              ],
              "example": "udp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortFilter"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortFilter"
            },
            "class": {
              "type": "integer",
              "description": "协议分类（0-8）：\n- 0: 网络协议自定义\n- 1: 网络游戏自定义\n- 2: 社交通讯自定义\n- 3: 传输下载自定义\n- 4: 休闲娱乐自定义\n- 5: 效率工具自定义\n- 6: 办公协作自定义\n- 7: 学习教育自定义\n- 8: 生活服务自定义\n",
              "minimum": 0,
              "maximum": 8,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "CustomProtocolEditInput": {
          "type": "object",
          "description": "PUT全量修改，所有字段均为required；不修改的字段请保持原值或传空值，未传入的字段可能被重置。",
          "required": [
            "class",
            "enabled",
            "comment",
            "name",
            "src_addr",
            "dst_addr",
            "protocol",
            "src_port",
            "dst_port"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态（启用/禁用）",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "name": {
              "type": "string",
              "description": "协议名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9]+$",
              "example": "11"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressFilter"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressFilter"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp",
                "icmp",
                "any"
              ],
              "example": "udp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortFilter"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortFilter"
            },
            "class": {
              "type": "integer",
              "description": "协议分类（0-8）：\n- 0: 网络协议自定义\n- 1: 网络游戏自定义\n- 2: 社交通讯自定义\n- 3: 传输下载自定义\n- 4: 休闲娱乐自定义\n- 5: 效率工具自定义\n- 6: 办公协作自定义\n- 7: 学习教育自定义\n- 8: 生活服务自定义\n",
              "minimum": 0,
              "maximum": 8,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "CustomProtocolResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CustomProtocol"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CustomProtocolListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CustomProtocol"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "custom-proto",
        "x-displayName": "自定义协议管理",
        "description": "自定义协议策略管理，支持9种协议分类及源/目的地址、端口、协议类型配置"
      }
    ]
  },
  "network/network-qos-ip.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "IP地址限速管理API",
      "version": "1.0.0",
      "summary": "IP地址限速管理完整功能",
      "description": "提供IP地址限速的完整管理功能，包括：\n- IP限速规则的创建、查询、更新、删除\n- 规则启用/停用状态控制\n- 支持独立和共享带宽类型\n- 支持协议、端口、时间等高级配置\n- 支持对象引用配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/qos/ip": {
        "get": {
          "summary": "获取IP限速列表",
          "description": "获取所有IP限速规则列表。\n支持分页功能。\n",
          "operationId": "listIpQos",
          "tags": [
            "qos-ip"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IP限速列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IpQosListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "interface": "wan1",
                          "protocol": "",
                          "src_port": "",
                          "type": 0,
                          "upload": 100,
                          "download": 100,
                          "time": {
                            "custom": [
                              {
                                "end_time": "10:00",
                                "start_time": "00:00",
                                "comment": "test11",
                                "type": "weekly",
                                "weekdays": "1234567"
                              },
                              {
                                "comment": "test11",
                                "type": "date",
                                "end_time": "2026-05-10T08:00",
                                "start_time": "2026-05-01T08:00"
                              }
                            ],
                            "object": [
                              {
                                "gid": "TIMEGP1",
                                "type": 4,
                                "gp_name": "11"
                              }
                            ]
                          },
                          "attr": 0,
                          "dst_port": "",
                          "tagname": "testmac_wan1",
                          "comment": "",
                          "id": 1,
                          "enabled": "yes",
                          "ip_addr": {
                            "custom": [
                              "192.168.9.169"
                            ]
                          }
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建IP限速规则",
          "description": "创建新的IP限速规则。\n支持独立和共享带宽配置，以及协议、端口、时间等高级选项。\n",
          "operationId": "createIpQos",
          "tags": [
            "qos-ip"
          ],
          "requestBody": {
            "required": true,
            "description": "IP限速规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpQosCreateInput"
                },
                "example": {
                  "upload": "100",
                  "download": "100",
                  "comment": "",
                  "enabled": "yes",
                  "type": 0,
                  "protocol": "any",
                  "interface": "wan1",
                  "ip_addr": {
                    "custom": [
                      "192.168.9.168"
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "tagname": "testmac_wan1"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/qos/ip/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "IP限速规则ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定IP限速规则",
          "description": "根据ID获取单个IP限速规则的详细信息。\n需要提供有效的规则ID。\n",
          "operationId": "getIpQos",
          "tags": [
            "qos-ip"
          ],
          "responses": {
            "200": {
              "description": "成功获取IP限速规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IpQosResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新IP限速规则",
          "description": "修改指定IP限速规则的配置信息。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateIpQos",
          "tags": [
            "qos-ip"
          ],
          "requestBody": {
            "required": true,
            "description": "IP限速规则更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpQosInput"
                },
                "example": {
                  "upload": "200",
                  "download": "200",
                  "comment": "updated",
                  "enabled": "yes",
                  "type": 0,
                  "protocol": "any",
                  "interface": "wan1",
                  "ip_addr": {
                    "custom": [
                      "192.168.9.169"
                    ]
                  },
                  "src_port": {
                    "custom": [],
                    "object": []
                  },
                  "dst_port": {
                    "custom": [],
                    "object": []
                  },
                  "tagname": "testmac_wan1_updated"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用IP限速规则",
          "description": "部分修改指定IP限速规则的配置信息。\n只更新提供的字段。\n",
          "operationId": "partialUpdateIpQos",
          "tags": [
            "qos-ip"
          ],
          "requestBody": {
            "required": true,
            "description": "IP限速规则部分更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpQosPatchInput"
                },
                "example": {
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除IP限速规则",
          "description": "删除指定的IP限速规则。\n删除后规则将被永久移除，无法恢复。\n",
          "operationId": "deleteIpQos",
          "tags": [
            "qos-ip"
          ],
          "responses": {
            "200": {
              "description": "IP限速规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问IP限速管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "IP限速规则不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "IpQos": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "testmac_wan1"
            },
            "ip_addr": {
              "type": "object",
              "description": "内网地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.9.168"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "IP对象引用列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型（0:ipv4, 1:ipv6, 2:mac, 3:port, 4:time, 5:protocol, 6:domain）",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 0
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
                        "minLength": 1,
                        "maxLength": 15,
                        "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
                        "example": "ipgroup1"
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象ID",
                        "example": "IPGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "type": {
              "type": "integer",
              "description": "带宽类型（0:独立, 1:共享）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "外网线路选择",
              "example": "wan1"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "default": "any",
              "example": "any"
            },
            "src_port": {
              "type": "object",
              "description": "源端口配置（对象类型，含custom和object数组）",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "description": "端口对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    }
                  },
                  "example": []
                }
              }
            },
            "dst_port": {
              "type": "object",
              "description": "目的端口配置（对象类型，含custom和object数组）",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义端口列表",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "description": "端口对象组",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    }
                  },
                  "example": []
                }
              }
            },
            "upload": {
              "type": "integer",
              "description": "上传带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "download": {
              "type": "integer",
              "description": "下载带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "time": {
              "type": "object",
              "description": "生效时间配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义时间列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "description": "时间类型",
                        "enum": [
                          "weekly",
                          "date"
                        ],
                        "example": "weekly"
                      },
                      "weekdays": {
                        "type": "string",
                        "description": "星期（1234567），weekly类型使用",
                        "pattern": "^[1-7]*$",
                        "example": "1234567"
                      },
                      "start_time": {
                        "type": "string",
                        "description": "开始时间",
                        "example": "00:00"
                      },
                      "end_time": {
                        "type": "string",
                        "description": "结束时间",
                        "example": "20:00"
                      },
                      "comment": {
                        "type": "string",
                        "description": "备注信息，最多64个字符",
                        "example": "test11"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                },
                "object": {
                  "type": "array",
                  "description": "时间对象引用列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 4
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
                        "minLength": 1,
                        "maxLength": 15,
                        "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
                        "example": "11"
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象ID",
                        "example": "TIMEGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "attr": {
              "type": "integer",
              "description": "属性（0:页面操作, 1:快速添加）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "IpQosCreateInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "upload",
            "download"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "testmac_wan1"
            },
            "ip_addr": {
              "type": "object",
              "description": "内网地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.9.168"
                  ]
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 0
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "ipgroup1"
                      },
                      "gid": {
                        "type": "string",
                        "example": "IPGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "type": {
              "type": "integer",
              "description": "带宽类型（0:独立, 1:共享）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "外网线路选择",
              "example": "wan1"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "default": "any",
              "example": "any"
            },
            "src_port": {
              "type": "object",
              "description": "源端口配置（对象类型，含custom和object数组）",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    }
                  },
                  "example": []
                }
              }
            },
            "dst_port": {
              "type": "object",
              "description": "目的端口配置（对象类型，含custom和object数组）",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    }
                  },
                  "example": []
                }
              }
            },
            "upload": {
              "type": "integer",
              "description": "上传带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "download": {
              "type": "integer",
              "description": "下载带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "time": {
              "type": "object",
              "description": "生效时间配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "weekly",
                          "date"
                        ],
                        "example": "weekly"
                      },
                      "weekdays": {
                        "type": "string",
                        "pattern": "^[1-7]*$",
                        "example": "1234567"
                      },
                      "start_time": {
                        "type": "string",
                        "example": "00:00"
                      },
                      "end_time": {
                        "type": "string",
                        "example": "20:00"
                      },
                      "comment": {
                        "type": "string",
                        "example": "test11"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 4
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "11"
                      },
                      "gid": {
                        "type": "string",
                        "example": "TIMEGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "attr": {
              "type": "integer",
              "description": "属性（0:页面操作, 1:快速添加）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "IpQosInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "upload",
            "download",
            "type",
            "protocol",
            "comment",
            "interface",
            "src_port",
            "dst_port"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "testmac_wan1"
            },
            "ip_addr": {
              "type": "object",
              "description": "内网地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "192.168.9.168"
                  ]
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 0
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "ipgroup1"
                      },
                      "gid": {
                        "type": "string",
                        "example": "IPGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "type": {
              "type": "integer",
              "description": "带宽类型（0:独立, 1:共享）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "外网线路选择",
              "example": "wan1"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp"
              ],
              "default": "any",
              "example": "any"
            },
            "src_port": {
              "type": "object",
              "description": "源端口配置（对象类型，含custom和object数组）",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    }
                  },
                  "example": []
                }
              }
            },
            "dst_port": {
              "type": "object",
              "description": "目的端口配置（对象类型，含custom和object数组）",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": []
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer"
                      },
                      "gid": {
                        "type": "string"
                      },
                      "gp_name": {
                        "type": "string"
                      }
                    }
                  },
                  "example": []
                }
              }
            },
            "upload": {
              "type": "integer",
              "description": "上传带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "download": {
              "type": "integer",
              "description": "下载带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "time": {
              "type": "object",
              "description": "生效时间配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "weekly",
                          "date"
                        ],
                        "example": "weekly"
                      },
                      "weekdays": {
                        "type": "string",
                        "pattern": "^[1-7]*$",
                        "example": "1234567"
                      },
                      "start_time": {
                        "type": "string",
                        "example": "00:00"
                      },
                      "end_time": {
                        "type": "string",
                        "example": "20:00"
                      },
                      "comment": {
                        "type": "string",
                        "example": "test11"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 4
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "11"
                      },
                      "gid": {
                        "type": "string",
                        "example": "TIMEGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "IpQosPatchInput": {
          "type": "object",
          "required": [
            "enabled"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            }
          },
          "additionalProperties": false
        },
        "IpQosResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/IpQos"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                }
              },
              "required": [
                "data",
                "total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "IpQosListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "IP限速规则列表",
                  "items": {
                    "$ref": "#/components/schemas/IpQos"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                }
              },
              "required": [
                "data",
                "total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "qos-ip",
        "x-displayName": "IP限速管理",
        "description": "IP地址限速管理，支持独立和共享带宽配置"
      }
    ]
  },
  "network/network-qos-mac.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "MAC地址限速管理API",
      "version": "1.0.0",
      "summary": "MAC地址限速管理完整功能",
      "description": "提供MAC地址限速的完整管理功能，包括：\n- MAC限速规则的创建、查询、更新、删除\n- 规则启用/停用状态控制\n- 支持独立和共享带宽类型\n- 支持IPv4/IPv6协议类型\n- 支持时间配置和对象引用\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/qos/mac": {
        "get": {
          "summary": "获取MAC限速列表",
          "description": "获取所有MAC限速规则列表。\n支持分页功能。\n",
          "operationId": "listMacQos",
          "tags": [
            "qos-mac"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000,
                "default": 20
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC限速列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacQosListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "enabled": "yes",
                          "upload": 100,
                          "tagname": "testmac_wan1",
                          "comment": "",
                          "mac_addr": {
                            "custom": [
                              "08:9b:4b:00:10:6e"
                            ],
                            "object": [
                              {
                                "type": 2,
                                "gid": "MACIP1",
                                "gp_name": "22"
                              }
                            ]
                          },
                          "ip_type": "4",
                          "time": {
                            "custom": [
                              {
                                "end_time": "20:00",
                                "comment": "test11",
                                "weekdays": "1234567",
                                "type": "weekly",
                                "start_time": "00:00"
                              },
                              {
                                "comment": "test11",
                                "end_time": "2026-05-10T08:00",
                                "type": "date",
                                "start_time": "2026-05-01T08:00"
                              }
                            ],
                            "object": [
                              {
                                "type": 4,
                                "gid": "TIMEGP1",
                                "gp_name": "11"
                              }
                            ]
                          },
                          "type": 0,
                          "attr": 0,
                          "download": 100,
                          "interface": "wan1",
                          "id": 1
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建MAC限速规则",
          "description": "创建新的MAC限速规则。\n支持独立和共享带宽配置，以及IPv4/IPv6协议类型选择。\n",
          "operationId": "createMacQos",
          "tags": [
            "qos-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "MAC限速规则配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MacQosCreateInput"
                },
                "example": {
                  "upload": "100",
                  "download": "100",
                  "comment": "",
                  "enabled": "yes",
                  "ip_type": "4",
                  "interface": "wan1",
                  "mac_addr": {
                    "custom": [
                      "08:9b:4b:00:10:6e"
                    ],
                    "object": [
                      {
                        "type": 2,
                        "gp_name": "22",
                        "gid": "MACIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "tagname": "testmac_wan1"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/qos/mac/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "MAC限速规则ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定MAC限速规则",
          "description": "根据ID获取单个MAC限速规则的详细信息。\n需要提供有效的规则ID。\n",
          "operationId": "getMacQos",
          "tags": [
            "qos-mac"
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC限速规则详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacQosResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新MAC限速规则",
          "description": "修改指定MAC限速规则的配置信息。\n支持完整更新。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateMacQos",
          "tags": [
            "qos-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "MAC限速规则更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MacQosInput"
                },
                "example": {
                  "upload": "200",
                  "download": "200",
                  "comment": "updated",
                  "enabled": "yes",
                  "ip_type": "4",
                  "interface": "wan1",
                  "mac_addr": {
                    "custom": [
                      "08:9b:4b:00:10:6f"
                    ]
                  },
                  "tagname": "testmac_wan1_updated"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用MAC限速规则",
          "description": "启用或停用指定MAC限速规则。\n仅支持修改 enabled 字段，传 yes 为启用，传 no 为停用。\n",
          "operationId": "partialUpdateMacQos",
          "tags": [
            "qos-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "MAC限速规则启用/停用数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MacQosPatchInput"
                },
                "example": {
                  "enabled": "yes"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除MAC限速规则",
          "description": "删除指定的MAC限速规则。\n删除后规则将被永久移除，无法恢复。\n",
          "operationId": "deleteMacQos",
          "tags": [
            "qos-mac"
          ],
          "responses": {
            "200": {
              "description": "MAC限速规则删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问MAC限速管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "MAC限速规则不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "MacQos": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "testmac_wan1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "mac_addr": {
              "type": "object",
              "description": "MAC地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义MAC地址列表",
                  "items": {
                    "type": "string",
                    "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"
                  },
                  "example": [
                    "08:9b:4b:00:10:6e"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "MAC对象引用列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型（0:ipv4, 1:ipv6, 2:mac, 3:port, 4:time, 5:protocol, 6:domain）",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 2
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
                        "minLength": 1,
                        "maxLength": 15,
                        "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
                        "example": "22"
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象ID",
                        "example": "MACIP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "type": {
              "type": "integer",
              "description": "带宽类型（0:独立, 1:共享）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "ip_type": {
              "type": "string",
              "description": "IP协议类型（4:IPv4, 6:IPv6）",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "interface": {
              "type": "string",
              "description": "外网线路选择",
              "example": "wan1"
            },
            "upload": {
              "type": "integer",
              "description": "上传带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "download": {
              "type": "integer",
              "description": "下载带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "time": {
              "type": "object",
              "description": "生效时间配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义时间列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "description": "时间类型",
                        "enum": [
                          "weekly",
                          "date"
                        ],
                        "example": "weekly"
                      },
                      "weekdays": {
                        "type": "string",
                        "description": "星期（1234567），weekly类型使用",
                        "pattern": "^[1-7]*$",
                        "example": "1234567"
                      },
                      "start_time": {
                        "type": "string",
                        "description": "开始时间",
                        "example": "00:00"
                      },
                      "end_time": {
                        "type": "string",
                        "description": "结束时间",
                        "example": "20:00"
                      },
                      "comment": {
                        "type": "string",
                        "description": "备注信息，最多64个字符",
                        "example": "test11"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                },
                "object": {
                  "type": "array",
                  "description": "时间对象引用列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "description": "对象类型",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 4
                      },
                      "gp_name": {
                        "type": "string",
                        "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
                        "minLength": 1,
                        "maxLength": 15,
                        "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
                        "example": "11"
                      },
                      "gid": {
                        "type": "string",
                        "description": "对象ID",
                        "example": "TIMEGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "attr": {
              "type": "integer",
              "description": "属性（0:页面操作, 1:快速添加）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "MacQosCreateInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "upload",
            "download"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "testmac_wan1"
            },
            "ip_type": {
              "type": "string",
              "description": "IP协议类型（4:IPv4, 6:IPv6），默认空代表IPv4",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "mac_addr": {
              "type": "object",
              "description": "MAC地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"
                  },
                  "example": [
                    "08:9b:4b:00:10:6e"
                  ]
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 2
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "22"
                      },
                      "gid": {
                        "type": "string",
                        "example": "MACIP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "type": {
              "type": "integer",
              "description": "带宽类型（0:独立, 1:共享），默认空代表独立限速",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "外网线路选择",
              "example": "wan1"
            },
            "upload": {
              "type": "integer",
              "description": "上传带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "download": {
              "type": "integer",
              "description": "下载带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "time": {
              "type": "object",
              "description": "生效时间配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "weekly",
                          "date"
                        ],
                        "example": "weekly"
                      },
                      "weekdays": {
                        "type": "string",
                        "pattern": "^[1-7]*$",
                        "example": "1234567"
                      },
                      "start_time": {
                        "type": "string",
                        "example": "00:00"
                      },
                      "end_time": {
                        "type": "string",
                        "example": "20:00"
                      },
                      "comment": {
                        "type": "string",
                        "example": "test11"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 4
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "11"
                      },
                      "gid": {
                        "type": "string",
                        "example": "TIMEGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "MacQosInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "upload",
            "download",
            "comment",
            "mac_addr",
            "interface"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "testmac_wan1"
            },
            "ip_type": {
              "type": "string",
              "description": "IP协议类型（4:IPv4, 6:IPv6）",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "mac_addr": {
              "type": "object",
              "description": "MAC地址配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"
                  },
                  "example": [
                    "08:9b:4b:00:10:6e"
                  ]
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 2
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "22"
                      },
                      "gid": {
                        "type": "string",
                        "example": "MACIP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "type": {
              "type": "integer",
              "description": "带宽类型（0:独立, 1:共享）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "外网线路选择",
              "example": "wan1"
            },
            "upload": {
              "type": "integer",
              "description": "上传带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "download": {
              "type": "integer",
              "description": "下载带宽限制（KB/s）",
              "minimum": 0,
              "example": 100
            },
            "time": {
              "type": "object",
              "description": "生效时间配置",
              "properties": {
                "custom": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "weekly",
                          "date"
                        ],
                        "example": "weekly"
                      },
                      "weekdays": {
                        "type": "string",
                        "pattern": "^[1-7]*$",
                        "example": "1234567"
                      },
                      "start_time": {
                        "type": "string",
                        "example": "00:00"
                      },
                      "end_time": {
                        "type": "string",
                        "example": "20:00"
                      },
                      "comment": {
                        "type": "string",
                        "example": "test11"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  }
                },
                "object": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "integer",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 4
                      },
                      "gp_name": {
                        "type": "string",
                        "example": "11"
                      },
                      "gid": {
                        "type": "string",
                        "example": "TIMEGP1"
                      }
                    },
                    "required": [
                      "type",
                      "gp_name",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "MacQosPatchInput": {
          "type": "object",
          "required": [
            "enabled"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则启用状态，yes为启用，no为停用",
              "example": "yes"
            }
          },
          "additionalProperties": false
        },
        "MacQosResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MacQos"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                }
              },
              "required": [
                "data",
                "total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MacQosListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "MAC限速规则列表",
                  "items": {
                    "$ref": "#/components/schemas/MacQos"
                  }
                },
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                }
              },
              "required": [
                "data",
                "total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "qos-mac",
        "x-displayName": "MAC限速管理",
        "description": "MAC地址限速管理，支持独立和共享带宽配置"
      }
    ]
  },
  "network/network-vlan.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "VLAN接口管理API",
      "version": "1.0.0",
      "summary": "VLAN接口管理完整功能",
      "description": "提供VLAN接口的完整管理功能，包括：\n- 查询VLAN接口配置列表（支持分页、关键字搜索、过滤）\n- 查询单个VLAN接口配置\n- 新建VLAN接口\n- 更新VLAN接口配置\n- 删除VLAN接口\n- 启用/停用VLAN接口\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/vlan": {
        "get": {
          "summary": "获取VLAN接口配置列表",
          "description": "查询VLAN接口配置列表，支持分页、关键字模糊匹配和字段过滤。\n",
          "operationId": "getVlanList",
          "tags": [
            "vlan"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/LimitParam"
            },
            {
              "$ref": "#/components/parameters/PageParam"
            },
            {
              "$ref": "#/components/parameters/KeyParam"
            },
            {
              "$ref": "#/components/parameters/PatternParam"
            },
            {
              "$ref": "#/components/parameters/FilterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取VLAN接口配置列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/VlanListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "vlan_id": "1001",
                          "vlan_name": "vlan1001",
                          "interface": "lan1",
                          "mac": "",
                          "ip_addr": "192.168.88.1",
                          "ip_addr_int": 3232258049,
                          "netmask": "255.255.255.255",
                          "ip_mask": "",
                          "enabled": "yes",
                          "comment": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "新建VLAN接口",
          "description": "创建一个新的VLAN接口。\n",
          "operationId": "createVlan",
          "tags": [
            "vlan"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VlanCreateRequest"
                },
                "example": {
                  "vlan_id": "1001",
                  "vlan_name": "vlan1001",
                  "interface": "lan1",
                  "mac": "",
                  "ip_addr": "192.168.88.1",
                  "netmask": "255.255.255.255",
                  "ip_mask": "",
                  "enabled": "yes",
                  "comment": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "成功创建VLAN接口",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateSuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "id": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/vlan/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "VLAN记录ID",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取单个VLAN接口配置",
          "description": "根据ID查询单个VLAN接口的配置详情。\n",
          "operationId": "getVlanById",
          "tags": [
            "vlan"
          ],
          "responses": {
            "200": {
              "description": "成功获取VLAN接口配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/VlanSingleResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "vlan_id": "1001",
                          "vlan_name": "vlan1001",
                          "interface": "lan1",
                          "mac": "",
                          "ip_addr": "192.168.88.1",
                          "ip_addr_int": 3232258049,
                          "netmask": "255.255.255.255",
                          "ip_mask": "",
                          "enabled": "yes",
                          "comment": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新VLAN接口配置",
          "description": "更新指定ID的VLAN接口配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateVlan",
          "tags": [
            "vlan"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VlanUpdateRequest"
                },
                "example": {
                  "vlan_id": "1001",
                  "vlan_name": "vlan1001",
                  "interface": "lan1",
                  "mac": "",
                  "ip_addr": "192.168.88.1",
                  "netmask": "255.255.255.255",
                  "ip_mask": "",
                  "enabled": "yes",
                  "comment": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用VLAN接口",
          "description": "切换指定VLAN接口的启用状态。\n",
          "operationId": "toggleVlan",
          "tags": [
            "vlan"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VlanToggleRequest"
                },
                "examples": {
                  "enable": {
                    "summary": "启用VLAN",
                    "value": {
                      "enabled": "yes"
                    }
                  },
                  "disable": {
                    "summary": "停用VLAN",
                    "value": {
                      "enabled": "no"
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除VLAN接口",
          "description": "删除指定ID的VLAN接口。\n",
          "operationId": "deleteVlan",
          "tags": [
            "vlan"
          ],
          "responses": {
            "200": {
              "description": "成功删除VLAN接口",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "LimitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页返回记录数",
          "required": false,
          "schema": {
            "type": "integer",
            "minimum": 1,
            "example": 10
          }
        },
        "PageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "required": false,
          "schema": {
            "type": "integer",
            "minimum": 1,
            "example": 1
          }
        },
        "KeyParam": {
          "name": "key",
          "in": "query",
          "description": "模糊搜索字段名（如 vlan_name、tagname、interface）",
          "required": false,
          "schema": {
            "type": "string",
            "example": "vlan_name"
          }
        },
        "PatternParam": {
          "name": "pattern",
          "in": "query",
          "description": "模糊搜索关键词（与key配合使用）",
          "required": false,
          "schema": {
            "type": "string",
            "example": "vlan100"
          }
        },
        "FilterParam": {
          "name": "filter",
          "in": "query",
          "description": "精确过滤条件，支持以下格式：\n- 精确匹配：filter=enabled==yes\n- 包含过滤：filter=interface:lan1\n- AND条件：filter=enabled==yes&filter=interface==lan1\n- OR条件：filter=vlan_id==100,vlan_id==200\n",
          "required": false,
          "schema": {
            "type": "string"
          },
          "example": "enabled==yes"
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "新建记录的ID",
                  "example": 1
                }
              },
              "required": [
                "id"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "VlanListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/VlanListResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "VlanListResults": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            },
            "data": {
              "type": "array",
              "description": "VLAN接口配置列表",
              "items": {
                "$ref": "#/components/schemas/VlanConfig"
              }
            }
          },
          "required": [
            "total",
            "data"
          ],
          "additionalProperties": false
        },
        "VlanSingleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码 (0=成功)",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/VlanListResults"
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "VlanConfig": {
          "type": "object",
          "required": [
            "id",
            "vlan_id",
            "vlan_name",
            "interface",
            "mac",
            "ip_addr",
            "ip_addr_int",
            "netmask",
            "ip_mask",
            "enabled",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "vlan_id": {
              "type": "string",
              "description": "VLAN ID（1-4094）",
              "example": "1001"
            },
            "vlan_name": {
              "type": "string",
              "description": "VLAN接口名称（以vlan开头）",
              "maxLength": 15,
              "example": "vlan1001"
            },
            "interface": {
              "type": "string",
              "description": "所属物理接口（LAN口）",
              "maxLength": 50,
              "example": "lan1"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址（空字符串表示不设置）",
              "maxLength": 17,
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "VLAN接口IP地址",
              "format": "ipv4",
              "example": "192.168.88.1"
            },
            "ip_addr_int": {
              "type": "integer",
              "format": "int64",
              "description": "IP地址整数表示",
              "minimum": 0,
              "example": 3232258049
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.255.255"
            },
            "ip_mask": {
              "type": "string",
              "description": "扩展IP输入，格式：192.168.88.1/255.255.255.0,192.168.89.2/255.255.255.0（多个用逗号分隔）",
              "example": ""
            },
            "enabled": {
              "type": "string",
              "description": "是否启用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "VlanCreateRequest": {
          "type": "object",
          "required": [
            "vlan_id",
            "vlan_name",
            "interface",
            "netmask",
            "enabled"
          ],
          "properties": {
            "vlan_id": {
              "type": "string",
              "description": "VLAN ID（1-4094）",
              "example": "1001"
            },
            "vlan_name": {
              "type": "string",
              "description": "VLAN接口名称（以vlan开头）",
              "maxLength": 15,
              "example": "vlan1001"
            },
            "interface": {
              "type": "string",
              "description": "所属物理接口（LAN口）",
              "maxLength": 50,
              "example": "lan1"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址（空字符串表示不设置）",
              "maxLength": 17,
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "VLAN接口IP地址",
              "format": "ipv4",
              "example": "192.168.88.1"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.255.255"
            },
            "ip_mask": {
              "type": "string",
              "description": "扩展IP输入，格式：192.168.88.1/255.255.255.0,192.168.89.2/255.255.255.0",
              "example": ""
            },
            "enabled": {
              "type": "string",
              "description": "是否启用",
              "enum": [
                "yes",
                "no"
              ],
              "default": "yes",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "VlanUpdateRequest": {
          "type": "object",
          "required": [
            "vlan_id",
            "vlan_name",
            "interface",
            "ip_addr",
            "netmask",
            "enabled",
            "mac",
            "ip_mask",
            "comment"
          ],
          "properties": {
            "vlan_id": {
              "type": "string",
              "description": "VLAN ID（1-4094）",
              "example": "1001"
            },
            "vlan_name": {
              "type": "string",
              "description": "VLAN接口名称（以vlan开头）",
              "maxLength": 15,
              "example": "vlan1001"
            },
            "interface": {
              "type": "string",
              "description": "所属物理接口（LAN口）",
              "maxLength": 50,
              "example": "lan1"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址（空字符串表示不设置）",
              "maxLength": 17,
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "VLAN接口IP地址",
              "format": "ipv4",
              "example": "192.168.88.1"
            },
            "netmask": {
              "type": "string",
              "description": "子网掩码",
              "format": "ipv4",
              "example": "255.255.255.255"
            },
            "ip_mask": {
              "type": "string",
              "description": "扩展IP输入，格式：192.168.88.1/255.255.255.0,192.168.89.2/255.255.255.0",
              "example": ""
            },
            "enabled": {
              "type": "string",
              "description": "是否启用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "VlanToggleRequest": {
          "type": "object",
          "required": [
            "enabled"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "启用状态 (yes=启用, no=停用)",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "vlan",
        "x-displayName": "VLAN接口",
        "description": "VLAN接口配置的增删改查及启用/停用管理"
      }
    ]
  },
  "network/network-wan.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "WAN接口管理API",
      "version": "1.0.0",
      "summary": "WAN接口配置查询",
      "description": "提供WAN接口的完整管理功能，包括：\n- WAN接口配置信息查询\n- WAN接口配置更新\n- WAN接口混合模式（基于物理网卡/VLAN）的配置信息查询\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/interfaces/wan-config": {
        "get": {
          "summary": "获取WAN接口配置",
          "description": "查询所有WAN接口的配置信息，包括接口名称、接入模式、绑定网卡、\nPPPoE/DHCP/静态IP参数、线路检测、定时重启、LTE拨号及多拨助手等配置。\n",
          "operationId": "getWanConfig",
          "tags": [
            "wan-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取WAN接口配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WanConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "name": "wan1",
                          "tagname": "wan1",
                          "comment": "",
                          "bandmode": 0,
                          "internet": 3,
                          "mac": "",
                          "speed": 0,
                          "duplex": 0,
                          "upload": 0,
                          "download": 0,
                          "qos_upload": 1000,
                          "qos_download": 1000,
                          "vendorclass": "",
                          "clientid": "",
                          "hostname": "",
                          "opt_type12": 0,
                          "opt_type60": 0,
                          "opt_type61": 0,
                          "wifi_wisp": 1,
                          "wifi_bssid": "",
                          "wifi_ssid": "",
                          "wifi_psk": "",
                          "ip_mask": "",
                          "gateway": "",
                          "username": "",
                          "password": "",
                          "timing_rst_switch": 0,
                          "timing_rst_week": "1234567",
                          "timing_rst_time": "12:00",
                          "cycle_rst_time": 0,
                          "pppoe_service": "",
                          "pppoe_ac": "",
                          "mtu": 1480,
                          "mru": 1480,
                          "default_route": 0,
                          "disc_auto_switch": 1,
                          "link_time": "00:00-23:59",
                          "check_link_mode": 3,
                          "check_link_host": "www.baidu.com",
                          "qos_switch": 1,
                          "enable_ipv6": 0,
                          "linkmode": 0,
                          "policy": 1,
                          "lte_service": "umts_gprs",
                          "lte_mode": "auto",
                          "lte_apn": "3gnet",
                          "lte_dialnum": "*99#",
                          "lte_pincode": "",
                          "lte_antenna_switch": 0,
                          "bandlist_5g": "1,3,5,8,28,41,77,78,79",
                          "sim_switch": 0,
                          "pppoe_ass_switch": 0,
                          "ass_multi_total": 10,
                          "ass_disc_rst_switch": 0,
                          "ass_rst_check_week": "1234567",
                          "ass_rst_check_time": "00:00-08:00",
                          "ass_rst_check_interval": 10,
                          "ass_rst_disc_num": 5,
                          "ass_rst_disc_norestart": 0,
                          "ass_check_errip_switch": 0,
                          "ass_check_errip_list": "10,172,192.168",
                          "pppoe_check_errip_switch": 0,
                          "pppoe_check_errip_list": "10,172,192.168",
                          "vlan_internet_info": "2,0,0",
                          "pppoe_ip_addr": "",
                          "pppoe_netmask": "",
                          "pppoe_gateway": "",
                          "pppoe_updatetime": 0,
                          "pppoe_dns1": "",
                          "pppoe_dns2": "",
                          "pppoe_macremote": "",
                          "pppoe_status": 0,
                          "dhcp_ip_addr": "",
                          "dhcp_netmask": "",
                          "dhcp_gateway": "",
                          "dhcp_updatetime": 0,
                          "dhcp_dns1": "",
                          "dhcp_dns2": "",
                          "dhcp_lease": 0,
                          "dhcp_status": 0,
                          "modified_time": 1772161919,
                          "bandif": "00:e2:69:00:89:e8",
                          "bandeth": "eth3"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/interfaces/wan-config/{id}": {
        "put": {
          "summary": "更新WAN接口配置",
          "description": "更新指定WAN接口的配置。本接口为全量修改，请求时需传入所有字段。\n无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n\n**参数按 internet 接入模式分组：**\n- 公共参数（所有模式必传）：internet, bandif, bandmode\n- internet=0/1/2 共用：default_route, disc_auto_switch, link_time, check_link_mode\n- internet=0（静态IP）专属：ip_mask, gateway\n- internet=1（DHCP）专属：vendorclass, clientid, hostname, opt_type12, opt_type60, opt_type61\n- internet=2（ADSL/PPPoE）专属：username, password, mtu, mru, timing_rst_*, pppoe_*\n- internet=3（混合模式）子接口PPPoE：pppoe_ass_switch, ass_multi_total, ass_rst_*\n",
          "operationId": "updateWanConfig",
          "tags": [
            "wan-interfaces"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "WAN接口ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1,
                "example": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WanConfigUpdateRequest"
                },
                "examples": {
                  "static_ip": {
                    "summary": "静态IP模式",
                    "value": {
                      "internet": 0,
                      "bandif": "00:e2:69:00:89:e8",
                      "bandmode": 0,
                      "mac": "",
                      "speed": 0,
                      "duplex": 0,
                      "comment": "",
                      "default_route": 1,
                      "disc_auto_switch": 1,
                      "link_time": "00:00-23:59",
                      "check_link_mode": 3,
                      "check_link_host": "www.baidu.com",
                      "ip_mask": "192.168.1.100/255.255.255.0",
                      "gateway": "192.168.1.1"
                    }
                  },
                  "dhcp": {
                    "summary": "DHCP模式",
                    "value": {
                      "internet": 1,
                      "bandif": "00:e2:69:00:89:e8",
                      "bandmode": 0,
                      "mac": "",
                      "speed": 0,
                      "duplex": 0,
                      "comment": "",
                      "default_route": 1,
                      "disc_auto_switch": 1,
                      "link_time": "00:00-23:59",
                      "check_link_mode": 1,
                      "check_link_host": "www.baidu.com",
                      "vendorclass": "",
                      "clientid": "",
                      "hostname": "",
                      "opt_type12": 0,
                      "opt_type60": 0,
                      "opt_type61": 0
                    }
                  },
                  "pppoe": {
                    "summary": "ADSL/PPPoE模式",
                    "value": {
                      "internet": 2,
                      "bandif": "00:e2:69:00:89:e8",
                      "bandmode": 0,
                      "mac": "",
                      "speed": 0,
                      "duplex": 0,
                      "comment": "",
                      "default_route": 1,
                      "disc_auto_switch": 1,
                      "link_time": "00:00-23:59",
                      "check_link_mode": 3,
                      "check_link_host": "www.baidu.com",
                      "username": "myuser",
                      "password": "mypassword",
                      "mtu": 1480,
                      "mru": 1480,
                      "timing_rst_switch": 0,
                      "timing_rst_week": "1234567",
                      "timing_rst_time": "12:00",
                      "cycle_rst_time": 0,
                      "pppoe_service": "",
                      "pppoe_ac": "",
                      "pppoe_check_errip_switch": 0,
                      "pppoe_check_errip_list": "10,172,192.168"
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/interfaces/wan-vlan-config": {
        "get": {
          "summary": "获取WAN混合模式配置",
          "description": "查询基于WAN接口的混合模式配置信息，包括基于物理网卡的混合模式\n和基于VLAN的混合模式。包含VLAN名称、接入模式、PPPoE/DHCP/静态IP\n参数、线路检测等配置。\n当WAN接口配置中 internet=3（基于物理网卡的混合模式）或\ninternet=4（基于VLAN的混合模式）时使用此接口查询详细配置。\n",
          "operationId": "getWanVlanConfig",
          "tags": [
            "wan-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取WAN混合模式配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WanVlanConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "vlan_data": [
                        {
                          "id": 3,
                          "interface": "wan1",
                          "vlan_name": "vwan666",
                          "vlan_id": "3",
                          "vlan_internet": 0,
                          "enabled": "yes",
                          "comment": "",
                          "mac": "00:71:6f:a6:0c:2d",
                          "upload": 0,
                          "download": 0,
                          "qos_upload": 0,
                          "qos_download": 0,
                          "vendorclass": "",
                          "clientid": "",
                          "hostname": "",
                          "opt_type12": 0,
                          "opt_type60": 0,
                          "opt_type61": 0,
                          "ip_mask": "192.168.3.220/255.255.255.0",
                          "gateway": "192.168.3.253",
                          "dhcp_gateway": "",
                          "dhcp_dns1": "",
                          "dhcp_dns2": "",
                          "username": "",
                          "password": "",
                          "timing_rst_switch": 0,
                          "timing_rst_week": "1234567",
                          "timing_rst_time": "12:00",
                          "cycle_rst_time": 0,
                          "pppoe_service": "",
                          "pppoe_ac": "",
                          "mtu": 1480,
                          "mru": 1480,
                          "default_route": 1,
                          "disc_auto_switch": 0,
                          "link_time": "00:00-23:59",
                          "check_link_mode": 1,
                          "check_link_host": "www.baidu.com",
                          "qos_switch": 0,
                          "pppoe_check_errip_switch": 0,
                          "pppoe_check_errip_list": "10,172,192.168",
                          "dhcp_lease": 0,
                          "dhcp_updatetime": 0,
                          "dhcp_netmask": "",
                          "dhcp_ip_addr": "",
                          "pppoe_macremote": "",
                          "pppoe_dns1": "",
                          "pppoe_dns2": "",
                          "pppoe_updatetime": 0,
                          "pppoe_gateway": "",
                          "pppoe_netmask": "",
                          "pppoe_ip_addr": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求语法错误或参数不合法"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WanConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WanConfigResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WanConfigResults": {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "description": "WAN接口配置列表",
              "items": {
                "$ref": "#/components/schemas/WanInterface"
              }
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": false
        },
        "WanInterface": {
          "type": "object",
          "required": [
            "id",
            "name",
            "tagname",
            "comment",
            "bandmode",
            "internet",
            "mac",
            "speed",
            "duplex",
            "upload",
            "download",
            "qos_upload",
            "qos_download",
            "vendorclass",
            "clientid",
            "hostname",
            "opt_type12",
            "opt_type60",
            "opt_type61",
            "wifi_wisp",
            "wifi_bssid",
            "wifi_ssid",
            "wifi_psk",
            "ip_mask",
            "gateway",
            "username",
            "password",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "cycle_rst_time",
            "pppoe_service",
            "pppoe_ac",
            "mtu",
            "mru",
            "default_route",
            "disc_auto_switch",
            "link_time",
            "check_link_mode",
            "check_link_host",
            "qos_switch",
            "enable_ipv6",
            "linkmode",
            "policy",
            "lte_service",
            "lte_mode",
            "lte_apn",
            "lte_dialnum",
            "lte_pincode",
            "lte_antenna_switch",
            "bandlist_5g",
            "sim_switch",
            "pppoe_ass_switch",
            "ass_multi_total",
            "ass_disc_rst_switch",
            "ass_rst_check_week",
            "ass_rst_check_time",
            "ass_rst_check_interval",
            "ass_rst_disc_num",
            "ass_rst_disc_norestart",
            "ass_check_errip_switch",
            "ass_check_errip_list",
            "pppoe_check_errip_switch",
            "pppoe_check_errip_list",
            "vlan_internet_info",
            "pppoe_ip_addr",
            "pppoe_netmask",
            "pppoe_gateway",
            "pppoe_updatetime",
            "pppoe_dns1",
            "pppoe_dns2",
            "pppoe_macremote",
            "pppoe_status",
            "dhcp_ip_addr",
            "dhcp_netmask",
            "dhcp_gateway",
            "dhcp_updatetime",
            "dhcp_dns1",
            "dhcp_dns2",
            "dhcp_lease",
            "dhcp_status",
            "modified_time",
            "bandif",
            "bandeth"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "接口ID",
              "minimum": 1,
              "example": 1
            },
            "name": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "wan1"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 50,
              "example": "wan1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "bandmode": {
              "type": "integer",
              "description": "绑定模式（0=网桥, 1=汇聚）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "internet": {
              "type": "integer",
              "description": "接入模式（0=静态IP, 1=DHCP, 2=ADSL/PPPoE, 3=基于物理网卡的混合模式, 4=基于VLAN的混合模式）",
              "enum": [
                0,
                1,
                2,
                3,
                4
              ],
              "example": 3
            },
            "mac": {
              "type": "string",
              "description": "网卡MAC地址（空字符串表示未设置）",
              "maxLength": 17,
              "example": ""
            },
            "speed": {
              "type": "integer",
              "description": "网卡速率（0=自动, 10/100/1000/10000 Mbps）",
              "enum": [
                0,
                10,
                100,
                1000,
                10000
              ],
              "example": 0
            },
            "duplex": {
              "type": "integer",
              "description": "工作模式（0=自动, 1=全双工, 2=半双工）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "upload": {
              "type": "integer",
              "description": "上行带宽（Kbps，0表示不限制）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下行带宽（Kbps，0表示不限制）",
              "minimum": 0,
              "example": 0
            },
            "qos_upload": {
              "type": "integer",
              "description": "QoS上行带宽（Kbps）",
              "minimum": 0,
              "example": 1000
            },
            "qos_download": {
              "type": "integer",
              "description": "QoS下行带宽（Kbps）",
              "minimum": 0,
              "example": 1000
            },
            "vendorclass": {
              "type": "string",
              "description": "DHCP厂商类别（internet=1时有效）",
              "maxLength": 100,
              "example": ""
            },
            "clientid": {
              "type": "string",
              "description": "DHCP客户端ID（internet=1时有效）",
              "maxLength": 100,
              "example": ""
            },
            "hostname": {
              "type": "string",
              "description": "DHCP主机名称（internet=1时有效）",
              "maxLength": 100,
              "example": ""
            },
            "opt_type12": {
              "type": "integer",
              "description": "hostname 的传值格式（internet=1时有效，0=字符串, 1=十六进制）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "opt_type60": {
              "type": "integer",
              "description": "vendorclass 的传值格式（internet=1时有效，0=字符串, 1=十六进制）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "opt_type61": {
              "type": "integer",
              "description": "clientid 的传值格式（internet=1时有效，0=字符串, 1=十六进制）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "wifi_wisp": {
              "type": "integer",
              "description": "是否支持WiFi WISP模式（0=不支持, 1=支持）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "wifi_bssid": {
              "type": "string",
              "description": "WiFi BSSID",
              "maxLength": 17,
              "example": ""
            },
            "wifi_ssid": {
              "type": "string",
              "description": "WiFi SSID",
              "maxLength": 100,
              "example": ""
            },
            "wifi_psk": {
              "type": "string",
              "description": "WiFi PSK密码",
              "maxLength": 200,
              "example": ""
            },
            "ip_mask": {
              "type": "string",
              "description": "网卡IP地址和子网掩码，格式：IP地址/子网掩码（静态IP模式有效）",
              "example": ""
            },
            "gateway": {
              "type": "string",
              "description": "网关地址（静态IP模式有效）",
              "example": ""
            },
            "username": {
              "type": "string",
              "description": "PPPoE拨号用户名",
              "maxLength": 100,
              "example": ""
            },
            "password": {
              "type": "string",
              "description": "PPPoE拨号密码",
              "format": "password",
              "maxLength": 100,
              "example": ""
            },
            "timing_rst_switch": {
              "type": "integer",
              "description": "是否开启定时重启（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重启周期（1234567表示每天，每位对应周一至周日）",
              "maxLength": 7,
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重启时间，格式：HH:MM",
              "maxLength": 5,
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "重启周期（分钟，0表示无限）",
              "minimum": 0,
              "example": 0
            },
            "pppoe_service": {
              "type": "string",
              "description": "PPPoE拨号服务名称",
              "maxLength": 100,
              "example": ""
            },
            "pppoe_ac": {
              "type": "string",
              "description": "PPPoE拨号AC名称",
              "maxLength": 100,
              "example": ""
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 0,
              "maximum": 9000,
              "example": 1480
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 0,
              "maximum": 9000,
              "example": 1480
            },
            "default_route": {
              "type": "integer",
              "description": "是否为默认路由（0=否, 1=是）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "disc_auto_switch": {
              "type": "integer",
              "description": "掉线自动切换（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "link_time": {
              "type": "string",
              "description": "上线时间段，格式：HH:MM-HH:MM",
              "maxLength": 11,
              "example": "00:00-23:59"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式（0=关闭, 1=HTTP+网关, 2=PING+网关, 3=HTTP+PING+网关, 4=HTTP, 5=PING, 6=HTTP+PING）",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 3
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测主机地址",
              "maxLength": 200,
              "example": "www.baidu.com"
            },
            "qos_switch": {
              "type": "integer",
              "description": "是否开启流控（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "enable_ipv6": {
              "type": "integer",
              "description": "IPv6接入模式（0=不启用, 1=以太网连接, 2=PPPoE连接）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "linkmode": {
              "type": "integer",
              "description": "链路聚合模式（0=手工链路聚合, 4=LACP链路聚合）",
              "enum": [
                0,
                4
              ],
              "example": 0
            },
            "policy": {
              "type": "integer",
              "description": "汇聚负载方式（0=layer2, 1=layer3+4, 2=layer2+3）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 1
            },
            "lte_service": {
              "type": "string",
              "description": "LTE拨号服务名称",
              "maxLength": 100,
              "example": "umts_gprs"
            },
            "lte_mode": {
              "type": "string",
              "description": "LTE拨号模式（auto=自动, manual=手动）",
              "enum": [
                "auto",
                "manual"
              ],
              "example": "auto"
            },
            "lte_apn": {
              "type": "string",
              "description": "LTE拨号APN",
              "maxLength": 100,
              "example": "3gnet"
            },
            "lte_dialnum": {
              "type": "string",
              "description": "LTE拨号号码",
              "maxLength": 50,
              "example": "*99#"
            },
            "lte_pincode": {
              "type": "string",
              "description": "LTE拨号PIN码",
              "maxLength": 20,
              "example": ""
            },
            "lte_antenna_switch": {
              "type": "integer",
              "description": "LTE天线开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "bandlist_5g": {
              "type": "string",
              "description": "5G频段列表（逗号分隔）",
              "example": "1,3,5,8,28,41,77,78,79"
            },
            "sim_switch": {
              "type": "integer",
              "description": "SIM卡切换开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "pppoe_ass_switch": {
              "type": "integer",
              "description": "PPPoE多拨助手开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ass_multi_total": {
              "type": "integer",
              "description": "多拨总数",
              "minimum": 0,
              "example": 10
            },
            "ass_disc_rst_switch": {
              "type": "integer",
              "description": "掉线重拨开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ass_rst_check_week": {
              "type": "string",
              "description": "重拨周期（1234567表示每天）",
              "maxLength": 7,
              "example": "1234567"
            },
            "ass_rst_check_time": {
              "type": "string",
              "description": "重拨时间段，格式：HH:MM-HH:MM",
              "maxLength": 11,
              "example": "00:00-08:00"
            },
            "ass_rst_check_interval": {
              "type": "integer",
              "description": "重拨间隔（分钟）",
              "minimum": 0,
              "example": 10
            },
            "ass_rst_disc_num": {
              "type": "integer",
              "description": "重拨次数",
              "minimum": 0,
              "example": 5
            },
            "ass_rst_disc_norestart": {
              "type": "integer",
              "description": "掉线禁止重拨（0=允许, 1=禁止）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ass_check_errip_switch": {
              "type": "integer",
              "description": "异常IP检测开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ass_check_errip_list": {
              "type": "string",
              "description": "异常IP检测列表（逗号分隔的IP前缀）",
              "example": "10,172,192.168"
            },
            "pppoe_check_errip_switch": {
              "type": "integer",
              "description": "PPPoE异常IP检测开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "pppoe_check_errip_list": {
              "type": "string",
              "description": "PPPoE异常IP检测列表（逗号分隔的IP前缀）",
              "example": "10,172,192.168"
            },
            "vlan_internet_info": {
              "type": "string",
              "description": "VLAN接入模式信息",
              "example": "2,0,0"
            },
            "pppoe_ip_addr": {
              "type": "string",
              "description": "PPPoE获取的IP地址",
              "example": ""
            },
            "pppoe_netmask": {
              "type": "string",
              "description": "PPPoE获取的子网掩码",
              "example": ""
            },
            "pppoe_gateway": {
              "type": "string",
              "description": "PPPoE获取的网关",
              "example": ""
            },
            "pppoe_updatetime": {
              "type": "integer",
              "format": "int64",
              "description": "PPPoE更新时间戳",
              "minimum": 0,
              "example": 0
            },
            "pppoe_dns1": {
              "type": "string",
              "description": "PPPoE获取的首选DNS",
              "example": ""
            },
            "pppoe_dns2": {
              "type": "string",
              "description": "PPPoE获取的备用DNS",
              "example": ""
            },
            "pppoe_macremote": {
              "type": "string",
              "description": "PPPoE远端MAC地址",
              "maxLength": 17,
              "example": ""
            },
            "pppoe_status": {
              "type": "integer",
              "description": "PPPoE连接状态",
              "minimum": 0,
              "example": 0
            },
            "dhcp_ip_addr": {
              "type": "string",
              "description": "DHCP获取的IP地址",
              "example": ""
            },
            "dhcp_netmask": {
              "type": "string",
              "description": "DHCP获取的子网掩码",
              "example": ""
            },
            "dhcp_gateway": {
              "type": "string",
              "description": "DHCP获取的网关",
              "example": ""
            },
            "dhcp_updatetime": {
              "type": "integer",
              "format": "int64",
              "description": "DHCP更新时间戳",
              "minimum": 0,
              "example": 0
            },
            "dhcp_dns1": {
              "type": "string",
              "description": "DHCP获取的首选DNS",
              "example": ""
            },
            "dhcp_dns2": {
              "type": "string",
              "description": "DHCP获取的备用DNS",
              "example": ""
            },
            "dhcp_lease": {
              "type": "integer",
              "description": "DHCP租期（秒）",
              "minimum": 0,
              "example": 0
            },
            "dhcp_status": {
              "type": "integer",
              "description": "DHCP连接状态",
              "minimum": 0,
              "example": 0
            },
            "modified_time": {
              "type": "integer",
              "format": "int64",
              "description": "修改时间戳（Unix时间戳）",
              "example": 1772161919
            },
            "bandif": {
              "type": "string",
              "description": "绑定网卡MAC地址（逗号分隔，多网卡时有效）",
              "example": "00:e2:69:00:89:e8"
            },
            "bandeth": {
              "type": "string",
              "description": "绑定网卡名称（逗号分隔，多网卡时有效）",
              "example": "eth3"
            }
          },
          "additionalProperties": false
        },
        "WanVlanConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WanVlanConfigResults"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WanVlanConfigResults": {
          "type": "object",
          "properties": {
            "vlan_data": {
              "type": "array",
              "description": "WAN混合模式VLAN配置列表",
              "items": {
                "$ref": "#/components/schemas/WanVlanInterface"
              }
            }
          },
          "required": [
            "vlan_data"
          ],
          "additionalProperties": false
        },
        "WanVlanInterface": {
          "type": "object",
          "required": [
            "id",
            "interface",
            "vlan_name",
            "vlan_id",
            "vlan_internet",
            "enabled",
            "comment",
            "mac",
            "upload",
            "download",
            "qos_upload",
            "qos_download",
            "vendorclass",
            "clientid",
            "hostname",
            "opt_type12",
            "opt_type60",
            "opt_type61",
            "ip_mask",
            "gateway",
            "dhcp_gateway",
            "dhcp_dns1",
            "dhcp_dns2",
            "username",
            "password",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "cycle_rst_time",
            "pppoe_service",
            "pppoe_ac",
            "mtu",
            "mru",
            "default_route",
            "disc_auto_switch",
            "link_time",
            "check_link_mode",
            "check_link_host",
            "qos_switch",
            "pppoe_check_errip_switch",
            "pppoe_check_errip_list",
            "dhcp_lease",
            "dhcp_updatetime",
            "dhcp_netmask",
            "dhcp_ip_addr",
            "pppoe_macremote",
            "pppoe_dns1",
            "pppoe_dns2",
            "pppoe_updatetime",
            "pppoe_gateway",
            "pppoe_netmask",
            "pppoe_ip_addr"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 3
            },
            "interface": {
              "type": "string",
              "description": "依赖的物理WAN接口名称",
              "maxLength": 50,
              "example": "wan1"
            },
            "vlan_name": {
              "type": "string",
              "description": "WAN接口的VLAN名称",
              "maxLength": 50,
              "example": "vwan666"
            },
            "vlan_id": {
              "type": "string",
              "description": "VLAN ID（支持QinQ格式如1000/100.200，范围1~4090）",
              "example": "3"
            },
            "vlan_internet": {
              "type": "integer",
              "description": "VLAN接入模式（0=静态IP, 1=DHCP, 2=ADSL/PPPoE）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "enabled": {
              "type": "string",
              "description": "是否启用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "mac": {
              "type": "string",
              "description": "VLAN MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "00:71:6f:a6:0c:2d"
            },
            "upload": {
              "type": "integer",
              "description": "上行带宽（Kbps，0表示不限制）",
              "minimum": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下行带宽（Kbps，0表示不限制）",
              "minimum": 0,
              "example": 0
            },
            "qos_upload": {
              "type": "integer",
              "description": "QoS上行带宽（Kbps）",
              "minimum": 0,
              "example": 0
            },
            "qos_download": {
              "type": "integer",
              "description": "QoS下行带宽（Kbps）",
              "minimum": 0,
              "example": 0
            },
            "vendorclass": {
              "type": "string",
              "description": "DHCP厂商类别",
              "maxLength": 100,
              "example": ""
            },
            "clientid": {
              "type": "string",
              "description": "DHCP客户端ID",
              "maxLength": 100,
              "example": ""
            },
            "hostname": {
              "type": "string",
              "description": "DHCP主机名称",
              "maxLength": 100,
              "example": ""
            },
            "opt_type12": {
              "type": "integer",
              "description": "hostname 的传值格式（0=字符串, 1=十六进制）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "opt_type60": {
              "type": "integer",
              "description": "vendorclass 的传值格式（0=字符串, 1=十六进制）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "opt_type61": {
              "type": "integer",
              "description": "clientid 的传值格式（0=字符串, 1=十六进制）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "ip_mask": {
              "type": "string",
              "description": "网卡IP地址和子网掩码，格式：IP地址/子网掩码（静态IP模式有效）",
              "example": "192.168.3.220/255.255.255.0"
            },
            "gateway": {
              "type": "string",
              "description": "静态IP网关",
              "example": "192.168.3.253"
            },
            "dhcp_gateway": {
              "type": "string",
              "description": "DHCP获取的网关",
              "example": ""
            },
            "dhcp_dns1": {
              "type": "string",
              "description": "DHCP获取的首选DNS",
              "example": ""
            },
            "dhcp_dns2": {
              "type": "string",
              "description": "DHCP获取的备用DNS",
              "example": ""
            },
            "username": {
              "type": "string",
              "description": "PPPoE拨号用户名",
              "maxLength": 100,
              "example": ""
            },
            "password": {
              "type": "string",
              "description": "PPPoE拨号密码",
              "format": "password",
              "maxLength": 100,
              "example": ""
            },
            "timing_rst_switch": {
              "type": "integer",
              "description": "是否开启定时重启（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重启周期（1234567表示每天）",
              "maxLength": 7,
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重启时间，格式：HH:MM",
              "maxLength": 5,
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "重启周期（分钟，0表示无限）",
              "minimum": 0,
              "example": 0
            },
            "pppoe_service": {
              "type": "string",
              "description": "PPPoE拨号服务名称",
              "maxLength": 100,
              "example": ""
            },
            "pppoe_ac": {
              "type": "string",
              "description": "PPPoE拨号AC名称",
              "maxLength": 100,
              "example": ""
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 0,
              "maximum": 9000,
              "example": 1480
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 0,
              "maximum": 9000,
              "example": 1480
            },
            "default_route": {
              "type": "integer",
              "description": "是否为默认路由（0=否, 1=是）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "disc_auto_switch": {
              "type": "integer",
              "description": "掉线自动切换（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "link_time": {
              "type": "string",
              "description": "上线时间段，格式：HH:MM-HH:MM",
              "maxLength": 11,
              "example": "00:00-23:59"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式（0=关闭, 1=HTTP+网关, 2=PING+网关, 3=HTTP+PING+网关, 4=HTTP, 5=PING, 6=HTTP+PING）",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测主机地址",
              "maxLength": 200,
              "example": "www.baidu.com"
            },
            "qos_switch": {
              "type": "integer",
              "description": "是否开启流控（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "pppoe_check_errip_switch": {
              "type": "integer",
              "description": "PPPoE异常IP检测开关（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "pppoe_check_errip_list": {
              "type": "string",
              "description": "PPPoE异常IP检测列表（逗号分隔的IP前缀）",
              "example": "10,172,192.168"
            },
            "dhcp_lease": {
              "type": "integer",
              "description": "DHCP租期（秒）",
              "minimum": 0,
              "example": 0
            },
            "dhcp_updatetime": {
              "type": "integer",
              "format": "int64",
              "description": "DHCP更新时间戳",
              "minimum": 0,
              "example": 0
            },
            "dhcp_netmask": {
              "type": "string",
              "description": "DHCP获取的子网掩码",
              "example": ""
            },
            "dhcp_ip_addr": {
              "type": "string",
              "description": "DHCP获取的IP地址",
              "example": ""
            },
            "pppoe_macremote": {
              "type": "string",
              "description": "PPPoE远端MAC地址",
              "maxLength": 17,
              "example": ""
            },
            "pppoe_dns1": {
              "type": "string",
              "description": "PPPoE获取的首选DNS",
              "example": ""
            },
            "pppoe_dns2": {
              "type": "string",
              "description": "PPPoE获取的备用DNS",
              "example": ""
            },
            "pppoe_updatetime": {
              "type": "integer",
              "format": "int64",
              "description": "PPPoE更新时间戳",
              "minimum": 0,
              "example": 0
            },
            "pppoe_gateway": {
              "type": "string",
              "description": "PPPoE获取的网关",
              "example": ""
            },
            "pppoe_netmask": {
              "type": "string",
              "description": "PPPoE获取的子网掩码",
              "example": ""
            },
            "pppoe_ip_addr": {
              "type": "string",
              "description": "PPPoE获取的IP地址",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果信息",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WanConfigCommonBase": {
          "type": "object",
          "required": [
            "internet",
            "bandif",
            "bandmode"
          ],
          "properties": {
            "internet": {
              "type": "integer",
              "description": "接入模式（0=静态IP, 1=DHCP, 2=ADSL/PPPoE, 3=基于物理网卡混合模式, 4=基于VLAN混合模式）",
              "enum": [
                0,
                1,
                2,
                3,
                4
              ],
              "example": 0
            },
            "bandif": {
              "type": "string",
              "description": "绑定网卡MAC地址，多个以逗号分隔",
              "example": "00:e2:69:00:89:e8"
            },
            "bandmode": {
              "type": "integer",
              "description": "绑定模式（0=网桥, 1=汇聚）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "mac": {
              "type": "string",
              "description": "克隆MAC地址，空字符串表示不克隆",
              "maxLength": 17,
              "example": ""
            },
            "speed": {
              "type": "integer",
              "description": "网卡速率（0=自动, 10/100/1000/10000 Mbps）",
              "enum": [
                0,
                10,
                100,
                1000,
                10000
              ],
              "example": 0
            },
            "duplex": {
              "type": "integer",
              "description": "工作模式（0=自动, 1=全双工, 2=半双工）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64字符",
              "maxLength": 64,
              "example": ""
            }
          }
        },
        "WanConfigLinkBase": {
          "type": "object",
          "required": [
            "default_route",
            "disc_auto_switch",
            "link_time",
            "check_link_mode"
          ],
          "properties": {
            "default_route": {
              "type": "integer",
              "description": "是否设置为默认路由（0=否, 1=是）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "disc_auto_switch": {
              "type": "integer",
              "description": "掉线自动切换（0=关闭, 1=开启）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "link_time": {
              "type": "string",
              "description": "上线时间段，格式：HH:MM-HH:MM",
              "maxLength": 11,
              "example": "00:00-23:59"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式（0=关闭, 1=HTTP+网关, 2=PING+网关, 3=HTTP+PING+网关, 4=HTTP, 5=PING, 6=HTTP+PING）",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 3
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测主机地址",
              "maxLength": 200,
              "example": "www.baidu.com"
            }
          }
        },
        "WanConfigStaticIPRequest": {
          "title": "静态IP模式 (internet=0)",
          "allOf": [
            {
              "$ref": "#/components/schemas/WanConfigCommonBase"
            },
            {
              "$ref": "#/components/schemas/WanConfigLinkBase"
            },
            {
              "type": "object",
              "required": [
                "ip_mask",
                "gateway"
              ],
              "properties": {
                "ip_mask": {
                  "type": "string",
                  "description": "静态IP地址和子网掩码，格式：IP/掩码，如 192.168.1.1/255.255.255.0",
                  "example": "192.168.1.100/255.255.255.0"
                },
                "gateway": {
                  "type": "string",
                  "description": "静态IP网关",
                  "example": "192.168.1.1"
                }
              }
            }
          ]
        },
        "WanConfigDHCPRequest": {
          "title": "DHCP模式 (internet=1)",
          "allOf": [
            {
              "$ref": "#/components/schemas/WanConfigCommonBase"
            },
            {
              "$ref": "#/components/schemas/WanConfigLinkBase"
            },
            {
              "type": "object",
              "properties": {
                "vendorclass": {
                  "type": "string",
                  "description": "DHCP厂商类别",
                  "maxLength": 100,
                  "example": ""
                },
                "clientid": {
                  "type": "string",
                  "description": "DHCP客户端ID",
                  "maxLength": 100,
                  "example": ""
                },
                "hostname": {
                  "type": "string",
                  "description": "DHCP主机名称",
                  "maxLength": 100,
                  "example": ""
                },
                "opt_type12": {
                  "type": "integer",
                  "description": "hostname 的传值格式（0=字符串, 1=十六进制）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "opt_type60": {
                  "type": "integer",
                  "description": "vendorclass 的传值格式（0=字符串, 1=十六进制）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "opt_type61": {
                  "type": "integer",
                  "description": "clientid 的传值格式（0=字符串, 1=十六进制）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                }
              }
            }
          ]
        },
        "WanConfigPPPoERequest": {
          "title": "ADSL/PPPoE模式 (internet=2)",
          "allOf": [
            {
              "$ref": "#/components/schemas/WanConfigCommonBase"
            },
            {
              "$ref": "#/components/schemas/WanConfigLinkBase"
            },
            {
              "type": "object",
              "required": [
                "username",
                "password"
              ],
              "properties": {
                "username": {
                  "type": "string",
                  "description": "PPPoE拨号用户名",
                  "maxLength": 100,
                  "example": "myuser"
                },
                "password": {
                  "type": "string",
                  "description": "PPPoE拨号密码",
                  "format": "password",
                  "maxLength": 100,
                  "example": "mypassword"
                },
                "mtu": {
                  "type": "integer",
                  "description": "MTU值（PPPoE建议范围512~1492）",
                  "minimum": 0,
                  "maximum": 9000,
                  "example": 1480
                },
                "mru": {
                  "type": "integer",
                  "description": "MRU值（PPPoE建议范围512~1492）",
                  "minimum": 0,
                  "maximum": 9000,
                  "example": 1480
                },
                "timing_rst_switch": {
                  "type": "integer",
                  "description": "定时重启开关（0=关闭, 1=开启）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "timing_rst_week": {
                  "type": "string",
                  "description": "定时重启周期，每位对应周一至周日",
                  "maxLength": 7,
                  "example": "1234567"
                },
                "timing_rst_time": {
                  "type": "string",
                  "description": "定时重启时间，格式：HH:MM",
                  "maxLength": 5,
                  "example": "12:00"
                },
                "cycle_rst_time": {
                  "type": "integer",
                  "description": "周期重启间隔（分钟，0=不启用）",
                  "minimum": 0,
                  "example": 0
                },
                "pppoe_service": {
                  "type": "string",
                  "description": "PPPoE服务名称",
                  "maxLength": 100,
                  "example": ""
                },
                "pppoe_ac": {
                  "type": "string",
                  "description": "PPPoE AC名称",
                  "maxLength": 100,
                  "example": ""
                },
                "pppoe_check_errip_switch": {
                  "type": "integer",
                  "description": "PPPoE异常IP检测开关（0=关闭, 1=开启）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "pppoe_check_errip_list": {
                  "type": "string",
                  "description": "PPPoE异常IP检测列表，逗号分隔IP前缀",
                  "example": "10,172,192.168"
                }
              }
            }
          ]
        },
        "WanConfigMixedPhysicalRequest": {
          "title": "基于物理网卡混合模式 (internet=3)",
          "description": "混合模式下WAN接口作为物理承载，实际接入参数在子VLAN接口中配置（通过 wan-vlan-config 管理）。\n当子接口 vlan_internet=2（PPPoE）时，可额外传入多拨助手参数。\n",
          "allOf": [
            {
              "$ref": "#/components/schemas/WanConfigCommonBase"
            },
            {
              "type": "object",
              "properties": {
                "pppoe_ass_switch": {
                  "type": "integer",
                  "description": "PPPoE多拨助手开关（0=关闭, 1=开启）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "ass_multi_total": {
                  "type": "integer",
                  "description": "多拨总数",
                  "minimum": 0,
                  "example": 10
                },
                "ass_rst_check_interval": {
                  "type": "integer",
                  "description": "重拨检测间隔（分钟）",
                  "minimum": 0,
                  "example": 10
                },
                "ass_rst_disc_num": {
                  "type": "integer",
                  "description": "触发重拨的掉线次数阈值",
                  "minimum": 0,
                  "example": 5
                },
                "ass_rst_disc_norestart": {
                  "type": "integer",
                  "description": "掉线后是否禁止重拨（0=允许, 1=禁止）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                }
              }
            }
          ]
        },
        "WanConfigMixedVLANRequest": {
          "title": "基于VLAN混合模式 (internet=4)",
          "description": "基于VLAN的混合模式，WAN接口作为物理承载，实际接入参数在子VLAN接口中配置（通过 wan-vlan-config 管理）。\n",
          "allOf": [
            {
              "$ref": "#/components/schemas/WanConfigCommonBase"
            }
          ]
        },
        "WanConfigUpdateRequest": {
          "description": "WAN接口配置更新请求体，按 `internet` 接入模式选择对应的参数结构：\n- `internet=0`（静态IP）：必填 `ip_mask`、`gateway` 及链路参数\n- `internet=1`（DHCP）：必填链路参数，可选 DHCP 扩展参数\n- `internet=2`（ADSL/PPPoE）：必填 `username`、`password` 及链路参数\n- `internet=3`（基于物理网卡混合模式）：子接口在 wan-vlan-config 中配置，可选多拨助手参数\n- `internet=4`（基于VLAN混合模式）：子接口在 wan-vlan-config 中配置\n",
          "oneOf": [
            {
              "$ref": "#/components/schemas/WanConfigStaticIPRequest"
            },
            {
              "$ref": "#/components/schemas/WanConfigDHCPRequest"
            },
            {
              "$ref": "#/components/schemas/WanConfigPPPoERequest"
            },
            {
              "$ref": "#/components/schemas/WanConfigMixedPhysicalRequest"
            },
            {
              "$ref": "#/components/schemas/WanConfigMixedVLANRequest"
            }
          ]
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer {token}\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "wan-interfaces",
        "x-displayName": "WAN接口",
        "description": "WAN接口配置及混合模式配置查询"
      }
    ]
  },
  "object_group/network-object-domain.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "域名对象管理API",
      "version": "1.0.0",
      "summary": "域名对象管理完整功能",
      "description": "提供域名对象的完整管理功能，包括：\n- 域名对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- 域名对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/domain-objects": {
        "get": {
          "summary": "获取域名对象列表",
          "description": "获取所有域名对象策略列表。\n支持分页功能。\n",
          "operationId": "listDomainObjects",
          "tags": [
            "object-domain"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000,
                "default": 20
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取域名对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DomainObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建域名对象",
          "description": "创建新的域名对象策略。\n支持多个域名配置。\n",
          "operationId": "createDomainObject",
          "tags": [
            "object-domain"
          ],
          "requestBody": {
            "required": true,
            "description": "域名对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainObjectInput"
                },
                "example": {
                  "group_name": "domain00",
                  "group_value": [
                    {
                      "domain": "www.baidu.com",
                      "comment": "test11"
                    },
                    {
                      "domain": "www.qq.com",
                      "comment": "test11"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/domain-objects/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "域名对象ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定域名对象",
          "description": "根据ID获取单个域名对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getDomainObject",
          "tags": [
            "object-domain"
          ],
          "responses": {
            "200": {
              "description": "成功获取域名对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DomainObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新域名对象",
          "description": "修改指定域名对象的配置信息。\n支持部分字段更新。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDomainObject",
          "tags": [
            "object-domain"
          ],
          "requestBody": {
            "required": true,
            "description": "域名对象更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainObjectInput"
                },
                "example": {
                  "group_name": "domain00",
                  "group_value": [
                    {
                      "domain": "www.example.com",
                      "comment": "updated"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除域名对象",
          "description": "删除指定的域名对象。\n删除后对象将被永久移除，无法恢复。\n",
          "operationId": "deleteDomainObject",
          "tags": [
            "object-domain"
          ],
          "responses": {
            "200": {
              "description": "域名对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/domain-objects/ref": {
        "get": {
          "summary": "查询域名对象引用关系",
          "description": "查询引用指定域名对象的所有规则列表。\n需要提供group_name参数。\n",
          "operationId": "getDomainObjectReferences",
          "tags": [
            "object-domain"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "对象名称",
              "schema": {
                "type": "string"
              },
              "example": "domain00"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取域名对象引用关系",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DomainObjectReferenceResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问域名对象管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "域名对象不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "DomainObject": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 15
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "domain00"
            },
            "group_value": {
              "type": "array",
              "description": "域名列表",
              "items": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "域名",
                    "format": "hostname",
                    "example": "www.baidu.com"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "DomainObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "domain00"
            },
            "group_value": {
              "type": "array",
              "description": "域名列表",
              "items": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "域名",
                    "format": "hostname",
                    "example": "www.baidu.com"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "DomainObjectResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "domain_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DomainObject"
                  }
                },
                "domain_total": {
                  "type": "integer",
                  "description": "域名对象总数",
                  "example": 1
                }
              },
              "required": [
                "domain_data",
                "domain_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DomainObjectListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "domain_data": {
                  "type": "array",
                  "description": "域名对象列表",
                  "items": {
                    "$ref": "#/components/schemas/DomainObject"
                  }
                },
                "domain_total": {
                  "type": "integer",
                  "description": "域名对象总数",
                  "example": 5
                }
              },
              "required": [
                "domain_data",
                "domain_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DomainObjectReferenceResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "type": "object",
                  "properties": {
                    "acl": {
                      "type": "array",
                      "description": "ACL规则列表",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tagname": {
                            "type": "string",
                            "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
                            "example": "acl33"
                          },
                          "enabled": {
                            "type": "string",
                            "description": "规则是否启用",
                            "enum": [
                              "yes",
                              "no"
                            ],
                            "example": "yes"
                          },
                          "id": {
                            "type": "integer",
                            "description": "规则ID",
                            "example": 1
                          }
                        },
                        "required": [
                          "tagname",
                          "enabled",
                          "id"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "acl"
                  ]
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-domain",
        "x-displayName": "域名对象管理",
        "description": "域名对象管理，支持域名配置和引用关系查询"
      }
    ]
  },
  "object_group/network-object-ip.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "IP对象管理API",
      "version": "1.0.0",
      "summary": "IP对象管理完整功能",
      "description": "提供IP对象的完整管理功能，包括：\n- IP对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- IP对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/ip-objects": {
        "get": {
          "summary": "获取IP对象列表",
          "description": "获取所有IP对象策略列表。\n支持分页功能。\n",
          "operationId": "listIpObjects",
          "tags": [
            "object-ip"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IP对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IpObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建IP对象",
          "description": "创建新的IP对象策略。\n支持单个IP、IP范围、IP/掩码格式。\n",
          "operationId": "createIpObject",
          "tags": [
            "object-ip"
          ],
          "requestBody": {
            "required": true,
            "description": "IP对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IPObjectInput"
                },
                "example": {
                  "group_name": "ip66",
                  "group_value": [
                    {
                      "ip": "192.168.44.5",
                      "comment": "test11"
                    },
                    {
                      "ip": "192.168.88.1/24",
                      "comment": "test_ipmask"
                    },
                    {
                      "ip": "192.168.99.1-192.168.99.100",
                      "comment": "test_iprange"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/ip-objects/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/ipObjectIdParam"
          }
        ],
        "get": {
          "summary": "获取指定IP对象",
          "description": "根据ID获取单个IP对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getIpObject",
          "tags": [
            "object-ip"
          ],
          "responses": {
            "200": {
              "description": "成功获取IP对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IpObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新IP对象",
          "description": "完全更新现有的IP对象配置。\n需要提供所有字段。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateIpObject",
          "tags": [
            "object-ip"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的IP对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IPObjectInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除IP对象",
          "description": "删除指定的IP对象。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteIpObject",
          "tags": [
            "object-ip"
          ],
          "responses": {
            "200": {
              "description": "IP对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/ip-objects/ref": {
        "get": {
          "summary": "查询IP对象引用",
          "description": "获取引用指定IP对象的规则列表。\n可以查询哪些ACL规则引用了特定的对象。\n",
          "operationId": "getIpObjectReferences",
          "tags": [
            "object-ip"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "IP对象名称",
              "schema": {
                "type": "string",
                "minLength": 1,
                "example": "ip66"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取引用信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IPObjectReferencesResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "rules_ref": {
                        "acl": [
                          {
                            "tagname": "acl33",
                            "rule_id": 1
                          },
                          {
                            "tagname": "001",
                            "rule_id": 50
                          },
                          {
                            "tagname": "053",
                            "rule_id": 100
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "ipObjectIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "IP对象ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段（当前版本未启用排序功能）",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "IpObjectResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "ip_data": {
                  "type": "array",
                  "description": "IP对象列表",
                  "items": {
                    "$ref": "#/components/schemas/IPObject"
                  }
                },
                "ip_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                }
              },
              "required": [
                "ip_data",
                "ip_total"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "IpObjectListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "ip_data": {
                  "type": "array",
                  "description": "IP对象列表",
                  "items": {
                    "$ref": "#/components/schemas/IPObject"
                  }
                },
                "ip_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                }
              },
              "required": [
                "ip_data",
                "ip_total"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "IpObjectValue": {
          "type": "object",
          "required": [
            "ip",
            "comment"
          ],
          "properties": {
            "ip": {
              "type": "string",
              "description": "IP地址，支持以下格式： - 单个IP地址：192.168.1.1 - IP地址范围：192.168.1.1-192.168.1.100 - IP地址/掩码：192.168.1.0/24",
              "pattern": "^((\\d{1,3}\\.){3}\\d{1,3})(-\\((\\d{1,3}\\.){3}\\d{1,3}\\))?(\\/(\\d{1,2}))?$",
              "example": "192.168.44.5"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9][\\u4e00-\\u9fa5a-zA-Z0-9_-]*$",
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "IPObject": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value",
            "enabled"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 1
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "ip66"
            },
            "group_value": {
              "type": "array",
              "description": "对象内容列表",
              "items": {
                "$ref": "#/components/schemas/IpObjectValue"
              },
              "minItems": 1,
              "maxItems": 100,
              "example": [
                {
                  "ip": "192.168.44.5",
                  "comment": "test11"
                },
                {
                  "ip": "192.168.88.1/24",
                  "comment": "test_ipmask"
                }
              ]
            },
            "enabled": {
              "type": "string",
              "description": "对象启用状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "created_time": {
              "type": "string",
              "format": "date-time",
              "description": "创建时间",
              "readOnly": true,
              "example": "2023-10-30T10:00:00Z"
            },
            "updated_time": {
              "type": "string",
              "format": "date-time",
              "description": "更新时间",
              "readOnly": true,
              "example": "2023-10-30T10:00:00Z"
            }
          },
          "additionalProperties": false
        },
        "IPObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "ip66"
            },
            "group_value": {
              "type": "array",
              "description": "对象内容列表",
              "items": {
                "$ref": "#/components/schemas/IpObjectValue"
              },
              "minItems": 1,
              "maxItems": 100,
              "example": [
                {
                  "ip": "192.168.44.5",
                  "comment": "test11"
                },
                {
                  "ip": "192.168.88.1/24",
                  "comment": "test_ipmask"
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "IpObjectReference": {
          "type": "object",
          "required": [
            "tagname",
            "rule_id"
          ],
          "properties": {
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 100,
              "example": "acl33"
            },
            "rule_id": {
              "type": "integer",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "IPObjectReferences": {
          "type": "object",
          "properties": {
            "acl": {
              "type": "array",
              "description": "ACL规则引用列表",
              "items": {
                "$ref": "#/components/schemas/IpObjectReference"
              },
              "example": [
                {
                  "tagname": "acl33",
                  "rule_id": 1
                },
                {
                  "tagname": "001",
                  "rule_id": 50
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "IPObjectReferencesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "$ref": "#/components/schemas/IPObjectReferences"
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-ip",
        "x-displayName": "IP对象管理",
        "description": "IP对象策略的管理和配置"
      }
    ]
  },
  "object_group/network-object-ip6.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "IPv6对象管理API",
      "version": "1.0.0",
      "summary": "IPv6对象管理完整功能",
      "description": "提供IPv6对象的完整管理功能，包括：\n- IPv6对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- IPv6对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/ip6-objects": {
        "get": {
          "summary": "获取IPv6对象列表",
          "description": "获取所有IPv6对象策略列表。\n支持分页功能。\n",
          "operationId": "listIp6Objects",
          "tags": [
            "object-ipv6"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000,
                "default": 20
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IPv6对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ip6ObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建IPv6对象",
          "description": "创建新的IPv6对象策略。\n支持单个IPv6地址或IPv6地址段。\n",
          "operationId": "createIp6Object",
          "tags": [
            "object-ipv6"
          ],
          "requestBody": {
            "required": true,
            "description": "IPv6对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ip6ObjectInput"
                },
                "example": {
                  "group_name": "ipv600",
                  "group_value": [
                    {
                      "ipv6": "2408:8207:3050:6360:aab8:e0ff:fe00:f72a",
                      "comment": "test11"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/ip6-objects/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "IPv6对象ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定IPv6对象",
          "description": "根据ID获取单个IPv6对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getIp6Object",
          "tags": [
            "object-ipv6"
          ],
          "responses": {
            "200": {
              "description": "成功获取IPv6对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ip6ObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新IPv6对象",
          "description": "修改指定IPv6对象的配置信息。\n支持部分字段更新。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateIp6Object",
          "tags": [
            "object-ipv6"
          ],
          "requestBody": {
            "required": true,
            "description": "IPv6对象更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ip6ObjectInput"
                },
                "example": {
                  "group_name": "ipv600",
                  "group_value": [
                    {
                      "ipv6": "2408:8207:3050:6360:aab8:e0ff:fe00:f72a",
                      "comment": "updated"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除IPv6对象",
          "description": "删除指定的IPv6对象。\n删除后对象将被永久移除，无法恢复。\n",
          "operationId": "deleteIp6Object",
          "tags": [
            "object-ipv6"
          ],
          "responses": {
            "200": {
              "description": "IPv6对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/ip6-objects/ref": {
        "get": {
          "summary": "查询IPv6对象引用关系",
          "description": "查询引用指定IPv6对象的所有规则列表。\n需要提供group_name参数。\n",
          "operationId": "getIp6ObjectReferences",
          "tags": [
            "object-ipv6"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "对象名称",
              "schema": {
                "type": "string"
              },
              "example": "ipv600"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IPv6对象引用关系",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ip6ObjectReferenceResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问IPv6对象管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "IPv6对象不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "Ip6Object": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 15
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "ipv600"
            },
            "group_value": {
              "type": "array",
              "description": "IPv6地址列表",
              "items": {
                "type": "object",
                "required": [
                  "ipv6"
                ],
                "properties": {
                  "ipv6": {
                    "type": "string",
                    "description": "IPv6地址",
                    "format": "ipv6",
                    "example": "2408:8207:3050:6360:aab8:e0ff:fe00:f72a"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "Ip6ObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "ipv600"
            },
            "group_value": {
              "type": "array",
              "description": "IPv6地址列表",
              "items": {
                "type": "object",
                "required": [
                  "ipv6"
                ],
                "properties": {
                  "ipv6": {
                    "type": "string",
                    "description": "IPv6地址",
                    "format": "ipv6",
                    "example": "2408:8207:3050:6360:aab8:e0ff:fe00:f72a"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "Ip6ObjectResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "ip6_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Ip6Object"
                  }
                },
                "ip6_total": {
                  "type": "integer",
                  "description": "IPv6对象总数",
                  "example": 1
                }
              },
              "required": [
                "ip6_data",
                "ip6_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Ip6ObjectListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "ip6_data": {
                  "type": "array",
                  "description": "IPv6对象列表",
                  "items": {
                    "$ref": "#/components/schemas/Ip6Object"
                  }
                },
                "ip6_total": {
                  "type": "integer",
                  "description": "IPv6对象总数",
                  "example": 5
                }
              },
              "required": [
                "ip6_data",
                "ip6_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Ip6ObjectReferenceResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "type": "object",
                  "properties": {
                    "acl": {
                      "type": "array",
                      "description": "ACL规则列表",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tagname": {
                            "type": "string",
                            "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
                            "example": "acl33"
                          },
                          "enabled": {
                            "type": "string",
                            "description": "规则是否启用",
                            "enum": [
                              "yes",
                              "no"
                            ],
                            "example": "yes"
                          },
                          "id": {
                            "type": "integer",
                            "description": "规则ID",
                            "example": 1
                          }
                        },
                        "required": [
                          "tagname",
                          "enabled",
                          "id"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "acl"
                  ]
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-ipv6",
        "x-displayName": "IPv6对象管理",
        "description": "IPv6对象管理，支持IPv6地址配置和引用关系查询"
      }
    ]
  },
  "object_group/network-object-mac.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "MAC对象管理API",
      "version": "1.0.0",
      "summary": "MAC对象管理完整功能",
      "description": "提供MAC对象的完整管理功能，包括：\n- MAC对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- MAC对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/mac-objects": {
        "get": {
          "summary": "获取MAC对象列表",
          "description": "获取所有MAC对象策略列表。\n支持分页功能。\n",
          "operationId": "listMacObjects",
          "tags": [
            "object-mac"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建MAC对象",
          "description": "创建新的MAC对象策略。\n支持MAC地址格式：08:9b:4b:00:10:6e。\n",
          "operationId": "createMacObject",
          "tags": [
            "object-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "MAC对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MACObjectInput"
                },
                "example": {
                  "group_name": "mac00",
                  "group_value": [
                    {
                      "mac": "08:9b:4b:00:10:6e",
                      "comment": "test11"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/mac-objects/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/macObjectIdParam"
          }
        ],
        "get": {
          "summary": "获取指定MAC对象",
          "description": "根据ID获取单个MAC对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getMacObject",
          "tags": [
            "object-mac"
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新MAC对象",
          "description": "完全更新现有的MAC对象配置。\n需要提供所有字段。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateMacObject",
          "tags": [
            "object-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的MAC对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MACObjectInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除MAC对象",
          "description": "删除指定的MAC对象。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteMacObject",
          "tags": [
            "object-mac"
          ],
          "responses": {
            "200": {
              "description": "MAC对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/mac-objects/ref": {
        "get": {
          "summary": "查询MAC对象引用",
          "description": "获取引用指定MAC对象的规则列表。\n可以查询哪些ACL规则引用了特定的对象。\n",
          "operationId": "getMacObjectReferences",
          "tags": [
            "object-mac"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "MAC对象名称",
              "schema": {
                "type": "string",
                "minLength": 1,
                "example": "mac00"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取引用信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MACObjectReferencesResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "rules_ref": {
                        "acl": [
                          {
                            "tagname": "acl33",
                            "enabled": "yes",
                            "id": 1
                          },
                          {
                            "tagname": "001",
                            "enabled": "yes",
                            "id": 50
                          },
                          {
                            "tagname": "053",
                            "enabled": "yes",
                            "id": 100
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "macObjectIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "MAC对象ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "MacObjectResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "mac_data": {
                  "type": "array",
                  "description": "MAC对象列表",
                  "items": {
                    "$ref": "#/components/schemas/MACObject"
                  }
                },
                "mac_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                }
              },
              "required": [
                "mac_data",
                "mac_total"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MacObjectListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "mac_data": {
                  "type": "array",
                  "description": "MAC对象列表",
                  "items": {
                    "$ref": "#/components/schemas/MACObject"
                  }
                },
                "mac_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                }
              },
              "required": [
                "mac_data",
                "mac_total"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MacObjectValue": {
          "type": "object",
          "required": [
            "mac"
          ],
          "properties": {
            "mac": {
              "type": "string",
              "description": "MAC地址，格式：08:9b:4b:00:10:6e\n使用冒号分隔的6组十六进制数\n",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:6e"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "MACObject": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value",
            "enabled"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 1
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "mac00"
            },
            "group_value": {
              "type": "array",
              "description": "对象内容列表",
              "items": {
                "$ref": "#/components/schemas/MacObjectValue"
              },
              "minItems": 1,
              "maxItems": 100,
              "example": [
                {
                  "mac": "08:9b:4b:00:10:6e",
                  "comment": "test11"
                }
              ]
            },
            "enabled": {
              "type": "string",
              "description": "对象启用状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "created_time": {
              "type": "string",
              "format": "date-time",
              "description": "创建时间",
              "readOnly": true,
              "example": "2023-10-30T10:00:00Z"
            },
            "updated_time": {
              "type": "string",
              "format": "date-time",
              "description": "更新时间",
              "readOnly": true,
              "example": "2023-10-30T10:00:00Z"
            }
          },
          "additionalProperties": false
        },
        "MACObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "mac00"
            },
            "group_value": {
              "type": "array",
              "description": "对象内容列表",
              "items": {
                "$ref": "#/components/schemas/MacObjectValue"
              },
              "minItems": 1,
              "maxItems": 100,
              "example": [
                {
                  "mac": "08:9b:4b:00:10:6e",
                  "comment": "test11"
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "MacObjectReference": {
          "type": "object",
          "required": [
            "tagname",
            "id",
            "enabled"
          ],
          "properties": {
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 100,
              "example": "acl33"
            },
            "id": {
              "type": "integer",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则是否启用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            }
          },
          "additionalProperties": false
        },
        "MACObjectReferences": {
          "type": "object",
          "properties": {
            "acl": {
              "type": "array",
              "description": "ACL规则引用列表",
              "items": {
                "$ref": "#/components/schemas/MacObjectReference"
              },
              "example": [
                {
                  "tagname": "acl33",
                  "enabled": "yes",
                  "id": 1
                },
                {
                  "tagname": "001",
                  "enabled": "yes",
                  "id": 50
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "MACObjectReferencesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "$ref": "#/components/schemas/MACObjectReferences"
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-mac",
        "x-displayName": "MAC对象管理",
        "description": "MAC对象策略的管理和配置"
      }
    ]
  },
  "object_group/network-object-port.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "端口对象管理API",
      "version": "1.0.0",
      "summary": "端口对象管理完整功能",
      "description": "提供端口对象的完整管理功能，包括：\n- 端口对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- 端口对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/port-objects": {
        "get": {
          "summary": "获取端口对象列表",
          "description": "获取所有端口对象策略列表。\n支持分页功能。\n",
          "operationId": "listPortObjects",
          "tags": [
            "object-port"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000,
                "default": 20
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取端口对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PortObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建端口对象",
          "description": "创建新的端口对象策略。\n支持单个端口或端口范围配置。\n",
          "operationId": "createPortObject",
          "tags": [
            "object-port"
          ],
          "requestBody": {
            "required": true,
            "description": "端口对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortObjectInput"
                },
                "example": {
                  "group_name": "port00",
                  "group_value": [
                    {
                      "port": "9000",
                      "comment": "test11"
                    },
                    {
                      "port": "10000-10200",
                      "comment": "test11"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/port-objects/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "端口对象ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定端口对象",
          "description": "根据ID获取单个端口对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getPortObject",
          "tags": [
            "object-port"
          ],
          "responses": {
            "200": {
              "description": "成功获取端口对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PortObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新端口对象",
          "description": "修改指定端口对象的配置信息。\n支持部分字段更新。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePortObject",
          "tags": [
            "object-port"
          ],
          "requestBody": {
            "required": true,
            "description": "端口对象更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortObjectInput"
                },
                "example": {
                  "group_name": "port00",
                  "group_value": [
                    {
                      "port": "8080",
                      "comment": "updated"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除端口对象",
          "description": "删除指定的端口对象。\n删除后对象将被永久移除，无法恢复。\n",
          "operationId": "deletePortObject",
          "tags": [
            "object-port"
          ],
          "responses": {
            "200": {
              "description": "端口对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/port-objects/ref": {
        "get": {
          "summary": "查询端口对象引用关系",
          "description": "查询引用指定端口对象的所有规则列表。\n需要提供group_name参数。\n",
          "operationId": "getPortObjectReferences",
          "tags": [
            "object-port"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "对象名称",
              "schema": {
                "type": "string"
              },
              "example": "port00"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取端口对象引用关系",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PortObjectReferenceResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问端口对象管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "端口对象不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "PortObject": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 15
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "port00"
            },
            "group_value": {
              "type": "array",
              "description": "端口列表",
              "items": {
                "type": "object",
                "required": [
                  "port"
                ],
                "properties": {
                  "port": {
                    "type": "string",
                    "description": "端口配置\n- 支持单个端口：9000\n- 支持端口范围：10000-10200\n",
                    "pattern": "^[0-9]+$|^[0-9]+-[0-9]+$",
                    "example": "9000"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "PortObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "port00"
            },
            "group_value": {
              "type": "array",
              "description": "端口列表",
              "items": {
                "type": "object",
                "required": [
                  "port"
                ],
                "properties": {
                  "port": {
                    "type": "string",
                    "description": "端口配置\n- 支持单个端口：9000\n- 支持端口范围：10000-10200\n",
                    "pattern": "^[0-9]+$|^[0-9]+-[0-9]+$",
                    "example": "10000-10200"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "PortObjectResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "port_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PortObject"
                  }
                },
                "port_total": {
                  "type": "integer",
                  "description": "端口对象总数",
                  "example": 1
                }
              },
              "required": [
                "port_data",
                "port_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PortObjectListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "port_data": {
                  "type": "array",
                  "description": "端口对象列表",
                  "items": {
                    "$ref": "#/components/schemas/PortObject"
                  }
                },
                "port_total": {
                  "type": "integer",
                  "description": "端口对象总数",
                  "example": 5
                }
              },
              "required": [
                "port_data",
                "port_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PortObjectReferenceResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "type": "object",
                  "properties": {
                    "acl": {
                      "type": "array",
                      "description": "ACL规则列表",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tagname": {
                            "type": "string",
                            "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
                            "example": "acl33"
                          },
                          "enabled": {
                            "type": "string",
                            "description": "规则是否启用",
                            "enum": [
                              "yes",
                              "no"
                            ],
                            "example": "yes"
                          },
                          "id": {
                            "type": "integer",
                            "description": "规则ID",
                            "example": 1
                          }
                        },
                        "required": [
                          "tagname",
                          "enabled",
                          "id"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "acl"
                  ]
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-port",
        "x-displayName": "端口对象管理",
        "description": "端口对象管理，支持端口配置和引用关系查询"
      }
    ]
  },
  "object_group/network-object-proto.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "协议对象管理API",
      "version": "1.0.0",
      "summary": "协议对象管理完整功能",
      "description": "提供协议对象的完整管理功能，包括：\n- 协议对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- 协议对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/proto-objects": {
        "get": {
          "summary": "获取协议对象列表",
          "description": "获取所有协议对象策略列表。\n支持分页功能。\n",
          "operationId": "listProtoObjects",
          "tags": [
            "object-proto"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000,
                "default": 20
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取协议对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ProtoObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建协议对象",
          "description": "创建新的协议对象策略。\n支持多种协议类型。\n",
          "operationId": "createProtoObject",
          "tags": [
            "object-proto"
          ],
          "requestBody": {
            "required": true,
            "description": "协议对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtoObjectInput"
                },
                "example": {
                  "group_name": "proto00",
                  "group_value": [
                    {
                      "proto": "文件传输",
                      "comment": "test11"
                    },
                    {
                      "proto": "DNS",
                      "comment": "test11"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/proto-objects/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "协议对象ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定协议对象",
          "description": "根据ID获取单个协议对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getProtoObject",
          "tags": [
            "object-proto"
          ],
          "responses": {
            "200": {
              "description": "成功获取协议对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ProtoObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新协议对象",
          "description": "修改指定协议对象的配置信息。\n支持部分字段更新。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateProtoObject",
          "tags": [
            "object-proto"
          ],
          "requestBody": {
            "required": true,
            "description": "协议对象更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtoObjectInput"
                },
                "example": {
                  "group_name": "proto00",
                  "group_value": [
                    {
                      "proto": "HTTP",
                      "comment": "updated"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除协议对象",
          "description": "删除指定的协议对象。\n删除后对象将被永久移除，无法恢复。\n",
          "operationId": "deleteProtoObject",
          "tags": [
            "object-proto"
          ],
          "responses": {
            "200": {
              "description": "协议对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/proto-objects/ref": {
        "get": {
          "summary": "查询协议对象引用关系",
          "description": "查询引用指定协议对象的所有规则列表。\n需要提供group_name参数。\n",
          "operationId": "getProtoObjectReferences",
          "tags": [
            "object-proto"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "对象名称",
              "schema": {
                "type": "string"
              },
              "example": "proto00"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取协议对象引用关系",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ProtoObjectReferenceResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问协议对象管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "协议对象不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ProtoObject": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 15
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "proto00"
            },
            "group_value": {
              "type": "array",
              "description": "协议列表",
              "items": {
                "type": "object",
                "required": [
                  "proto"
                ],
                "properties": {
                  "proto": {
                    "type": "string",
                    "description": "协议名称",
                    "example": "文件传输"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "ProtoObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "example": "proto00"
            },
            "group_value": {
              "type": "array",
              "description": "协议列表",
              "items": {
                "type": "object",
                "required": [
                  "proto"
                ],
                "properties": {
                  "proto": {
                    "type": "string",
                    "description": "协议名称",
                    "example": "DNS"
                  },
                  "comment": {
                    "type": "string",
                    "description": "备注信息，最多64个字符，不支持特殊字符",
                    "maxLength": 64,
                    "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
                    "example": "test11"
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "ProtoObjectResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "proto_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProtoObject"
                  }
                },
                "proto_total": {
                  "type": "integer",
                  "description": "协议对象总数",
                  "example": 1
                }
              },
              "required": [
                "proto_data",
                "proto_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ProtoObjectListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "proto_data": {
                  "type": "array",
                  "description": "协议对象列表",
                  "items": {
                    "$ref": "#/components/schemas/ProtoObject"
                  }
                },
                "proto_total": {
                  "type": "integer",
                  "description": "协议对象总数",
                  "example": 5
                }
              },
              "required": [
                "proto_data",
                "proto_total"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ProtoObjectReferenceResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "type": "object",
                  "properties": {
                    "acl": {
                      "type": "array",
                      "description": "ACL规则列表",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tagname": {
                            "type": "string",
                            "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
                            "example": "acl33"
                          },
                          "enabled": {
                            "type": "string",
                            "description": "规则是否启用",
                            "enum": [
                              "yes",
                              "no"
                            ],
                            "example": "yes"
                          },
                          "id": {
                            "type": "integer",
                            "description": "规则ID",
                            "example": 1
                          }
                        },
                        "required": [
                          "tagname",
                          "enabled",
                          "id"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "acl"
                  ]
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-proto",
        "x-displayName": "协议对象管理",
        "description": "协议对象管理，支持协议配置和引用关系查询"
      }
    ]
  },
  "object_group/network-object-time.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "时间对象管理API",
      "version": "1.0.0",
      "summary": "时间对象管理完整功能",
      "description": "提供时间对象的完整管理功能，包括：\n- 时间对象的创建、查询、更新、删除\n- 对象启用/停用状态控制\n- 支持两种时间类型：weekly（按周循环）和date（日期时间）\n- 时间对象引用关系查询\n支持分页功能。\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/time-objects": {
        "get": {
          "summary": "获取时间对象列表",
          "description": "获取所有时间对象策略列表。\n支持分页功能。\n",
          "operationId": "listTimeObjects",
          "tags": [
            "object-time"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取时间对象列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/TimeObjectListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建时间对象",
          "description": "创建新的时间对象策略。\n支持两种时间类型：\n- weekly（按周循环）：需要weekdays、start_time、end_time\n- date（日期时间）：需要start_time、end_time\n",
          "operationId": "createTimeObject",
          "tags": [
            "object-time"
          ],
          "requestBody": {
            "required": true,
            "description": "时间对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeObjectInput"
                },
                "example": {
                  "group_name": "time00",
                  "group_value": [
                    {
                      "type": "weekly",
                      "weekdays": "1234567",
                      "start_time": "00:00",
                      "end_time": "20:00",
                      "comment": "test11"
                    },
                    {
                      "type": "date",
                      "start_time": "2026-05-01T08:00",
                      "end_time": "2026-05-10T08:00",
                      "comment": "test11"
                    }
                  ]
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/time-objects/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/timeObjectIdParam"
          }
        ],
        "get": {
          "summary": "获取指定时间对象",
          "description": "根据ID获取单个时间对象的详细信息。\n需要提供有效的对象ID。\n",
          "operationId": "getTimeObject",
          "tags": [
            "object-time"
          ],
          "responses": {
            "200": {
              "description": "成功获取时间对象详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/TimeObjectResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新时间对象",
          "description": "完全更新现有的时间对象配置。\n需要提供所有字段。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateTimeObject",
          "tags": [
            "object-time"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的时间对象配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeObjectInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除时间对象",
          "description": "删除指定的时间对象。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteTimeObject",
          "tags": [
            "object-time"
          ],
          "responses": {
            "200": {
              "description": "时间对象删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/time-objects/ref": {
        "get": {
          "summary": "查询时间对象引用",
          "description": "获取引用指定时间对象的规则列表。\n可以查询哪些ACL规则引用了特定的对象。\n",
          "operationId": "getTimeObjectReferences",
          "tags": [
            "object-time"
          ],
          "parameters": [
            {
              "name": "group_name",
              "in": "query",
              "required": true,
              "description": "时间对象名称",
              "schema": {
                "type": "string",
                "minLength": 1,
                "example": "time00"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取引用信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/TimeObjectReferencesResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "rules_ref": {
                        "acl": [
                          {
                            "tagname": "acl33",
                            "enabled": "yes",
                            "id": 1
                          },
                          {
                            "tagname": "001",
                            "enabled": "yes",
                            "id": 50
                          },
                          {
                            "tagname": "053",
                            "enabled": "yes",
                            "id": 100
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "timeObjectIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "时间对象ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "TimeObjectValue": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time",
            "comment"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间对象类型：\n- weekly：按周循环\n- date：日期时间\n",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "weekdays": {
              "type": "string",
              "description": "星期（仅weekly类型使用）\n格式：1234567（1-7分别代表周一到周日）\n",
              "pattern": "^[1-7]+$",
              "minLength": 1,
              "maxLength": 7,
              "example": "1234567"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间或日期时间：\n- weekly类型：格式00:00\n- date类型：格式2026-05-01T08:00\n",
              "pattern": "^([0-1][0-9]:[0-5][0-9]|[2][0-3]:[0-5][0-9]|[0-9]:[0-5][0-9]|[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-5][0-9])$",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间或日期时间：\n- weekly类型：格式00:00\n- date类型：格式2026-05-01T08:00\n",
              "pattern": "^([0-1][0-9]:[0-5][0-9]|[2][0-3]:[0-5][0-9]|[0-9]:[0-5][0-9]|[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-5][0-9])$",
              "example": "20:00"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9][\\u4e00-\\u9fa5a-zA-Z0-9_-]*$",
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "required": [
            "id",
            "group_name",
            "group_value",
            "enabled"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "对象ID",
              "minimum": 1,
              "example": 1
            },
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "time00"
            },
            "group_value": {
              "type": "array",
              "description": "对象内容列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectValue"
              },
              "minItems": 1,
              "maxItems": 100,
              "example": [
                {
                  "type": "weekly",
                  "weekdays": "1234567",
                  "start_time": "00:00",
                  "end_time": "20:00",
                  "comment": "test11"
                },
                {
                  "type": "date",
                  "start_time": "2026-05-01T08:00",
                  "end_time": "2026-05-10T08:00",
                  "comment": "test11"
                }
              ]
            },
            "enabled": {
              "type": "string",
              "description": "对象启用状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "created_time": {
              "type": "string",
              "format": "date-time",
              "description": "创建时间",
              "readOnly": true,
              "example": "2023-10-30T10:00:00Z"
            },
            "updated_time": {
              "type": "string",
              "format": "date-time",
              "description": "更新时间",
              "readOnly": true,
              "example": "2023-10-30T10:00:00Z"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectInput": {
          "type": "object",
          "required": [
            "group_name",
            "group_value"
          ],
          "properties": {
            "group_name": {
              "type": "string",
              "description": "对象名称（仅支持中文、英文、数字，长度限制1-15字符）",
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "time00"
            },
            "group_value": {
              "type": "array",
              "description": "对象内容列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectValue"
              },
              "minItems": 1,
              "maxItems": 100,
              "example": [
                {
                  "type": "weekly",
                  "weekdays": "1234567",
                  "start_time": "00:00",
                  "end_time": "20:00",
                  "comment": "test11"
                },
                {
                  "type": "date",
                  "start_time": "2026-05-01T08:00",
                  "end_time": "2026-05-10T08:00",
                  "comment": "test11"
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "TimeObjectReference": {
          "type": "object",
          "required": [
            "tagname",
            "id",
            "enabled"
          ],
          "properties": {
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "maxLength": 100,
              "example": "acl33"
            },
            "id": {
              "type": "integer",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则是否启用",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectReferences": {
          "type": "object",
          "properties": {
            "acl": {
              "type": "array",
              "description": "ACL规则引用列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectReference"
              },
              "example": [
                {
                  "tagname": "acl33",
                  "enabled": "yes",
                  "id": 1
                },
                {
                  "tagname": "001",
                  "enabled": "yes",
                  "id": 50
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "TimeObjectReferencesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "rules_ref": {
                  "$ref": "#/components/schemas/TimeObjectReferences"
                }
              },
              "required": [
                "rules_ref"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "TimeObjectResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "time_data": {
                  "type": "array",
                  "description": "时间对象列表",
                  "items": {
                    "$ref": "#/components/schemas/TimeObject"
                  }
                },
                "time_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                }
              },
              "required": [
                "time_data",
                "time_total"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "TimeObjectListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "time_data": {
                  "type": "array",
                  "description": "时间对象列表",
                  "items": {
                    "$ref": "#/components/schemas/TimeObject"
                  }
                },
                "time_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                }
              },
              "required": [
                "time_data",
                "time_total"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "object-time",
        "x-displayName": "时间对象管理",
        "description": "时间对象策略的管理和配置，支持weekly和date两种时间类型"
      }
    ]
  },
  "route/network-static-routes.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "静态路由策略管理API",
      "version": "1.0.0",
      "description": "提供静态路由策略的完整管理功能，包括：\n- 静态路由策略的增删改查\n- 策略启用/停用管理\n- 支持IPv4和IPv6路由配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "static-routes",
        "x-displayName": "静态路由",
        "description": "静态路由策略管理和配置"
      }
    ],
    "paths": {
      "/api/v4.0/routing/static-routes": {
        "get": {
          "tags": [
            "static-routes"
          ],
          "summary": "获取所有静态路由策略",
          "description": "获取当前配置的所有静态路由策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listStaticRoutes",
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取静态路由策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/StaticRouteListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          }
        },
        "post": {
          "tags": [
            "static-routes"
          ],
          "summary": "添加静态路由策略",
          "description": "创建新的静态路由策略。需要指定目标地址、网关、接口等路由信息。\n支持IPv4和IPv6地址类型。\n",
          "operationId": "createStaticRoute",
          "requestBody": {
            "required": true,
            "description": "静态路由配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaticRouteInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "route_to_lan",
                  "comment": "路由到内网段",
                  "interface": "lan1",
                  "dst_addr": "192.168.2.0",
                  "netmask": "255.255.255.0",
                  "gateway": "192.168.1.1",
                  "prio": 1,
                  "ip_type": "4"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            }
          }
        }
      },
      "/api/v4.0/routing/static-routes/{id}": {
        "get": {
          "tags": [
            "static-routes"
          ],
          "summary": "获取指定静态路由策略",
          "description": "获取指定ID的静态路由策略详细信息",
          "operationId": "getStaticRoute",
          "parameters": [
            {
              "$ref": "#/components/parameters/staticRouteIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取静态路由策略信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/StaticRouteResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "put": {
          "tags": [
            "static-routes"
          ],
          "summary": "更新静态路由策略",
          "description": "完全更新指定ID的静态路由策略\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateStaticRoute",
          "parameters": [
            {
              "$ref": "#/components/parameters/staticRouteIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "静态路由配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaticRouteUpdateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            }
          }
        },
        "patch": {
          "tags": [
            "static-routes"
          ],
          "summary": "启用/停用静态路由策略",
          "description": "启用或停用指定ID的静态路由策略",
          "operationId": "updateStaticRouteStatus",
          "parameters": [
            {
              "$ref": "#/components/parameters/staticRouteIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态，yes为启用，no为停用"
                    }
                  },
                  "example": {
                    "enabled": "no"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "delete": {
          "tags": [
            "static-routes"
          ],
          "summary": "删除静态路由策略",
          "description": "删除指定ID的静态路由策略",
          "operationId": "deleteStaticRoute",
          "parameters": [
            {
              "$ref": "#/components/parameters/staticRouteIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功删除静态路由策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "staticRouteIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "静态路由策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、interface、prio等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=prio>1&filter=interface==eth0\n- OR条件：filter=dst_addr==192.168.1.0,filter=dst_addr==192.168.2.0\n",
          "schema": {
            "type": "string",
            "example": "enabled==yes"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "静态路由策略名称或目标地址冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建成功后返回的资源ID",
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "StaticRouteListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StaticRoute"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "StaticRouteResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StaticRoute"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "StaticRoute": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "interface",
            "dst_addr",
            "netmask",
            "gateway",
            "prio",
            "ip_type"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "主键ID",
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "策略状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "route_to_lan"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "interface": {
              "type": "string",
              "description": "路由接口，auto为自动选择",
              "example": "wan1"
            },
            "dst_addr": {
              "type": "string",
              "format": "ipv4",
              "description": "目的地址",
              "example": "192.168.2.0"
            },
            "netmask": {
              "type": "string",
              "description": "网络掩码",
              "example": "255.255.255.0"
            },
            "gateway": {
              "type": "string",
              "format": "ipv4",
              "description": "网关地址（可为空，表示不指定网关）",
              "example": "192.168.1.1"
            },
            "gateway_int": {
              "type": "integer",
              "description": "网关地址整数表示（系统自动计算）",
              "readOnly": true,
              "example": 3232235777
            },
            "prio": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99,
              "description": "优先级（1-99，数值越小优先级越高）",
              "example": 1
            },
            "ip_type": {
              "type": "string",
              "enum": [
                "4",
                "6"
              ],
              "description": "IP类型，4为IPv4，6为IPv6",
              "example": "4"
            },
            "dst_addr_int": {
              "type": "integer",
              "description": "目的地址整数表示（系统自动计算）",
              "readOnly": true,
              "example": 3232235520
            }
          },
          "additionalProperties": false
        },
        "StaticRouteInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "interface",
            "dst_addr",
            "netmask",
            "ip_type",
            "prio"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "策略状态，yes为启用（默认），no为停用",
              "default": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "route_to_lan"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "default": ""
            },
            "interface": {
              "type": "string",
              "description": "路由接口，auto为自动选择",
              "default": "auto",
              "example": "wan1"
            },
            "dst_addr": {
              "type": "string",
              "description": "目的地址",
              "example": "192.168.2.0"
            },
            "netmask": {
              "type": "string",
              "description": "网络掩码",
              "example": "255.255.255.0"
            },
            "gateway": {
              "type": "string",
              "description": "网关地址",
              "example": "192.168.1.1"
            },
            "prio": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99,
              "description": "优先级（1-99，数值越小优先级越高）",
              "default": 1,
              "example": 1
            },
            "ip_type": {
              "type": "string",
              "enum": [
                "4",
                "6"
              ],
              "description": "IP类型，4为IPv4（默认），6为IPv6",
              "default": "4",
              "example": "4"
            }
          },
          "additionalProperties": false
        },
        "StaticRouteUpdateInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "interface",
            "dst_addr",
            "netmask",
            "ip_type",
            "prio",
            "comment",
            "gateway"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "策略状态，yes为启用（默认），no为停用",
              "default": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "route_to_lan"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "default": ""
            },
            "interface": {
              "type": "string",
              "description": "路由接口，auto为自动选择",
              "default": "auto",
              "example": "wan1"
            },
            "dst_addr": {
              "type": "string",
              "description": "目的地址",
              "example": "192.168.2.0"
            },
            "netmask": {
              "type": "string",
              "description": "网络掩码",
              "example": "255.255.255.0"
            },
            "gateway": {
              "type": "string",
              "description": "网关地址",
              "example": "192.168.1.1"
            },
            "prio": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99,
              "description": "优先级（1-99，数值越小优先级越高）",
              "default": 1,
              "example": 1
            },
            "ip_type": {
              "type": "string",
              "enum": [
                "4",
                "6"
              ],
              "description": "IP类型，4为IPv4（默认），6为IPv6",
              "default": "4",
              "example": "4"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "route/network-stream-domain.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "域名分流策略管理API",
      "version": "1.0.0",
      "description": "提供域名分流策略的完整管理功能，包括：\n- 域名分流策略的增删改查\n- 策略启用/停用管理\n- 支持源地址、域名、时间的复杂条件配置\n- 支持对象组和自定义规则组合\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "stream-domain",
        "x-displayName": "域名分流",
        "description": "域名分流策略管理和配置"
      }
    ],
    "paths": {
      "/api/v4.0/routing/domain-rules": {
        "get": {
          "tags": [
            "stream-domain"
          ],
          "summary": "获取所有域名分流策略",
          "description": "获取当前配置的所有域名分流策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listDomainRules",
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取域名分流策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/SuccessResponse"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "results": {
                            "$ref": "#/components/schemas/DomainRulesListResult"
                          }
                        }
                      }
                    ]
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "tagname": "1123",
                          "comment": "",
                          "interface": "wan1",
                          "prio": 31,
                          "domain": {
                            "object": {},
                            "custom": [
                              "www.baidu.com"
                            ]
                          },
                          "time": {
                            "object": {},
                            "custom": [
                              {
                                "comment": "",
                                "end_time": "23:59",
                                "start_time": "00:00",
                                "type": "weekly",
                                "weekdays": "1234567"
                              }
                            ]
                          },
                          "src_addr": {
                            "object": {},
                            "custom": {}
                          }
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          }
        },
        "post": {
          "tags": [
            "stream-domain"
          ],
          "summary": "添加域名分流策略",
          "description": "创建新的域名分流策略。支持基于域名的流量分流到指定接口。\n可配置源地址、域名列表、生效时间等复杂条件。\n",
          "operationId": "createDomainRule",
          "requestBody": {
            "required": true,
            "description": "域名分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "domain_rule_1",
                  "comment": "",
                  "domain": {
                    "custom": [
                      "www.baidu.com"
                    ],
                    "object": [
                      {
                        "type": 6,
                        "gp_name": "search",
                        "gid": "DOMAIN1"
                      }
                    ]
                  },
                  "interface": "wan2",
                  "prio": 31,
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:1e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      },
                      {
                        "type": 2,
                        "gp_name": "22",
                        "gid": "MACIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            }
          }
        }
      },
      "/api/v4.0/routing/domain-rules/{id}": {
        "get": {
          "tags": [
            "stream-domain"
          ],
          "summary": "获取指定域名分流策略",
          "description": "获取指定ID的域名分流策略详细信息",
          "operationId": "getDomainRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取域名分流策略信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/GetDomainRuleResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "tagname": "test33",
                          "domain": {
                            "custom": [
                              "www.baidu.com"
                            ]
                          },
                          "interface": "wan2",
                          "prio": 31,
                          "src_addr": {
                            "object": [
                              {
                                "gp_name": "11",
                                "gid": "GPIP1",
                                "type": 0
                              }
                            ],
                            "custom": [
                              "192.168.9.169",
                              "08:9b:4b:00:10:1e"
                            ]
                          },
                          "comment": "",
                          "time": {
                            "object": [
                              {
                                "gp_name": "11",
                                "gid": "GPIP1",
                                "type": 4
                              }
                            ],
                            "custom": [
                              {
                                "start_time": "00:00",
                                "weekdays": "1234567",
                                "end_time": "20:00",
                                "comment": "test11",
                                "type": "weekly"
                              }
                            ]
                          }
                        }
                      ],
                      "total": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "put": {
          "tags": [
            "stream-domain"
          ],
          "summary": "更新域名分流策略",
          "description": "完全更新指定ID的域名分流策略\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDomainRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "域名分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "domain_rule_1",
                  "comment": "",
                  "domain": {
                    "custom": [
                      "www.baidu.com"
                    ]
                  },
                  "interface": "wan2",
                  "prio": 31,
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:1e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "iKuai-Group",
                        "gid": "GPIP1"
                      },
                      {
                        "type": 2,
                        "gp_name": "iKuai-Mac",
                        "gid": "MACIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "iKuai-TimeGroup",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "patch": {
          "tags": [
            "stream-domain"
          ],
          "summary": "启用/停用域名分流策略",
          "description": "启用或停用指定ID的域名分流策略",
          "operationId": "updateDomainRuleStatus",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态，yes为启用，no为停用"
                    }
                  },
                  "example": {
                    "enabled": "no"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "delete": {
          "tags": [
            "stream-domain"
          ],
          "summary": "删除域名分流策略",
          "description": "删除指定ID的域名分流策略",
          "operationId": "deleteDomainRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功删除域名分流策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、interface、prio等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=prio>10&filter=interface==wan2\n- OR条件：filter=tagname==rule1,filter=tagname==rule2\n",
          "schema": {
            "type": "string",
            "example": "enabled==yes"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建操作返回的资源ID",
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "GetDomainRuleResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "results"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/DomainRulesListResult"
            }
          }
        },
        "DomainRulesListResult": {
          "type": "object",
          "required": [
            "data",
            "total"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/DomainRule"
              }
            },
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 2
            }
          }
        },
        "DomainRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "interface",
            "prio"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "主键ID",
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "test22"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": ""
            },
            "domain": {
              "$ref": "#/components/schemas/DomainObject"
            },
            "interface": {
              "type": "string",
              "description": "线路接口",
              "example": "wan2"
            },
            "prio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63,
              "description": "优先级（0-63，0最高）",
              "example": 31
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          }
        },
        "DomainRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "interface",
            "enabled",
            "domain",
            "prio"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用（默认），no为停用",
              "default": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "test33"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符",
              "default": ""
            },
            "domain": {
              "$ref": "#/components/schemas/DomainObjectInput"
            },
            "interface": {
              "type": "string",
              "description": "线路接口",
              "example": "wan2"
            },
            "prio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63,
              "description": "优先级（0-63，0最高）",
              "default": 31,
              "example": 31
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObjectInput"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObjectInput"
            }
          },
          "additionalProperties": false
        },
        "DomainObject": {
          "type": "object",
          "description": "域名对象",
          "properties": {
            "object": {
              "type": "object",
              "description": "域名对象组（key为对象名称）",
              "additionalProperties": true,
              "example": {}
            },
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义域名列表",
              "example": [
                "www.baidu.com"
              ]
            }
          }
        },
        "DomainObjectInput": {
          "type": "object",
          "description": "域名对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "hostname"
              },
              "description": "自定义域名列表",
              "example": [
                "www.baidu.com"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "域名对象列表"
            }
          }
        },
        "SrcAddrObject": {
          "type": "object",
          "description": "源地址对象",
          "properties": {
            "object": {
              "type": "object",
              "description": "源地址对象组（key为对象名称）",
              "additionalProperties": true,
              "example": {}
            },
            "custom": {
              "type": "object",
              "description": "自定义源地址（key-value形式）",
              "additionalProperties": true,
              "example": {}
            }
          }
        },
        "SrcAddrObjectInput": {
          "type": "object",
          "description": "源地址对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:1e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "TimeObject": {
          "type": "object",
          "description": "生效时间对象",
          "properties": {
            "object": {
              "type": "object",
              "description": "时间对象组（key为对象名称）",
              "additionalProperties": true,
              "example": {}
            },
            "custom": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeCustom"
              },
              "description": "自定义时间规则列表"
            }
          }
        },
        "TimeObjectInput": {
          "type": "object",
          "description": "生效时间对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeCustom"
              },
              "description": "自定义时间规则列表"
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "时间对象列表"
            }
          }
        },
        "TimeCustom": {
          "type": "object",
          "description": "自定义时间规则",
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "weekly",
                "date"
              ],
              "description": "时间类型，weekly为周期性，date为日期范围"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7对应周一到周日），weekly类型时必需",
              "example": "1234567"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": "test11"
            }
          }
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型 0:ipv4 1:ipv6 2:mac 3:port, 4:time, 5:protocol 6:domain",
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP12"
            }
          }
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "route/network-stream-ipport.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "端口分流策略管理API",
      "version": "1.0.0",
      "description": "提供端口分流策略的完整管理功能，包括：\n- 端口分流策略的增删改查\n- 策略启用/停用管理\n- 支持基于五元组的流量分流（源地址、目的地址、协议、源端口、目的端口）\n- 支持wan转发和lan转发两种转发方式\n- 支持地区分流和接口绑定\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "stream-ipport",
        "x-displayName": "端口分流",
        "description": "端口分流策略管理和配置"
      }
    ],
    "paths": {
      "/api/v4.0/routing/five-tuple-rules": {
        "get": {
          "tags": [
            "stream-ipport"
          ],
          "summary": "获取所有端口分流策略",
          "description": "获取当前配置的所有端口分流策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listFiveTupleRules",
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取端口分流策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/SuccessResponse"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "results": {
                            "$ref": "#/components/schemas/FiveTupleRulesListResult"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          }
        },
        "post": {
          "tags": [
            "stream-ipport"
          ],
          "summary": "添加端口分流策略",
          "description": "创建新的端口分流策略。支持基于五元组（源地址、目的地址、协议、源端口、目的端口）的流量分流。\n可配置wan转发或lan转发，支持负载均衡和地区分流。\n",
          "operationId": "createFiveTupleRule",
          "requestBody": {
            "required": true,
            "description": "端口分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FiveTupleRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "port_rule_1",
                  "type": 0,
                  "interface": "wan2",
                  "protocol": "tcp",
                  "prio": 31,
                  "mode": 0,
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:6e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "添加端口分流策略的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateFiveTupleRuleResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            }
          }
        }
      },
      "/api/v4.0/routing/five-tuple-rules/{id}": {
        "get": {
          "tags": [
            "stream-ipport"
          ],
          "summary": "获取指定端口分流策略",
          "description": "获取指定ID的端口分流策略详细信息",
          "operationId": "getFiveTupleRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "端口分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取端口分流策略信息",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/SuccessResponse"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "data": {
                            "$ref": "#/components/schemas/FiveTupleRule"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "put": {
          "tags": [
            "stream-ipport"
          ],
          "summary": "更新端口分流策略",
          "description": "完全更新指定ID的端口分流策略\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateFiveTupleRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "端口分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "端口分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FiveTupleRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "port_rule_1",
                  "comment": "",
                  "type": 0,
                  "nexthop": "",
                  "interface": "wan2",
                  "protocol": "tcp",
                  "prio": 31,
                  "mode": 0,
                  "iface_band": 0,
                  "src_addr_inv": 0,
                  "dst_addr_inv": 0,
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:6e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "dst_addr": {},
                  "src_port": {},
                  "dst_port": {},
                  "dst_type": 0,
                  "area_code": "",
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "patch": {
          "tags": [
            "stream-ipport"
          ],
          "summary": "启用/停用端口分流策略",
          "description": "启用或停用指定ID的端口分流策略",
          "operationId": "updateFiveTupleRuleStatus",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "端口分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态，yes为启用，no为停用"
                    }
                  },
                  "example": {
                    "enabled": "no"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "delete": {
          "tags": [
            "stream-ipport"
          ],
          "summary": "删除端口分流策略",
          "description": "删除指定ID的端口分流策略",
          "operationId": "deleteFiveTupleRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "端口分流策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功删除端口分流策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、interface、prio等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=prio>10&filter=type==0\n- OR条件：filter=tagname==rule1,filter=tagname==rule2\n",
          "schema": {
            "type": "string",
            "example": "enabled==yes"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "CreateFiveTupleRuleResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "添加端口分流策略的业务响应。\n返回 HTTP 200 时，仍需通过 `code` 字段判断业务是否成功。\n"
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示创建成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建操作返回的资源ID，成功时返回",
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "FiveTupleRulesListResult": {
          "type": "object",
          "required": [
            "data",
            "total"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/FiveTupleRule"
              }
            },
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            }
          }
        },
        "FiveTupleRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "type"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "主键ID",
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "10"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": ""
            },
            "type": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "转发方式，0:wan转发, 1:lan转发",
              "example": 0
            },
            "nexthop": {
              "type": "string",
              "description": "下一跳路由网关（type=1 lan转发时必填）",
              "example": ""
            },
            "interface": {
              "type": "string",
              "description": "路由接口（wan转发生效）",
              "example": "wan2"
            },
            "mode": {
              "type": "integer",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                6
              ],
              "description": "负载均衡方式 0: 新建连接 1:sip 2:sip+sport 3:sip+dip 4:sip+dip+dport 5:sip+sport+dip+dport 6:主备模式",
              "example": 0
            },
            "prio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63,
              "description": "优先级（0-63，0最高）",
              "example": 31
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObject"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/DstAddrObject"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp",
                "icmp"
              ],
              "description": "协议类型",
              "example": "tcp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "dst_type": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "目的类型，0:目的地址, 1:目的地区",
              "example": 0
            },
            "area_code": {
              "type": "string",
              "description": "地区代码",
              "example": ""
            },
            "iface_band": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "是否绑定接口，0:不绑定, 1:绑定",
              "example": 0
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          }
        },
        "FiveTupleRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "type",
            "src_addr_inv",
            "dst_addr_inv",
            "enabled",
            "interface",
            "mode",
            "prio",
            "src_addr",
            "dst_addr",
            "protocol",
            "src_port",
            "dst_port",
            "iface_band",
            "time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用（默认），no为停用",
              "default": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "port_rule_1"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符",
              "default": ""
            },
            "type": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "转发方式，0:wan转发（默认）, 1:lan转发",
              "default": 0
            },
            "nexthop": {
              "type": "string",
              "description": "下一跳路由网关（lan转发生效）",
              "default": ""
            },
            "interface": {
              "type": "string",
              "description": "路由接口（wan转发生效）",
              "example": "wan2"
            },
            "mode": {
              "type": "integer",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                6
              ],
              "description": "负载均衡方式 0: 新建连接 1:sip 2:sip+sport 3:sip+dip 4:sip+dip+dport 5:sip+sport+dip+dport 6:主备模式",
              "default": 0,
              "example": 0
            },
            "prio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63,
              "description": "优先级（0-63，0最高）",
              "default": 31,
              "example": 31
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObjectInput"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/DstAddrObjectInput"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp",
                "icmp"
              ],
              "description": "协议类型",
              "example": "tcp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObjectInput"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObjectInput"
            },
            "dst_type": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "目的类型，0:目的地址（默认）, 1:目的地区",
              "default": 0
            },
            "area_code": {
              "type": "string",
              "description": "地区代码",
              "default": ""
            },
            "iface_band": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "是否绑定接口，0:不绑定（默认）, 1:绑定",
              "default": 0
            },
            "time": {
              "$ref": "#/components/schemas/TimeObjectInput"
            },
            "src_addr_inv": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "源地址取反，0:不取反（默认），1:取反",
              "default": 0
            },
            "dst_addr_inv": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "目的地址取反，0:不取反（默认），1:取反",
              "default": 0
            }
          },
          "additionalProperties": false
        },
        "SrcAddrObject": {
          "type": "object",
          "description": "源地址对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:6e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "SrcAddrObjectInput": {
          "type": "object",
          "description": "源地址对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:6e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "DstAddrObject": {
          "type": "object",
          "description": "目的地址对象"
        },
        "DstAddrObjectInput": {
          "type": "object",
          "description": "目的地址对象输入"
        },
        "PortObject": {
          "type": "object",
          "description": "端口对象"
        },
        "PortObjectInput": {
          "type": "object",
          "description": "端口对象输入"
        },
        "TimeObject": {
          "type": "object",
          "description": "生效时间对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeCustom"
              },
              "description": "自定义时间规则列表"
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "时间对象列表"
            }
          }
        },
        "TimeObjectInput": {
          "type": "object",
          "description": "生效时间对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeCustom"
              },
              "description": "自定义时间规则列表"
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "时间对象列表"
            }
          }
        },
        "TimeCustom": {
          "type": "object",
          "description": "自定义时间规则",
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "weekly",
                "date"
              ],
              "description": "时间类型，weekly为周期性，date为日期范围"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7对应周一到周日），weekly类型时必需",
              "example": "1234567"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": "test11"
            }
          }
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型 0:ipv4 1:ipv6 2:mac 3:port, 4:time, 5:protocol 6:domain",
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          }
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "route/network-stream-l7.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "协议分流策略管理API",
      "version": "1.0.0",
      "description": "提供协议分流策略的完整管理功能，包括：\n- 协议分流策略的增删改查\n- 策略启用/停用管理\n- 支持基于应用协议的流量分流\n- 支持源地址、应用协议、生效时间的复杂条件配置\n- 支持对象组和自定义规则组合\n- 支持接口绑定功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "stream-proto",
        "x-displayName": "协议分流",
        "description": "协议分流策略管理和配置"
      }
    ],
    "paths": {
      "/api/v4.0/routing/app-protocols": {
        "get": {
          "tags": [
            "stream-proto"
          ],
          "summary": "获取所有协议分流策略",
          "description": "获取当前配置的所有协议分流策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listAppProtocols",
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取协议分流策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          }
        },
        "post": {
          "tags": [
            "stream-proto"
          ],
          "summary": "添加协议分流策略",
          "description": "创建新的协议分流策略。支持基于应用协议的流量分流到指定接口。\n可配置源地址、应用协议列表、生效时间等复杂条件。\n",
          "operationId": "createAppProtocol",
          "requestBody": {
            "required": true,
            "description": "协议分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppProtocolInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "test3",
                  "comment": "",
                  "interface": "wan2",
                  "mode": 0,
                  "prio": 1,
                  "iface_band": 0,
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:1e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "app_proto": {
                    "custom": [
                      "其它HTTP",
                      "文件传输",
                      "DNS",
                      "Baidu"
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            }
          }
        }
      },
      "/api/v4.0/routing/app-protocols/{id}": {
        "get": {
          "tags": [
            "stream-proto"
          ],
          "summary": "获取指定协议分流策略",
          "description": "获取指定ID的协议分流策略详细信息",
          "operationId": "getAppProtocol",
          "parameters": [
            {
              "$ref": "#/components/parameters/appProtocolIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取协议分流策略信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "put": {
          "tags": [
            "stream-proto"
          ],
          "summary": "更新协议分流策略",
          "description": "完全更新指定ID的协议分流策略\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateAppProtocol",
          "parameters": [
            {
              "$ref": "#/components/parameters/appProtocolIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "协议分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppProtocolInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "test3",
                  "comment": "",
                  "interface": "wan2",
                  "mode": 0,
                  "prio": 1,
                  "iface_band": 0,
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:1e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "iKuai-Group",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "app_proto": {
                    "custom": [
                      "其它HTTP",
                      "文件传输",
                      "DNS",
                      "Baidu"
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "iKuai-TimeGroup",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "patch": {
          "tags": [
            "stream-proto"
          ],
          "summary": "启用/停用协议分流策略",
          "description": "启用或停用指定ID的协议分流策略",
          "operationId": "updateAppProtocolStatus",
          "parameters": [
            {
              "$ref": "#/components/parameters/appProtocolIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态，yes为启用，no为停用"
                    }
                  },
                  "example": {
                    "enabled": "no"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "delete": {
          "tags": [
            "stream-proto"
          ],
          "summary": "删除协议分流策略",
          "description": "删除指定ID的协议分流策略",
          "operationId": "deleteAppProtocol",
          "parameters": [
            {
              "$ref": "#/components/parameters/appProtocolIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功删除协议分流策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "appProtocolIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "协议分流策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、interface、prio等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=prio>10&filter=interface==wan2\n- OR条件：filter=tagname==rule1,filter=tagname==rule2\n",
          "schema": {
            "type": "string",
            "example": "enabled==yes"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建操作返回的资源ID",
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "AppProtocolListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AppProtocol"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocolResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AppProtocol"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocol": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "interface",
            "prio",
            "comment",
            "mode",
            "iface_band"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "主键ID",
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "test3"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": ""
            },
            "interface": {
              "type": "string",
              "description": "线路接口",
              "example": "wan2"
            },
            "mode": {
              "type": "integer",
              "enum": [
                0,
                1,
                3
              ],
              "description": "负载方式 0: 新建连接 1:sip 3:sip+dip",
              "example": 0
            },
            "prio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63,
              "description": "优先级（0-63，0最高）",
              "example": 1
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObject"
            },
            "app_proto": {
              "$ref": "#/components/schemas/AppProtoObject"
            },
            "iface_band": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "是否绑定接口，0:不绑定, 1:绑定",
              "example": 0
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "AppProtocolInput": {
          "type": "object",
          "required": [
            "tagname",
            "enabled",
            "interface",
            "prio",
            "mode",
            "app_proto",
            "iface_band"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用（默认），no为停用",
              "default": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "test3"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符",
              "default": ""
            },
            "interface": {
              "type": "string",
              "description": "线路接口",
              "example": "wan2"
            },
            "mode": {
              "type": "integer",
              "enum": [
                0,
                1,
                3
              ],
              "description": "负载方式 0: 新建连接 1:sip 3:sip+dip",
              "default": 0,
              "example": 1
            },
            "prio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 63,
              "description": "优先级（0-63，0最高）",
              "example": 1
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObjectInput"
            },
            "app_proto": {
              "$ref": "#/components/schemas/AppProtoObjectInput"
            },
            "iface_band": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "是否绑定接口，0:不绑定（默认）, 1:绑定",
              "default": 0
            },
            "time": {
              "$ref": "#/components/schemas/TimeObjectInput"
            }
          },
          "additionalProperties": false
        },
        "SrcAddrObject": {
          "type": "object",
          "description": "源地址对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:1e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "SrcAddrObjectInput": {
          "type": "object",
          "description": "源地址对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:1e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "AppProtoObject": {
          "type": "object",
          "description": "应用协议对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义应用协议列表",
              "example": [
                "其它HTTP",
                "文件传输",
                "DNS",
                "Baidu"
              ]
            }
          }
        },
        "AppProtoObjectInput": {
          "type": "object",
          "description": "应用协议对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义应用协议列表",
              "example": [
                "其它HTTP",
                "文件传输",
                "DNS",
                "Baidu"
              ]
            }
          }
        },
        "TimeObject": {
          "type": "object",
          "description": "生效时间对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeCustom"
              },
              "description": "自定义时间规则列表"
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "时间对象列表"
            }
          }
        },
        "TimeObjectInput": {
          "type": "object",
          "description": "生效时间对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TimeCustom"
              },
              "description": "自定义时间规则列表"
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "时间对象列表"
            }
          }
        },
        "TimeCustom": {
          "type": "object",
          "description": "自定义时间规则",
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "weekly",
                "date"
              ],
              "description": "时间类型，weekly为周期性，date为日期范围"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7对应周一到周日），weekly类型时必需",
              "example": "1234567"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": "test11"
            }
          }
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型 0:ipv4 1:ipv6 2:mac 3:port, 4:time, 5:protocol 6:domain",
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          }
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "route/network-stream-load.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "多线负载分流策略管理API",
      "version": "1.0.0",
      "description": "提供多线负载分流策略的完整管理功能，包括：\n- 多线负载分流策略的增删改查\n- 策略启用/停用管理\n- 支持多种负载均衡模式\n- 支持运营商线路配置和权重调整\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "stream-load",
        "x-displayName": "多线负载分流",
        "description": "多线负载分流策略管理和配置"
      }
    ],
    "paths": {
      "/api/v4.0/routing/load-balance-rules": {
        "get": {
          "tags": [
            "stream-load"
          ],
          "summary": "获取所有多线负载分流策略",
          "description": "获取当前配置的所有多线负载分流策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listLoadBalanceRules",
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取多线负载分流策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/LoadBalanceRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          }
        },
        "post": {
          "tags": [
            "stream-load"
          ],
          "summary": "添加多线负载分流策略",
          "description": "创建新的多线负载分流策略。支持多种负载均衡模式和线路权重配置。\n可配置不同的运营商线路和负载权重。\n",
          "operationId": "createLoadBalanceRule",
          "requestBody": {
            "required": true,
            "description": "多线负载分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoadBalanceRuleInput"
                },
                "example": {
                  "mode": 0,
                  "comment": "111",
                  "isp_name": "all",
                  "interface": "wan2",
                  "weight": "1",
                  "enabled": "yes",
                  "tagname": "11"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            }
          }
        }
      },
      "/api/v4.0/routing/load-balance-rules/{id}": {
        "get": {
          "tags": [
            "stream-load"
          ],
          "summary": "获取指定多线负载分流策略",
          "description": "获取指定ID的多线负载分流策略详细信息",
          "operationId": "getLoadBalanceRule",
          "parameters": [
            {
              "$ref": "#/components/parameters/loadBalanceRuleIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取多线负载分流策略信息",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/LoadBalanceRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "put": {
          "tags": [
            "stream-load"
          ],
          "summary": "更新多线负载分流策略",
          "description": "完全更新指定ID的多线负载分流策略\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateLoadBalanceRule",
          "parameters": [
            {
              "$ref": "#/components/parameters/loadBalanceRuleIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "多线负载分流策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoadBalanceRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "patch": {
          "tags": [
            "stream-load"
          ],
          "summary": "启用/停用多线负载分流策略",
          "description": "启用或停用指定ID的多线负载分流策略",
          "operationId": "updateLoadBalanceRuleStatus",
          "parameters": [
            {
              "$ref": "#/components/parameters/loadBalanceRuleIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态，yes为启用，no为停用"
                    }
                  },
                  "example": {
                    "enabled": "no"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "delete": {
          "tags": [
            "stream-load"
          ],
          "summary": "删除多线负载分流策略",
          "description": "删除指定ID的多线负载分流策略",
          "operationId": "deleteLoadBalanceRule",
          "parameters": [
            {
              "$ref": "#/components/parameters/loadBalanceRuleIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功删除多线负载分流策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "loadBalanceRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "多线负载分流策略ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、interface、mode等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=mode>0&filter=interface==wan2\n- OR条件：filter=tagname==rule1,filter=tagname==rule2\n",
          "schema": {
            "type": "string",
            "example": "enabled==yes"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建操作返回的资源ID",
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "LoadBalanceRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LoadBalanceRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "LoadBalanceRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LoadBalanceRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "LoadBalanceRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "interface",
            "mode"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "主键ID",
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": "111"
            },
            "interface": {
              "type": "string",
              "description": "线路名称",
              "example": "wan2"
            },
            "weight": {
              "type": "string",
              "description": "负载比重（1-10）",
              "example": "1"
            },
            "mode": {
              "type": "integer",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                6,
                7
              ],
              "description": "负载模式(0:源IP+目的IP+目的端口,1:源IP+目的IP,2:新建连接数,3:实时流量,4:实时连接数,6:源IP,7:源IP+源端口)",
              "example": 0
            },
            "isp_name": {
              "type": "string",
              "description": "运营商名称，内置值：all（全部）、chinatelecom（电信）、chinaunicom（联通）、chinamobile（移动）、chinacernet（教育网），或自定义运营商名称",
              "example": "all"
            }
          },
          "additionalProperties": false
        },
        "LoadBalanceRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "interface",
            "mode",
            "enabled",
            "weight",
            "isp_name"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用（默认），no为停用",
              "default": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符",
              "default": "",
              "example": "111"
            },
            "interface": {
              "type": "string",
              "description": "线路名称",
              "example": "wan2"
            },
            "weight": {
              "type": "string",
              "description": "负载比重（1-10）",
              "pattern": "^([1-9]|10)$",
              "default": "1",
              "example": "1"
            },
            "mode": {
              "type": "integer",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                6,
                7
              ],
              "description": "负载模式(0:源IP+目的IP+目的端口,1:源IP+目的IP,2:新建连接数,3:实时流量,4:实时连接数,6:源IP,7:源IP+源端口)",
              "example": 0
            },
            "isp_name": {
              "type": "string",
              "description": "运营商名称，内置值：all（全部）、chinatelecom（电信）、chinaunicom（联通）、chinamobile（移动）、chinacernet（教育网），或自定义运营商名称",
              "default": "",
              "example": "all"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "route/network-stream-updown.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "上下行分离策略管理API",
      "version": "1.0.0",
      "description": "提供上下行分离策略的完整管理功能，包括：\n- 上下行分离策略的增删改查\n- 策略启用/停用管理\n- 支持基于五元组的流量分离（源地址、目的地址、协议、源端口、目的端口）\n- 支持配置上行接口和下行接口\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "tags": [
      {
        "name": "stream-updown",
        "x-displayName": "上下行分离",
        "description": "上下行分离策略管理和配置"
      }
    ],
    "paths": {
      "/api/v4.0/routing/updown": {
        "get": {
          "tags": [
            "stream-updown"
          ],
          "summary": "获取所有上下行分离策略",
          "description": "获取当前配置的所有上下行分离策略列表。\n支持分页、过滤和排序功能。\n",
          "operationId": "listUpDownRules",
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取上下行分离策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/SuccessResponse"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "results": {
                            "$ref": "#/components/schemas/UpDownRulesListResult"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          }
        },
        "post": {
          "tags": [
            "stream-updown"
          ],
          "summary": "添加上下行分离策略",
          "description": "创建新的上下行分离策略。支持基于五元组（源地址、目的地址、协议、源端口、目的端口）的流量分离。\n可配置上行接口和下行接口，实现流量的上下行分离。\n",
          "operationId": "createUpDownRule",
          "requestBody": {
            "required": true,
            "description": "上下行分离策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpDownRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "iKuai-UpDown",
                  "upiface": "wan1",
                  "downiface": "wan2",
                  "protocol": "tcp",
                  "src_addr": {
                    "custom": [
                      "192.168.9.169"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "iKuai-Group",
                        "gid": "GPIP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            }
          }
        }
      },
      "/api/v4.0/routing/updown/{id}": {
        "get": {
          "tags": [
            "stream-updown"
          ],
          "summary": "获取指定上下行分离策略",
          "description": "获取指定ID的上下行分离策略详细信息",
          "operationId": "getUpDownRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "上下行分离策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取上下行分离策略信息",
              "content": {
                "application/json": {
                  "schema": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/SuccessResponse"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "data": {
                            "$ref": "#/components/schemas/UpDownRule"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "put": {
          "tags": [
            "stream-updown"
          ],
          "summary": "更新上下行分离策略",
          "description": "完全更新指定ID的上下行分离策略\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateUpDownRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "上下行分离策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "上下行分离策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpDownRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "iKuai-UpDown",
                  "comment": "",
                  "upiface": "wan1",
                  "downiface": "wan2",
                  "protocol": "tcp",
                  "src_addr": {
                    "custom": [
                      "192.168.9.169"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "iKuai-Group",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "src_port": {
                    "custom": [
                      "80",
                      "443"
                    ],
                    "object": [
                      {
                        "type": 3,
                        "gp_name": "iKuai-PortGroup",
                        "gid": "PORTGP1"
                      }
                    ]
                  },
                  "dst_port": {
                    "custom": [
                      "8080"
                    ],
                    "object": [
                      {
                        "type": 3,
                        "gp_name": "iKuai-DstPort",
                        "gid": "PORTGP2"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "patch": {
          "tags": [
            "stream-updown"
          ],
          "summary": "启用/停用上下行分离策略",
          "description": "启用或停用指定ID的上下行分离策略",
          "operationId": "updateUpDownRuleStatus",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "上下行分离策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "策略启用状态，yes为启用，no为停用"
                    }
                  },
                  "example": {
                    "enabled": "no"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        },
        "delete": {
          "tags": [
            "stream-updown"
          ],
          "summary": "删除上下行分离策略",
          "description": "删除指定ID的上下行分离策略",
          "operationId": "deleteUpDownRule",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "上下行分离策略ID",
              "schema": {
                "type": "integer",
                "format": "int64",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功删除上下行分离策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            }
          }
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、upiface、downiface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- ==（等于）\n- !=（不等于）\n- >（大于）\n- >=（大于等于）\n- <（小于）\n- <=（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=upiface==wan1&filter=protocol==tcp\n- OR条件：filter=tagname==rule1,filter=tagname==rule2\n",
          "schema": {
            "type": "string",
            "example": "enabled==yes"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          }
        },
        "CreateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "创建操作返回的资源ID",
              "example": 1
            }
          }
        },
        "UpDownRulesListResult": {
          "type": "object",
          "required": [
            "data",
            "total"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/UpDownRule"
              }
            },
            "total": {
              "type": "integer",
              "description": "总记录数",
              "example": 1
            }
          }
        },
        "UpDownRule": {
          "type": "object",
          "required": [
            "id",
            "tagname",
            "enabled",
            "upiface",
            "downiface"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "主键ID",
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "iKuai-UpDown"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "iKuai备注"
            },
            "upiface": {
              "type": "string",
              "description": "上行接口（WAN口）",
              "example": "wan1"
            },
            "downiface": {
              "type": "string",
              "description": "下行接口（WAN口）",
              "example": "wan2"
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObject"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/DstAddrObject"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp",
                "icmp"
              ],
              "description": "协议类型",
              "example": "tcp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            }
          }
        },
        "UpDownRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "upiface",
            "downiface",
            "enabled"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "规则状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15,
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "iKuai-UpDown"
            },
            "comment": {
              "type": "string",
              "maxLength": 64,
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "default": "",
              "example": "iKuai备注"
            },
            "upiface": {
              "type": "string",
              "description": "上行接口（WAN口）",
              "example": "wan1"
            },
            "downiface": {
              "type": "string",
              "description": "下行接口（WAN口）",
              "example": "wan2"
            },
            "src_addr": {
              "$ref": "#/components/schemas/SrcAddrObjectInput"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/DstAddrObjectInput"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "any",
                "tcp",
                "udp",
                "tcp+udp",
                "icmp"
              ],
              "description": "协议类型",
              "default": "any",
              "example": "tcp"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObjectInput"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObjectInput"
            }
          },
          "additionalProperties": false
        },
        "SrcAddrObject": {
          "type": "object",
          "description": "源地址对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:6e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "SrcAddrObjectInput": {
          "type": "object",
          "description": "源地址对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义源地址列表（支持IP和MAC地址）",
              "example": [
                "192.168.9.169",
                "08:9b:4b:00:10:6e"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "DstAddrObject": {
          "type": "object",
          "description": "目的地址对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义目的地址列表",
              "example": [
                "10.0.0.1"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "DstAddrObjectInput": {
          "type": "object",
          "description": "目的地址对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义目的地址列表",
              "example": [
                "10.0.0.1"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "网络对象列表"
            }
          }
        },
        "PortObject": {
          "type": "object",
          "description": "端口对象",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义端口列表",
              "example": [
                "80",
                "443",
                "8080"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "端口对象列表"
            }
          }
        },
        "PortObjectInput": {
          "type": "object",
          "description": "端口对象输入",
          "properties": {
            "custom": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "自定义端口列表",
              "example": [
                "80",
                "443",
                "8080"
              ]
            },
            "object": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              },
              "description": "端口对象列表"
            }
          }
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型 0:ipv4 1:ipv6 2:mac 3:port",
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "iKuai-Group"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          }
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ]
  },
  "vpn/auth-ikev2-server.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "IKEv2/IPSec服务器管理API",
      "version": "1.0.0",
      "summary": "IKEv2/IPSec服务器配置管理",
      "description": "提供IKEv2/IPSec服务器的配置管理功能，包括：\n- IKEv2/IPSec服务基础配置\n- 认证方式配置（secret/mschapv2）\n- 地址池和DNS配置\n- 证书和密钥管理\n- 连接控制和安全设置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/ikev2/services": {
        "get": {
          "summary": "获取IKEv2/IPSec服务器配置",
          "description": "获取当前IKEv2/IPSec服务器的配置信息。\n包括服务状态、认证方式、网络配置、证书等。\n",
          "operationId": "getIkev2ServerConfig",
          "tags": [
            "ikev2-server"
          ],
          "responses": {
            "200": {
              "description": "成功获取IKEv2/IPSec配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ikev2ServerConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "enabled": "no",
                          "name": "",
                          "authby": "mschapv2",
                          "addrpool": "10.6.1.0/24",
                          "keyexchange": "ikev2",
                          "aggressive": "yes",
                          "secret": "verystrong",
                          "leftid": "",
                          "rightid": "",
                          "dns1": "114.114.114.114",
                          "dns2": "119.29.29.29",
                          "share_deny": 0,
                          "mtu": 1400,
                          "privatekey": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsikev2PrivateKeyDemoData11111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFikev2PrivateKeyDemoPayload4444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@",
                          "leftcert": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOikev2LeftCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgSUtFdjIg@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA4MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGTAXBgNVBAMMEHZwbi5leGFtcGxlLmNvbTCCASIw@DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKikev2LeftCertDemoData11111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AgMBAAGjUDBOMB0GA1UdDgQWBBRikev2LeftCertDemo111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaaaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新IKEv2/IPSec服务器配置",
          "description": "更新IKEv2/IPSec服务器的配置信息。\n支持更新认证方式、网络配置、证书、安全设置等。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateIkev2ServerConfig",
          "tags": [
            "ikev2-server"
          ],
          "requestBody": {
            "required": true,
            "description": "IKEv2/IPSec服务器配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ikev2ServerConfigInput"
                },
                "example": {
                  "enabled": "yes",
                  "authby": "mschapv2",
                  "addrpool": "10.6.1.0/24",
                  "secret": "verystrong",
                  "leftid": "vpn.example.com",
                  "rightid": "",
                  "dns1": "114.114.114.114",
                  "dns2": "119.29.29.29",
                  "share_deny": 0,
                  "mtu": 1400,
                  "privatekey": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsikev2PrivateKeyDemoData11111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFikev2PrivateKeyDemoPayload4444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@",
                  "leftcert": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOikev2LeftCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgSUtFdjIg@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA4MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGTAXBgNVBAMMEHZwbi5leGFtcGxlLmNvbTCCASIw@DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKikev2LeftCertDemoData11111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AgMBAAGjUDBOMB0GA1UdDgQWBBRikev2LeftCertDemo111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaaaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "Ikev2ServerConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "authby",
            "addrpool",
            "keyexchange",
            "aggressive",
            "secret",
            "dns1",
            "dns2",
            "share_deny",
            "mtu",
            "leftid",
            "rightid",
            "privatekey",
            "leftcert"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "name": {
              "type": "string",
              "description": "服务名称（唯一）",
              "example": ""
            },
            "authby": {
              "type": "string",
              "description": "认证方式：secret-预共享密钥，mschapv2-EAP-MSCHAPv2",
              "enum": [
                "secret",
                "mschapv2"
              ],
              "example": "mschapv2"
            },
            "addrpool": {
              "type": "string",
              "description": "客户端地址池，CIDR网络地址格式（如 10.6.1.0/24），必须为网络地址而非主机地址",
              "example": "10.6.1.0/24"
            },
            "keyexchange": {
              "type": "string",
              "description": "密钥交换协议",
              "enum": [
                "ikev2"
              ],
              "example": "ikev2"
            },
            "aggressive": {
              "type": "string",
              "description": "是否开启激进模式",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥（authby=secret时必填，1-64个字符，）",
              "maxLength": 64,
              "example": "verystrong"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识，长度为 1-64 个字符。\n当 authby=mschapv2 时，建议配置为服务端证书对应的标识值。\n对于非 iKuai 路由客户端对接场景，必须使用以域名签发的服务器证书，并将本地标识配置为与该证书主题名称（CN）或主体备用名称（SAN）一致的完整域名（FQDN）。\n若本地标识与证书对应域名不一致，可能导致客户端身份校验失败或连接建立失败。\n",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpn.example.com"
            },
            "rightid": {
              "type": "string",
              "description": "对端标识（允许为空，最多100个字符）",
              "maxLength": 100,
              "example": ""
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "example": "119.29.29.29"
            },
            "share_deny": {
              "type": "integer",
              "description": "共享数超出处理动作",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "privatekey": {
              "type": "string",
              "description": "私钥，authby=mschapv2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsikev2PrivateKeyDemoData11111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFikev2PrivateKeyDemoPayload4444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "leftcert": {
              "type": "string",
              "description": "本地证书，authby=mschapv2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOikev2LeftCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgSUtFdjIg@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA4MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGTAXBgNVBAMMEHZwbi5leGFtcGxlLmNvbTCCASIw@DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKikev2LeftCertDemoData11111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AgMBAAGjUDBOMB0GA1UdDgQWBBRikev2LeftCertDemo111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaaaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            }
          },
          "additionalProperties": false
        },
        "Ikev2ServerConfigInput": {
          "type": "object",
          "description": "PUT全量修改，所有字段均为required；不修改的字段请传空值或原值",
          "required": [
            "id",
            "enabled",
            "authby",
            "addrpool",
            "secret",
            "leftid",
            "rightid",
            "dns1",
            "dns2",
            "share_deny",
            "mtu",
            "privatekey",
            "leftcert"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID，必须传入",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "authby": {
              "type": "string",
              "description": "认证方式：secret-预共享密钥，mschapv2-EAP-MSCHAPv2",
              "enum": [
                "secret",
                "mschapv2"
              ],
              "default": "mschapv2",
              "example": "mschapv2"
            },
            "addrpool": {
              "type": "string",
              "description": "客户端地址池，CIDR网络地址格式（如 10.6.1.0/24），必须为网络地址而非主机地址",
              "default": "10.6.1.0/24",
              "example": "10.6.1.0/24"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥（authby=secret时必填，1-64个字符，）",
              "maxLength": 64,
              "example": "verystrong"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识，authby=mschapv2 时必填，长度为 1-64 个字符。\n对于非 iKuai 路由客户端对接场景，必须使用以域名签发的服务器证书，并将本地标识配置为与该证书主题名称（CN）或主体备用名称（SAN）一致的完整域名（FQDN）。\n若本地标识与证书对应域名不一致，可能导致客户端身份校验失败或连接建立失败。\n",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpn.example.com"
            },
            "rightid": {
              "type": "string",
              "description": "对端标识（1-100个字符，）",
              "maxLength": 100,
              "example": ""
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "default": "114.114.114.114",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "default": "119.29.29.29",
              "example": "119.29.29.29"
            },
            "share_deny": {
              "type": "integer",
              "description": "共享数超出处理动作",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "privatekey": {
              "type": "string",
              "description": "私钥，authby=mschapv2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsikev2PrivateKeyDemoData11111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFikev2PrivateKeyDemoPayload4444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "leftcert": {
              "type": "string",
              "description": "本地证书，authby=mschapv2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOikev2LeftCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgSUtFdjIg@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA4MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGTAXBgNVBAMMEHZwbi5leGFtcGxlLmNvbTCCASIw@DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKikev2LeftCertDemoData11111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AgMBAAGjUDBOMB0GA1UdDgQWBBRikev2LeftCertDemo111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaaaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            }
          },
          "additionalProperties": false
        },
        "Ikev2ServerConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Ikev2ServerConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "ikev2-server",
        "x-displayName": "IKEv2/IPSec服务器管理",
        "description": "IKEv2/IPSec服务器的配置管理，包括认证、网络、证书等设置"
      }
    ]
  },
  "vpn/auth-l2tp.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "L2TP服务器管理API",
      "version": "1.0.0",
      "summary": "L2TP服务器配置管理",
      "description": "提供L2TP服务器的配置管理功能，包括：\n- L2TP服务基础配置\n- IPSec预共享密钥配置\n- 地址池和DNS配置\n- 网络连接控制\n- 安全和性能设置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/l2tp/services": {
        "get": {
          "summary": "获取L2TP服务器配置",
          "description": "获取当前L2TP服务器的配置信息。\n包括服务状态、网络配置、IPSec设置等。\n",
          "operationId": "getL2tpServerConfig",
          "tags": [
            "l2tp-server"
          ],
          "responses": {
            "200": {
              "description": "成功获取L2TP配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/L2tpServerConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "enabled": "no",
                          "server_ip": "10.1.0.1",
                          "server_port": 1701,
                          "addr_pool": "10.1.0.2-10.1.0.254",
                          "dns1": "114.114.114.114",
                          "force_ipsec": 0,
                          "dns2": "119.29.29.29",
                          "rightid": "",
                          "mtu": 1400,
                          "mru": 1400,
                          "ipsec_secret": "",
                          "leftid": "",
                          "id": 1
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新L2TP服务器配置",
          "description": "更新L2TP服务器的配置信息。\n支持更新网络配置、IPSec设置、安全参数等。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateL2tpServerConfig",
          "tags": [
            "l2tp-server"
          ],
          "requestBody": {
            "required": true,
            "description": "L2TP服务器配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/L2tpServerConfigInput"
                },
                "example": {
                  "enabled": "yes",
                  "server_ip": "10.1.0.1",
                  "server_port": 1701,
                  "addr_pool": "10.1.0.2-10.1.0.254",
                  "dns1": "114.114.114.114",
                  "dns2": "119.29.29.29",
                  "mtu": 1400,
                  "mru": 1400,
                  "ipsec_secret": "mysecret",
                  "leftid": "vpn.example.com",
                  "rightid": "",
                  "force_ipsec": 1
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "L2tpServerConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "server_ip",
            "server_port",
            "addr_pool",
            "dns1",
            "dns2",
            "mtu",
            "mru",
            "force_ipsec"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "server_ip": {
              "type": "string",
              "description": "服务器地址",
              "example": "10.1.0.1"
            },
            "server_port": {
              "type": "integer",
              "description": "服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1701,
              "example": 1701
            },
            "addr_pool": {
              "type": "string",
              "description": "客户端地址池",
              "example": "10.1.0.2-10.1.0.254"
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "example": "119.29.29.29"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "example": 1400
            },
            "ipsec_secret": {
              "type": "string",
              "description": "IPSec预共享密钥",
              "maxLength": 64,
              "example": ""
            },
            "leftid": {
              "type": "string",
              "description": "IPSec本地标识（允许为空，最多100个字符）",
              "maxLength": 100,
              "example": ""
            },
            "rightid": {
              "type": "string",
              "description": "IPSec对端标识（允许为空，最多100个字符）",
              "maxLength": 100,
              "example": ""
            },
            "force_ipsec": {
              "type": "integer",
              "description": "禁止非加密的连接，0为允许，1为禁止",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "L2tpServerConfigInput": {
          "type": "object",
          "required": [
            "enabled",
            "server_ip",
            "server_port",
            "addr_pool",
            "dns1",
            "dns2",
            "mtu",
            "mru",
            "force_ipsec"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "server_ip": {
              "type": "string",
              "description": "服务器地址，必须为合法IP",
              "default": "10.1.0.1",
              "example": "10.1.0.1"
            },
            "server_port": {
              "type": "integer",
              "description": "服务器端口，不传时默认1701",
              "minimum": 1,
              "maximum": 65535,
              "default": 1701,
              "example": 1701
            },
            "addr_pool": {
              "type": "string",
              "description": "客户端地址池",
              "default": "10.1.0.2-10.1.0.254",
              "example": "10.1.0.2-10.1.0.254"
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "default": "114.114.114.114",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "default": "119.29.29.29",
              "example": "119.29.29.29"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "ipsec_secret": {
              "type": "string",
              "description": "IPSec预共享密钥",
              "maxLength": 64,
              "example": "mysecret"
            },
            "leftid": {
              "type": "string",
              "description": "IPSec本地标识（允许为空，最多100个字符）",
              "maxLength": 100,
              "example": "vpn.example.com"
            },
            "rightid": {
              "type": "string",
              "description": "IPSec对端标识（允许为空，最多100个字符）",
              "maxLength": 100,
              "example": ""
            },
            "force_ipsec": {
              "type": "integer",
              "description": "禁止非加密的连接，0为允许，1为禁止",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "L2tpServerConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/L2tpServerConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "l2tp-server",
        "x-displayName": "L2TP服务器管理",
        "description": "L2TP服务器的配置管理，包括IPSec设置和网络配置"
      }
    ]
  },
  "vpn/auth-openvpn.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "OpenVPN服务器管理API",
      "version": "1.0.0",
      "summary": "OpenVPN服务器配置管理",
      "description": "提供OpenVPN服务器的配置管理功能，包括：\n- OpenVPN服务基础配置\n- 协议和加密配置\n- 证书和认证配置\n- 网络和路由配置\n- 客户端推送配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/openvpn/services": {
        "get": {
          "summary": "获取OpenVPN服务器配置",
          "description": "获取当前OpenVPN服务器的配置信息。\n包括服务状态、协议设置、加密配置、证书等。\n",
          "operationId": "getOpenVpnServerConfig",
          "tags": [
            "openvpn-server"
          ],
          "responses": {
            "200": {
              "description": "成功获取OpenVPN配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/OpenVpnServerConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "enabled": "no",
                          "proto": "udp",
                          "port": "1194",
                          "subnet": "10.7.7.0",
                          "mask": "255.255.255.0",
                          "tun_mtu": "1400",
                          "cipher": "BF-CBC",
                          "auth": "",
                          "comp_lzo": "1",
                          "dev_type": "tun",
                          "topology": "subnet",
                          "method": 0,
                          "tls_auth": "-----BEGIN#OpenVPN#Static#key#V1-----@2048#bit#OpenVPN#static#key@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@-----END#OpenVPN#Static#key#V1-----@",
                          "ca": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@",
                          "cert": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOserverCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgU2VydmVy@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tc2VydmVyLWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCserverCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBSserverCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@",
                          "key": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsserverPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFserverPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@",
                          "push_gateway": "0",
                          "push_route": "10.7.0.0/16",
                          "push_route_comment": "",
                          "push_dns": "",
                          "extra_config": "",
                          "status": 0
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新OpenVPN服务器配置",
          "description": "更新OpenVPN服务器的配置信息。\n支持更新协议设置、加密配置、证书、网络配置等。\n`tls_auth` 仅 method=1 或 2 时必填；`auth`、`push_gateway`、`push_dns` 若 GET 回显存在则原样透传，否则可不传。\n",
          "operationId": "updateOpenVpnServerConfig",
          "tags": [
            "openvpn-server"
          ],
          "requestBody": {
            "required": true,
            "description": "OpenVPN服务器配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenVpnServerConfigInput"
                },
                "example": {
                  "enabled": "yes",
                  "proto": "udp",
                  "port": "1194",
                  "subnet": "10.7.7.0",
                  "mask": "255.255.255.0",
                  "tun_mtu": "1400",
                  "cipher": "BF-CBC",
                  "comp_lzo": "1",
                  "dev_type": "tun",
                  "topology": "subnet",
                  "method": 0,
                  "tls_auth": "-----BEGIN#OpenVPN#Static#key#V1-----@2048#bit#OpenVPN#static#key@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@-----END#OpenVPN#Static#key#V1-----@",
                  "ca": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@",
                  "cert": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOserverCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgU2VydmVy@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tc2VydmVyLWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCserverCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBSserverCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@",
                  "key": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsserverPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFserverPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@",
                  "push_gateway": "0",
                  "push_route": "10.7.0.0/16",
                  "push_dns": "8.8.8.8",
                  "extra_config": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "OpenVpnServerConfig": {
          "type": "object",
          "required": [
            "enabled",
            "proto",
            "port",
            "subnet",
            "mask",
            "tun_mtu",
            "cipher",
            "auth",
            "comp_lzo",
            "dev_type",
            "topology",
            "method",
            "tls_auth",
            "ca",
            "cert",
            "key",
            "push_gateway",
            "push_route",
            "push_route_comment",
            "push_dns",
            "extra_config"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "proto": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "udp",
                "tcp"
              ],
              "example": "udp"
            },
            "port": {
              "type": "string",
              "description": "服务端口",
              "example": "1194"
            },
            "subnet": {
              "type": "string",
              "description": "VPN网段",
              "example": "10.7.7.0"
            },
            "mask": {
              "type": "string",
              "description": "网段掩码",
              "example": "255.255.255.0"
            },
            "tun_mtu": {
              "type": "string",
              "description": "隧道MTU，576-1500",
              "example": "1400"
            },
            "cipher": {
              "type": "string",
              "description": "加密算法（最多64个字符）",
              "maxLength": 64,
              "example": "BF-CBC"
            },
            "auth": {
              "type": "string",
              "description": "认证算法",
              "example": "SHA256"
            },
            "comp_lzo": {
              "type": "string",
              "description": "LZO压缩",
              "enum": [
                "0",
                "1"
              ],
              "example": "1"
            },
            "dev_type": {
              "type": "string",
              "description": "设备类型",
              "enum": [
                "tun",
                "tap"
              ],
              "example": "tun"
            },
            "topology": {
              "type": "string",
              "description": "网络拓扑",
              "enum": [
                "net30",
                "subnet"
              ],
              "example": "subnet"
            },
            "method": {
              "type": "integer",
              "description": "认证方法：0-账号认证，1-tls-auth，2-tls-crypt",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "tls_auth": {
              "type": "string",
              "description": "TLS 认证密钥，method=1 或 method=2 时必填，使用转义后的单行 OpenVPN Static key 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到合法的 OpenVPN Static key 内容。\n",
              "example": "-----BEGIN#OpenVPN#Static#key#V1-----@2048#bit#OpenVPN#static#key@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@-----END#OpenVPN#Static#key#V1-----@"
            },
            "ca": {
              "type": "string",
              "description": "CA证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@"
            },
            "cert": {
              "type": "string",
              "description": "服务器证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOserverCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgU2VydmVy@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tc2VydmVyLWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCserverCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBSserverCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            },
            "key": {
              "type": "string",
              "description": "服务器私钥，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsserverPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFserverPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "push_gateway": {
              "type": "string",
              "description": "推送网关",
              "example": "0"
            },
            "push_route": {
              "type": "string",
              "description": "推送路由",
              "example": "10.7.0.0/16"
            },
            "push_route_comment": {
              "type": "string",
              "description": "路由备注（最多64个字符）",
              "maxLength": 64,
              "example": ""
            },
            "push_dns": {
              "type": "string",
              "description": "推送DNS",
              "example": "8.8.8.8"
            },
            "extra_config": {
              "type": "string",
              "description": "额外配置",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "OpenVpnServerConfigInput": {
          "type": "object",
          "required": [
            "enabled",
            "proto",
            "port",
            "subnet",
            "mask",
            "tun_mtu",
            "cipher",
            "comp_lzo",
            "dev_type",
            "topology",
            "method",
            "ca",
            "cert",
            "key"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "proto": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "udp",
                "tcp"
              ],
              "example": "udp"
            },
            "port": {
              "type": "string",
              "description": "服务端口，1-65535",
              "default": "1194",
              "example": "1194"
            },
            "subnet": {
              "type": "string",
              "description": "VPN网段，必须为合法IP",
              "example": "10.7.7.0"
            },
            "mask": {
              "type": "string",
              "description": "网段掩码，必须为合法IP",
              "example": "255.255.255.0"
            },
            "tun_mtu": {
              "type": "string",
              "description": "隧道MTU，576-1500",
              "default": "1400",
              "example": "1400"
            },
            "cipher": {
              "type": "string",
              "description": "加密算法（最多64个字符）",
              "maxLength": 64,
              "default": "BF-CBC",
              "example": "BF-CBC"
            },
            "comp_lzo": {
              "type": "string",
              "description": "LZO压缩",
              "enum": [
                "0",
                "1"
              ],
              "default": "1",
              "example": "1"
            },
            "dev_type": {
              "type": "string",
              "description": "设备类型",
              "enum": [
                "tun",
                "tap"
              ],
              "default": "tun",
              "example": "tun"
            },
            "topology": {
              "type": "string",
              "description": "网络拓扑",
              "enum": [
                "net30",
                "subnet"
              ],
              "default": "subnet",
              "example": "subnet"
            },
            "method": {
              "type": "integer",
              "description": "认证方法：0-账号认证，1-tls-auth，2-tls-crypt",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "tls_auth": {
              "type": "string",
              "description": "TLS 认证密钥，method=1 或 method=2 时必填，使用转义后的单行 OpenVPN Static key 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到合法的 OpenVPN Static key 内容。\n",
              "example": "-----BEGIN#OpenVPN#Static#key#V1-----@2048#bit#OpenVPN#static#key@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@11111111111111111111111111111111@-----END#OpenVPN#Static#key#V1-----@"
            },
            "ca": {
              "type": "string",
              "description": "CA证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@"
            },
            "cert": {
              "type": "string",
              "description": "服务器证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOserverCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgU2VydmVy@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tc2VydmVyLWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCserverCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBSserverCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAaabbbbccccdddd@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            },
            "key": {
              "type": "string",
              "description": "服务器私钥，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsserverPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFserverPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "push_gateway": {
              "type": "string",
              "description": "推送网关",
              "default": "0",
              "example": "0"
            },
            "push_route": {
              "type": "string",
              "description": "推送路由",
              "example": "10.7.0.0/16"
            },
            "push_route_comment": {
              "type": "string",
              "description": "路由备注（最多64个字符）",
              "maxLength": 64,
              "example": ""
            },
            "push_dns": {
              "type": "string",
              "description": "推送DNS",
              "example": "8.8.8.8"
            },
            "extra_config": {
              "type": "string",
              "description": "额外配置",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "OpenVpnServerConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OpenVpnServerConfig"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "openvpn-server",
        "x-displayName": "OpenVPN服务器管理",
        "description": "OpenVPN服务器的配置管理，包括协议、加密、证书和网络配置"
      }
    ]
  },
  "vpn/auth-pptp.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "PPTP服务器管理API",
      "version": "1.0.0",
      "summary": "PPTP服务器配置管理",
      "description": "提供PPTP服务器的配置管理功能，包括：\n- PPTP服务基础配置\n- 服务器地址和端口配置\n- 地址池和DNS配置\n- MPPE加密协议配置\n- 网络传输优化设置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/pptp/services": {
        "get": {
          "summary": "获取PPTP服务器配置",
          "description": "获取当前PPTP服务器的配置信息。\n包括服务状态、网络配置、DNS设置、加密协议等。\n",
          "operationId": "getPptpServerConfig",
          "tags": [
            "pptp-server"
          ],
          "responses": {
            "200": {
              "description": "成功获取PPTP配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PptpServerConfigResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新PPTP服务器配置",
          "description": "更新PPTP服务器的配置信息。\n支持更新网络配置、DNS设置、加密协议、传输参数等。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePptpServerConfig",
          "tags": [
            "pptp-server"
          ],
          "requestBody": {
            "required": true,
            "description": "PPTP服务器配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PptpServerConfigInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如唯一性冲突）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "PptpServerConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "dns1",
            "dns2",
            "addr_pool",
            "open_mppe",
            "server_ip",
            "server_port",
            "mtu",
            "mru"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "example": "119.29.29.29"
            },
            "addr_pool": {
              "type": "string",
              "description": "客户端地址池",
              "example": "10.0.0.2-10.0.0.254"
            },
            "open_mppe": {
              "type": "integer",
              "description": "MPPE加密协议，0-关闭，1-强制开启，2-自动协商",
              "enum": [
                0,
                1,
                2
              ],
              "example": 2
            },
            "server_ip": {
              "type": "string",
              "description": "服务器地址，必须为合法IP",
              "example": "10.0.0.1"
            },
            "server_port": {
              "type": "integer",
              "description": "服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1723,
              "example": 1723
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            }
          },
          "additionalProperties": false
        },
        "PptpServerConfigInput": {
          "type": "object",
          "required": [
            "enabled",
            "dns1",
            "dns2",
            "addr_pool",
            "open_mppe",
            "server_ip",
            "server_port",
            "mtu",
            "mru"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "default": "114.114.114.114",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "default": "119.29.29.29",
              "example": "119.29.29.29"
            },
            "addr_pool": {
              "type": "string",
              "description": "客户端地址池",
              "default": "10.0.0.2-10.0.0.254",
              "example": "10.0.0.2-10.0.0.254"
            },
            "open_mppe": {
              "type": "integer",
              "description": "MPPE加密协议，0-关闭，1-强制开启，2-自动协商",
              "enum": [
                0,
                1,
                2
              ],
              "default": 2,
              "example": 2
            },
            "server_ip": {
              "type": "string",
              "description": "服务器地址，必须为合法IP",
              "default": "10.0.0.1",
              "example": "10.0.0.1"
            },
            "server_port": {
              "type": "integer",
              "description": "服务器端口，不传时默认1723",
              "minimum": 1,
              "maximum": 65535,
              "default": 1723,
              "example": 1723
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            }
          },
          "additionalProperties": false
        },
        "PptpServerConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PptpServerConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "pptp-server",
        "x-displayName": "PPTP服务器管理",
        "description": "PPTP服务器的配置管理，包括网络配置和MPPE加密设置"
      }
    ]
  },
  "vpn/network-ikev2.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "IKEv2 VPN客户端管理API",
      "version": "1.0.0",
      "summary": "IKEv2 VPN客户端的完整管理功能",
      "description": "提供IKEv2 VPN客户端的完整管理功能，包括：\n- IKEv2客户端的创建、查询、更新、删除\n- 客户端启用/停用状态控制\n- 支持分页、模糊匹配和过滤功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/ikev2/clients": {
        "get": {
          "summary": "获取IKEv2客户端列表",
          "description": "获取所有IKEv2客户端配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listIkev2Clients",
          "tags": [
            "ikev2-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，支持name、comment、remote_addr、interface等字段",
              "schema": {
                "type": "string",
                "enum": [
                  "name",
                  "comment",
                  "remote_addr",
                  "interface",
                  "leftid",
                  "rightid",
                  "username"
                ],
                "example": "name"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=name==test1,name==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IKEv2客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ikev2ClientListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建IKEv2客户端",
          "description": "添加新的IKEv2 VPN客户端配置。\n支持MSCHAPv2和Secret认证方式。\n",
          "operationId": "createIkev2Client",
          "tags": [
            "ikev2-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "IKEv2客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ikev2ClientInput"
                },
                "example": {
                  "enabled": "yes",
                  "name": "ikev2_client_001",
                  "comment": "主办公室VPN连接",
                  "remote_addr": "vpn.example.com",
                  "interface": "wan1",
                  "authby": "mschapv2",
                  "secret": "verystrongkey",
                  "leftid": "localikev2",
                  "rightid": "remoteikev2",
                  "username": "vpnuser",
                  "passwd": "vpnpassword",
                  "check_link_mode": 2,
                  "check_link_host": "www.baidu.com"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/ikev2/clients/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/ikev2ClientIdParam"
          }
        ],
        "get": {
          "summary": "获取指定IKEv2客户端",
          "description": "根据ID获取单个IKEv2客户端的详细配置信息。\n需要提供有效的客户端ID。\n",
          "operationId": "getIkev2Client",
          "tags": [
            "ikev2-clients"
          ],
          "responses": {
            "200": {
              "description": "成功获取IKEv2客户端详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/Ikev2ClientResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新IKEv2客户端",
          "description": "完全更新现有的IKEv2客户端配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateIkev2Client",
          "tags": [
            "ikev2-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的IKEv2客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ikev2ClientUpdateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用IKEv2客户端",
          "description": "部分更新现有的IKEv2客户端配置。\n主要用于启用/停用客户端状态。\n",
          "operationId": "patchIkev2Client",
          "tags": [
            "ikev2-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "客户端启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除IKEv2客户端",
          "description": "删除指定的IKEv2客户端配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteIkev2Client",
          "tags": [
            "ikev2-clients"
          ],
          "responses": {
            "200": {
              "description": "IKEv2客户端删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "ikev2ClientIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "IKEv2客户端ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、remote_addr、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "Ikev2ClientResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Ikev2Client"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Ikev2ClientListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Ikev2Client"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "Ikev2Client": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "comment",
            "remote_addr",
            "interface",
            "authby",
            "aggressive",
            "secret",
            "leftid",
            "rightid",
            "username",
            "passwd",
            "check_link_mode",
            "check_link_host"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端名称",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "ikev2_client"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9][\\u4e00-\\u9fa5a-zA-Z0-9_-]*$",
              "example": "主办公室VPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "远端服务器地址",
              "format": "hostname",
              "example": "vpn.example.com"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 576,
              "maximum": 1500,
              "default": 1400,
              "example": 1400
            },
            "authby": {
              "type": "string",
              "enum": [
                "secret",
                "mschapv2"
              ],
              "description": "认证方式",
              "default": "mschapv2",
              "example": "mschapv2"
            },
            "aggressive": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "激进模式",
              "default": "yes",
              "example": "yes"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥（authby=secret 时必填）",
              "minLength": 1,
              "maxLength": 64,
              "example": "verystrongkey"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识符",
              "pattern": "^[a-zA-Z0-9@.-]+$",
              "minLength": 1,
              "maxLength": 100,
              "example": "localikev2"
            },
            "rightid": {
              "type": "string",
              "description": "远端标识符",
              "pattern": "^[a-zA-Z0-9@.-]+$",
              "maxLength": 100,
              "example": "remoteikev2"
            },
            "username": {
              "type": "string",
              "description": "用户名（authby=mschapv2 时必填，1-64字符）",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（authby=mschapv2 时必填，1-64字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "minimum": 1,
              "maximum": 6,
              "default": 2,
              "example": 2
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "format": "hostname",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "ip_addr": {
              "type": "string",
              "description": "分配的IP地址",
              "readOnly": true,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "Ikev2ClientInput": {
          "type": "object",
          "required": [
            "enabled",
            "name",
            "remote_addr",
            "interface",
            "authby",
            "leftid",
            "check_link_mode",
            "check_link_host"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端名称",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 15,
              "example": "ikev2_client"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\u4e00-\\u9fa5a-zA-Z0-9][\\u4e00-\\u9fa5a-zA-Z0-9_-]*$",
              "example": "主办公室VPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "远端服务器地址",
              "format": "hostname",
              "example": "vpn.example.com"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 576,
              "maximum": 1500,
              "default": 1400,
              "example": 1400
            },
            "authby": {
              "type": "string",
              "enum": [
                "secret",
                "mschapv2"
              ],
              "description": "认证方式",
              "default": "mschapv2",
              "example": "mschapv2"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥（authby=secret 时必填）",
              "minLength": 1,
              "maxLength": 64,
              "example": "verystrongkey"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识符",
              "pattern": "^[a-zA-Z0-9@.-]+$",
              "minLength": 1,
              "maxLength": 100,
              "example": "localikev2"
            },
            "rightid": {
              "type": "string",
              "description": "远端标识符",
              "pattern": "^[a-zA-Z0-9@.-]+$",
              "maxLength": 100,
              "example": "remoteikev2"
            },
            "username": {
              "type": "string",
              "description": "用户名（authby=mschapv2 时必填，1-64字符）",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（authby=mschapv2 时必填，1-64字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "minimum": 1,
              "maximum": 6,
              "default": 2,
              "example": 2
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "format": "hostname",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            }
          },
          "additionalProperties": false
        },
        "Ikev2ClientUpdateInput": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "remote_addr",
            "interface",
            "authby",
            "leftid",
            "check_link_mode",
            "check_link_host"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端名称，必须以iked开头，仅支持英文、数字、下划线，总长度5-15字符，不可重复",
              "pattern": "^iked[a-zA-Z0-9_]*$",
              "minLength": 5,
              "maxLength": 15,
              "example": "ikedclient"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "example": "主办公室VPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "远端服务器地址",
              "format": "hostname",
              "example": "vpn.example.com"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "authby": {
              "type": "string",
              "enum": [
                "secret",
                "mschapv2"
              ],
              "description": "认证方式",
              "default": "mschapv2",
              "example": "mschapv2"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥（authby=secret 时必填）",
              "minLength": 1,
              "maxLength": 64,
              "example": "verystrongkey"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识符",
              "minLength": 1,
              "maxLength": 100,
              "example": "localikev2"
            },
            "rightid": {
              "type": "string",
              "description": "远端标识符",
              "maxLength": 100,
              "example": "remoteikev2"
            },
            "username": {
              "type": "string",
              "description": "用户名（authby=mschapv2 时必填，1-64字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（authby=mschapv2 时必填，1-64字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "minimum": 1,
              "maximum": 6,
              "default": 1,
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "format": "hostname",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "ikev2-clients",
        "x-displayName": "IKEv2 VPN客户端",
        "description": "IKEv2 VPN客户端的管理和配置"
      }
    ]
  },
  "vpn/network-ipsec-vpn.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "IPSEC VPN客户端管理API",
      "version": "1.0.0",
      "summary": "IPSEC VPN客户端的完整管理功能",
      "description": "提供IPSEC VPN客户端的完整管理功能，包括：\n- IPSEC客户端的创建、查询、更新、删除\n- 客户端启用/停用状态控制\n- 支持分页、模糊匹配和过滤功能\n- 支持导入导出\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4.0",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/ipsec/clients": {
        "get": {
          "summary": "获取IPSEC客户端列表",
          "description": "获取所有IPSEC客户端配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listIpsecClients",
          "tags": [
            "IPSEC VPN客户端"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，与 pattern 参数联合使用",
              "schema": {
                "type": "string",
                "enum": [
                  "name",
                  "comment",
                  "remote_addr",
                  "interface",
                  "authby",
                  "leftsubnet",
                  "rightsubnet",
                  "leftid",
                  "rightid"
                ],
                "example": "name"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容，与 key 参数联合使用",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=name==test1,name==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取IPSEC客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IpsecClientListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建IPSEC客户端",
          "description": "添加新的IPSEC VPN客户端配置。\n\n**条件必填字段：**\n- `aggressive`：当 keyexchange=ikev1 时必填，枚举值 0|1\n- `secret`：当 authby=secret 时必填\n- `leftid`、`rightid`、`privatekey`、`leftcert`、`rightcert`：当 authby=pubkey 时必填\n- `dpddelay`、`dpdtimeout`：当 dpdaction 不为 none 时必填\n- `remote_addr`：当 leftid 和 rightid 不同时存在时必填\n",
          "operationId": "createIpsecClient",
          "tags": [
            "IPSEC VPN客户端"
          ],
          "requestBody": {
            "required": true,
            "description": "IPSEC客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpsecClientInput"
                },
                "example": {
                  "name": "ipsecoffice",
                  "comment": "主办公室IPSec_VPN连接",
                  "remote_addr": "vpn.ikuai.cn",
                  "authby": "secret",
                  "leftsubnet": "192.168.1.0/24",
                  "rightsubnet": "192.168.99.0/24",
                  "interface": "wan1",
                  "enabled": "yes",
                  "keyexchange": "ikev2",
                  "aggressive": "0",
                  "ikelifetime": 3,
                  "ike_enc": "aes256",
                  "ike_auth": "sha256",
                  "ike_dh": "modp2048",
                  "secret": "sharedsecret123",
                  "lifetime": 1,
                  "esp_enc": "aes256",
                  "esp_auth": "sha256",
                  "dpdaction": "none",
                  "compress": "0"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "IPSEC客户端创建成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/ipsec/clients/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/ipsecClientIdParam"
          }
        ],
        "get": {
          "summary": "获取指定IPSEC客户端",
          "description": "根据ID获取单个IPSEC客户端的详细配置信息。\n",
          "operationId": "getIpsecClient",
          "tags": [
            "IPSEC VPN客户端"
          ],
          "responses": {
            "200": {
              "description": "成功获取IPSEC客户端详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/IpsecClientResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新IPSEC客户端",
          "description": "完全更新现有的IPSEC客户端配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateIpsecClient",
          "tags": [
            "IPSEC VPN客户端"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的IPSEC客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IpsecClientUpdateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用IPSEC客户端",
          "description": "部分更新现有的IPSEC客户端配置。\n主要用于启用/停用客户端状态。\n",
          "operationId": "patchIpsecClient",
          "tags": [
            "IPSEC VPN客户端"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "客户端启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除IPSEC客户端",
          "description": "删除指定的IPSEC客户端配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteIpsecClient",
          "tags": [
            "IPSEC VPN客户端"
          ],
          "responses": {
            "200": {
              "description": "IPSEC客户端删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "ipsecClientIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "IPSEC客户端ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、remote_addr、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "IpsecClientResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/IpsecClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "IpsecClientListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/IpsecClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "IpsecClient": {
          "type": "object",
          "required": [
            "id",
            "name",
            "comment",
            "remote_addr",
            "authby",
            "leftsubnet",
            "rightsubnet",
            "interface",
            "enabled",
            "keyexchange",
            "aggressive",
            "keyingtries",
            "ikelifetime",
            "ike_enc",
            "ike_auth",
            "ike_dh",
            "secret",
            "leftid",
            "rightid",
            "privatekey",
            "leftcert",
            "rightcert",
            "lifetime",
            "esp_enc",
            "esp_auth",
            "dpdaction",
            "dpddelay",
            "dpdtimeout",
            "compress",
            "status"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "name": {
              "type": "string",
              "description": "客户端名称，必须以ipsec开头，仅支持英文、数字、下划线，总长度6-16字符",
              "pattern": "^ipsec[a-zA-Z0-9_]*$",
              "minLength": 6,
              "maxLength": 16,
              "example": "ipsecoffice"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "主办公室IPSec_VPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "远端服务器地址，支持IPv4/IPv6/域名",
              "example": "vpn.ikuai.cn"
            },
            "authby": {
              "type": "string",
              "enum": [
                "secret",
                "pubkey"
              ],
              "description": "认证方式，secret为预共享密钥，pubkey为证书认证",
              "example": "secret"
            },
            "leftsubnet": {
              "type": "string",
              "description": "本地子网，格式为IP/掩码",
              "example": "192.168.1.0/24"
            },
            "rightsubnet": {
              "type": "string",
              "description": "远端子网，支持多个IP/掩码，逗号分隔，不可重复",
              "example": "192.168.99.0/24"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto表示自动选择，或指定WAN接口名称",
              "example": "wan1"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "keyexchange": {
              "type": "string",
              "enum": [
                "ikev1",
                "ikev2"
              ],
              "description": "密钥交换协议版本",
              "example": "ikev2"
            },
            "aggressive": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "激进模式，0为关闭，1为开启（仅keyexchange=ikev1时有效）",
              "example": "0"
            },
            "keyingtries": {
              "type": "integer",
              "description": "重试次数，0表示无限重试",
              "minimum": 0,
              "example": 3
            },
            "ikelifetime": {
              "type": "integer",
              "description": "IKE密钥生命周期（小时）",
              "minimum": 1,
              "maximum": 72,
              "example": 3
            },
            "ike_enc": {
              "type": "string",
              "enum": [
                "",
                "aes128",
                "aes192",
                "aes256",
                "3des",
                "des"
              ],
              "description": "IKE加密算法，留空表示使用默认算法组合",
              "example": "aes256"
            },
            "ike_auth": {
              "type": "string",
              "enum": [
                "",
                "md5",
                "sha1",
                "sha256",
                "sha512"
              ],
              "description": "IKE认证算法，留空表示使用默认算法组合",
              "example": "sha256"
            },
            "ike_dh": {
              "type": "string",
              "enum": [
                "",
                "modp768",
                "modp1024",
                "modp1536",
                "modp2048",
                "modp3072",
                "modp4096"
              ],
              "description": "IKE DH组，留空表示使用默认DH组",
              "example": "modp2048"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥，authby=secret时必填，最大64字符",
              "maxLength": 64,
              "example": "sharedsecret123"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识符，authby=pubkey时必填，最大100字符",
              "maxLength": 100,
              "example": "localgateway"
            },
            "rightid": {
              "type": "string",
              "description": "对方标识符，authby=pubkey时必填，最大100字符",
              "maxLength": 100,
              "example": "remotegateway"
            },
            "privatekey": {
              "type": "string",
              "description": "私钥内容，authby=pubkey时必填",
              "example": ""
            },
            "leftcert": {
              "type": "string",
              "description": "本地证书内容，authby=pubkey时必填",
              "example": ""
            },
            "rightcert": {
              "type": "string",
              "description": "远端证书内容，authby=pubkey时必填",
              "example": ""
            },
            "lifetime": {
              "type": "integer",
              "description": "IPSec SA生命周期（小时）",
              "minimum": 1,
              "maximum": 72,
              "example": 1
            },
            "esp_enc": {
              "type": "string",
              "enum": [
                "",
                "aes128",
                "aes192",
                "aes256",
                "3des",
                "des"
              ],
              "description": "ESP加密算法，留空表示使用默认算法组合",
              "example": "aes256"
            },
            "esp_auth": {
              "type": "string",
              "enum": [
                "",
                "md5",
                "sha1",
                "sha256",
                "sha512"
              ],
              "description": "ESP认证算法，留空表示使用默认算法组合",
              "example": "sha256"
            },
            "dpdaction": {
              "type": "string",
              "enum": [
                "none",
                "clear",
                "hold",
                "restart"
              ],
              "description": "DPD操作，none表示不启用DPD",
              "example": "none"
            },
            "dpddelay": {
              "type": "integer",
              "description": "DPD检测间隔（秒），dpdaction不为none时必填，范围5-300",
              "minimum": 5,
              "maximum": 300,
              "example": 30
            },
            "dpdtimeout": {
              "type": "integer",
              "description": "DPD超时时间（秒），dpdaction不为none时必填",
              "minimum": 60,
              "maximum": 600,
              "example": 150
            },
            "compress": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "数据压缩，0为关闭，1为开启",
              "example": "0"
            },
            "status": {
              "type": "integer",
              "description": "连接状态，0=已停用，1=已连接，2=连接中",
              "enum": [
                0,
                1,
                2
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "IpsecClientInput": {
          "type": "object",
          "required": [
            "enabled",
            "name",
            "leftsubnet",
            "rightsubnet",
            "interface",
            "keyexchange",
            "authby",
            "ikelifetime",
            "lifetime",
            "dpdaction",
            "compress"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "客户端名称，必须以ipsec开头，仅支持英文、数字、下划线，总长度6-16字符，不可重复",
              "pattern": "^ipsec[a-zA-Z0-9_]*$",
              "minLength": 6,
              "maxLength": 16,
              "example": "ipsecoffice"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "主办公室IPSec_VPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "远端服务器地址，支持IPv4/IPv6/域名",
              "example": "vpn.ikuai.cn"
            },
            "authby": {
              "type": "string",
              "enum": [
                "secret",
                "pubkey"
              ],
              "description": "认证方式，secret为预共享密钥，pubkey为证书认证",
              "example": "secret"
            },
            "leftsubnet": {
              "type": "string",
              "description": "本地子网，格式为IP/掩码",
              "example": "192.168.1.0/24"
            },
            "rightsubnet": {
              "type": "string",
              "description": "远端子网，支持多个IP/掩码，逗号分隔，不可重复；IKEv1模式下不支持多子网",
              "example": "192.168.99.0/24"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto表示自动选择，或指定WAN接口名称",
              "example": "wan1"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "keyexchange": {
              "type": "string",
              "enum": [
                "ikev1",
                "ikev2"
              ],
              "description": "密钥交换协议版本",
              "example": "ikev2"
            },
            "aggressive": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "激进模式，0为关闭，1为开启；当 keyexchange=ikev1 时必填",
              "example": "0"
            },
            "ikelifetime": {
              "type": "integer",
              "description": "IKE密钥生命周期（小时）",
              "minimum": 1,
              "maximum": 72,
              "example": 3
            },
            "ike_enc": {
              "type": "string",
              "enum": [
                "",
                "aes128",
                "aes192",
                "aes256",
                "3des",
                "des"
              ],
              "description": "IKE加密算法，留空表示使用默认算法组合",
              "example": "aes256"
            },
            "ike_auth": {
              "type": "string",
              "enum": [
                "",
                "md5",
                "sha1",
                "sha256",
                "sha512"
              ],
              "description": "IKE认证算法，留空表示使用默认算法组合",
              "example": "sha256"
            },
            "ike_dh": {
              "type": "string",
              "enum": [
                "",
                "modp768",
                "modp1024",
                "modp1536",
                "modp2048",
                "modp3072",
                "modp4096"
              ],
              "description": "IKE DH组，留空表示使用默认DH组",
              "example": "modp2048"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥，authby=secret时必填，最大64字符",
              "maxLength": 64,
              "example": "sharedsecret123"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识符，authby=pubkey时必填，最大100字符",
              "maxLength": 100,
              "example": "localgateway"
            },
            "rightid": {
              "type": "string",
              "description": "对方标识符，authby=pubkey时必填，最大100字符",
              "maxLength": 100,
              "example": "remotegateway"
            },
            "privatekey": {
              "type": "string",
              "description": "私钥内容，authby=pubkey时必填",
              "example": ""
            },
            "leftcert": {
              "type": "string",
              "description": "本地证书内容，authby=pubkey时必填",
              "example": ""
            },
            "rightcert": {
              "type": "string",
              "description": "远端证书内容，authby=pubkey时必填",
              "example": ""
            },
            "lifetime": {
              "type": "integer",
              "description": "IPSec SA生命周期（小时）",
              "minimum": 1,
              "maximum": 72,
              "example": 1
            },
            "esp_enc": {
              "type": "string",
              "enum": [
                "",
                "aes128",
                "aes192",
                "aes256",
                "3des",
                "des"
              ],
              "description": "ESP加密算法，留空表示使用默认算法组合",
              "example": "aes256"
            },
            "esp_auth": {
              "type": "string",
              "enum": [
                "",
                "md5",
                "sha1",
                "sha256",
                "sha512"
              ],
              "description": "ESP认证算法，留空表示使用默认算法组合",
              "example": "sha256"
            },
            "dpdaction": {
              "type": "string",
              "enum": [
                "none",
                "clear",
                "hold",
                "restart"
              ],
              "description": "DPD操作，none表示不启用DPD",
              "example": "none"
            },
            "dpddelay": {
              "type": "integer",
              "description": "DPD检测间隔（秒），dpdaction不为none时必填，范围5-300",
              "minimum": 5,
              "maximum": 300,
              "example": 30
            },
            "dpdtimeout": {
              "type": "integer",
              "description": "DPD超时时间（秒），dpdaction不为none时必填",
              "minimum": 60,
              "maximum": 600,
              "example": 150
            },
            "compress": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "数据压缩，0为关闭，1为开启",
              "example": "0"
            }
          },
          "additionalProperties": false
        },
        "IpsecClientUpdateInput": {
          "type": "object",
          "required": [
            "id",
            "name",
            "comment",
            "remote_addr",
            "leftsubnet",
            "rightsubnet",
            "interface",
            "enabled",
            "keyexchange",
            "aggressive",
            "ikelifetime",
            "ike_enc",
            "ike_auth",
            "ike_dh",
            "authby",
            "secret",
            "leftid",
            "rightid",
            "privatekey",
            "leftcert",
            "rightcert",
            "lifetime",
            "esp_enc",
            "esp_auth",
            "compress",
            "dpdaction",
            "dpddelay",
            "dpdtimeout"
          ],
          "description": "**条件字段说明（全量修改时仍需传入，不适用时传空值）：**\n- `remote_addr`：leftid 和 rightid 不同时存在时必填；leftid 和 rightid 均有值时可传空值\n- `aggressive`：keyexchange=ikev1 时生效，ikev2 时传 \"0\"\n- `secret`：authby=secret 时必填；authby=pubkey 时传空值\n- `leftid`、`rightid`、`privatekey`、`leftcert`、`rightcert`：authby=pubkey 时必填；否则传空值\n- `dpddelay`、`dpdtimeout`：dpdaction 不为 none 时生效；dpdaction=none 时传 0\n",
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "name": {
              "type": "string",
              "description": "客户端名称，必须以ipsec开头，仅支持英文、数字、下划线，总长度6-16字符，不可重复",
              "pattern": "^ipsec[a-zA-Z0-9_]*$",
              "minLength": 6,
              "maxLength": 16,
              "example": "ipsecoffice"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "主办公室IPSec_VPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "远端服务器地址，支持IPv4/IPv6/域名",
              "example": "vpn.ikuai.cn"
            },
            "authby": {
              "type": "string",
              "enum": [
                "secret",
                "pubkey"
              ],
              "description": "认证方式，secret为预共享密钥，pubkey为证书认证",
              "example": "secret"
            },
            "leftsubnet": {
              "type": "string",
              "description": "本地子网，格式为IPv4/掩码",
              "example": "192.168.1.0/24"
            },
            "rightsubnet": {
              "type": "string",
              "description": "远端子网，支持多个IPv4/掩码，逗号分隔，不可重复；IKEv1模式下不支持多子网",
              "example": "192.168.99.0/24"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto表示自动选择，或指定WAN接口名称",
              "example": "wan1"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "keyexchange": {
              "type": "string",
              "enum": [
                "ikev1",
                "ikev2"
              ],
              "description": "密钥交换协议版本",
              "example": "ikev2"
            },
            "aggressive": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "激进模式，0为关闭，1为开启；keyexchange=ikev1 时生效",
              "example": "0"
            },
            "ikelifetime": {
              "type": "integer",
              "description": "IKE密钥生命周期（小时）",
              "minimum": 1,
              "maximum": 72,
              "example": 3
            },
            "ike_enc": {
              "type": "string",
              "enum": [
                "",
                "aes128",
                "aes192",
                "aes256",
                "3des",
                "des"
              ],
              "description": "IKE加密算法，留空表示使用默认算法组合",
              "example": "aes256"
            },
            "ike_auth": {
              "type": "string",
              "enum": [
                "",
                "md5",
                "sha1",
                "sha256",
                "sha512"
              ],
              "description": "IKE认证算法，留空表示使用默认算法组合",
              "example": "sha256"
            },
            "ike_dh": {
              "type": "string",
              "enum": [
                "",
                "modp768",
                "modp1024",
                "modp1536",
                "modp2048",
                "modp3072",
                "modp4096"
              ],
              "description": "IKE DH组，留空表示使用默认DH组",
              "example": "modp2048"
            },
            "secret": {
              "type": "string",
              "description": "预共享密钥，authby=secret时必填，最大64字符；authby=pubkey时传空值",
              "maxLength": 64,
              "example": "sharedsecret123"
            },
            "leftid": {
              "type": "string",
              "description": "本地标识符，authby=pubkey时必填，最大100字符；authby=secret时传空值",
              "maxLength": 100,
              "example": "localgateway"
            },
            "rightid": {
              "type": "string",
              "description": "对方标识符，authby=pubkey时必填，最大100字符；authby=secret时传空值",
              "maxLength": 100,
              "example": "remotegateway"
            },
            "privatekey": {
              "type": "string",
              "description": "私钥内容，authby=pubkey时必填；authby=secret时传空值",
              "example": ""
            },
            "leftcert": {
              "type": "string",
              "description": "本地证书内容，authby=pubkey时必填；authby=secret时传空值",
              "example": ""
            },
            "rightcert": {
              "type": "string",
              "description": "远端证书内容，authby=pubkey时必填；authby=secret时传空值",
              "example": ""
            },
            "lifetime": {
              "type": "integer",
              "description": "IPSec SA生命周期（小时）",
              "minimum": 1,
              "maximum": 72,
              "example": 1
            },
            "esp_enc": {
              "type": "string",
              "enum": [
                "",
                "aes128",
                "aes192",
                "aes256",
                "3des",
                "des"
              ],
              "description": "ESP加密算法，留空表示使用默认算法组合",
              "example": "aes256"
            },
            "esp_auth": {
              "type": "string",
              "enum": [
                "",
                "md5",
                "sha1",
                "sha256",
                "sha512"
              ],
              "description": "ESP认证算法，留空表示使用默认算法组合",
              "example": "sha256"
            },
            "dpdaction": {
              "type": "string",
              "enum": [
                "none",
                "clear",
                "hold",
                "restart"
              ],
              "description": "DPD操作，none表示不启用DPD",
              "example": "none"
            },
            "dpddelay": {
              "type": "integer",
              "description": "DPD检测间隔（秒），dpdaction不为none时生效，范围5-300；dpdaction=none时传0",
              "minimum": 5,
              "maximum": 300,
              "example": 30
            },
            "dpdtimeout": {
              "type": "integer",
              "description": "DPD超时时间（秒），dpdaction不为none时生效，范围60-600；dpdaction=none时传0",
              "minimum": 60,
              "maximum": 600,
              "example": 150
            },
            "compress": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "数据压缩，0为关闭，1为开启",
              "example": "0"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "IPSEC VPN客户端",
        "description": "IPSEC VPN客户端的管理和配置"
      }
    ]
  },
  "vpn/network-l2tp-client.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "L2TP VPN客户端管理API",
      "version": "1.0.0",
      "summary": "L2TP VPN客户端的完整管理功能",
      "description": "提供L2TP VPN客户端的完整管理功能，包括：\n- L2TP客户端的创建、查询、更新、删除\n- 客户端启用/停用状态控制\n- 支持分页、模糊匹配和过滤功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4.0",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/l2tp/clients": {
        "get": {
          "summary": "获取L2TP客户端列表",
          "description": "获取所有L2TP客户端配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listL2tpClients",
          "tags": [
            "l2tp-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，支持name、comment、server、interface、username等字段",
              "schema": {
                "type": "string",
                "enum": [
                  "name",
                  "comment",
                  "server",
                  "interface",
                  "username",
                  "ipsec_secret",
                  "leftid",
                  "rightid"
                ],
                "example": "name"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=name==test1,name==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取L2TP客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/L2tpClientListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建L2TP客户端",
          "description": "添加新的L2TP VPN客户端配置。\n支持IPSec加密和带宽控制功能。\n",
          "operationId": "createL2tpClient",
          "tags": [
            "l2tp-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "L2TP客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/L2tpClientInput"
                },
                "example": {
                  "enabled": "yes",
                  "name": "l2tp_main_office",
                  "comment": "主办公室L2TPVPN连接",
                  "server": "vpn.example.com",
                  "server_port": 1701,
                  "username": "vpnuser",
                  "passwd": "vpnpassword123",
                  "ipsec_secret": "ipseckey123",
                  "interface": "wan1",
                  "leftid": "locall2tp",
                  "rightid": "remotel2tp",
                  "upload": 10000,
                  "download": 50000,
                  "mtu": 1400,
                  "mru": 1400,
                  "check_link_mode": 2,
                  "check_link_host": "www.baidu.com",
                  "timing_rst_switch": 0,
                  "timing_rst_week": "1234567",
                  "timing_rst_time": "12:00",
                  "cycle_rst_time": 0
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/l2tp/clients/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/l2tpClientIdParam"
          }
        ],
        "get": {
          "summary": "获取指定L2TP客户端",
          "description": "根据ID获取单个L2TP客户端的详细配置信息。\n需要提供有效的客户端ID。\n",
          "operationId": "getL2tpClient",
          "tags": [
            "l2tp-clients"
          ],
          "responses": {
            "200": {
              "description": "成功获取L2TP客户端详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/L2tpClientResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新L2TP客户端",
          "description": "完全更新现有的L2TP客户端配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateL2tpClient",
          "tags": [
            "l2tp-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的L2TP客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/L2tpClientUpdateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用L2TP客户端",
          "description": "部分更新现有的L2TP客户端配置。\n主要用于启用/停用客户端状态。\n",
          "operationId": "patchL2tpClient",
          "tags": [
            "l2tp-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "客户端启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除L2TP客户端",
          "description": "删除指定的L2TP客户端配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteL2tpClient",
          "tags": [
            "l2tp-clients"
          ],
          "responses": {
            "200": {
              "description": "L2TP客户端删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "l2tpClientIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "L2TP客户端ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、server、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "code": {
              "type": "integer",
              "description": "返回码",
              "example": 0
            },
            "rowid": {
              "type": "integer",
              "description": "新创建记录的ID",
              "example": 1
            }
          },
          "required": [
            "message",
            "code",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "L2tpClientResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/L2tpClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "L2tpClientListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/L2tpClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "L2tpClient": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "comment",
            "server",
            "server_port",
            "username",
            "passwd",
            "ipsec_secret",
            "interface",
            "leftid",
            "rightid",
            "mtu",
            "mru",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "cycle_rst_time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端名称（必须以l2tp开头）",
              "pattern": "^l2tp[a-zA-Z0-9_-]*$",
              "minLength": 4,
              "maxLength": 15,
              "example": "l2tp1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "example": "主办公室L2TPVPN连接"
            },
            "server": {
              "type": "string",
              "description": "L2TP服务器地址",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpn.example.com"
            },
            "server_port": {
              "type": "integer",
              "description": "L2TP服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1701,
              "example": 1701
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpnpassword123"
            },
            "ipsec_secret": {
              "type": "string",
              "description": "IPSec预共享密钥（可选为空）",
              "maxLength": 63,
              "example": "ipseckey123"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "leftid": {
              "type": "string",
              "description": "IPSec本地标识符（可选为空）",
              "maxLength": 255,
              "example": "locall2tp"
            },
            "rightid": {
              "type": "string",
              "description": "IPSec对端标识符（可选为空）",
              "maxLength": 255,
              "example": "remotel2tp"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "minimum": 0,
              "maximum": 6,
              "default": 2,
              "example": 2
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址（可选为空）",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "定时重拨开关，0为关闭，1为开启",
              "default": 0,
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期设置（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "default": "1234567",
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间（HH:MM格式）",
              "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
              "default": "12:00",
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "周期重连时间（分钟），0表示无限（可选）",
              "minimum": 0,
              "maximum": 500000,
              "default": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "description": "上行带宽限速（Kbps），0表示不限速（可选为空）",
              "minimum": 0,
              "maximum": 1000000000,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下行带宽限速（Kbps），0表示不限速（可选为空）",
              "minimum": 0,
              "maximum": 1000000000,
              "example": 0
            },
            "updatetime": {
              "type": "string",
              "description": "更新时间",
              "readOnly": true,
              "example": ""
            },
            "dns1": {
              "type": "string",
              "description": "DNS1",
              "readOnly": true,
              "example": ""
            },
            "dns2": {
              "type": "string",
              "description": "DNS2",
              "readOnly": true,
              "example": ""
            },
            "mppe": {
              "type": "string",
              "description": "MPPE加密",
              "readOnly": true,
              "example": ""
            },
            "gateway": {
              "type": "string",
              "description": "网关",
              "readOnly": true,
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "分配的IP地址",
              "readOnly": true,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "L2tpClientInput": {
          "type": "object",
          "required": [
            "enabled",
            "name",
            "server",
            "server_port",
            "username",
            "passwd",
            "interface",
            "mtu",
            "mru",
            "check_link_mode",
            "check_link_host",
            "cycle_rst_time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端名称（必须以l2tp开头）",
              "pattern": "^l2tp[a-zA-Z0-9_-]*$",
              "minLength": 4,
              "maxLength": 15,
              "example": "l2tp1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "example": "主办公室L2TP_VPN连接"
            },
            "server": {
              "type": "string",
              "description": "L2TP服务器地址",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpn.example.com"
            },
            "server_port": {
              "type": "integer",
              "description": "L2TP服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1701,
              "example": 1701
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 100,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword123"
            },
            "ipsec_secret": {
              "type": "string",
              "description": "IPSec预共享密钥",
              "minLength": 1,
              "maxLength": 64,
              "example": "ipseckey123"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "leftid": {
              "type": "string",
              "description": "IPSec本地标识符（可选为空）",
              "maxLength": 100,
              "example": "locall2tp"
            },
            "rightid": {
              "type": "string",
              "description": "IPSec对端标识符（可选为空）",
              "maxLength": 100,
              "example": "remotel2tp"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "minimum": 0,
              "maximum": 6,
              "default": 2,
              "example": 2
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "定时重拨开关，0为关闭，1为开启（可选）",
              "default": 0,
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期设置（1-7代表周一到周日，timing_rst_switch=1时必填）",
              "pattern": "^[1-7]+$",
              "default": "1234567",
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间（HH:MM格式，timing_rst_switch=1时必填）",
              "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
              "default": "12:00",
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "周期重连时间（分钟），0表示无限（可选）",
              "minimum": 0,
              "maximum": 500000,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "L2tpClientUpdateInput": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "server",
            "server_port",
            "username",
            "passwd",
            "interface",
            "mtu",
            "mru",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "cycle_rst_time",
            "ipsec_secret",
            "leftid",
            "rightid",
            "timing_rst_week",
            "timing_rst_time",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端名称（必须以l2tp开头）",
              "pattern": "^l2tp[a-zA-Z0-9_-]*$",
              "minLength": 4,
              "maxLength": 15,
              "example": "l2tp1"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "example": "主办公室L2TP_VPN连接"
            },
            "server": {
              "type": "string",
              "description": "L2TP服务器地址",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpn.example.com"
            },
            "server_port": {
              "type": "integer",
              "description": "L2TP服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1701,
              "example": 1701
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 100,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword123"
            },
            "ipsec_secret": {
              "type": "string",
              "description": "IPSec预共享密钥（可选为空）",
              "maxLength": 64,
              "example": "ipseckey123"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "leftid": {
              "type": "string",
              "description": "IPSec本地标识符（可选为空）",
              "maxLength": 100,
              "example": "locall2tp"
            },
            "rightid": {
              "type": "string",
              "description": "IPSec对端标识符（可选为空）",
              "maxLength": 100,
              "example": "remotel2tp"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "minimum": 1,
              "maximum": 6,
              "default": 1,
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "定时重拨开关，0为关闭，1为开启",
              "default": 0,
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期设置（1-7代表周一到周日，timing_rst_switch=1时必填）",
              "pattern": "^[1-7]+$",
              "default": "1234567",
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间（HH:MM格式，timing_rst_switch=1时必填）",
              "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
              "default": "12:00",
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "周期重连时间（分钟），0表示无限",
              "minimum": 0,
              "maximum": 500000,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "l2tp-clients",
        "x-displayName": "L2TP VPN客户端",
        "description": "L2TP VPN客户端的管理和配置"
      }
    ]
  },
  "vpn/network-openvpn-client.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "OpenVPN客户端管理API",
      "version": "1.0.0",
      "summary": "OpenVPN客户端的完整管理功能",
      "description": "提供OpenVPN客户端的完整管理功能，包括：\n- OpenVPN客户端的创建、查询、更新、删除\n- 客户端启用/停用状态控制\n- 支持分页、模糊匹配和过滤功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4.0",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/openvpn/clients": {
        "get": {
          "summary": "获取OpenVPN客户端列表",
          "description": "获取所有OpenVPN客户端配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listOpenvpnClients",
          "tags": [
            "OpenVPN客户端"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，与 pattern 参数联合使用",
              "schema": {
                "type": "string",
                "enum": [
                  "name",
                  "comment",
                  "remote_addr",
                  "interface",
                  "username",
                  "proto",
                  "dev_type",
                  "cipher"
                ],
                "example": "name"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容，与 key 参数联合使用",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=name==test1,name==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取OpenVPN客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/OpenvpnClientListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建OpenVPN客户端",
          "description": "添加新的OpenVPN客户端配置。\n\n**条件必填字段：**\n- `username`、`password`：当 method=0（账号认证）时必填\n- `tls_auth`、`cert`、`key`：当 method=1（tls-auth）或 method=2（tls-crypt）时必填\n- `timing_rst_week`、`timing_rst_time`：当 timing_rst_switch=1 时必填\n- `ca`：使用转义后的单行 PEM 字符串，原始换行替换为 `@`，原始空格替换为 `#`\n",
          "operationId": "createOpenvpnClient",
          "tags": [
            "OpenVPN客户端"
          ],
          "requestBody": {
            "required": true,
            "description": "OpenVPN客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenvpnClientInput"
                },
                "example": {
                  "enabled": "yes",
                  "name": "ovpn_office",
                  "comment": "主办公室OpenVPN连接",
                  "remote_addr": "vpn.ikuai.cn",
                  "remote_port": 1194,
                  "method": 0,
                  "username": "vpnuser",
                  "password": "vpnpassword",
                  "interface": "wan1",
                  "proto": "udp",
                  "dev_type": "tun",
                  "cipher": "AES-256-CBC",
                  "comp_lzo": "1",
                  "tun_mtu": 1400,
                  "ca": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@",
                  "accept_push_route": "0",
                  "route": "",
                  "timing_rst_switch": "0",
                  "check_link_mode": 1,
                  "check_link_host": "www.baidu.com",
                  "extra_config": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "OpenVPN客户端创建成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/openvpn/clients/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/openvpnClientIdParam"
          }
        ],
        "get": {
          "summary": "获取指定OpenVPN客户端",
          "description": "根据ID获取单个OpenVPN客户端的详细配置信息。\n",
          "operationId": "getOpenvpnClient",
          "tags": [
            "OpenVPN客户端"
          ],
          "responses": {
            "200": {
              "description": "成功获取OpenVPN客户端详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/OpenvpnClientResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新OpenVPN客户端",
          "description": "完全更新现有的OpenVPN客户端配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateOpenvpnClient",
          "tags": [
            "OpenVPN客户端"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的OpenVPN客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenvpnClientUpdateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用OpenVPN客户端",
          "description": "部分更新现有的OpenVPN客户端配置。\n主要用于启用/停用客户端状态。\n",
          "operationId": "patchOpenvpnClient",
          "tags": [
            "OpenVPN客户端"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "客户端启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除OpenVPN客户端",
          "description": "删除指定的OpenVPN客户端配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteOpenvpnClient",
          "tags": [
            "OpenVPN客户端"
          ],
          "responses": {
            "200": {
              "description": "OpenVPN客户端删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "openvpnClientIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "OpenVPN客户端ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、remote_addr、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "OpenvpnClientResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OpenvpnClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "OpenvpnClientListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OpenvpnClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "OpenvpnClient": {
          "type": "object",
          "required": [
            "id",
            "name",
            "comment",
            "remote_addr",
            "remote_port",
            "username",
            "password",
            "interface",
            "enabled",
            "proto",
            "dev_type",
            "cipher",
            "method",
            "tls_auth",
            "ca",
            "cert",
            "key",
            "redirect_gateway",
            "accept_push_route",
            "route",
            "comp_lzo",
            "tun_mtu",
            "tunnel_ip",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "extra_config"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "name": {
              "type": "string",
              "description": "客户端连接名称，必须以ovpn开头，仅支持英文、数字、下划线，5-15字符，不可重复",
              "pattern": "^ovpn[0-9A-Za-z_]{1,11}$",
              "minLength": 5,
              "maxLength": 15,
              "example": "ovpn_office"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "主办公室OpenVPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "OpenVPN服务器地址，支持IPv4、IPv6或域名",
              "example": "vpn.ikuai.cn"
            },
            "remote_port": {
              "type": "integer",
              "description": "OpenVPN服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "example": 1194
            },
            "username": {
              "type": "string",
              "description": "用户名，method=0时必填",
              "maxLength": 60,
              "example": "vpnuser"
            },
            "password": {
              "type": "string",
              "description": "密码，method=0时必填",
              "maxLength": 64,
              "example": "vpnpassword"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto表示自动选择，或指定WAN接口名称",
              "example": "wan1"
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "proto": {
              "type": "string",
              "enum": [
                "udp",
                "tcp"
              ],
              "description": "传输协议",
              "example": "udp"
            },
            "dev_type": {
              "type": "string",
              "enum": [
                "tun",
                "tap"
              ],
              "description": "设备类型",
              "example": "tun"
            },
            "cipher": {
              "type": "string",
              "description": "加密算法",
              "enum": [
                "BF-CBC",
                "BF-CFB",
                "BF-OFB",
                "DES-CFB",
                "DES-CBC",
                "RC2-CBC",
                "RC2-CFB",
                "RC2-OFB",
                "DES-EDE-CBC",
                "DES-EDE3-CBC",
                "DES-OFB",
                "DES-EDE-CFB",
                "DES-EDE3-CFB",
                "DES-EDE-OFB",
                "DES-EDE3-OFB",
                "DESX-CBC",
                "RC2-40-CBC",
                "CAST5-CBC",
                "CAST5-CFB",
                "CAST5-OFB",
                "RC2-64-CBC",
                "AES-128-CBC",
                "AES-128-OFB",
                "AES-128-CFB",
                "AES-192-CBC",
                "AES-192-OFB",
                "AES-192-CFB",
                "AES-256-CBC",
                "AES-256-OFB",
                "AES-256-CFB",
                "AES-128-CFB1",
                "AES-192-CFB1",
                "AES-256-CFB1",
                "AES-128-CFB8",
                "AES-192-CFB8",
                "AES-256-CFB8",
                "AES-256-GCM",
                "DES-CFB1",
                "DES-CFB8",
                "DES-EDE3-CFB1",
                "DES-EDE3-CFB8",
                "SEED-CBC",
                "SEED-OFB",
                "SEED-CFB",
                "none"
              ],
              "example": "AES-256-CBC"
            },
            "method": {
              "type": "integer",
              "enum": [
                0,
                1,
                2
              ],
              "description": "认证方式，0=账号认证，1=tls-auth，2=tls-crypt",
              "example": 0
            },
            "tls_auth": {
              "type": "string",
              "description": "静态密钥，method=1或method=2时必填",
              "example": ""
            },
            "ca": {
              "type": "string",
              "description": "CA证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@"
            },
            "cert": {
              "type": "string",
              "description": "客户端证书，method=1 或 method=2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOclientCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgQ2xpZW50@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tY2xpZW50LWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCclientCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBRclientCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAzzzzyyyyxxxxwwww@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            },
            "key": {
              "type": "string",
              "description": "客户端私钥，method=1 或 method=2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsclientPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFclientPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "redirect_gateway": {
              "type": "string",
              "description": "重定向网关，1为开启",
              "example": ""
            },
            "accept_push_route": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "是否接受路由推送，0为拒绝，1为接受",
              "example": "0"
            },
            "route": {
              "type": "string",
              "description": "自定义路由，多条逗号分隔，格式为IP/掩码",
              "example": "192.168.1.0/24"
            },
            "comp_lzo": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "LZO压缩，0为关闭，1为开启",
              "example": "1"
            },
            "tun_mtu": {
              "type": "integer",
              "description": "隧道MTU",
              "minimum": 1000,
              "maximum": 1500,
              "example": 1400
            },
            "tunnel_ip": {
              "type": "string",
              "description": "隧道IP地址（只读，系统自动获取）",
              "example": "10.8.0.2"
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址，支持IPv4或域名",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "string",
              "enum": [
                "",
                "0",
                "1"
              ],
              "description": "定时重拨开关，空或0为关闭，1为开启",
              "example": "0"
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期，timing_rst_switch=1时必填，1-7代表周一到周日",
              "example": ""
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间，timing_rst_switch=1时必填，HH:MM格式",
              "example": ""
            },
            "extra_config": {
              "type": "string",
              "description": "附加配置参数",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "OpenvpnClientInput": {
          "type": "object",
          "required": [
            "enabled",
            "name",
            "remote_addr",
            "remote_port",
            "method",
            "interface",
            "proto",
            "dev_type",
            "cipher",
            "tun_mtu",
            "ca",
            "comp_lzo",
            "accept_push_route",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端连接名称，必须以ovpn开头，仅支持英文、数字、下划线，5-15字符，不可重复",
              "pattern": "^ovpn[0-9A-Za-z_]{1,11}$",
              "minLength": 5,
              "maxLength": 15,
              "example": "ovpn_office"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "主办公室OpenVPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "OpenVPN服务器地址，支持IPv4、IPv6或域名",
              "example": "vpn.ikuai.cn"
            },
            "remote_port": {
              "type": "integer",
              "description": "OpenVPN服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "example": 1194
            },
            "method": {
              "type": "integer",
              "enum": [
                0,
                1,
                2
              ],
              "description": "认证方式，0=账号认证，1=tls-auth，2=tls-crypt",
              "example": 0
            },
            "username": {
              "type": "string",
              "description": "用户名，method=0时必填",
              "maxLength": 60,
              "example": "vpnuser"
            },
            "password": {
              "type": "string",
              "description": "密码，method=0时必填",
              "maxLength": 64,
              "example": "vpnpassword"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto表示自动选择，或指定WAN接口名称",
              "example": "wan1"
            },
            "proto": {
              "type": "string",
              "enum": [
                "udp",
                "tcp"
              ],
              "description": "传输协议",
              "example": "udp"
            },
            "dev_type": {
              "type": "string",
              "enum": [
                "tun",
                "tap"
              ],
              "description": "设备类型",
              "example": "tun"
            },
            "cipher": {
              "type": "string",
              "description": "加密算法",
              "enum": [
                "BF-CBC",
                "BF-CFB",
                "BF-OFB",
                "DES-CFB",
                "DES-CBC",
                "RC2-CBC",
                "RC2-CFB",
                "RC2-OFB",
                "DES-EDE-CBC",
                "DES-EDE3-CBC",
                "DES-OFB",
                "DES-EDE-CFB",
                "DES-EDE3-CFB",
                "DES-EDE-OFB",
                "DES-EDE3-OFB",
                "DESX-CBC",
                "RC2-40-CBC",
                "CAST5-CBC",
                "CAST5-CFB",
                "CAST5-OFB",
                "RC2-64-CBC",
                "AES-128-CBC",
                "AES-128-OFB",
                "AES-128-CFB",
                "AES-192-CBC",
                "AES-192-OFB",
                "AES-192-CFB",
                "AES-256-CBC",
                "AES-256-OFB",
                "AES-256-CFB",
                "AES-128-CFB1",
                "AES-192-CFB1",
                "AES-256-CFB1",
                "AES-128-CFB8",
                "AES-192-CFB8",
                "AES-256-CFB8",
                "AES-256-GCM",
                "DES-CFB1",
                "DES-CFB8",
                "DES-EDE3-CFB1",
                "DES-EDE3-CFB8",
                "SEED-CBC",
                "SEED-OFB",
                "SEED-CFB",
                "none"
              ],
              "example": "AES-256-CBC"
            },
            "tls_auth": {
              "type": "string",
              "description": "静态密钥，method=1或method=2时必填",
              "example": ""
            },
            "ca": {
              "type": "string",
              "description": "CA证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@"
            },
            "cert": {
              "type": "string",
              "description": "客户端证书，method=1 或 method=2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOclientCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgQ2xpZW50@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tY2xpZW50LWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCclientCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBRclientCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAzzzzyyyyxxxxwwww@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            },
            "key": {
              "type": "string",
              "description": "客户端私钥，method=1 或 method=2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsclientPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFclientPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "redirect_gateway": {
              "type": "string",
              "description": "重定向网关，1为开启",
              "example": ""
            },
            "accept_push_route": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "是否接受路由推送，0为拒绝，1为接受",
              "example": "0"
            },
            "route": {
              "type": "string",
              "description": "自定义路由，多条逗号分隔，格式为IP/掩码",
              "example": ""
            },
            "comp_lzo": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "LZO压缩，0为关闭，1为开启",
              "example": "1"
            },
            "tun_mtu": {
              "type": "integer",
              "description": "隧道MTU",
              "minimum": 1000,
              "maximum": 1500,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址，支持IPv4或域名",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "string",
              "enum": [
                "",
                "0",
                "1"
              ],
              "description": "定时重拨开关，空或0为关闭，1为开启",
              "example": "0"
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期，timing_rst_switch=1时必填，1-7代表周一到周日",
              "example": ""
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间，timing_rst_switch=1时必填，HH:MM格式",
              "example": ""
            },
            "extra_config": {
              "type": "string",
              "description": "附加配置参数",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "OpenvpnClientUpdateInput": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "remote_addr",
            "remote_port",
            "method",
            "interface",
            "proto",
            "dev_type",
            "cipher",
            "tun_mtu",
            "ca",
            "comp_lzo",
            "accept_push_route",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "tls_auth",
            "cert",
            "key",
            "username",
            "password",
            "extra_config",
            "route",
            "comment",
            "timing_rst_week",
            "timing_rst_time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "客户端连接名称，必须以ovpn开头，仅支持英文、数字、下划线，5-15字符，不可重复",
              "pattern": "^ovpn[0-9A-Za-z_]{1,11}$",
              "minLength": 5,
              "maxLength": 15,
              "example": "ovpn_office"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "maxLength": 64,
              "example": "主办公室OpenVPN连接"
            },
            "remote_addr": {
              "type": "string",
              "description": "OpenVPN服务器地址，支持IPv4、IPv6或域名",
              "example": "vpn.ikuai.cn"
            },
            "remote_port": {
              "type": "integer",
              "description": "OpenVPN服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "example": 1194
            },
            "method": {
              "type": "integer",
              "enum": [
                0,
                1,
                2
              ],
              "description": "认证方式，0=账号认证，1=tls-auth，2=tls-crypt",
              "example": 0
            },
            "username": {
              "type": "string",
              "description": "用户名，method=0时必填",
              "maxLength": 60,
              "example": "vpnuser"
            },
            "password": {
              "type": "string",
              "description": "密码，method=0时必填",
              "maxLength": 64,
              "example": "vpnpassword"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto表示自动选择，或指定WAN接口名称",
              "example": "wan1"
            },
            "proto": {
              "type": "string",
              "enum": [
                "udp",
                "tcp"
              ],
              "description": "传输协议",
              "example": "udp"
            },
            "dev_type": {
              "type": "string",
              "enum": [
                "tun",
                "tap"
              ],
              "description": "设备类型",
              "example": "tun"
            },
            "cipher": {
              "type": "string",
              "description": "加密算法",
              "enum": [
                "BF-CBC",
                "BF-CFB",
                "BF-OFB",
                "DES-CFB",
                "DES-CBC",
                "RC2-CBC",
                "RC2-CFB",
                "RC2-OFB",
                "DES-EDE-CBC",
                "DES-EDE3-CBC",
                "DES-OFB",
                "DES-EDE-CFB",
                "DES-EDE3-CFB",
                "DES-EDE-OFB",
                "DES-EDE3-OFB",
                "DESX-CBC",
                "RC2-40-CBC",
                "CAST5-CBC",
                "CAST5-CFB",
                "CAST5-OFB",
                "RC2-64-CBC",
                "AES-128-CBC",
                "AES-128-OFB",
                "AES-128-CFB",
                "AES-192-CBC",
                "AES-192-OFB",
                "AES-192-CFB",
                "AES-256-CBC",
                "AES-256-OFB",
                "AES-256-CFB",
                "AES-128-CFB1",
                "AES-192-CFB1",
                "AES-256-CFB1",
                "AES-128-CFB8",
                "AES-192-CFB8",
                "AES-256-CFB8",
                "AES-256-GCM",
                "DES-CFB1",
                "DES-CFB8",
                "DES-EDE3-CFB1",
                "DES-EDE3-CFB8",
                "SEED-CBC",
                "SEED-OFB",
                "SEED-CFB",
                "none"
              ],
              "example": "AES-256-CBC"
            },
            "tls_auth": {
              "type": "string",
              "description": "静态密钥，method=1或method=2时必填",
              "example": ""
            },
            "ca": {
              "type": "string",
              "description": "CA证书，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDQTCCAimgAwIBAgIJAMqVcmi6/37xMA0GCSqGSIb3DQEBCwUAMDcxCzAJBgNV@BAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgRGV2aWNlIENB@MB4XDTI2MDIwNjEwMzExMFoXDTM2MDIwNDEwMzExMFowNzELMAkGA1UEBhMCQ04x@DjAMBgNVBAoMBWlLdWFpMRgwFgYDVQQDDA9pS3VhaSBEZXZpY2UgQ0EwggEiMA0G@CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCeCJGD4jX3PY5IdOYRv0gxfYPYikOc@hQkF5XAWQZgFxnuelDEkzl7RCOFVqsnwY/npOzI7VSsyLACPNkOdvyEvO+QGfRli@3zx0EfwRHGhLQbt/TDT0D9IZCab2oswdYjORtXcIe5dT3j2i8M2vv6wnJ7ip8GKu@ahfgJzakBZIRcQyEopTCmNbC5VAdCb/gQ0ezPnogPG6pbxxgE8OJIGH0+IgMFFTv@0wKVOCyHJgZNAZNnzP3yi5SCJvBnfU4wadXDAztGtq5El5l2lBP7s3KH65u0M/46@wo5NHyxZhn+M8S86EE4RkAeHI+1FqJASjW9ivNTRphFZMyW/Q4qbdEtrAgMBAAGj@UDBOMB0GA1UdDgQWBBRYp/q+2podeA2lc3khLBN+RGf+5TAfBgNVHSMEGDAWgBRY@p/q+2podeA2lc3khLBN+RGf+5TAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBCwUA@A4IBAQCHj5mxVYnaQcvMpjpWdXBS6XVpdiRpuqzRoqOYEnhzXOwwqnJ/EkJwa0RH@wFZUZrQC9bbxnIz+9kmlQKoTwtzzd9GVZeb3JeU9fcd/1BJdRLRiqqXw1EW0+QOV@7NCP1NqVMUsornypW1Y0JPcNfcvx/+oQXIIsS3EjOn+ye3ZASSRNi6+4zXNX2l53@8revjpAVnww0FS/zDeFGD9c9n6aYxvLxqXaBgNO3eOb2EAQAuNwncOvXZ9hBY8rz@A9jTuDVM1inhzROPguwt+j2moZedLm8DRgQxHjIkVvIOsq/50ApOVlGBCHjGJsay@tj3+p42yHrbmuCKvE6cCc0m2fhpw@-----END#CERTIFICATE-----@"
            },
            "cert": {
              "type": "string",
              "description": "客户端证书，method=1 或 method=2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 以 X.509 证书方式正常解析的 PEM 内容。\n",
              "example": "-----BEGIN#CERTIFICATE-----@MIIDWjCCAkKgAwIBAgIJAOclientCertDemoMA0GCSqGSIb3DQEBCwUAMDcxCzAJ@BgNVBAYTAkNOMQ4wDAYDVQQKDAVpS3VhaTEYMBYGA1UEAwwPaUt1YWkgQ2xpZW50@Q0EwHhcNMjYwMjA2MTAzMTEwWhcNMzYwMjA0MTAzMTEwWjA6MQswCQYDVQQGEwJD@TjEOMAwGA1UECgwFaUt1YWkxGzAZBgNVBAMMEm9wZW52cG4tY2xpZW50LWNlcnQw@ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCclientCertDemoData@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@AgMBAAGjUDBOMB0GA1UdDgQWBBRclientCertDemo1111111111111111111111@MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAAzzzzyyyyxxxxwwww@1111111111111111111111111111111111111111111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@-----END#CERTIFICATE-----@"
            },
            "key": {
              "type": "string",
              "description": "客户端私钥，method=1 或 method=2 时必填，使用转义后的单行 PEM 字符串传递：\n- 原始换行符替换为 `@`\n- 原始空格替换为 `#`\n按上述规则还原后，应得到可被 OpenSSL 正常识别的 PEM 私钥内容。\n",
              "example": "-----BEGIN#RSA#PRIVATE#KEY-----@MIIEowIBAAKCAQEAsclientPrivateKeyDemoData1111111111111111111111111@2222222222222222222222222222222222222222222222222222222222222222@3333333333333333333333333333333333333333333333333333333333333333@AoIBAFclientPrivateKeyDemoPayload444444444444444444444444444444444@5555555555555555555555555555555555555555555555555555555555555555@6666666666666666666666666666666666666666666666666666666666666666@-----END#RSA#PRIVATE#KEY-----@"
            },
            "accept_push_route": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "是否接受路由推送，0为拒绝，1为接受",
              "example": "0"
            },
            "route": {
              "type": "string",
              "description": "自定义路由，多条逗号分隔，格式为IP/掩码",
              "example": ""
            },
            "comp_lzo": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "description": "LZO压缩，0为关闭，1为开启",
              "example": "1"
            },
            "tun_mtu": {
              "type": "integer",
              "description": "隧道MTU",
              "minimum": 1000,
              "maximum": 1500,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址，支持IPv4或域名",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "string",
              "enum": [
                "",
                "0",
                "1"
              ],
              "description": "定时重拨开关，空或0为关闭，1为开启",
              "example": "0"
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期，timing_rst_switch=1时必填，1-7代表周一到周日",
              "example": ""
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间，timing_rst_switch=1时必填，HH:MM格式",
              "example": ""
            },
            "extra_config": {
              "type": "string",
              "description": "附加配置参数",
              "example": ""
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "OpenVPN客户端",
        "description": "OpenVPN客户端的管理和配置"
      }
    ]
  },
  "vpn/network-pptp-client.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "PPTP VPN客户端管理API",
      "version": "1.0.0",
      "summary": "PPTP VPN客户端的完整管理功能",
      "description": "提供PPTP VPN客户端的完整管理功能，包括：\n- PPTP客户端的创建、查询、更新、删除\n- 客户端启用/停用状态控制\n- 支持分页、模糊匹配和过滤功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4.0",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/pptp/clients": {
        "get": {
          "summary": "获取PPTP客户端列表",
          "description": "获取所有PPTP客户端配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listPptpClients",
          "tags": [
            "pptp-clients"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，与 pattern 参数联合使用",
              "schema": {
                "type": "string",
                "enum": [
                  "name",
                  "comment",
                  "server",
                  "interface",
                  "username"
                ],
                "example": "name"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容，与 key 参数联合使用",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=name==test1,name==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取PPTP客户端列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PptpClientListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建PPTP客户端",
          "description": "添加新的PPTP VPN客户端配置。\n支持定时重拨功能。\n",
          "operationId": "createPptpClient",
          "tags": [
            "pptp-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "PPTP客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PptpClientInput"
                },
                "example": {
                  "enabled": "yes",
                  "name": "pptp_office",
                  "comment": "主办公室PPTP连接",
                  "server": "vpn.ikuai.cn",
                  "server_port": 1723,
                  "username": "vpnuser",
                  "passwd": "vpnpassword123",
                  "interface": "wan1",
                  "mtu": 1400,
                  "mru": 1400,
                  "check_link_mode": 2,
                  "check_link_host": "www.baidu.com",
                  "timing_rst_switch": 0,
                  "timing_rst_week": "1234567",
                  "timing_rst_time": "12:00",
                  "cycle_rst_time": 0
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/pptp/clients/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/pptpClientIdParam"
          }
        ],
        "get": {
          "summary": "获取指定PPTP客户端",
          "description": "根据ID获取单个PPTP客户端的详细配置信息。\n需要提供有效的客户端ID。\n",
          "operationId": "getPptpClient",
          "tags": [
            "pptp-clients"
          ],
          "responses": {
            "200": {
              "description": "成功获取PPTP客户端详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PptpClientResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新PPTP客户端",
          "description": "完全更新现有的PPTP客户端配置。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePptpClient",
          "tags": [
            "pptp-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的PPTP客户端配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PptpClientUpdateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用PPTP客户端",
          "description": "部分更新现有的PPTP客户端配置。\n主要用于启用/停用客户端状态。\n",
          "operationId": "patchPptpClient",
          "tags": [
            "pptp-clients"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "客户端启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除PPTP客户端",
          "description": "删除指定的PPTP客户端配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deletePptpClient",
          "tags": [
            "pptp-clients"
          ],
          "responses": {
            "200": {
              "description": "PPTP客户端删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pptpClientIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "PPTP客户端ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、server、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "PptpClientResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PptpClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PptpClientListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PptpClient"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PptpClient": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "comment",
            "server",
            "server_port",
            "username",
            "passwd",
            "interface",
            "download",
            "mtu",
            "mru",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "cycle_rst_time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "拨号名称，必须以pptp开头，仅支持英文、数字、下划线，5-15字符，唯一",
              "pattern": "^pptp[0-9A-Za-z_]{1,11}$",
              "minLength": 5,
              "maxLength": 15,
              "example": "pptp_office"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符",
              "example": "主办公室PPTP连接"
            },
            "server": {
              "type": "string",
              "description": "PPTP服务器地址",
              "maxLength": 128,
              "example": "vpn.ikuai.cn"
            },
            "server_port": {
              "type": "integer",
              "description": "PPTP服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1723,
              "example": 1723
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword123"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto为自动选择，或指定WAN接口名",
              "example": "wan1"
            },
            "download": {
              "type": "integer",
              "description": "下行带宽（Kbps），由流控模块管理",
              "readOnly": true,
              "example": 0
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1400,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式：0关闭，1 HTTP+网关，2 PING+网关，3 HTTP+PING+网关，4 HTTP，5 PING，6 HTTP+PING",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "default": 2,
              "example": 2
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "定时重拨开关，0为关闭，1为开启",
              "default": 0,
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期设置（1-7代表周一到周日），timing_rst_switch=1时必填",
              "pattern": "^[1-7]+$",
              "default": "1234567",
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间（HH:MM格式），timing_rst_switch=1时必填",
              "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
              "default": "12:00",
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "周期重连时间（分钟），0表示无限",
              "minimum": 0,
              "maximum": 500000,
              "default": 0,
              "example": 0
            },
            "mppe": {
              "type": "string",
              "description": "MPPE加密",
              "readOnly": true,
              "example": ""
            },
            "updatetime": {
              "type": "string",
              "description": "更新时间",
              "readOnly": true,
              "example": ""
            },
            "dns1": {
              "type": "string",
              "description": "DNS1",
              "readOnly": true,
              "example": ""
            },
            "dns2": {
              "type": "string",
              "description": "DNS2",
              "readOnly": true,
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "分配的IP地址",
              "readOnly": true,
              "example": ""
            },
            "gateway": {
              "type": "string",
              "description": "网关",
              "readOnly": true,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "PptpClientInput": {
          "type": "object",
          "required": [
            "enabled",
            "name",
            "server",
            "username",
            "passwd",
            "interface",
            "mtu",
            "mru",
            "server_port",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "cycle_rst_time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "拨号名称，必须以pptp开头，唯一",
              "pattern": "^pptp",
              "maxLength": 64,
              "example": "pptp_office"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "主办公室PPTP连接"
            },
            "server": {
              "type": "string",
              "description": "PPTP服务器地址",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpn.ikuai.cn"
            },
            "server_port": {
              "type": "integer",
              "description": "PPTP服务器端口，不传则默认1723",
              "minimum": 1,
              "maximum": 65535,
              "default": 1723,
              "example": 1723
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword123"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto为自动选择，或指定WAN接口名",
              "example": "wan1"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式：0关闭，1 HTTP+网关，2 PING+网关，3 HTTP+PING+网关，4 HTTP，5 PING，6 HTTP+PING",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "default": 2,
              "example": 2
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "定时重拨开关，0为关闭，1为开启",
              "default": 0,
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期设置（1-7代表周一到周日），timing_rst_switch=1时必填",
              "pattern": "^[1-7]+$",
              "default": "1234567",
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间（HH:MM格式），timing_rst_switch=1时必填",
              "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
              "default": "12:00",
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "周期重连时间（分钟），0表示无限",
              "minimum": 0,
              "maximum": 500000,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "PptpClientUpdateInput": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "server",
            "username",
            "passwd",
            "interface",
            "mtu",
            "mru",
            "server_port",
            "check_link_mode",
            "check_link_host",
            "timing_rst_switch",
            "timing_rst_week",
            "timing_rst_time",
            "cycle_rst_time",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "客户端ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "客户端启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "拨号名称，必须以pptp开头，唯一",
              "pattern": "^pptp[0-9A-Za-z_]{1,11}$",
              "minLength": 5,
              "maxLength": 15,
              "example": "pptp_office"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "主办公室PPTP连接"
            },
            "server": {
              "type": "string",
              "description": "PPTP服务器地址",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpn.ikuai.cn"
            },
            "server_port": {
              "type": "integer",
              "description": "PPTP服务器端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1723,
              "example": 1723
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 128,
              "example": "vpnuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "vpnpassword123"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口，auto为自动选择，或指定WAN接口名",
              "example": "wan1"
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "example": 1400
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "example": 1400
            },
            "check_link_mode": {
              "type": "integer",
              "description": "线路检测模式：1 HTTP+网关，2 PING+网关，3 HTTP+PING+网关，4 HTTP，5 PING，6 HTTP+PING",
              "enum": [
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "default": 1,
              "example": 1
            },
            "check_link_host": {
              "type": "string",
              "description": "线路检测地址",
              "default": "www.baidu.com",
              "example": "www.baidu.com"
            },
            "timing_rst_switch": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "description": "定时重拨开关，0为关闭，1为开启",
              "default": 0,
              "example": 0
            },
            "timing_rst_week": {
              "type": "string",
              "description": "定时重拨星期设置（1-7代表周一到周日），timing_rst_switch=1时必填",
              "pattern": "^[1-7]+$",
              "default": "1234567",
              "example": "1234567"
            },
            "timing_rst_time": {
              "type": "string",
              "description": "定时重拨时间（HH:MM格式），timing_rst_switch=1时必填",
              "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
              "default": "12:00",
              "example": "12:00"
            },
            "cycle_rst_time": {
              "type": "integer",
              "description": "周期重连时间（分钟），0表示无限",
              "minimum": 0,
              "maximum": 500000,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "pptp-clients",
        "x-displayName": "PPTP VPN客户端",
        "description": "PPTP VPN客户端的管理和配置"
      }
    ]
  },
  "vpn/network-wireguard.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "WireGuard管理API",
      "version": "1.0.0",
      "summary": "WireGuard的完整管理功能",
      "description": "提供WireGuard的完整管理功能，包括：\n- WireGuard接口的创建、查询、更新、删除\n- WireGuard隧道的创建、查询、更新、删除\n- 接口和隧道启用/停用状态控制\n- 支持分页、模糊匹配和过滤功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/vpn/wireguard": {
        "get": {
          "summary": "获取WireGuard接口列表",
          "description": "获取所有WireGuard接口配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listWireguardInterfaces",
          "tags": [
            "wireguard-interfaces"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，支持name、interface、local_address等字段",
              "schema": {
                "type": "string",
                "enum": [
                  "name",
                  "interface",
                  "local_address",
                  "local_publickey",
                  "local_listenport"
                ],
                "example": "name"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=name==test1,name==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取WireGuard接口列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WireguardInterfaceListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建WireGuard接口",
          "description": "添加新的WireGuard接口配置。\n设置本地私钥、地址和监听端口等参数。\n",
          "operationId": "createWireguardInterface",
          "tags": [
            "wireguard-interfaces"
          ],
          "requestBody": {
            "required": true,
            "description": "WireGuard接口配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WireguardInterfaceInput"
                },
                "example": {
                  "enabled": "yes",
                  "name": "wg0",
                  "interface": "auto",
                  "local_privatekey": "privatekey123",
                  "local_publickey": "publickey123",
                  "local_address": "10.0.0.1/24",
                  "local_listenport": 5000,
                  "mtu": 1420
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/wireguard/{wg_id}": {
        "parameters": [
          {
            "name": "wg_id",
            "in": "path",
            "required": true,
            "description": "WireGuard接口ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定WireGuard接口",
          "description": "根据ID获取单个WireGuard接口的详细配置信息。\n需要提供有效的接口ID。\n",
          "operationId": "getWireguardInterface",
          "tags": [
            "wireguard-interfaces"
          ],
          "responses": {
            "200": {
              "description": "成功获取WireGuard接口详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WireguardInterfaceResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新WireGuard接口",
          "description": "完全更新现有的WireGuard接口配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateWireguardInterface",
          "tags": [
            "wireguard-interfaces"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的WireGuard接口配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WireguardInterfaceInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用WireGuard接口",
          "description": "部分更新现有的WireGuard接口配置。\n主要用于启用/停用接口状态。\n",
          "operationId": "patchWireguardInterface",
          "tags": [
            "wireguard-interfaces"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "接口启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除WireGuard接口",
          "description": "删除指定的WireGuard接口配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteWireguardInterface",
          "tags": [
            "wireguard-interfaces"
          ],
          "responses": {
            "200": {
              "description": "WireGuard接口删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/wireguard/{wg_id}/peers": {
        "parameters": [
          {
            "name": "wg_id",
            "in": "path",
            "required": true,
            "description": "WireGuard接口ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取WireGuard隧道列表",
          "description": "获取所有WireGuard隧道配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listWireguardTunnels",
          "tags": [
            "wireguard-tunnels"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段名称，支持comment、interface、peer_publickey等字段",
              "schema": {
                "type": "string",
                "enum": [
                  "comment",
                  "interface",
                  "peer_publickey",
                  "allowips",
                  "endpoint"
                ],
                "example": "comment"
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string",
                "example": "test"
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：==、!=、>、>=、<、<=\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=interface==wan1\n- OR条件：filter=comment==test1,comment==test2\n",
              "schema": {
                "type": "string",
                "example": "enabled==yes"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取WireGuard隧道列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WireguardTunnelListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建WireGuard隧道",
          "description": "添加新的WireGuard隧道配置。\n设置对端公钥、允许访问IP和端点等参数。\n",
          "operationId": "createWireguardTunnel",
          "tags": [
            "wireguard-tunnels"
          ],
          "requestBody": {
            "required": true,
            "description": "WireGuard隧道配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WireguardTunnelInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "分支机构隧道连接",
                  "interface": "wan1",
                  "peer_publickey": "peerpublickey123",
                  "presharedkey": "sharedsecret123",
                  "allowips": "192.168.2.0/24",
                  "endpoint": "remote.example.com",
                  "endpoint_port": 5001,
                  "keepalive": 10
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/vpn/wireguard/{wg_id}/peers/{peer_id}": {
        "parameters": [
          {
            "name": "wg_id",
            "in": "path",
            "required": true,
            "description": "WireGuard接口ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          },
          {
            "name": "peer_id",
            "in": "path",
            "required": true,
            "description": "WireGuard隧道ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定WireGuard隧道",
          "description": "根据ID获取单个WireGuard隧道的详细配置信息。\n需要提供有效的隧道ID。\n",
          "operationId": "getWireguardTunnel",
          "tags": [
            "wireguard-tunnels"
          ],
          "responses": {
            "200": {
              "description": "成功获取WireGuard隧道详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WireguardTunnelResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新WireGuard隧道",
          "description": "完全更新现有的WireGuard隧道配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateWireguardTunnel",
          "tags": [
            "wireguard-tunnels"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的WireGuard隧道配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WireguardTunnelInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用WireGuard隧道",
          "description": "部分更新现有的WireGuard隧道配置。\n主要用于启用/停用隧道状态。\n",
          "operationId": "patchWireguardTunnel",
          "tags": [
            "wireguard-tunnels"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "隧道启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除WireGuard隧道",
          "description": "删除指定的WireGuard隧道配置。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteWireguardTunnel",
          "tags": [
            "wireguard-tunnels"
          ],
          "responses": {
            "200": {
              "description": "WireGuard隧道删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "wireguardInterfaceIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "WireGuard接口ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "wireguardTunnelIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "WireGuard隧道ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、name、interface、local_address等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WireguardInterfaceResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "隧道总数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "隧道列表（含实时流量统计）",
                  "items": {
                    "$ref": "#/components/schemas/WireguardTunnel"
                  }
                },
                "iface_total": {
                  "type": "integer",
                  "description": "接口总数",
                  "example": 1
                },
                "iface_data": {
                  "type": "array",
                  "description": "接口列表",
                  "items": {
                    "$ref": "#/components/schemas/WireguardInterface"
                  }
                },
                "interface": {
                  "type": "array",
                  "description": "可选 WAN 口列表",
                  "items": {
                    "type": "object"
                  }
                },
                "wg_iface": {
                  "type": "array",
                  "description": "已创建的 WG 接口名称列表",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "total",
                "data",
                "iface_total",
                "iface_data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WireguardInterfaceListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "iface_total": {
                  "type": "integer",
                  "description": "接口总数",
                  "example": 3
                },
                "iface_data": {
                  "type": "array",
                  "description": "接口列表",
                  "items": {
                    "$ref": "#/components/schemas/WireguardInterface"
                  }
                }
              },
              "required": [
                "iface_total",
                "iface_data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WireguardTunnelResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WireguardTunnel"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WireguardTunnelListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WireguardTunnel"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WireguardInterface": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "name",
            "interface",
            "local_privatekey",
            "local_publickey",
            "local_address",
            "local_listenport",
            "mtu"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "接口ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "接口启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "WG接口名",
              "pattern": "^wg",
              "minLength": 2,
              "maxLength": 15,
              "example": "wg0"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "enum": [
                "auto",
                "wan1",
                "wan2",
                "lan1",
                "lan2"
              ],
              "default": "auto",
              "example": "wan1"
            },
            "local_privatekey": {
              "type": "string",
              "description": "本地私钥（Base64编码，44字符）",
              "minLength": 44,
              "maxLength": 44,
              "pattern": "^[A-Za-z0-9+/]+={0,2}$",
              "example": "yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk="
            },
            "local_publickey": {
              "type": "string",
              "description": "本地公钥（Base64编码，44字符）",
              "minLength": 44,
              "maxLength": 44,
              "pattern": "^[A-Za-z0-9+/]+={0,2}$",
              "example": "HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw="
            },
            "local_address": {
              "type": "string",
              "description": "本地地址",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[1-2][0-9]|3[0-2])$",
              "example": "10.0.0.1/24"
            },
            "local_listenport": {
              "type": "integer",
              "description": "本地监听端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 5000,
              "example": 5000
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1500,
              "default": 1420,
              "example": 1420
            }
          },
          "additionalProperties": false
        },
        "WireguardInterfaceInput": {
          "type": "object",
          "required": [
            "enabled",
            "name",
            "interface",
            "local_privatekey",
            "local_publickey",
            "local_address",
            "local_listenport",
            "mtu"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "接口启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "name": {
              "type": "string",
              "description": "WG接口名",
              "pattern": "^wg",
              "minLength": 2,
              "maxLength": 15,
              "example": "wg0"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "enum": [
                "auto",
                "wan1",
                "wan2",
                "lan1",
                "lan2"
              ],
              "default": "auto",
              "example": "wan1"
            },
            "local_privatekey": {
              "type": "string",
              "description": "本地私钥（Base64编码，44字符）",
              "minLength": 44,
              "maxLength": 44,
              "pattern": "^[A-Za-z0-9+/]+={0,2}$",
              "example": "yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk="
            },
            "local_publickey": {
              "type": "string",
              "description": "本地公钥（Base64编码，44字符）",
              "minLength": 44,
              "maxLength": 44,
              "pattern": "^[A-Za-z0-9+/]+={0,2}$",
              "example": "HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw="
            },
            "local_address": {
              "type": "string",
              "description": "本地地址",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[1-2][0-9]|3[0-2])$",
              "example": "10.0.0.1/24"
            },
            "local_listenport": {
              "type": "integer",
              "description": "本地监听端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 5000,
              "example": 5000
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1500,
              "default": 1420,
              "example": 1420
            }
          },
          "additionalProperties": false
        },
        "WireguardTunnel": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "comment",
            "interface",
            "peer_publickey",
            "presharedkey",
            "allowips",
            "endpoint",
            "endpoint_port"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "隧道ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "隧道启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "分支机构隧道连接"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "peer_publickey": {
              "type": "string",
              "description": "对端公钥（Base64编码，44字符）",
              "minLength": 44,
              "maxLength": 44,
              "pattern": "^[A-Za-z0-9+/]+={0,2}$",
              "example": "HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw="
            },
            "presharedkey": {
              "type": "string",
              "description": "预共享密钥（Base64编码，44字符，可选为空）",
              "maxLength": 44,
              "example": ""
            },
            "allowips": {
              "type": "string",
              "description": "允许访问的IP地址范围",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[1-2][0-9]|3[0-2])(,((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[1-2][0-9]|3[0-2]))*$",
              "example": "192.168.2.0/24"
            },
            "endpoint": {
              "type": "string",
              "description": "对端节点IP地址",
              "format": "hostname",
              "example": "remote.example.com"
            },
            "endpoint_port": {
              "type": "integer",
              "description": "对端端口（可选，为空或合法端口号）",
              "minimum": 1,
              "maximum": 65535,
              "example": 5001
            },
            "keepalive": {
              "type": "integer",
              "description": "保活间隔（秒），0 表示禁用，范围 0-500",
              "minimum": 0,
              "maximum": 500,
              "example": 10
            },
            "upload": {
              "type": "string",
              "description": "上传流量（实时统计，只读）",
              "readOnly": true,
              "example": "1024000"
            },
            "download": {
              "type": "string",
              "description": "下载流量（实时统计，只读）",
              "readOnly": true,
              "example": "2048000"
            }
          },
          "additionalProperties": false
        },
        "WireguardTunnelInput": {
          "type": "object",
          "required": [
            "enabled",
            "peer_publickey",
            "allowips",
            "comment",
            "interface",
            "keepalive"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "隧道启用状态，yes为启用，no为停用",
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "分支机构隧道连接"
            },
            "interface": {
              "type": "string",
              "description": "绑定的网络接口",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "minLength": 1,
              "maxLength": 20,
              "example": "wan1"
            },
            "peer_publickey": {
              "type": "string",
              "description": "对端公钥（Base64编码，44字符）",
              "minLength": 44,
              "maxLength": 44,
              "pattern": "^[A-Za-z0-9+/]+={0,2}$",
              "example": "HIgo9xNzJMWLKASShiTqIybxZ0U3wGLiUeJ1PKf8ykw="
            },
            "presharedkey": {
              "type": "string",
              "description": "预共享密钥（Base64编码，44字符，可选为空）",
              "maxLength": 44,
              "example": ""
            },
            "allowips": {
              "type": "string",
              "description": "允许访问的IP地址范围",
              "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[1-2][0-9]|3[0-2])(,((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[1-2][0-9]|3[0-2]))*$",
              "example": "192.168.2.0/24"
            },
            "endpoint": {
              "type": "string",
              "description": "对端节点IP地址",
              "format": "hostname",
              "example": "remote.example.com"
            },
            "endpoint_port": {
              "type": "integer",
              "description": "对端端口（可选，为空或合法端口号）",
              "minimum": 1,
              "maximum": 65535,
              "example": 5001
            },
            "keepalive": {
              "type": "integer",
              "description": "保活间隔（秒），范围 0-500，0 表示禁用",
              "minimum": 0,
              "maximum": 500,
              "example": 10
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "wireguard-interfaces",
        "x-displayName": "WireGuard接口管理",
        "description": "WireGuard接口的管理和配置"
      },
      {
        "name": "wireguard-tunnels",
        "x-displayName": "WireGuard隧道管理",
        "description": "WireGuard隧道的管理和配置"
      }
    ]
  },
  "wireless/ac_status.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "AC服务管理API",
      "version": "4.0.0",
      "description": "AC服务状态管理和AP配置相关接口\n\n主要功能：\n- AC服务的启动、停止和状态查询\n- AP设备配置的获取和管理\n- 支持多种频段的AP配置（2.4G/5G/5G Radio2）\n- 完整的SSID安全、VLAN、限速等配置\n"
    },
    "paths": {
      "/api/v4.0/network/ac/services:start": {
        "post": {
          "tags": [
            "ac-service"
          ],
          "summary": "开启AC服务",
          "description": "启动AC控制器服务",
          "operationId": "startACService",
          "responses": {
            "200": {
              "description": "成功开启AC服务",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/ac/services:stop": {
        "post": {
          "tags": [
            "ac-service"
          ],
          "summary": "关闭AC服务",
          "description": "停止AC控制器服务",
          "operationId": "stopACService",
          "responses": {
            "200": {
              "description": "成功关闭AC服务",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/ac/services": {
        "get": {
          "tags": [
            "ac-service"
          ],
          "summary": "获取AC服务状态",
          "description": "查询AC服务的当前运行状态",
          "operationId": "getACServiceStatus",
          "responses": {
            "200": {
              "description": "成功获取AC服务状态",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AcServiceStatusResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "ac_status": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/ac/ap-config": {
        "get": {
          "tags": [
            "ap-config"
          ],
          "summary": "获取所有AP配置列表",
          "description": "获取所有AP设备的配置信息和状态",
          "operationId": "listAPConfigs",
          "responses": {
            "200": {
              "description": "成功获取AP配置列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/APConfigListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/network/ac/ap-config/{id}": {
        "get": {
          "tags": [
            "ap-config"
          ],
          "summary": "获取指定AP配置",
          "description": "根据ID获取指定AP设备的详细配置信息",
          "operationId": "getAPConfig",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "AP配置ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取AP配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/APConfigSingleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "tags": [
            "ap-config"
          ],
          "summary": "更新AP配置",
          "description": "更新指定AP设备的配置参数\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateAPConfig",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "AP配置ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "AP配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APConfigUpdate"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求参数错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "AcServiceStatusResponse": {
          "type": "object",
          "description": "AC服务状态响应",
          "required": [
            "message",
            "results"
          ],
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "ac_status"
              ],
              "properties": {
                "ac_status": {
                  "type": "integer",
                  "description": "AC服务状态（0:关闭, 1:开启）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 1
                }
              }
            }
          },
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "description": "成功响应",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "description": "错误响应",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息描述",
              "example": "错误信息"
            }
          },
          "additionalProperties": false
        },
        "APConfigListResponse": {
          "type": "object",
          "description": "AP配置列表响应",
          "required": [
            "message",
            "results"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "total",
                "data"
              ],
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "AP配置列表",
                  "items": {
                    "$ref": "#/components/schemas/APConfig"
                  }
                }
              }
            }
          },
          "additionalProperties": false
        },
        "APConfigSingleResponse": {
          "type": "object",
          "description": "单个AP配置响应",
          "required": [
            "message",
            "results"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "required": [
                "total",
                "data"
              ],
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "符合条件的记录数（找到则为1，未找到则为0）",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "AP配置数据",
                  "items": {
                    "$ref": "#/components/schemas/APConfig"
                  }
                }
              }
            }
          },
          "additionalProperties": false
        },
        "APConfig": {
          "type": "object",
          "description": "AP配置和状态信息",
          "required": [
            "id",
            "tagname"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "AP配置ID (主键)",
              "example": 1
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "IK-H13_427hy999"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "gid": {
              "type": "integer",
              "description": "所属AP分组ID，0表示默认分组（未分组）",
              "minimum": 0,
              "example": 0
            },
            "mlo_radio0": {
              "type": "integer",
              "description": "MLO radio0 2.4G频段开关（开启MLO的射频相同SSID的序号配置保持一致时，该SSID的MLO功能才能生效）",
              "example": 0
            },
            "mlo_radio1": {
              "type": "integer",
              "description": "MLO radio1 5G R1频段开关",
              "example": 0
            },
            "mlo_radio2": {
              "type": "integer",
              "description": "MLO radio2 5G R2频段开关",
              "example": 0
            },
            "flicker": {
              "type": "string",
              "description": "定位闪烁灯（off:关闭, on:开启）",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "lights": {
              "type": "integer",
              "description": "状态灯开关（0:关闭, 1:开启）",
              "example": 1
            },
            "ssid1": {
              "type": "string",
              "description": "2.4G SSID1",
              "example": "iKuai172_2G"
            },
            "ssid2": {
              "type": "string",
              "description": "2.4G SSID2",
              "example": ""
            },
            "hide_ssid1": {
              "type": "integer",
              "description": "隐藏2.4G SSID1开关 (0:不隐藏, 1:隐藏)",
              "example": 0
            },
            "hide_ssid2": {
              "type": "integer",
              "description": "隐藏2.4G SSID2开关",
              "example": 0
            },
            "isolate1": {
              "type": "integer",
              "description": "2.4G SSID1的访客模式开关 (0:关闭, 1:开启)",
              "example": 0
            },
            "isolate2": {
              "type": "integer",
              "description": "2.4G SSID2的访客模式开关",
              "example": 0
            },
            "qos_atf": {
              "type": "integer",
              "description": "2.4G的ATF公平调度算法 (0:关闭, 1:开启)",
              "example": 0
            },
            "load_strategy": {
              "type": "integer",
              "description": "2.4G负载策略 (0:关闭, 1:拒绝接入, 2:隐藏SSID)",
              "example": 0
            },
            "autohide_maxsta": {
              "type": "integer",
              "description": "2.4G负载策略阀值1",
              "example": 1
            },
            "autohide_resume": {
              "type": "integer",
              "description": "2.4G负载策略阀值2",
              "example": 0
            },
            "max_pc": {
              "type": "integer",
              "description": "2.4G最大带机量",
              "example": 0
            },
            "channel": {
              "type": "integer",
              "description": "2.4G信道 (0表示自动)",
              "example": 0
            },
            "min_signal": {
              "type": "integer",
              "description": "2.4G最低连接信号",
              "example": 0
            },
            "enc1": {
              "type": "string",
              "description": "2.4G SSID1加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key1": {
              "type": "string",
              "description": "2.4G SSID1密码 (SSID密码长度须在8-64个字符之间)",
              "example": "12345678"
            },
            "enc2": {
              "type": "string",
              "description": "2.4G SSID2加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key2": {
              "type": "string",
              "description": "2.4G SSID2密码",
              "example": ""
            },
            "ssid1_vlan": {
              "type": "string",
              "description": "2.4G SSID1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid1_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID1 VLAN ID (范围1-4090)",
              "example": 1
            },
            "ssid2_vlan": {
              "type": "string",
              "description": "2.4G SSID2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid2_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID2 VLAN ID",
              "example": 1
            },
            "ssid1_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID1限速开关 (0:关闭, 1:开启)",
              "example": 0
            },
            "ssid1_upload": {
              "type": "integer",
              "description": "2.4G SSID1上行限速",
              "example": 0
            },
            "ssid1_download": {
              "type": "integer",
              "description": "2.4G SSID1下行限速",
              "example": 0
            },
            "ssid2_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID2限速开关",
              "example": 0
            },
            "ssid2_upload": {
              "type": "integer",
              "description": "2.4G SSID2上行限速",
              "example": 0
            },
            "ssid2_download": {
              "type": "integer",
              "description": "2.4G SSID2下行限速",
              "example": 0
            },
            "auth_server1": {
              "type": "string",
              "description": "2.4G SSID1 RADIUS服务器IP",
              "example": ""
            },
            "auth_port1": {
              "type": "integer",
              "description": "2.4G SSID1 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret1": {
              "type": "string",
              "description": "2.4G SSID1 RADIUS密钥",
              "example": ""
            },
            "slave_auth1": {
              "type": "integer",
              "description": "2.4G SSID1备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server1": {
              "type": "string",
              "description": "2.4G SSID1备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port1": {
              "type": "integer",
              "description": "2.4G SSID1备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret1": {
              "type": "string",
              "description": "2.4G SSID1备份RADIUS密钥",
              "example": ""
            },
            "auth_server2": {
              "type": "string",
              "description": "2.4G SSID2 RADIUS服务器IP",
              "example": ""
            },
            "auth_port2": {
              "type": "integer",
              "description": "2.4G SSID2 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret2": {
              "type": "string",
              "description": "2.4G SSID2 RADIUS密钥",
              "example": ""
            },
            "slave_auth2": {
              "type": "integer",
              "description": "2.4G SSID2备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server2": {
              "type": "string",
              "description": "2.4G SSID2备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port2": {
              "type": "integer",
              "description": "2.4G SSID2备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret2": {
              "type": "string",
              "description": "2.4G SSID2备份RADIUS密钥",
              "example": ""
            },
            "signal_str": {
              "type": "integer",
              "description": "2.4G信号强度",
              "example": 0
            },
            "studio_ssid": {
              "type": "string",
              "description": "2.4G工作室SSID",
              "example": ""
            },
            "ssid3": {
              "type": "string",
              "description": "5G SSID1",
              "example": "iKuai172_5G"
            },
            "ssid4": {
              "type": "string",
              "description": "5G SSID2",
              "example": ""
            },
            "hide_ssid3": {
              "type": "integer",
              "description": "5G隐藏SSID1开关",
              "example": 0
            },
            "hide_ssid4": {
              "type": "integer",
              "description": "5G隐藏SSID2开关",
              "example": 0
            },
            "isolate3": {
              "type": "integer",
              "description": "5G SSID1访客模式开关",
              "example": 0
            },
            "isolate4": {
              "type": "integer",
              "description": "5G SSID2访客模式开关",
              "example": 0
            },
            "qos_atf_5g": {
              "type": "integer",
              "description": "5G ATF公平调度算法",
              "example": 0
            },
            "load_strategy_5g": {
              "type": "integer",
              "description": "5G负载策略 (0:关闭, 1:拒绝接入, 2:隐藏SSID)",
              "example": 0
            },
            "autohide_maxsta_5g": {
              "type": "integer",
              "description": "5G负载策略阀值1",
              "example": 1
            },
            "autohide_resume_5g": {
              "type": "integer",
              "description": "5G负载策略阀值2",
              "example": 0
            },
            "max_pc_5g": {
              "type": "integer",
              "description": "5G最大带机量",
              "example": 0
            },
            "channel_5g": {
              "type": "integer",
              "description": "5G信道",
              "example": 0
            },
            "min_signal_5g": {
              "type": "integer",
              "description": "5G最低连接信号",
              "example": 0
            },
            "enc3": {
              "type": "string",
              "description": "5G SSID1加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "wpa2"
            },
            "key3": {
              "type": "string",
              "description": "5G SSID1密码",
              "example": "12345678"
            },
            "enc4": {
              "type": "string",
              "description": "5G SSID2加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key4": {
              "type": "string",
              "description": "5G SSID2密码",
              "example": ""
            },
            "ssid3_vlan": {
              "type": "string",
              "description": "5G SSID1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid3_vlan_id": {
              "type": "integer",
              "description": "5G SSID1 VLAN ID",
              "example": 1
            },
            "ssid4_vlan": {
              "type": "string",
              "description": "5G SSID2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid4_vlan_id": {
              "type": "integer",
              "description": "5G SSID2 VLAN ID",
              "example": 1
            },
            "ssid3_ratelimit": {
              "type": "integer",
              "description": "5G SSID1限速开关",
              "example": 0
            },
            "ssid3_upload": {
              "type": "integer",
              "description": "5G SSID1上行限速",
              "example": 0
            },
            "ssid3_download": {
              "type": "integer",
              "description": "5G SSID1下行限速",
              "example": 0
            },
            "ssid4_ratelimit": {
              "type": "integer",
              "description": "5G SSID2限速开关",
              "example": 0
            },
            "ssid4_upload": {
              "type": "integer",
              "description": "5G SSID2上行限速",
              "example": 0
            },
            "ssid4_download": {
              "type": "integer",
              "description": "5G SSID2下行限速",
              "example": 0
            },
            "auth_server3": {
              "type": "string",
              "description": "5G SSID1 RADIUS服务器IP",
              "example": ""
            },
            "auth_port3": {
              "type": "integer",
              "description": "5G SSID1 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret3": {
              "type": "string",
              "description": "5G SSID1 RADIUS密钥",
              "example": ""
            },
            "slave_auth3": {
              "type": "integer",
              "description": "5G SSID1备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server3": {
              "type": "string",
              "description": "5G SSID1备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port3": {
              "type": "integer",
              "description": "5G SSID1备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret3": {
              "type": "string",
              "description": "5G SSID1备份RADIUS密钥",
              "example": ""
            },
            "auth_server4": {
              "type": "string",
              "description": "5G SSID2 RADIUS服务器IP",
              "example": ""
            },
            "auth_port4": {
              "type": "integer",
              "description": "5G SSID2 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret4": {
              "type": "string",
              "description": "5G SSID2 RADIUS密钥",
              "example": ""
            },
            "slave_auth4": {
              "type": "integer",
              "description": "5G SSID2备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server4": {
              "type": "string",
              "description": "5G SSID2备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port4": {
              "type": "integer",
              "description": "5G SSID2备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret4": {
              "type": "string",
              "description": "5G SSID2备份RADIUS密钥",
              "example": ""
            },
            "signal_str_5g": {
              "type": "integer",
              "description": "5G信号强度",
              "example": 0
            },
            "studio_ssid_5g": {
              "type": "string",
              "description": "5G工作室SSID",
              "example": ""
            },
            "task_switch1": {
              "type": "integer",
              "description": "开启时间计划任务1",
              "example": 0
            },
            "task_strategy1": {
              "type": "string",
              "description": "任务策略1 (one:一次, month:每月, week:每周)",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "task_date1": {
              "type": "string",
              "description": "任务日期1",
              "example": "2018-01-01"
            },
            "task_time1": {
              "type": "string",
              "description": "任务时间1",
              "example": "00:00-23:59"
            },
            "task_switch2": {
              "type": "integer",
              "description": "开启时间计划任务2",
              "example": 0
            },
            "task_strategy2": {
              "type": "string",
              "description": "任务策略2",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "task_date2": {
              "type": "string",
              "description": "任务日期2",
              "example": "2018-01-01"
            },
            "task_time2": {
              "type": "string",
              "description": "任务时间2",
              "example": "00:00-23:59"
            },
            "task_switch3": {
              "type": "integer",
              "description": "开启时间计划任务3",
              "example": 0
            },
            "task_strategy3": {
              "type": "string",
              "description": "任务策略3",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "task_date3": {
              "type": "string",
              "description": "任务日期3",
              "example": "2018-01-01"
            },
            "task_time3": {
              "type": "string",
              "description": "任务时间3",
              "example": "00:00-23:59"
            },
            "reboot_strategy": {
              "type": "string",
              "description": "重启策略 (one:一次, month:每月, week:每周)",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "reboot_date": {
              "type": "string",
              "description": "重启日期",
              "example": "2018-01-01"
            },
            "channel_width_2g": {
              "type": "integer",
              "description": "2.4G频宽",
              "enum": [
                20,
                40
              ],
              "example": 20
            },
            "channel_width_5g": {
              "type": "integer",
              "description": "5G频宽",
              "enum": [
                20,
                40,
                80
              ],
              "example": 40
            },
            "port1_vlan": {
              "type": "string",
              "description": "端口1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port1_vlan_id": {
              "type": "integer",
              "description": "端口1 VLAN ID (1-4090)",
              "example": 1
            },
            "port2_vlan": {
              "type": "string",
              "description": "端口2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port2_vlan_id": {
              "type": "integer",
              "description": "端口2 VLAN ID",
              "example": 1
            },
            "port3_vlan": {
              "type": "string",
              "description": "端口3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port3_vlan_id": {
              "type": "integer",
              "description": "端口3 VLAN ID",
              "example": 1
            },
            "port4_vlan": {
              "type": "string",
              "description": "端口4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port4_vlan_id": {
              "type": "integer",
              "description": "端口4 VLAN ID",
              "example": 1
            },
            "ap_roaming": {
              "type": "integer",
              "description": "AP快速漫游灵敏度设置 (0-5，分别对应关闭、极低、低、中、高、极高)",
              "minimum": 0,
              "maximum": 5,
              "example": 1
            },
            "perfer_5g": {
              "type": "integer",
              "description": "5G优先 (0:关闭, 1:开启)",
              "example": 1
            },
            "studio_mode": {
              "type": "integer",
              "description": "工作室模式开关",
              "example": 0
            },
            "gateway_check": {
              "type": "integer",
              "description": "网关检测开关",
              "example": 0
            },
            "country": {
              "type": "string",
              "description": "地区/国家码",
              "enum": [
                "CN",
                "US",
                "TW"
              ],
              "example": "CN"
            },
            "ssid_union": {
              "type": "integer",
              "description": "多频合一 (合并后只保存2.4G的参数配置即可)",
              "example": 0
            },
            "ssid5": {
              "type": "string",
              "description": "2.4G SSID3名称 (31个字符限制)",
              "example": ""
            },
            "ssid6": {
              "type": "string",
              "description": "2.4G SSID4名称 (31个字符限制)",
              "example": ""
            },
            "hide_ssid5": {
              "type": "integer",
              "description": "2.4G隐藏SSID3开关",
              "example": 0
            },
            "hide_ssid6": {
              "type": "integer",
              "description": "2.4G隐藏SSID4开关",
              "example": 0
            },
            "isolate5": {
              "type": "integer",
              "description": "2.4G SSID3访客模式开关",
              "example": 0
            },
            "isolate6": {
              "type": "integer",
              "description": "2.4G SSID4访客模式开关",
              "example": 0
            },
            "enc5": {
              "type": "string",
              "description": "2.4G SSID3加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key5": {
              "type": "string",
              "description": "2.4G SSID3密码",
              "example": ""
            },
            "enc6": {
              "type": "string",
              "description": "2.4G SSID4加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key6": {
              "type": "string",
              "description": "2.4G SSID4密码",
              "example": ""
            },
            "ssid5_vlan": {
              "type": "string",
              "description": "2.4G SSID3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid5_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID3 VLAN ID",
              "example": 0
            },
            "ssid6_vlan": {
              "type": "string",
              "description": "2.4G SSID4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid6_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID4 VLAN ID",
              "example": 0
            },
            "ssid5_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID3限速开关",
              "example": 0
            },
            "ssid5_upload": {
              "type": "integer",
              "description": "2.4G SSID3上行限速",
              "example": 0
            },
            "ssid5_download": {
              "type": "integer",
              "description": "2.4G SSID3下行限速",
              "example": 0
            },
            "ssid6_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID4限速开关",
              "example": 0
            },
            "ssid6_upload": {
              "type": "integer",
              "description": "2.4G SSID4上行限速",
              "example": 0
            },
            "ssid6_download": {
              "type": "integer",
              "description": "2.4G SSID4下行限速",
              "example": 0
            },
            "auth_server5": {
              "type": "string",
              "description": "2.4G SSID3 RADIUS服务器IP",
              "example": ""
            },
            "auth_port5": {
              "type": "integer",
              "description": "2.4G SSID3 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret5": {
              "type": "string",
              "description": "2.4G SSID3 RADIUS密钥",
              "example": ""
            },
            "slave_auth5": {
              "type": "integer",
              "description": "2.4G SSID3备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server5": {
              "type": "string",
              "description": "2.4G SSID3备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port5": {
              "type": "integer",
              "description": "2.4G SSID3备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret5": {
              "type": "string",
              "description": "2.4G SSID3备份RADIUS密钥",
              "example": ""
            },
            "auth_server6": {
              "type": "string",
              "description": "2.4G SSID4 RADIUS服务器IP",
              "example": ""
            },
            "auth_port6": {
              "type": "integer",
              "description": "2.4G SSID4 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret6": {
              "type": "string",
              "description": "2.4G SSID4 RADIUS密钥",
              "example": ""
            },
            "slave_auth6": {
              "type": "integer",
              "description": "2.4G SSID4备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server6": {
              "type": "string",
              "description": "2.4G SSID4备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port6": {
              "type": "integer",
              "description": "2.4G SSID4备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret6": {
              "type": "string",
              "description": "2.4G SSID4备份RADIUS密钥",
              "example": ""
            },
            "ssid7": {
              "type": "string",
              "description": "5G SSID3名称 (31个字符限制)",
              "example": ""
            },
            "ssid8": {
              "type": "string",
              "description": "5G SSID4名称 (31个字符限制)",
              "example": ""
            },
            "hide_ssid7": {
              "type": "integer",
              "description": "5G隐藏SSID3开关",
              "example": 0
            },
            "hide_ssid8": {
              "type": "integer",
              "description": "5G隐藏SSID4开关",
              "example": 0
            },
            "isolate7": {
              "type": "integer",
              "description": "5G SSID3访客模式开关",
              "example": 0
            },
            "isolate8": {
              "type": "integer",
              "description": "5G SSID4访客模式开关",
              "example": 0
            },
            "enc7": {
              "type": "string",
              "description": "5G SSID3加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key7": {
              "type": "string",
              "description": "5G SSID3密码",
              "example": ""
            },
            "enc8": {
              "type": "string",
              "description": "5G SSID4加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key8": {
              "type": "string",
              "description": "5G SSID4密码",
              "example": ""
            },
            "ssid7_vlan": {
              "type": "string",
              "description": "5G SSID3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid7_vlan_id": {
              "type": "integer",
              "description": "5G SSID3 VLAN ID",
              "example": 0
            },
            "ssid8_vlan": {
              "type": "string",
              "description": "5G SSID4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid8_vlan_id": {
              "type": "integer",
              "description": "5G SSID4 VLAN ID",
              "example": 0
            },
            "ssid7_ratelimit": {
              "type": "integer",
              "description": "5G SSID3限速开关",
              "example": 0
            },
            "ssid7_upload": {
              "type": "integer",
              "description": "5G SSID3上行限速",
              "example": 0
            },
            "ssid7_download": {
              "type": "integer",
              "description": "5G SSID3下行限速",
              "example": 0
            },
            "ssid8_ratelimit": {
              "type": "integer",
              "description": "5G SSID4限速开关",
              "example": 0
            },
            "ssid8_upload": {
              "type": "integer",
              "description": "5G SSID4上行限速",
              "example": 0
            },
            "ssid8_download": {
              "type": "integer",
              "description": "5G SSID4下行限速",
              "example": 0
            },
            "auth_server7": {
              "type": "string",
              "description": "5G SSID3 RADIUS服务器IP",
              "example": ""
            },
            "auth_port7": {
              "type": "integer",
              "description": "5G SSID3 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret7": {
              "type": "string",
              "description": "5G SSID3 RADIUS密钥",
              "example": ""
            },
            "slave_auth7": {
              "type": "integer",
              "description": "5G SSID3备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server7": {
              "type": "string",
              "description": "5G SSID3备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port7": {
              "type": "integer",
              "description": "5G SSID3备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret7": {
              "type": "string",
              "description": "5G SSID3备份RADIUS密钥",
              "example": ""
            },
            "auth_server8": {
              "type": "string",
              "description": "5G SSID4 RADIUS服务器IP",
              "example": ""
            },
            "auth_port8": {
              "type": "integer",
              "description": "5G SSID4 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret8": {
              "type": "string",
              "description": "5G SSID4 RADIUS密钥",
              "example": ""
            },
            "slave_auth8": {
              "type": "integer",
              "description": "5G SSID4备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server8": {
              "type": "string",
              "description": "5G SSID4备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port8": {
              "type": "integer",
              "description": "5G SSID4备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret8": {
              "type": "string",
              "description": "5G SSID4备份RADIUS密钥",
              "example": ""
            },
            "ssid9": {
              "type": "string",
              "description": "5G Radio2 SSID1名称 (31个字符限制)",
              "example": ""
            },
            "ssid10": {
              "type": "string",
              "description": "5G Radio2 SSID2名称 (31个字符限制)",
              "example": ""
            },
            "ssid11": {
              "type": "string",
              "description": "5G Radio2 SSID3名称 (31个字符限制)",
              "example": ""
            },
            "ssid12": {
              "type": "string",
              "description": "5G Radio2 SSID4名称 (31个字符限制)",
              "example": ""
            },
            "hide_ssid9": {
              "type": "integer",
              "description": "5G Radio2 SSID1隐藏开关",
              "example": 0
            },
            "hide_ssid10": {
              "type": "integer",
              "description": "5G Radio2 SSID2隐藏开关",
              "example": 0
            },
            "hide_ssid11": {
              "type": "integer",
              "description": "5G Radio2 SSID3隐藏开关",
              "example": 0
            },
            "hide_ssid12": {
              "type": "integer",
              "description": "5G Radio2 SSID4隐藏开关",
              "example": 0
            },
            "isolate9": {
              "type": "integer",
              "description": "5G Radio2 SSID1访客模式",
              "example": 0
            },
            "isolate10": {
              "type": "integer",
              "description": "5G Radio2 SSID2访客模式",
              "example": 0
            },
            "isolate11": {
              "type": "integer",
              "description": "5G Radio2 SSID3访客模式",
              "example": 0
            },
            "isolate12": {
              "type": "integer",
              "description": "5G Radio2 SSID4访客模式",
              "example": 0
            },
            "enc9": {
              "type": "string",
              "description": "5G Radio2 SSID1加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key9": {
              "type": "string",
              "description": "5G Radio2 SSID1密码",
              "example": ""
            },
            "enc10": {
              "type": "string",
              "description": "5G Radio2 SSID2加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key10": {
              "type": "string",
              "description": "5G Radio2 SSID2密码",
              "example": ""
            },
            "enc11": {
              "type": "string",
              "description": "5G Radio2 SSID3加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key11": {
              "type": "string",
              "description": "5G Radio2 SSID3密码",
              "example": ""
            },
            "enc12": {
              "type": "string",
              "description": "5G Radio2 SSID4加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key12": {
              "type": "string",
              "description": "5G Radio2 SSID4密码",
              "example": ""
            },
            "ssid9_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid9_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID1 VLAN ID",
              "example": 1
            },
            "ssid10_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid10_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID2 VLAN ID",
              "example": 1
            },
            "ssid11_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid11_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID3 VLAN ID",
              "example": 1
            },
            "ssid12_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid12_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID4 VLAN ID",
              "example": 1
            },
            "ssid9_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID1限速开关",
              "example": 0
            },
            "ssid9_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID1上行限速",
              "example": 0
            },
            "ssid9_download": {
              "type": "integer",
              "description": "5G Radio2 SSID1下行限速",
              "example": 0
            },
            "ssid10_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID2限速开关",
              "example": 0
            },
            "ssid10_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID2上行限速",
              "example": 0
            },
            "ssid10_download": {
              "type": "integer",
              "description": "5G Radio2 SSID2下行限速",
              "example": 0
            },
            "ssid11_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID3限速开关",
              "example": 0
            },
            "ssid11_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID3上行限速",
              "example": 0
            },
            "ssid11_download": {
              "type": "integer",
              "description": "5G Radio2 SSID3下行限速",
              "example": 0
            },
            "ssid12_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID4限速开关",
              "example": 0
            },
            "ssid12_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID4上行限速",
              "example": 0
            },
            "ssid12_download": {
              "type": "integer",
              "description": "5G Radio2 SSID4下行限速",
              "example": 0
            },
            "auth_server9": {
              "type": "string",
              "description": "5G Radio2 SSID1 RADIUS服务器IP",
              "example": ""
            },
            "auth_port9": {
              "type": "integer",
              "description": "5G Radio2 SSID1 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret9": {
              "type": "string",
              "description": "5G Radio2 SSID1 RADIUS密钥",
              "example": ""
            },
            "slave_auth9": {
              "type": "integer",
              "description": "5G Radio2 SSID1备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server9": {
              "type": "string",
              "description": "5G Radio2 SSID1备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port9": {
              "type": "integer",
              "description": "5G Radio2 SSID1备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret9": {
              "type": "string",
              "description": "5G Radio2 SSID1备份RADIUS密钥",
              "example": ""
            },
            "auth_server10": {
              "type": "string",
              "description": "5G Radio2 SSID2 RADIUS服务器IP",
              "example": ""
            },
            "auth_port10": {
              "type": "integer",
              "description": "5G Radio2 SSID2 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret10": {
              "type": "string",
              "description": "5G Radio2 SSID2 RADIUS密钥",
              "example": ""
            },
            "slave_auth10": {
              "type": "integer",
              "description": "5G Radio2 SSID2备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server10": {
              "type": "string",
              "description": "5G Radio2 SSID2备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port10": {
              "type": "integer",
              "description": "5G Radio2 SSID2备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret10": {
              "type": "string",
              "description": "5G Radio2 SSID2备份RADIUS密钥",
              "example": ""
            },
            "auth_server11": {
              "type": "string",
              "description": "5G Radio2 SSID3 RADIUS服务器IP",
              "example": ""
            },
            "auth_port11": {
              "type": "integer",
              "description": "5G Radio2 SSID3 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret11": {
              "type": "string",
              "description": "5G Radio2 SSID3 RADIUS密钥",
              "example": ""
            },
            "slave_auth11": {
              "type": "integer",
              "description": "5G Radio2 SSID3备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server11": {
              "type": "string",
              "description": "5G Radio2 SSID3备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port11": {
              "type": "integer",
              "description": "5G Radio2 SSID3备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret11": {
              "type": "string",
              "description": "5G Radio2 SSID3备份RADIUS密钥",
              "example": ""
            },
            "auth_server12": {
              "type": "string",
              "description": "5G Radio2 SSID4 RADIUS服务器IP",
              "example": ""
            },
            "auth_port12": {
              "type": "integer",
              "description": "5G Radio2 SSID4 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret12": {
              "type": "string",
              "description": "5G Radio2 SSID4 RADIUS密钥",
              "example": ""
            },
            "slave_auth12": {
              "type": "integer",
              "description": "5G Radio2 SSID4备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server12": {
              "type": "string",
              "description": "5G Radio2 SSID4备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port12": {
              "type": "integer",
              "description": "5G Radio2 SSID4备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret12": {
              "type": "string",
              "description": "5G Radio2 SSID4备份RADIUS密钥",
              "example": ""
            },
            "load_strategy_d5g": {
              "type": "integer",
              "description": "5G Radio2负载策略 (0:关闭, 1:拒绝接入, 2:隐藏SSID)",
              "example": 0
            },
            "autohide_maxsta_d5g": {
              "type": "integer",
              "description": "5G Radio2负载策略阀值1",
              "example": 1
            },
            "autohide_resume_d5g": {
              "type": "integer",
              "description": "5G Radio2负载策略阀值2",
              "example": 0
            },
            "qos_atf_d5g": {
              "type": "integer",
              "description": "5G Radio2 ATF公平调度算法",
              "example": 0
            },
            "channel_d5g": {
              "type": "integer",
              "description": "5G Radio2信道",
              "example": 0
            },
            "min_signal_d5g": {
              "type": "integer",
              "description": "5G Radio2最低连接信号",
              "example": 0
            },
            "signal_str_d5g": {
              "type": "integer",
              "description": "5G Radio2信号强度",
              "example": 0
            },
            "studio_ssid_d5g": {
              "type": "string",
              "description": "5G Radio2工作室SSID列表",
              "example": ""
            },
            "channel_width_d5g": {
              "type": "integer",
              "description": "5G Radio2频宽",
              "enum": [
                20,
                40,
                80,
                160
              ],
              "example": 40
            },
            "advanced": {
              "type": "integer",
              "description": "2.4G高级设置开关",
              "example": 0
            },
            "beacon_interval": {
              "type": "integer",
              "description": "2.4G高级设置-beacon帧间隔 (范围100-1000)",
              "minimum": 100,
              "maximum": 1000,
              "example": 200
            },
            "beacon_txpower": {
              "type": "integer",
              "description": "2.4G高级设置-beacon发射功率 (范围0-100)",
              "minimum": 0,
              "maximum": 100,
              "example": 0
            },
            "rts": {
              "type": "integer",
              "description": "2.4G高级设置-RTS门限 (0表示关闭, 范围0-2346)",
              "minimum": 0,
              "maximum": 2346,
              "example": 0
            },
            "hwmode": {
              "type": "string",
              "description": "2.4G高级设置-射频工作模式",
              "enum": [
                "11b/g/n/ax/be",
                "11b/g/n/ax",
                "11b/g/n",
                "11n",
                "11b/g"
              ],
              "example": ""
            },
            "dis_legacy": {
              "type": "string",
              "description": "2.4G高级设置-低速率接入限制",
              "example": "0"
            },
            "mgmt_rate": {
              "type": "integer",
              "description": "2.4G高级设置-管理帧速率 (1000:1Mbps, 2000:2Mbps, 5500:5.5Mbps, 6000:6Mbps, 11000:11Mbps)",
              "enum": [
                1000,
                2000,
                5500,
                6000,
                11000
              ],
              "example": 1000
            },
            "advanced_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置开关",
              "example": 0
            },
            "beacon_interval_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置-beacon帧间隔",
              "minimum": 100,
              "maximum": 1000,
              "example": 200
            },
            "beacon_txpower_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置-beacon发射功率",
              "minimum": 0,
              "maximum": 100,
              "example": 0
            },
            "rts_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置-RTS门限",
              "minimum": 0,
              "maximum": 2346,
              "example": 0
            },
            "hwmode_5g": {
              "type": "string",
              "description": "5G Radio1高级设置-射频工作模式",
              "enum": [
                "11a/n/ac/ax/be",
                "11a/n/ac/ax",
                "11a/n/ac",
                "11n",
                "11a/n"
              ],
              "example": ""
            },
            "advanced_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置开关",
              "example": 0
            },
            "beacon_interval_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置-beacon帧间隔",
              "minimum": 100,
              "maximum": 1000,
              "example": 200
            },
            "beacon_txpower_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置-beacon发射功率",
              "minimum": 0,
              "maximum": 100,
              "example": 0
            },
            "rts_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置-RTS门限",
              "minimum": 0,
              "maximum": 2346,
              "example": 0
            },
            "hwmode_d5g": {
              "type": "string",
              "description": "5G Radio2高级设置-射频工作模式",
              "enum": [
                "11a/n/ac/ax/be",
                "11a/n/ac/ax",
                "11a/n/ac",
                "11n",
                "11a/n"
              ],
              "example": ""
            },
            "band_list": {
              "type": "string",
              "description": "频宽支持列表 (为0代表AP没有提供支持列表)",
              "example": "0"
            },
            "channel_list": {
              "type": "string",
              "description": "信道支持列表 (为0代表AP没有提供支持列表)",
              "example": "0"
            },
            "studio_num": {
              "type": "integer",
              "description": "工作室模式支持的SSID数",
              "example": 0
            },
            "all_chan": {
              "type": "string",
              "description": "AP全部支持的信道，冒号间隔 (2.4G信道:5G R1信道:5G R2信道，如 1-13:36-64,100-165:149-165)",
              "example": ""
            },
            "support_5g": {
              "type": "integer",
              "description": "支持5G (0:不支持, 1:双频, 2:两个5G)",
              "example": 1
            },
            "support_wpa3": {
              "type": "integer",
              "description": "支持WPA3",
              "example": 0
            },
            "support_8021x": {
              "type": "integer",
              "description": "支持802.1X",
              "example": 1
            },
            "support_wifi6": {
              "type": "integer",
              "description": "支持WiFi6",
              "example": 0
            },
            "support_netoptimize": {
              "type": "integer",
              "description": "支持无线网优",
              "example": 1
            },
            "support_studio": {
              "type": "integer",
              "description": "支持工作室模式",
              "example": 0
            },
            "support_strategy_access_deny": {
              "type": "integer",
              "description": "支持射频拒绝接入",
              "example": 1
            },
            "support_strategy_autohide": {
              "type": "integer",
              "description": "支持射频自动隐藏",
              "example": 1
            },
            "status": {
              "type": "integer",
              "description": "新的状态标识 (-1:未开启时间, 0:未连接, 1:已连接)",
              "example": 1
            },
            "connected": {
              "type": "integer",
              "description": "连接状态 (0:断开, 1:连接)",
              "example": 1
            },
            "new_version": {
              "type": "string",
              "description": "新版本号 (格式 1.2.0 或者空字符串)",
              "example": ""
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "example": "192.168.33.2"
            },
            "on_channel": {
              "type": "string",
              "description": "当前信道",
              "example": "11"
            },
            "upload": {
              "type": "string",
              "description": "实时流量上行",
              "example": "0"
            },
            "download": {
              "type": "string",
              "description": "实时流量下行",
              "example": "62195"
            },
            "total_up": {
              "type": "integer",
              "description": "总上行流量",
              "example": 2157886486
            },
            "total_down": {
              "type": "integer",
              "description": "总下行流量",
              "example": 64546750016
            },
            "online": {
              "type": "integer",
              "description": "在线终端数量 (2.4G)",
              "example": 0
            },
            "bssid1": {
              "type": "string",
              "description": "2.4G BSSID1",
              "example": "08:9b:4b:1a:42:7d"
            },
            "bssid2": {
              "type": "string",
              "description": "2.4G BSSID2",
              "example": "0e:9b:4b:1a:42:7d"
            },
            "uptime": {
              "type": "integer",
              "description": "运行时间",
              "example": 4057411
            },
            "online_5g": {
              "type": "integer",
              "description": "在线终端数量 (5G Radio1)",
              "example": 0
            },
            "on_channel_5g": {
              "type": "string",
              "description": "5G Radio1当前信道",
              "example": "44"
            },
            "bssid1_5g": {
              "type": "string",
              "description": "5G Radio1 BSSID1",
              "example": "08:9b:4b:1a:42:7e"
            },
            "bssid2_5g": {
              "type": "string",
              "description": "5G Radio1 BSSID2",
              "example": "0e:9b:4b:1a:42:7e"
            },
            "link_speed": {
              "type": "integer",
              "description": "连接速率 (0:未知, 10/100/1000/10000 Mbps)",
              "enum": [
                0,
                10,
                100,
                1000,
                10000
              ],
              "example": 0
            },
            "mac": {
              "type": "string",
              "description": "AP MAC地址",
              "example": "08:9b:4b:1a:42:7c"
            },
            "pa_support": {
              "type": "integer",
              "description": "支持PA功放",
              "example": 0
            },
            "firmware": {
              "type": "string",
              "description": "固件名称",
              "example": "IK-WAQCA9531_H13V2_5G"
            },
            "version": {
              "type": "string",
              "description": "AP版本号",
              "example": "1.7.5"
            },
            "ap_model": {
              "type": "string",
              "description": "AP型号",
              "example": "IK-H13"
            }
          }
        },
        "APConfigUpdate": {
          "type": "object",
          "description": "AP配置更新参数",
          "required": [
            "id",
            "tagname",
            "comment",
            "gid",
            "mlo_radio0",
            "mlo_radio1",
            "mlo_radio2",
            "flicker",
            "lights",
            "ssid1",
            "ssid2",
            "hide_ssid1",
            "hide_ssid2",
            "isolate1",
            "isolate2",
            "qos_atf",
            "load_strategy",
            "autohide_maxsta",
            "autohide_resume",
            "max_pc",
            "channel",
            "min_signal",
            "enc1",
            "key1",
            "enc2",
            "key2",
            "ssid1_vlan",
            "ssid1_vlan_id",
            "ssid2_vlan",
            "ssid2_vlan_id",
            "ssid1_ratelimit",
            "ssid1_upload",
            "ssid1_download",
            "ssid2_ratelimit",
            "ssid2_upload",
            "ssid2_download",
            "auth_server1",
            "auth_port1",
            "acct_secret1",
            "slave_auth1",
            "slave_auth_server1",
            "slave_auth_port1",
            "slave_acct_secret1",
            "auth_server2",
            "auth_port2",
            "acct_secret2",
            "slave_auth2",
            "slave_auth_server2",
            "slave_auth_port2",
            "slave_acct_secret2",
            "signal_str",
            "studio_ssid",
            "ssid3",
            "ssid4",
            "hide_ssid3",
            "hide_ssid4",
            "isolate3",
            "isolate4",
            "qos_atf_5g",
            "load_strategy_5g",
            "autohide_maxsta_5g",
            "autohide_resume_5g",
            "max_pc_5g",
            "channel_5g",
            "min_signal_5g",
            "enc3",
            "key3",
            "enc4",
            "key4",
            "ssid3_vlan",
            "ssid3_vlan_id",
            "ssid4_vlan",
            "ssid4_vlan_id",
            "ssid3_ratelimit",
            "ssid3_upload",
            "ssid3_download",
            "ssid4_ratelimit",
            "ssid4_upload",
            "ssid4_download",
            "auth_server3",
            "auth_port3",
            "acct_secret3",
            "slave_auth3",
            "slave_auth_server3",
            "slave_auth_port3",
            "slave_acct_secret3",
            "auth_server4",
            "auth_port4",
            "acct_secret4",
            "slave_auth4",
            "slave_auth_server4",
            "slave_auth_port4",
            "slave_acct_secret4",
            "signal_str_5g",
            "studio_ssid_5g",
            "task_switch1",
            "task_strategy1",
            "task_date1",
            "task_time1",
            "task_switch2",
            "task_strategy2",
            "task_date2",
            "task_time2",
            "task_switch3",
            "task_strategy3",
            "task_date3",
            "task_time3",
            "reboot_strategy",
            "reboot_date",
            "channel_width_2g",
            "channel_width_5g",
            "port1_vlan",
            "port1_vlan_id",
            "port2_vlan",
            "port2_vlan_id",
            "port3_vlan",
            "port3_vlan_id",
            "port4_vlan",
            "port4_vlan_id",
            "ap_roaming",
            "perfer_5g",
            "studio_mode",
            "gateway_check",
            "country",
            "ssid_union",
            "ssid5",
            "ssid6",
            "hide_ssid5",
            "hide_ssid6",
            "isolate5",
            "isolate6",
            "enc5",
            "key5",
            "enc6",
            "key6",
            "ssid5_vlan",
            "ssid5_vlan_id",
            "ssid6_vlan",
            "ssid6_vlan_id",
            "ssid5_ratelimit",
            "ssid5_upload",
            "ssid5_download",
            "ssid6_ratelimit",
            "ssid6_upload",
            "ssid6_download",
            "auth_server5",
            "auth_port5",
            "acct_secret5",
            "slave_auth5",
            "slave_auth_server5",
            "slave_auth_port5",
            "slave_acct_secret5",
            "auth_server6",
            "auth_port6",
            "acct_secret6",
            "slave_auth6",
            "slave_auth_server6",
            "slave_auth_port6",
            "slave_acct_secret6",
            "ssid7",
            "ssid8",
            "hide_ssid7",
            "hide_ssid8",
            "isolate7",
            "isolate8",
            "enc7",
            "key7",
            "enc8",
            "key8",
            "ssid7_vlan",
            "ssid7_vlan_id",
            "ssid8_vlan",
            "ssid8_vlan_id",
            "ssid7_ratelimit",
            "ssid7_upload",
            "ssid7_download",
            "ssid8_ratelimit",
            "ssid8_upload",
            "ssid8_download",
            "auth_server7",
            "auth_port7",
            "acct_secret7",
            "slave_auth7",
            "slave_auth_server7",
            "slave_auth_port7",
            "slave_acct_secret7",
            "auth_server8",
            "auth_port8",
            "acct_secret8",
            "slave_auth8",
            "slave_auth_server8",
            "slave_auth_port8",
            "slave_acct_secret8",
            "ssid9",
            "ssid10",
            "ssid11",
            "ssid12",
            "hide_ssid9",
            "hide_ssid10",
            "hide_ssid11",
            "hide_ssid12",
            "isolate9",
            "isolate10",
            "isolate11",
            "isolate12",
            "enc9",
            "key9",
            "enc10",
            "key10",
            "enc11",
            "key11",
            "enc12",
            "key12",
            "ssid9_vlan",
            "ssid9_vlan_id",
            "ssid10_vlan",
            "ssid10_vlan_id",
            "ssid11_vlan",
            "ssid11_vlan_id",
            "ssid12_vlan",
            "ssid12_vlan_id",
            "ssid9_ratelimit",
            "ssid9_upload",
            "ssid9_download",
            "ssid10_ratelimit",
            "ssid10_upload",
            "ssid10_download",
            "ssid11_ratelimit",
            "ssid11_upload",
            "ssid11_download",
            "ssid12_ratelimit",
            "ssid12_upload",
            "ssid12_download",
            "auth_server9",
            "auth_port9",
            "acct_secret9",
            "slave_auth9",
            "slave_auth_server9",
            "slave_auth_port9",
            "slave_acct_secret9",
            "auth_server10",
            "auth_port10",
            "acct_secret10",
            "slave_auth10",
            "slave_auth_server10",
            "slave_auth_port10",
            "slave_acct_secret10",
            "auth_server11",
            "auth_port11",
            "acct_secret11",
            "slave_auth11",
            "slave_auth_server11",
            "slave_auth_port11",
            "slave_acct_secret11",
            "auth_server12",
            "auth_port12",
            "acct_secret12",
            "slave_auth12",
            "slave_auth_server12",
            "slave_auth_port12",
            "slave_acct_secret12",
            "load_strategy_d5g",
            "autohide_maxsta_d5g",
            "autohide_resume_d5g",
            "qos_atf_d5g",
            "channel_d5g",
            "min_signal_d5g",
            "signal_str_d5g",
            "studio_ssid_d5g",
            "channel_width_d5g",
            "advanced",
            "beacon_interval",
            "beacon_txpower",
            "rts",
            "hwmode",
            "dis_legacy",
            "mgmt_rate",
            "advanced_5g",
            "beacon_interval_5g",
            "beacon_txpower_5g",
            "rts_5g",
            "hwmode_5g",
            "advanced_d5g",
            "beacon_interval_d5g",
            "beacon_txpower_d5g",
            "rts_d5g",
            "hwmode_d5g"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "description": "AP配置ID (主键)",
              "example": 1
            },
            "gid": {
              "type": "string",
              "description": "AP所属分组ID，0表示未加入分组",
              "example": "0"
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "example": "IK-H13_427hy999"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "mlo_radio0": {
              "type": "integer",
              "description": "MLO radio0 2.4G频段开关",
              "example": 0
            },
            "mlo_radio1": {
              "type": "integer",
              "description": "MLO radio1 5G R1频段开关",
              "example": 0
            },
            "mlo_radio2": {
              "type": "integer",
              "description": "MLO radio2 5G R2频段开关",
              "example": 0
            },
            "flicker": {
              "type": "string",
              "description": "定位闪烁灯",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "lights": {
              "type": "integer",
              "description": "状态灯开关",
              "example": 1
            },
            "ssid1": {
              "type": "string",
              "description": "2.4G SSID1",
              "example": "iKuai172_2G"
            },
            "ssid2": {
              "type": "string",
              "description": "2.4G SSID2",
              "example": ""
            },
            "hide_ssid1": {
              "type": "integer",
              "description": "隐藏2.4G SSID1开关",
              "example": 0
            },
            "hide_ssid2": {
              "type": "integer",
              "description": "隐藏2.4G SSID2开关",
              "example": 0
            },
            "isolate1": {
              "type": "integer",
              "description": "2.4G SSID1的访客模式开关",
              "example": 0
            },
            "isolate2": {
              "type": "integer",
              "description": "2.4G SSID2的访客模式开关",
              "example": 0
            },
            "qos_atf": {
              "type": "integer",
              "description": "2.4G的ATF公平调度算法",
              "example": 0
            },
            "load_strategy": {
              "type": "integer",
              "description": "2.4G负载策略",
              "example": 0
            },
            "autohide_maxsta": {
              "type": "integer",
              "description": "2.4G负载策略阀值1",
              "example": 1
            },
            "autohide_resume": {
              "type": "integer",
              "description": "2.4G负载策略阀值2",
              "example": 0
            },
            "max_pc": {
              "type": "integer",
              "description": "2.4G最大带机量",
              "example": 0
            },
            "channel": {
              "type": "integer",
              "description": "2.4G信道",
              "example": 0
            },
            "min_signal": {
              "type": "integer",
              "description": "2.4G最低连接信号",
              "example": 0
            },
            "enc1": {
              "type": "string",
              "description": "2.4G SSID1加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key1": {
              "type": "string",
              "description": "2.4G SSID1密码",
              "example": "12345678"
            },
            "enc2": {
              "type": "string",
              "description": "2.4G SSID2加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key2": {
              "type": "string",
              "description": "2.4G SSID2密码",
              "example": ""
            },
            "ssid1_vlan": {
              "type": "string",
              "description": "2.4G SSID1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid1_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID1 VLAN ID",
              "example": 1
            },
            "ssid2_vlan": {
              "type": "string",
              "description": "2.4G SSID2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid2_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID2 VLAN ID",
              "example": 1
            },
            "ssid1_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID1限速开关",
              "example": 0
            },
            "ssid1_upload": {
              "type": "integer",
              "description": "2.4G SSID1上行限速",
              "example": 0
            },
            "ssid1_download": {
              "type": "integer",
              "description": "2.4G SSID1下行限速",
              "example": 0
            },
            "ssid2_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID2限速开关",
              "example": 0
            },
            "ssid2_upload": {
              "type": "integer",
              "description": "2.4G SSID2上行限速",
              "example": 0
            },
            "ssid2_download": {
              "type": "integer",
              "description": "2.4G SSID2下行限速",
              "example": 0
            },
            "auth_server1": {
              "type": "string",
              "description": "2.4G SSID1 RADIUS服务器IP",
              "example": ""
            },
            "auth_port1": {
              "type": "integer",
              "description": "2.4G SSID1 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret1": {
              "type": "string",
              "description": "2.4G SSID1 RADIUS密钥",
              "example": ""
            },
            "slave_auth1": {
              "type": "integer",
              "description": "2.4G SSID1备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server1": {
              "type": "string",
              "description": "2.4G SSID1备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port1": {
              "type": "integer",
              "description": "2.4G SSID1备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret1": {
              "type": "string",
              "description": "2.4G SSID1备份RADIUS密钥",
              "example": ""
            },
            "auth_server2": {
              "type": "string",
              "description": "2.4G SSID2 RADIUS服务器IP",
              "example": ""
            },
            "auth_port2": {
              "type": "integer",
              "description": "2.4G SSID2 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret2": {
              "type": "string",
              "description": "2.4G SSID2 RADIUS密钥",
              "example": ""
            },
            "slave_auth2": {
              "type": "integer",
              "description": "2.4G SSID2备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server2": {
              "type": "string",
              "description": "2.4G SSID2备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port2": {
              "type": "integer",
              "description": "2.4G SSID2备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret2": {
              "type": "string",
              "description": "2.4G SSID2备份RADIUS密钥",
              "example": ""
            },
            "signal_str": {
              "type": "integer",
              "description": "2.4G信号强度",
              "example": 0
            },
            "studio_ssid": {
              "type": "string",
              "description": "2.4G工作室SSID",
              "example": ""
            },
            "ssid3": {
              "type": "string",
              "description": "5G SSID1",
              "example": "iKuai172_5G"
            },
            "ssid4": {
              "type": "string",
              "description": "5G SSID2",
              "example": ""
            },
            "hide_ssid3": {
              "type": "integer",
              "description": "5G隐藏SSID1开关",
              "example": 0
            },
            "hide_ssid4": {
              "type": "integer",
              "description": "5G隐藏SSID2开关",
              "example": 0
            },
            "isolate3": {
              "type": "integer",
              "description": "5G SSID1访客模式开关",
              "example": 0
            },
            "isolate4": {
              "type": "integer",
              "description": "5G SSID2访客模式开关",
              "example": 0
            },
            "qos_atf_5g": {
              "type": "integer",
              "description": "5G ATF公平调度算法",
              "example": 0
            },
            "load_strategy_5g": {
              "type": "integer",
              "description": "5G负载策略",
              "example": 0
            },
            "autohide_maxsta_5g": {
              "type": "integer",
              "description": "5G负载策略阀值1",
              "example": 1
            },
            "autohide_resume_5g": {
              "type": "integer",
              "description": "5G负载策略阀值2",
              "example": 0
            },
            "max_pc_5g": {
              "type": "integer",
              "description": "5G最大带机量",
              "example": 0
            },
            "channel_5g": {
              "type": "integer",
              "description": "5G信道",
              "example": 0
            },
            "min_signal_5g": {
              "type": "integer",
              "description": "5G最低连接信号",
              "example": 0
            },
            "enc3": {
              "type": "string",
              "description": "5G SSID1加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "wpa2"
            },
            "key3": {
              "type": "string",
              "description": "5G SSID1密码",
              "example": "12345678"
            },
            "enc4": {
              "type": "string",
              "description": "5G SSID2加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key4": {
              "type": "string",
              "description": "5G SSID2密码",
              "example": ""
            },
            "ssid3_vlan": {
              "type": "string",
              "description": "5G SSID1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid3_vlan_id": {
              "type": "integer",
              "description": "5G SSID1 VLAN ID",
              "example": 1
            },
            "ssid4_vlan": {
              "type": "string",
              "description": "5G SSID2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid4_vlan_id": {
              "type": "integer",
              "description": "5G SSID2 VLAN ID",
              "example": 1
            },
            "ssid3_ratelimit": {
              "type": "integer",
              "description": "5G SSID1限速开关",
              "example": 0
            },
            "ssid3_upload": {
              "type": "integer",
              "description": "5G SSID1上行限速",
              "example": 0
            },
            "ssid3_download": {
              "type": "integer",
              "description": "5G SSID1下行限速",
              "example": 0
            },
            "ssid4_ratelimit": {
              "type": "integer",
              "description": "5G SSID2限速开关",
              "example": 0
            },
            "ssid4_upload": {
              "type": "integer",
              "description": "5G SSID2上行限速",
              "example": 0
            },
            "ssid4_download": {
              "type": "integer",
              "description": "5G SSID2下行限速",
              "example": 0
            },
            "auth_server3": {
              "type": "string",
              "description": "5G SSID1 RADIUS服务器IP",
              "example": ""
            },
            "auth_port3": {
              "type": "integer",
              "description": "5G SSID1 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret3": {
              "type": "string",
              "description": "5G SSID1 RADIUS密钥",
              "example": ""
            },
            "slave_auth3": {
              "type": "integer",
              "description": "5G SSID1备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server3": {
              "type": "string",
              "description": "5G SSID1备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port3": {
              "type": "integer",
              "description": "5G SSID1备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret3": {
              "type": "string",
              "description": "5G SSID1备份RADIUS密钥",
              "example": ""
            },
            "auth_server4": {
              "type": "string",
              "description": "5G SSID2 RADIUS服务器IP",
              "example": ""
            },
            "auth_port4": {
              "type": "integer",
              "description": "5G SSID2 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret4": {
              "type": "string",
              "description": "5G SSID2 RADIUS密钥",
              "example": ""
            },
            "slave_auth4": {
              "type": "integer",
              "description": "5G SSID2备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server4": {
              "type": "string",
              "description": "5G SSID2备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port4": {
              "type": "integer",
              "description": "5G SSID2备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret4": {
              "type": "string",
              "description": "5G SSID2备份RADIUS密钥",
              "example": ""
            },
            "signal_str_5g": {
              "type": "integer",
              "description": "5G信号强度",
              "example": 0
            },
            "studio_ssid_5g": {
              "type": "string",
              "description": "5G工作室SSID",
              "example": ""
            },
            "task_switch1": {
              "type": "integer",
              "description": "开启时间计划任务1",
              "example": 0
            },
            "task_strategy1": {
              "type": "string",
              "description": "任务策略1",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "task_date1": {
              "type": "string",
              "description": "任务日期1",
              "example": "2018-01-01"
            },
            "task_time1": {
              "type": "string",
              "description": "任务时间1",
              "example": "00:00-23:59"
            },
            "task_switch2": {
              "type": "integer",
              "description": "开启时间计划任务2",
              "example": 0
            },
            "task_strategy2": {
              "type": "string",
              "description": "任务策略2",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "task_date2": {
              "type": "string",
              "description": "任务日期2",
              "example": "2018-01-01"
            },
            "task_time2": {
              "type": "string",
              "description": "任务时间2",
              "example": "00:00-23:59"
            },
            "task_switch3": {
              "type": "integer",
              "description": "开启时间计划任务3",
              "example": 0
            },
            "task_strategy3": {
              "type": "string",
              "description": "任务策略3",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "task_date3": {
              "type": "string",
              "description": "任务日期3",
              "example": "2018-01-01"
            },
            "task_time3": {
              "type": "string",
              "description": "任务时间3",
              "example": "00:00-23:59"
            },
            "reboot_strategy": {
              "type": "string",
              "description": "重启策略",
              "enum": [
                "one",
                "month",
                "week"
              ],
              "example": "one"
            },
            "reboot_date": {
              "type": "string",
              "description": "重启日期",
              "example": "2018-01-01"
            },
            "channel_width_2g": {
              "type": "integer",
              "description": "2.4G频宽",
              "enum": [
                20,
                40
              ],
              "example": 20
            },
            "channel_width_5g": {
              "type": "integer",
              "description": "5G频宽",
              "enum": [
                20,
                40,
                80
              ],
              "example": 40
            },
            "port1_vlan": {
              "type": "string",
              "description": "端口1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port1_vlan_id": {
              "type": "integer",
              "description": "端口1 VLAN ID",
              "example": 1
            },
            "port2_vlan": {
              "type": "string",
              "description": "端口2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port2_vlan_id": {
              "type": "integer",
              "description": "端口2 VLAN ID",
              "example": 1
            },
            "port3_vlan": {
              "type": "string",
              "description": "端口3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port3_vlan_id": {
              "type": "integer",
              "description": "端口3 VLAN ID",
              "example": 1
            },
            "port4_vlan": {
              "type": "string",
              "description": "端口4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "port4_vlan_id": {
              "type": "integer",
              "description": "端口4 VLAN ID",
              "example": 1
            },
            "ap_roaming": {
              "type": "integer",
              "description": "AP快速漫游灵敏度设置",
              "minimum": 0,
              "maximum": 5,
              "example": 1
            },
            "perfer_5g": {
              "type": "integer",
              "description": "5G优先",
              "example": 1
            },
            "studio_mode": {
              "type": "integer",
              "description": "工作室模式开关",
              "example": 0
            },
            "gateway_check": {
              "type": "integer",
              "description": "网关检测开关",
              "example": 0
            },
            "country": {
              "type": "string",
              "description": "地区/国家码",
              "enum": [
                "CN",
                "US",
                "TW"
              ],
              "example": "CN"
            },
            "ssid_union": {
              "type": "integer",
              "description": "多频合一",
              "example": 0
            },
            "ssid5": {
              "type": "string",
              "description": "2.4G SSID3名称",
              "example": ""
            },
            "ssid6": {
              "type": "string",
              "description": "2.4G SSID4名称",
              "example": ""
            },
            "hide_ssid5": {
              "type": "integer",
              "description": "2.4G隐藏SSID3开关",
              "example": 0
            },
            "hide_ssid6": {
              "type": "integer",
              "description": "2.4G隐藏SSID4开关",
              "example": 0
            },
            "isolate5": {
              "type": "integer",
              "description": "2.4G SSID3访客模式开关",
              "example": 0
            },
            "isolate6": {
              "type": "integer",
              "description": "2.4G SSID4访客模式开关",
              "example": 0
            },
            "enc5": {
              "type": "string",
              "description": "2.4G SSID3加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key5": {
              "type": "string",
              "description": "2.4G SSID3密码",
              "example": ""
            },
            "enc6": {
              "type": "string",
              "description": "2.4G SSID4加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key6": {
              "type": "string",
              "description": "2.4G SSID4密码",
              "example": ""
            },
            "ssid5_vlan": {
              "type": "string",
              "description": "2.4G SSID3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid5_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID3 VLAN ID",
              "example": 0
            },
            "ssid6_vlan": {
              "type": "string",
              "description": "2.4G SSID4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid6_vlan_id": {
              "type": "integer",
              "description": "2.4G SSID4 VLAN ID",
              "example": 0
            },
            "ssid5_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID3限速开关",
              "example": 0
            },
            "ssid5_upload": {
              "type": "integer",
              "description": "2.4G SSID3上行限速",
              "example": 0
            },
            "ssid5_download": {
              "type": "integer",
              "description": "2.4G SSID3下行限速",
              "example": 0
            },
            "ssid6_ratelimit": {
              "type": "integer",
              "description": "2.4G SSID4限速开关",
              "example": 0
            },
            "ssid6_upload": {
              "type": "integer",
              "description": "2.4G SSID4上行限速",
              "example": 0
            },
            "ssid6_download": {
              "type": "integer",
              "description": "2.4G SSID4下行限速",
              "example": 0
            },
            "auth_server5": {
              "type": "string",
              "description": "2.4G SSID3 RADIUS服务器IP",
              "example": ""
            },
            "auth_port5": {
              "type": "integer",
              "description": "2.4G SSID3 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret5": {
              "type": "string",
              "description": "2.4G SSID3 RADIUS密钥",
              "example": ""
            },
            "slave_auth5": {
              "type": "integer",
              "description": "2.4G SSID3备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server5": {
              "type": "string",
              "description": "2.4G SSID3备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port5": {
              "type": "integer",
              "description": "2.4G SSID3备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret5": {
              "type": "string",
              "description": "2.4G SSID3备份RADIUS密钥",
              "example": ""
            },
            "auth_server6": {
              "type": "string",
              "description": "2.4G SSID4 RADIUS服务器IP",
              "example": ""
            },
            "auth_port6": {
              "type": "integer",
              "description": "2.4G SSID4 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret6": {
              "type": "string",
              "description": "2.4G SSID4 RADIUS密钥",
              "example": ""
            },
            "slave_auth6": {
              "type": "integer",
              "description": "2.4G SSID4备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server6": {
              "type": "string",
              "description": "2.4G SSID4备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port6": {
              "type": "integer",
              "description": "2.4G SSID4备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret6": {
              "type": "string",
              "description": "2.4G SSID4备份RADIUS密钥",
              "example": ""
            },
            "ssid7": {
              "type": "string",
              "description": "5G SSID3名称",
              "example": ""
            },
            "ssid8": {
              "type": "string",
              "description": "5G SSID4名称",
              "example": ""
            },
            "hide_ssid7": {
              "type": "integer",
              "description": "5G隐藏SSID3开关",
              "example": 0
            },
            "hide_ssid8": {
              "type": "integer",
              "description": "5G隐藏SSID4开关",
              "example": 0
            },
            "isolate7": {
              "type": "integer",
              "description": "5G SSID3访客模式开关",
              "example": 0
            },
            "isolate8": {
              "type": "integer",
              "description": "5G SSID4访客模式开关",
              "example": 0
            },
            "enc7": {
              "type": "string",
              "description": "5G SSID3加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key7": {
              "type": "string",
              "description": "5G SSID3密码",
              "example": ""
            },
            "enc8": {
              "type": "string",
              "description": "5G SSID4加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key8": {
              "type": "string",
              "description": "5G SSID4密码",
              "example": ""
            },
            "ssid7_vlan": {
              "type": "string",
              "description": "5G SSID3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid7_vlan_id": {
              "type": "integer",
              "description": "5G SSID3 VLAN ID",
              "example": 0
            },
            "ssid8_vlan": {
              "type": "string",
              "description": "5G SSID4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid8_vlan_id": {
              "type": "integer",
              "description": "5G SSID4 VLAN ID",
              "example": 0
            },
            "ssid7_ratelimit": {
              "type": "integer",
              "description": "5G SSID3限速开关",
              "example": 0
            },
            "ssid7_upload": {
              "type": "integer",
              "description": "5G SSID3上行限速",
              "example": 0
            },
            "ssid7_download": {
              "type": "integer",
              "description": "5G SSID3下行限速",
              "example": 0
            },
            "ssid8_ratelimit": {
              "type": "integer",
              "description": "5G SSID4限速开关",
              "example": 0
            },
            "ssid8_upload": {
              "type": "integer",
              "description": "5G SSID4上行限速",
              "example": 0
            },
            "ssid8_download": {
              "type": "integer",
              "description": "5G SSID4下行限速",
              "example": 0
            },
            "auth_server7": {
              "type": "string",
              "description": "5G SSID3 RADIUS服务器IP",
              "example": ""
            },
            "auth_port7": {
              "type": "integer",
              "description": "5G SSID3 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret7": {
              "type": "string",
              "description": "5G SSID3 RADIUS密钥",
              "example": ""
            },
            "slave_auth7": {
              "type": "integer",
              "description": "5G SSID3备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server7": {
              "type": "string",
              "description": "5G SSID3备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port7": {
              "type": "integer",
              "description": "5G SSID3备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret7": {
              "type": "string",
              "description": "5G SSID3备份RADIUS密钥",
              "example": ""
            },
            "auth_server8": {
              "type": "string",
              "description": "5G SSID4 RADIUS服务器IP",
              "example": ""
            },
            "auth_port8": {
              "type": "integer",
              "description": "5G SSID4 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret8": {
              "type": "string",
              "description": "5G SSID4 RADIUS密钥",
              "example": ""
            },
            "slave_auth8": {
              "type": "integer",
              "description": "5G SSID4备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server8": {
              "type": "string",
              "description": "5G SSID4备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port8": {
              "type": "integer",
              "description": "5G SSID4备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret8": {
              "type": "string",
              "description": "5G SSID4备份RADIUS密钥",
              "example": ""
            },
            "ssid9": {
              "type": "string",
              "description": "5G Radio2 SSID1名称",
              "example": ""
            },
            "ssid10": {
              "type": "string",
              "description": "5G Radio2 SSID2名称",
              "example": ""
            },
            "ssid11": {
              "type": "string",
              "description": "5G Radio2 SSID3名称",
              "example": ""
            },
            "ssid12": {
              "type": "string",
              "description": "5G Radio2 SSID4名称",
              "example": ""
            },
            "hide_ssid9": {
              "type": "integer",
              "description": "5G Radio2 SSID1隐藏开关",
              "example": 0
            },
            "hide_ssid10": {
              "type": "integer",
              "description": "5G Radio2 SSID2隐藏开关",
              "example": 0
            },
            "hide_ssid11": {
              "type": "integer",
              "description": "5G Radio2 SSID3隐藏开关",
              "example": 0
            },
            "hide_ssid12": {
              "type": "integer",
              "description": "5G Radio2 SSID4隐藏开关",
              "example": 0
            },
            "isolate9": {
              "type": "integer",
              "description": "5G Radio2 SSID1访客模式",
              "example": 0
            },
            "isolate10": {
              "type": "integer",
              "description": "5G Radio2 SSID2访客模式",
              "example": 0
            },
            "isolate11": {
              "type": "integer",
              "description": "5G Radio2 SSID3访客模式",
              "example": 0
            },
            "isolate12": {
              "type": "integer",
              "description": "5G Radio2 SSID4访客模式",
              "example": 0
            },
            "enc9": {
              "type": "string",
              "description": "5G Radio2 SSID1加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key9": {
              "type": "string",
              "description": "5G Radio2 SSID1密码",
              "example": ""
            },
            "enc10": {
              "type": "string",
              "description": "5G Radio2 SSID2加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key10": {
              "type": "string",
              "description": "5G Radio2 SSID2密码",
              "example": ""
            },
            "enc11": {
              "type": "string",
              "description": "5G Radio2 SSID3加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key11": {
              "type": "string",
              "description": "5G Radio2 SSID3密码",
              "example": ""
            },
            "enc12": {
              "type": "string",
              "description": "5G Radio2 SSID4加密策略",
              "enum": [
                "off",
                "wpa",
                "wpa2",
                "wpa+wpa2",
                "8021x"
              ],
              "example": "off"
            },
            "key12": {
              "type": "string",
              "description": "5G Radio2 SSID4密码",
              "example": ""
            },
            "ssid9_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID1 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid9_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID1 VLAN ID",
              "example": 1
            },
            "ssid10_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID2 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid10_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID2 VLAN ID",
              "example": 1
            },
            "ssid11_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID3 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid11_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID3 VLAN ID",
              "example": 1
            },
            "ssid12_vlan": {
              "type": "string",
              "description": "5G Radio2 SSID4 VLAN开关",
              "enum": [
                "off",
                "on"
              ],
              "example": "off"
            },
            "ssid12_vlan_id": {
              "type": "integer",
              "description": "5G Radio2 SSID4 VLAN ID",
              "example": 1
            },
            "ssid9_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID1限速开关",
              "example": 0
            },
            "ssid9_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID1上行限速",
              "example": 0
            },
            "ssid9_download": {
              "type": "integer",
              "description": "5G Radio2 SSID1下行限速",
              "example": 0
            },
            "ssid10_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID2限速开关",
              "example": 0
            },
            "ssid10_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID2上行限速",
              "example": 0
            },
            "ssid10_download": {
              "type": "integer",
              "description": "5G Radio2 SSID2下行限速",
              "example": 0
            },
            "ssid11_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID3限速开关",
              "example": 0
            },
            "ssid11_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID3上行限速",
              "example": 0
            },
            "ssid11_download": {
              "type": "integer",
              "description": "5G Radio2 SSID3下行限速",
              "example": 0
            },
            "ssid12_ratelimit": {
              "type": "integer",
              "description": "5G Radio2 SSID4限速开关",
              "example": 0
            },
            "ssid12_upload": {
              "type": "integer",
              "description": "5G Radio2 SSID4上行限速",
              "example": 0
            },
            "ssid12_download": {
              "type": "integer",
              "description": "5G Radio2 SSID4下行限速",
              "example": 0
            },
            "auth_server9": {
              "type": "string",
              "description": "5G Radio2 SSID1 RADIUS服务器IP",
              "example": ""
            },
            "auth_port9": {
              "type": "integer",
              "description": "5G Radio2 SSID1 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret9": {
              "type": "string",
              "description": "5G Radio2 SSID1 RADIUS密钥",
              "example": ""
            },
            "slave_auth9": {
              "type": "integer",
              "description": "5G Radio2 SSID1备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server9": {
              "type": "string",
              "description": "5G Radio2 SSID1备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port9": {
              "type": "integer",
              "description": "5G Radio2 SSID1备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret9": {
              "type": "string",
              "description": "5G Radio2 SSID1备份RADIUS密钥",
              "example": ""
            },
            "auth_server10": {
              "type": "string",
              "description": "5G Radio2 SSID2 RADIUS服务器IP",
              "example": ""
            },
            "auth_port10": {
              "type": "integer",
              "description": "5G Radio2 SSID2 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret10": {
              "type": "string",
              "description": "5G Radio2 SSID2 RADIUS密钥",
              "example": ""
            },
            "slave_auth10": {
              "type": "integer",
              "description": "5G Radio2 SSID2备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server10": {
              "type": "string",
              "description": "5G Radio2 SSID2备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port10": {
              "type": "integer",
              "description": "5G Radio2 SSID2备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret10": {
              "type": "string",
              "description": "5G Radio2 SSID2备份RADIUS密钥",
              "example": ""
            },
            "auth_server11": {
              "type": "string",
              "description": "5G Radio2 SSID3 RADIUS服务器IP",
              "example": ""
            },
            "auth_port11": {
              "type": "integer",
              "description": "5G Radio2 SSID3 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret11": {
              "type": "string",
              "description": "5G Radio2 SSID3 RADIUS密钥",
              "example": ""
            },
            "slave_auth11": {
              "type": "integer",
              "description": "5G Radio2 SSID3备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server11": {
              "type": "string",
              "description": "5G Radio2 SSID3备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port11": {
              "type": "integer",
              "description": "5G Radio2 SSID3备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret11": {
              "type": "string",
              "description": "5G Radio2 SSID3备份RADIUS密钥",
              "example": ""
            },
            "auth_server12": {
              "type": "string",
              "description": "5G Radio2 SSID4 RADIUS服务器IP",
              "example": ""
            },
            "auth_port12": {
              "type": "integer",
              "description": "5G Radio2 SSID4 RADIUS服务端口",
              "example": 1812
            },
            "acct_secret12": {
              "type": "string",
              "description": "5G Radio2 SSID4 RADIUS密钥",
              "example": ""
            },
            "slave_auth12": {
              "type": "integer",
              "description": "5G Radio2 SSID4备份RADIUS服务是否开启",
              "example": 0
            },
            "slave_auth_server12": {
              "type": "string",
              "description": "5G Radio2 SSID4备份RADIUS服务器IP",
              "example": ""
            },
            "slave_auth_port12": {
              "type": "integer",
              "description": "5G Radio2 SSID4备份RADIUS服务端口",
              "example": 1812
            },
            "slave_acct_secret12": {
              "type": "string",
              "description": "5G Radio2 SSID4备份RADIUS密钥",
              "example": ""
            },
            "load_strategy_d5g": {
              "type": "integer",
              "description": "5G Radio2负载策略",
              "example": 0
            },
            "autohide_maxsta_d5g": {
              "type": "integer",
              "description": "5G Radio2负载策略阀值1",
              "example": 1
            },
            "autohide_resume_d5g": {
              "type": "integer",
              "description": "5G Radio2负载策略阀值2",
              "example": 0
            },
            "qos_atf_d5g": {
              "type": "integer",
              "description": "5G Radio2 ATF公平调度算法",
              "example": 0
            },
            "channel_d5g": {
              "type": "integer",
              "description": "5G Radio2信道",
              "example": 0
            },
            "min_signal_d5g": {
              "type": "integer",
              "description": "5G Radio2最低连接信号",
              "example": 0
            },
            "signal_str_d5g": {
              "type": "integer",
              "description": "5G Radio2信号强度",
              "example": 0
            },
            "studio_ssid_d5g": {
              "type": "string",
              "description": "5G Radio2工作室SSID列表",
              "example": ""
            },
            "channel_width_d5g": {
              "type": "integer",
              "description": "5G Radio2频宽",
              "enum": [
                20,
                40,
                80,
                160
              ],
              "example": 40
            },
            "advanced": {
              "type": "integer",
              "description": "2.4G高级设置开关",
              "example": 0
            },
            "beacon_interval": {
              "type": "integer",
              "description": "2.4G高级设置-beacon帧间隔",
              "minimum": 100,
              "maximum": 1000,
              "example": 200
            },
            "beacon_txpower": {
              "type": "integer",
              "description": "2.4G高级设置-beacon发射功率",
              "minimum": 0,
              "maximum": 100,
              "example": 0
            },
            "rts": {
              "type": "integer",
              "description": "2.4G高级设置-RTS门限",
              "minimum": 0,
              "maximum": 2346,
              "example": 0
            },
            "hwmode": {
              "type": "string",
              "description": "2.4G高级设置-射频工作模式",
              "enum": [
                "11b/g/n/ax/be",
                "11b/g/n/ax",
                "11b/g/n",
                "11n",
                "11b/g"
              ],
              "example": ""
            },
            "dis_legacy": {
              "type": "string",
              "description": "2.4G高级设置-低速率接入限制",
              "example": "0"
            },
            "mgmt_rate": {
              "type": "integer",
              "description": "2.4G高级设置-管理帧速率",
              "enum": [
                1000,
                2000,
                5500,
                6000,
                11000
              ],
              "example": 1000
            },
            "advanced_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置开关",
              "example": 0
            },
            "beacon_interval_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置-beacon帧间隔",
              "minimum": 100,
              "maximum": 1000,
              "example": 200
            },
            "beacon_txpower_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置-beacon发射功率",
              "minimum": 0,
              "maximum": 100,
              "example": 0
            },
            "rts_5g": {
              "type": "integer",
              "description": "5G Radio1高级设置-RTS门限",
              "minimum": 0,
              "maximum": 2346,
              "example": 0
            },
            "hwmode_5g": {
              "type": "string",
              "description": "5G Radio1高级设置-射频工作模式",
              "enum": [
                "11a/n/ac/ax/be",
                "11a/n/ac/ax",
                "11a/n/ac",
                "11n",
                "11a/n"
              ],
              "example": ""
            },
            "advanced_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置开关",
              "example": 0
            },
            "beacon_interval_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置-beacon帧间隔",
              "minimum": 100,
              "maximum": 1000,
              "example": 200
            },
            "beacon_txpower_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置-beacon发射功率",
              "minimum": 0,
              "maximum": 100,
              "example": 0
            },
            "rts_d5g": {
              "type": "integer",
              "description": "5G Radio2高级设置-RTS门限",
              "minimum": 0,
              "maximum": 2346,
              "example": 0
            },
            "hwmode_d5g": {
              "type": "string",
              "description": "5G Radio2高级设置-射频工作模式",
              "enum": [
                "11a/n/ac/ax/be",
                "11a/n/ac/ax",
                "11a/n/ac",
                "11n",
                "11a/n"
              ],
              "example": ""
            }
          }
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer <token>\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "ac-service",
        "x-displayName": "AC服务管理",
        "description": "AC服务的启动、停止和状态查询"
      },
      {
        "name": "ap-config",
        "x-displayName": "AP配置管理",
        "description": "AP设备配置的获取和管理"
      }
    ],
    "servers": [
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ]
  },
  "wireless/wireless-wls-black.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "无线访问控制管理API",
      "version": "1.0.0",
      "summary": "无线黑白名单的完整管理功能",
      "description": "提供无线访问控制的完整管理功能，包括：\n- 无线黑白名单规则管理\n- 支持自定义MAC地址和MAC对象组\n- SSID和AP设备过滤\n- 时间段和周期控制\n- 黑白名单模式切换\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/wireless/access-control/rules": {
        "get": {
          "summary": "获取无线黑白名单列表",
          "description": "获取当前配置的无线黑白名单规则列表，支持分页功能。\n包含规则状态、模式、MAC地址列表、SSID、AP、时间控制等信息。\n",
          "operationId": "listWirelessAccessRules",
          "tags": [
            "wireless-acl"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取无线黑白名单列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessAccessRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加无线黑白名单配置",
          "description": "添加新的无线黑白名单规则，支持黑名单和白名单两种模式。\n可以设置MAC地址过滤、SSID和AP设备控制、时间段限制等。\n",
          "operationId": "createWirelessAccessRule",
          "tags": [
            "wireless-acl"
          ],
          "requestBody": {
            "required": true,
            "description": "无线黑白名单配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WirelessAccessRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "11",
                  "mode": 0,
                  "lmac": {
                    "custom": [
                      "08:9b:4b:00:10:6e"
                    ],
                    "object": [
                      {
                        "type": 2,
                        "gp_name": "mac11",
                        "gid": "MACGP23"
                      }
                    ]
                  },
                  "lssid": "10095g",
                  "lap": "08:9b:4b:01:00:01",
                  "week": "1234567",
                  "time": "00:00-23:59",
                  "comment": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessAccessErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（名称已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessAccessErrorResponse"
                  },
                  "example": {
                    "message": "规则名称已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/wireless/access-control/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/wirelessAccessRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定无线黑白名单",
          "description": "根据规则ID获取单个无线黑白名单规则的详细信息。\n",
          "operationId": "getWirelessAccessRule",
          "tags": [
            "wireless-acl"
          ],
          "responses": {
            "200": {
              "description": "成功获取无线黑白名单详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessAccessRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新无线黑白名单的配置",
          "description": "完全更新现有的无线黑白名单规则配置。\n需要提供所有字段。\n",
          "operationId": "updateWirelessAccessRule",
          "tags": [
            "wireless-acl"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的无线黑白名单配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WirelessAccessRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用无线黑白名单",
          "description": "部分更新无线黑白名单规则配置，主要用于启用/停用规则状态。\n支持修改enabled字段来控制规则的执行状态。\n",
          "operationId": "patchWirelessAccessRule",
          "tags": [
            "wireless-acl"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除无线黑白名单",
          "description": "删除指定的无线黑白名单规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteWirelessAccessRule",
          "tags": [
            "wireless-acl"
          ],
          "responses": {
            "200": {
              "description": "无线黑白名单删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "wirelessAccessRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "无线访问控制规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、enabled等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建记录ID",
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WirelessAccessErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "无线访问控制业务错误信息描述"
            }
          }
        },
        "WirelessAccessRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WirelessAccessRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessAccessRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WirelessAccessRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessAccessRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "mode",
            "lmac",
            "lssid",
            "lap",
            "week",
            "time",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "maxLength": 15,
              "example": "11"
            },
            "mode": {
              "type": "integer",
              "description": "模式，0为黑名单，1为白名单",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "lmac": {
              "$ref": "#/components/schemas/MacList"
            },
            "lssid": {
              "type": "string",
              "description": "SSID列表，ALL表示所有SSID",
              "pattern": "^[a-zA-Z0-9-_,]+$",
              "default": "ALL",
              "example": "10095g"
            },
            "lap": {
              "type": "string",
              "description": "AP列表，ALL表示所有AP，支持MAC地址格式",
              "pattern": "^[a-zA-Z0-9-_,]+$",
              "default": "ALL",
              "example": "08:9b:4b:01:00:01"
            },
            "week": {
              "type": "string",
              "description": "生效周期，1234567表示周一到周日",
              "pattern": "^[1-7]*$",
              "default": "1234567",
              "example": "1234567"
            },
            "time": {
              "type": "string",
              "description": "生效时间段，支持多个时间段用逗号分隔",
              "pattern": "^([0-9]{2}:[0-9]{2}-[0-9]{2}:[0-9]{2})(,([0-9]{2}:[0-9]{2}-[0-9]{2}:[0-9]{2}))*$",
              "default": "00:00-23:59",
              "example": "00:00-23:59"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "WirelessAccessRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "mode",
            "lmac",
            "lssid",
            "week",
            "time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "maxLength": 15,
              "example": "11"
            },
            "mode": {
              "type": "integer",
              "description": "模式，0为黑名单，1为白名单",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "lmac": {
              "$ref": "#/components/schemas/MacList"
            },
            "lssid": {
              "type": "string",
              "description": "SSID列表，ALL表示所有SSID",
              "pattern": "^[a-zA-Z0-9-_,]+$",
              "default": "ALL",
              "example": "10095g"
            },
            "lap": {
              "type": "string",
              "description": "AP列表，ALL表示所有AP，支持MAC地址格式",
              "pattern": "^[a-zA-Z0-9-_,]+$",
              "default": "ALL",
              "example": "08:9b:4b:01:00:01"
            },
            "week": {
              "type": "string",
              "description": "生效周期，1234567表示周一到周日",
              "pattern": "^[1-7]*$",
              "default": "1234567",
              "example": "1234567"
            },
            "time": {
              "type": "string",
              "description": "生效时间段，支持多个时间段用逗号分隔",
              "pattern": "^([0-9]{2}:[0-9]{2}-[0-9]{2}:[0-9]{2})(,([0-9]{2}:[0-9]{2}-[0-9]{2}:[0-9]{2}))*$",
              "default": "00:00-23:59",
              "example": "00:00-23:59"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "MacList": {
          "type": "object",
          "required": [
            "custom",
            "object"
          ],
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义MAC地址列表",
              "items": {
                "type": "string",
                "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                "example": "08:9b:4b:00:10:6e"
              },
              "example": [
                "08:9b:4b:00:10:6e",
                "08:9b:4b:00:10:0e"
              ]
            },
            "object": {
              "type": "array",
              "description": "MAC对象组列表",
              "items": {
                "$ref": "#/components/schemas/MacObject"
              },
              "example": [
                {
                  "type": 2,
                  "gp_name": "mac11",
                  "gid": "MACGP23"
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "MacObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "minimum": 1,
              "maximum": 10,
              "example": 2
            },
            "gp_name": {
              "type": "string",
              "description": "对象组名称",
              "maxLength": 50,
              "example": "mac11"
            },
            "gid": {
              "type": "string",
              "description": "对象组ID",
              "maxLength": 50,
              "example": "MACGP23"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "wireless-acl",
        "x-displayName": "无线访问控制",
        "description": "无线黑白名单规则的管理，支持MAC地址、SSID、AP、时间等控制"
      }
    ]
  },
  "wireless/wireless-wls-mvlan.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "无线终端VLAN管理API",
      "version": "1.0.0",
      "summary": "无线终端VLAN分配的完整管理功能",
      "description": "提供无线终端VLAN分配的完整管理功能，包括：\n- 无线终端VLAN规则管理\n- 支持自定义MAC地址和MAC对象组\n- SSID过滤控制\n- VLAN ID分配配置\n- 规则启用状态控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/wireless/vlan/rules": {
        "get": {
          "summary": "获取无线终端VLAN列表",
          "description": "获取当前配置的无线终端VLAN规则列表，支持分页功能。\n包含规则状态、VLAN ID、MAC地址列表、SSID配置等信息。\n",
          "operationId": "listWirelessVlanRules",
          "tags": [
            "wireless-mvlan"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取无线终端VLAN列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessVlanRuleListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加无线终端VLAN配置",
          "description": "添加新的无线终端VLAN分配规则，为特定MAC地址或MAC组\n分配指定的VLAN ID。支持SSID过滤控制。\n",
          "operationId": "createWirelessVlanRule",
          "tags": [
            "wireless-mvlan"
          ],
          "requestBody": {
            "required": true,
            "description": "无线终端VLAN配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WirelessVlanRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "22",
                  "vlanid": 11,
                  "lmac": {
                    "custom": [
                      "08:9b:4b:00:10:6e"
                    ],
                    "object": [
                      {
                        "type": 2,
                        "gp_name": "mac11",
                        "gid": "MACGP23"
                      }
                    ]
                  },
                  "lssid": "10095g",
                  "comment": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "description": "请求参数不合法",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessVlanErrorResponse"
                  },
                  "example": {
                    "message": "请求参数不合法"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "description": "资源冲突（名称已存在）",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessVlanErrorResponse"
                  },
                  "example": {
                    "message": "规则名称已存在"
                  }
                }
              }
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/wireless/vlan/rules/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/wirelessVlanRuleIdParam"
          }
        ],
        "get": {
          "summary": "获取指定无线终端VLAN",
          "description": "根据规则ID获取单个无线终端VLAN分配规则的详细信息。\n",
          "operationId": "getWirelessVlanRule",
          "tags": [
            "wireless-mvlan"
          ],
          "responses": {
            "200": {
              "description": "成功获取无线终端VLAN详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessVlanRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新无线终端VLAN的配置",
          "description": "完全更新现有的无线终端VLAN分配规则配置。\n需要提供所有字段。\n",
          "operationId": "updateWirelessVlanRule",
          "tags": [
            "wireless-mvlan"
          ],
          "requestBody": {
            "required": true,
            "description": "完整的无线终端VLAN配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WirelessVlanRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用无线终端VLAN",
          "description": "部分更新无线终端VLAN分配规则配置，主要用于启用/停用规则状态。\n支持修改enabled字段来控制规则的执行状态。\n",
          "operationId": "patchWirelessVlanRule",
          "tags": [
            "wireless-mvlan"
          ],
          "requestBody": {
            "required": true,
            "description": "部分更新数据（如启用状态）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "description": "规则启用状态",
                      "example": "yes"
                    }
                  },
                  "example": {
                    "enabled": "yes"
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除无线终端VLAN",
          "description": "删除指定的无线终端VLAN分配规则。\n删除后无法恢复，请谨慎操作。\n",
          "operationId": "deleteWirelessVlanRule",
          "tags": [
            "wireless-mvlan"
          ],
          "responses": {
            "200": {
              "description": "无线终端VLAN删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "wirelessVlanRuleIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "无线终端VLAN规则ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "example": 1
          }
        },
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、tagname、enabled、vlanid等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "id"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateSuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建记录ID",
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WirelessVlanErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "无线终端VLAN业务错误信息描述"
            }
          }
        },
        "WirelessVlanRuleListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WirelessVlanRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessVlanRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WirelessVlanRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WirelessVlanRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "vlanid",
            "lmac",
            "lssid",
            "comment"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "规则ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "maxLength": 15,
              "example": "11"
            },
            "vlanid": {
              "type": "integer",
              "description": "VLAN ID",
              "minimum": 1,
              "maximum": 4090,
              "default": 0,
              "example": 11
            },
            "lmac": {
              "$ref": "#/components/schemas/MacList"
            },
            "lssid": {
              "type": "string",
              "description": "SSID列表，不传或传空时默认匹配全部 SSID（ALL）",
              "pattern": "^[a-zA-Z0-9-_,]+$",
              "default": "ALL",
              "example": "10095g"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "WirelessVlanRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "vlanid",
            "lmac",
            "lssid"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ],
              "description": "状态，yes为启用，no为停用",
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "pattern": "^[a-zA-Z0-9_-]+$",
              "maxLength": 15,
              "example": "22"
            },
            "vlanid": {
              "type": "integer",
              "description": "VLAN ID",
              "minimum": 1,
              "maximum": 4090,
              "default": 0,
              "example": 11
            },
            "lmac": {
              "$ref": "#/components/schemas/MacList"
            },
            "lssid": {
              "type": "string",
              "description": "SSID列表，不传或传空时默认匹配全部 SSID（ALL）",
              "pattern": "^[a-zA-Z0-9-_,]+$",
              "default": "ALL",
              "example": "10095g"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "MacList": {
          "type": "object",
          "required": [
            "custom",
            "object"
          ],
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义MAC地址列表",
              "items": {
                "type": "string",
                "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                "example": "08:9b:4b:00:10:6e"
              },
              "example": [
                "08:9b:4b:00:10:6e",
                "08:9b:4b:00:10:0e"
              ]
            },
            "object": {
              "type": "array",
              "description": "MAC对象组列表",
              "items": {
                "$ref": "#/components/schemas/MacObject"
              },
              "example": [
                {
                  "type": 2,
                  "gp_name": "mac11",
                  "gid": "MACGP23"
                }
              ]
            }
          },
          "additionalProperties": false
        },
        "MacObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "minimum": 1,
              "maximum": 10,
              "example": 2
            },
            "gp_name": {
              "type": "string",
              "description": "对象组名称",
              "maxLength": 50,
              "example": "mac11"
            },
            "gid": {
              "type": "string",
              "description": "对象组ID",
              "maxLength": 50,
              "example": "MACGP23"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "wireless-mvlan",
        "x-displayName": "无线终端VLAN",
        "description": "无线终端VLAN分配规则的管理，支持MAC地址、SSID控制和VLAN ID分配"
      }
    ]
  },
  "security/security-acl-l7.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "应用协议控制API",
      "version": "1.0.0",
      "summary": "应用协议控制策略管理",
      "description": "提供应用协议控制策略的完整管理功能，包括：\n- 创建、更新、删除应用协议控制策略\n- 启用/禁用应用协议控制策略\n- 支持多种应用协议识别和控制\n- 源地址和目的地址过滤\n- 时间规则控制\n- 优先级管理\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/app-protocols/professional/rules": {
        "get": {
          "summary": "获取应用协议控制策略列表",
          "description": "获取应用协议控制策略列表，支持分页和过滤查询",
          "operationId": "getAppProtocolRules",
          "tags": [
            "acl-l7"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、action、app_proto、prio等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=action==drop\n- OR条件：filter=app_proto==HTTP,filter=app_proto==HTTPS\n- 优先级范围：filter=prio>=10&filter=prio<=50\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&action==drop"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（prio, id, create_time等）",
              "schema": {
                "type": "string",
                "enum": [
                  "prio",
                  "id",
                  "create_time"
                ],
                "default": "prio"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取应用协议控制策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建应用协议控制策略",
          "description": "创建新的应用协议控制策略，支持多种应用协议识别和控制动作\n",
          "operationId": "createAppProtocolRule",
          "tags": [
            "acl-l7"
          ],
          "requestBody": {
            "required": true,
            "description": "应用协议控制策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppProtocolRuleCreateInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "",
                  "prio": 31,
                  "action": "drop",
                  "app_proto": {
                    "custom": [
                      "其它HTTP",
                      "文件传输",
                      "DNS",
                      "Baidu"
                    ]
                  },
                  "src_addr": "",
                  "time": {
                    "custom": [
                      {
                        "start_time": "00:00",
                        "comment": "test11",
                        "end_time": "10:00",
                        "type": "weekly",
                        "weekdays": "1"
                      }
                    ]
                  },
                  "dst_addr": "",
                  "tagname": "33"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/app-protocols/professional/rules/{id}": {
        "get": {
          "summary": "获取单个应用协议控制策略",
          "description": "根据ID获取指定的应用协议控制策略详情",
          "operationId": "getAppProtocolRule",
          "tags": [
            "acl-l7"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "应用协议控制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取应用协议控制策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AppProtocolRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新应用协议控制策略",
          "description": "完整更新指定的应用协议控制策略配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateAppProtocolRule",
          "tags": [
            "acl-l7"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "应用协议控制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "应用协议控制策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppProtocolRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "",
                  "prio": 31,
                  "action": "drop",
                  "app_proto": {
                    "custom": [
                      "其它HTTP",
                      "文件传输",
                      "DNS",
                      "Baidu"
                    ]
                  },
                  "src_addr": "",
                  "time": {
                    "custom": [
                      {
                        "start_time": "00:00",
                        "comment": "test11",
                        "end_time": "10:00",
                        "type": "weekly",
                        "weekdays": "1"
                      }
                    ]
                  },
                  "dst_addr": "",
                  "tagname": "33"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用应用协议控制策略",
          "description": "切换应用协议控制策略的启用状态",
          "operationId": "toggleAppProtocolRule",
          "tags": [
            "acl-l7"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "应用协议控制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除应用协议控制策略",
          "description": "删除指定的应用协议控制策略",
          "operationId": "deleteAppProtocolRule",
          "tags": [
            "acl-l7"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "应用协议控制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "应用协议控制策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问应用协议控制策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "应用协议控制策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如优先级重复）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AppProtocolRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "action",
            "app_proto"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 2
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "prio": {
              "type": "integer",
              "description": "规则优先级（0~63, 0最高）",
              "minimum": 0,
              "maximum": 63,
              "example": 31
            },
            "action": {
              "type": "string",
              "description": "动作类型",
              "enum": [
                "accept",
                "drop"
              ],
              "example": "drop"
            },
            "app_proto": {
              "$ref": "#/components/schemas/AppProtocolObject"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "name": {
              "type": "string",
              "description": "协议名称",
              "example": "未知应用,常用协议"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:6e"
            },
            "expires": {
              "type": "integer",
              "description": "到期时间戳（0表示永不过期）",
              "minimum": 0,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "AppProtocolRuleCreateInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "action",
            "app_proto",
            "prio"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "33"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "prio": {
              "type": "integer",
              "description": "规则优先级（0~63, 0最高）",
              "minimum": 0,
              "maximum": 63,
              "example": 31
            },
            "action": {
              "type": "string",
              "description": "动作类型",
              "enum": [
                "accept",
                "drop"
              ],
              "example": "drop"
            },
            "app_proto": {
              "$ref": "#/components/schemas/AppProtocolObject"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "AppProtocolRuleInput": {
          "type": "object",
          "description": "PUT全量修改，所有字段均为必填，未修改的字段须传原值或传空值。> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。",
          "required": [
            "enabled",
            "tagname",
            "action",
            "app_proto",
            "prio",
            "comment",
            "src_addr",
            "dst_addr"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "33"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "prio": {
              "type": "integer",
              "description": "规则优先级（0~63, 0最高）",
              "minimum": 0,
              "maximum": 63,
              "example": 31
            },
            "action": {
              "type": "string",
              "description": "动作类型",
              "enum": [
                "accept",
                "drop"
              ],
              "example": "drop"
            },
            "app_proto": {
              "$ref": "#/components/schemas/AppProtocolObject"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "CreateAppProtocolRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的应用协议控制策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "AppProtocolRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/AppProtocolRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocolRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "应用协议控制策略列表",
                  "items": {
                    "$ref": "#/components/schemas/AppProtocolRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AppProtocolObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义应用协议列表",
              "items": {
                "type": "string"
              },
              "example": [
                "其它HTTP",
                "文件传输"
              ]
            },
            "object": {
              "type": "array",
              "description": "应用协议对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": [
                "192.168.1.100"
              ]
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型：\n- 0: IP对象\n- 1: IPv6对象\n- 2: MAC地址对象\n- 3: 端口对象\n- 4: 时间对象\n- 5: 协议对象\n- 6: 域名对象\n",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型：\n- 0: IP对象\n- 1: IPv6对象\n- 2: MAC地址对象\n- 3: 端口对象\n- 4: 时间对象\n- 5: 协议对象\n- 6: 域名对象\n",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "10:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateAppProtocolRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "acl-l7",
        "x-displayName": "应用协议控制",
        "description": "应用协议控制策略管理，包括协议识别、过滤动作和时间规则控制"
      }
    ]
  },
  "security/security-acl-mac.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "MAC访问控制API",
      "version": "1.0.0",
      "summary": "MAC地址访问控制完整管理",
      "description": "提供MAC地址访问控制的完整管理功能，包括：\n- MAC黑白名单模式配置（黑名单/白名单模式切换）\n- 创建、更新、删除MAC黑白名单策略\n- 启用/禁用MAC策略\n- 支持时间规则控制\n- 终端名称管理\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/mac-mode": {
        "get": {
          "summary": "获取MAC黑白名单模式",
          "description": "获取当前配置的MAC访问控制模式（黑名单或白名单模式）",
          "operationId": "getMacAclMode",
          "tags": [
            "acl-mac"
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC访问控制模式",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacAclModeResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "acl_mac": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "设置MAC黑白名单模式",
          "description": "配置MAC访问控制模式，可选择黑名单模式或白名单模式。\n- 黑名单模式：阻止指定的MAC地址访问\n- 白名单模式：仅允许指定的MAC地址访问\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateMacAclMode",
          "tags": [
            "acl-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "MAC访问控制模式配置",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MacAclModeInput"
                },
                "example": {
                  "acl_mac": 1
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "MAC访问控制模式更新成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "Success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/mac-rules": {
        "get": {
          "summary": "获取MAC黑白名单策略列表",
          "description": "获取MAC地址黑白名单策略列表，支持分页和过滤查询",
          "operationId": "getMacRules",
          "tags": [
            "acl-mac"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、mac、tagname、expires等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=expires==0\n- OR条件：filter=mac==08:9b:4b:00:10:2e,filter=mac==08:9b:4b:00:10:1e\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&mac==08:9b:4b:00:10:2e"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, create_time等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "create_time",
                  "mac"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建MAC黑白名单策略",
          "description": "创建新的MAC地址黑白名单策略，支持时间规则控制\n",
          "operationId": "createMacRule",
          "tags": [
            "acl-mac"
          ],
          "requestBody": {
            "required": true,
            "description": "MAC策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MacRuleInput"
                },
                "example": {
                  "mac": "08:9b:4b:00:10:2e",
                  "enabled": "yes",
                  "comment": "111",
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "tagname": "aaaa"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/mac-rules/{id}": {
        "get": {
          "summary": "获取单个MAC策略",
          "description": "根据ID获取指定的MAC策略详情",
          "operationId": "getMacRule",
          "tags": [
            "acl-mac"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "MAC策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取MAC策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MacRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新MAC策略",
          "description": "完整更新指定的MAC策略配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateMacRule",
          "tags": [
            "acl-mac"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "MAC策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "MAC策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MacRuleInput"
                },
                "example": {
                  "mac": "08:9b:4b:00:10:2e",
                  "enabled": "yes",
                  "comment": "111",
                  "expires": 0,
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "tagname": "aaaa"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用MAC策略",
          "description": "切换MAC策略的启用状态",
          "operationId": "toggleMacRule",
          "tags": [
            "acl-mac"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "MAC策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除MAC策略",
          "description": "删除指定的MAC策略",
          "operationId": "deleteMacRule",
          "tags": [
            "acl-mac"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "MAC策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "MAC策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问MAC策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "MAC策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "MAC地址已存在或规则名称重复"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "MacAclModeInput": {
          "type": "object",
          "required": [
            "acl_mac"
          ],
          "properties": {
            "acl_mac": {
              "type": "integer",
              "description": "MAC访问控制模式",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "MacAclModeResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "acl_mac": {
                  "type": "integer",
                  "description": "MAC访问控制模式（0:黑名单模式, 1:白名单模式）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 1
                }
              },
              "required": [
                "acl_mac"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "MacRule": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "enabled",
            "tagname"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:2e"
            },
            "enabled": {
              "type": "string",
              "description": "策略状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "aaaa"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "111"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "expires": {
              "type": "integer",
              "description": "到期时间戳（0表示永不过期）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "MacRuleInput": {
          "type": "object",
          "required": [
            "mac",
            "enabled",
            "tagname",
            "expires"
          ],
          "properties": {
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:2e"
            },
            "enabled": {
              "type": "string",
              "description": "策略状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "aaaa"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "111"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "expires": {
              "type": "integer",
              "description": "到期时间，Unix时间戳，0表示永不过期",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "CreateMacRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应代码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的MAC策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "MacRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/MacRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "MacRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "description": "MAC策略列表",
                  "items": {
                    "$ref": "#/components/schemas/MacRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "工作时间段"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateMacRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "acl-mac",
        "x-displayName": "MAC访问控制",
        "description": "MAC地址访问控制完整管理，包括黑白名单模式配置、策略创建、时间规则控制和终端名称管理"
      }
    ]
  },
  "security/security-acl.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "ACL访问控制列表API",
      "version": "1.0.0",
      "summary": "ACL访问控制策略管理",
      "description": "提供ACL访问控制列表的完整管理功能，包括：\n- 创建、更新、删除ACL策略\n- 启用/禁用ACL策略\n- 支持IPv4和IPv6地址控制\n- 协议和端口过滤\n- 时间规则控制\n- 地区归属地过滤\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/acl-rules": {
        "get": {
          "summary": "获取ACL策略列表",
          "description": "获取ACL访问控制策略列表，支持分页和过滤查询",
          "operationId": "getAclRules",
          "tags": [
            "acl-rules"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、action、protocol、ip_type、dir、prio等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=action==drop\n- OR条件：filter=protocol==tcp,filter=protocol==udp\n- 优先级范围：filter=prio>=10&filter=prio<=50\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&action==drop"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（prio, create_time等）",
              "schema": {
                "type": "string",
                "enum": [
                  "prio",
                  "create_time",
                  "id"
                ],
                "default": "prio"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取ACL策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AclRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建ACL策略",
          "description": "创建新的ACL访问控制策略，支持IPv4/IPv6地址、协议、端口等条件的过滤控制\n",
          "operationId": "createAclRule",
          "tags": [
            "acl-rules"
          ],
          "requestBody": {
            "required": true,
            "description": "ACL策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AclRuleInput"
                },
                "example": {
                  "protocol": "any",
                  "action": "drop",
                  "dir": "forward",
                  "ctdir": 0,
                  "iinterface": "any",
                  "ointerface": "any",
                  "src_addr": {
                    "custom": [
                      "192.168.9.169",
                      "08:9b:4b:00:10:6e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      },
                      {
                        "type": 2,
                        "gp_name": "22",
                        "gid": "MACIP1"
                      }
                    ]
                  },
                  "src_addr_inv": 0,
                  "dst_addr": "",
                  "dst_addr_inv": 0,
                  "dst_port": "",
                  "src_type": 0,
                  "dst_type": 0,
                  "comment": "hylitest",
                  "enabled": "yes",
                  "ip_type": "4",
                  "src6_addr": "",
                  "dst6_addr": "",
                  "src6_mode": 1,
                  "dst6_mode": 0,
                  "src6_suffix": "::abcd::ffff",
                  "dst6_suffix": "",
                  "src_area_code": "",
                  "dst_area_code": "",
                  "prio": 10,
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "tagname": "053"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/acl-rules/{id}": {
        "get": {
          "summary": "获取单个ACL策略",
          "description": "根据ID获取指定的ACL策略详情",
          "operationId": "getAclRule",
          "tags": [
            "acl-rules"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "ACL策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取ACL策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AclRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新ACL策略",
          "description": "完整更新指定的ACL策略配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateAclRule",
          "tags": [
            "acl-rules"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "ACL策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "ACL策略更新数据（全量修改，所有字段必填）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AclRuleEditInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "hylitest",
                  "dir": "forward",
                  "ctdir": 0,
                  "action": "drop",
                  "iinterface": "any",
                  "ointerface": "any",
                  "src_addr": {
                    "custom": [
                      "192.168.9.169"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "dst_addr": "",
                  "src_addr_inv": 0,
                  "dst_addr_inv": 0,
                  "protocol": "any",
                  "src_port": "",
                  "dst_port": "",
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "ip_type": "4",
                  "src6_addr": "",
                  "dst6_addr": "",
                  "src6_mode": 0,
                  "dst6_mode": 0,
                  "src6_suffix": "",
                  "dst6_suffix": "",
                  "src_type": 0,
                  "src_area_code": "",
                  "dst_type": 0,
                  "dst_area_code": "",
                  "prio": 10,
                  "tagname": "053"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用ACL策略",
          "description": "切换ACL策略的启用状态",
          "operationId": "toggleAclRule",
          "tags": [
            "acl-rules"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "ACL策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除ACL策略",
          "description": "删除指定的ACL策略",
          "operationId": "deleteAclRule",
          "tags": [
            "acl-rules"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "ACL策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "ACL策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问ACL策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "ACL策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如优先级重复）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AclRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "ip_type",
            "protocol",
            "action",
            "dir",
            "ctdir",
            "prio",
            "src_addr_inv",
            "dst_addr_inv",
            "src_type",
            "dst_type",
            "src6_mode",
            "dst6_mode",
            "iinterface",
            "ointerface"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "action": {
              "type": "string",
              "description": "动作",
              "enum": [
                "accept",
                "drop"
              ],
              "example": "drop"
            },
            "dir": {
              "type": "string",
              "description": "流量方向",
              "enum": [
                "input",
                "forward"
              ],
              "example": "forward"
            },
            "ctdir": {
              "type": "integer",
              "description": "连接方向匹配（0:关闭, 1:ORIGINAL方向, 2:REPLY方向）",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "iinterface": {
              "type": "string",
              "description": "入接口",
              "example": "any"
            },
            "ointerface": {
              "type": "string",
              "description": "出接口",
              "example": "any"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_addr_inv": {
              "type": "integer",
              "description": "源地址取反(0:不取反, 1:取反)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst_addr_inv": {
              "type": "integer",
              "description": "目的地址取反(0:不取反, 1:取反)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src_type": {
              "type": "integer",
              "description": "源类型(0:IP, 1:IP归属地)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src_area_code": {
              "type": "string",
              "description": "源地区归属地代码（国家/省/市代码）",
              "example": "CN"
            },
            "dst_type": {
              "type": "integer",
              "description": "目的类型(0:IP, 1:IP归属地)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "dst_area_code": {
              "type": "string",
              "description": "目的地区归属地代码",
              "example": "US"
            },
            "src6_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst6_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src6_mode": {
              "type": "integer",
              "description": "IPv6源后缀匹配(0:关闭, 1:开启)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "dst6_mode": {
              "type": "integer",
              "description": "IPv6目的后缀匹配(0:关闭, 1:开启)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src6_suffix": {
              "type": "string",
              "description": "IPv6后缀源地址",
              "example": "::abcd::ffff"
            },
            "dst6_suffix": {
              "type": "string",
              "description": "IPv6后缀目的地址",
              "example": ""
            },
            "prio": {
              "type": "integer",
              "description": "优先级(0-63, 0最高)",
              "minimum": 0,
              "maximum": 63,
              "example": 10
            },
            "protocol": {
              "type": "string",
              "description": "协议类型，IPv4支持：tcp/udp/tcp+udp/icmp/gre/any；IPv6支持：tcp/udp/icmpv6/any",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp",
                "icmp",
                "gre",
                "any",
                "icmpv6"
              ],
              "example": "any"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "ip_type": {
              "type": "string",
              "description": "IP类型",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "enabled": {
              "type": "string",
              "description": "策略状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "hylitest"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "acl33"
            }
          },
          "additionalProperties": false
        },
        "AclRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "ip_type",
            "dir",
            "action",
            "iinterface",
            "ointerface",
            "protocol",
            "prio",
            "tagname",
            "ctdir",
            "src_addr_inv",
            "dst_addr_inv",
            "src6_mode",
            "dst6_mode"
          ],
          "properties": {
            "action": {
              "type": "string",
              "description": "动作",
              "enum": [
                "accept",
                "drop"
              ],
              "example": "drop"
            },
            "dir": {
              "type": "string",
              "description": "流量方向",
              "enum": [
                "input",
                "forward"
              ],
              "example": "forward"
            },
            "ctdir": {
              "type": "integer",
              "description": "连接方向匹配（0:关闭, 1:ORIGINAL方向, 2:REPLY方向）",
              "enum": [
                0,
                1,
                2
              ],
              "default": 0,
              "example": 0
            },
            "iinterface": {
              "type": "string",
              "description": "入接口",
              "example": "any"
            },
            "ointerface": {
              "type": "string",
              "description": "出接口",
              "example": "any"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_addr_inv": {
              "type": "integer",
              "description": "源地址取反(0:不取反, 1:取反)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst_addr_inv": {
              "type": "integer",
              "description": "目的地址取反(0:不取反, 1:取反)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src_type": {
              "type": "integer",
              "description": "源类型(0:IP, 1:IP归属地)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src_area_code": {
              "type": "string",
              "description": "源地区归属地代码（国家/省/市代码）",
              "example": "CN"
            },
            "dst_type": {
              "type": "integer",
              "description": "目的类型(0:IP, 1:IP归属地)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "dst_area_code": {
              "type": "string",
              "description": "目的地区归属地代码",
              "example": "US"
            },
            "src6_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst6_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src6_mode": {
              "type": "integer",
              "description": "IPv6源后缀匹配(0:关闭, 1:开启)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "dst6_mode": {
              "type": "integer",
              "description": "IPv6目的后缀匹配(0:关闭, 1:开启)",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src6_suffix": {
              "type": "string",
              "description": "IPv6后缀源地址",
              "example": "::abcd::ffff"
            },
            "dst6_suffix": {
              "type": "string",
              "description": "IPv6后缀目的地址",
              "example": ""
            },
            "prio": {
              "type": "integer",
              "description": "优先级(0-63, 0最高)",
              "minimum": 0,
              "maximum": 63,
              "example": 10
            },
            "protocol": {
              "type": "string",
              "description": "协议类型，IPv4支持：tcp/udp/tcp+udp/icmp/gre/any；IPv6支持：tcp/udp/icmpv6/any",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp",
                "icmp",
                "gre",
                "any",
                "icmpv6"
              ],
              "example": "any"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "ip_type": {
              "type": "string",
              "description": "IP类型",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "enabled": {
              "type": "string",
              "description": "策略状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "hylitest"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "053"
            }
          },
          "additionalProperties": false
        },
        "AclRuleEditInput": {
          "type": "object",
          "description": "PUT全量修改时使用，所有字段均为required，未修改的字段须传原值",
          "required": [
            "enabled",
            "comment",
            "dir",
            "ctdir",
            "action",
            "iinterface",
            "ointerface",
            "src_addr",
            "dst_addr",
            "src_addr_inv",
            "dst_addr_inv",
            "protocol",
            "src_port",
            "dst_port",
            "time",
            "ip_type",
            "src6_addr",
            "dst6_addr",
            "src6_mode",
            "dst6_mode",
            "src6_suffix",
            "dst6_suffix",
            "src_type",
            "src_area_code",
            "dst_type",
            "dst_area_code",
            "prio",
            "tagname"
          ],
          "properties": {
            "action": {
              "type": "string",
              "description": "动作",
              "enum": [
                "accept",
                "drop"
              ],
              "example": "drop"
            },
            "dir": {
              "type": "string",
              "description": "流量方向",
              "enum": [
                "input",
                "forward"
              ],
              "example": "forward"
            },
            "ctdir": {
              "type": "integer",
              "description": "连接方向匹配（0:关闭, 1:ORIGINAL方向, 2:REPLY方向）",
              "enum": [
                0,
                1,
                2
              ],
              "example": 0
            },
            "iinterface": {
              "type": "string",
              "description": "入接口",
              "example": "any"
            },
            "ointerface": {
              "type": "string",
              "description": "出接口",
              "example": "any"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_addr_inv": {
              "type": "integer",
              "description": "源地址取反(0:不取反, 1:取反)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "dst_addr_inv": {
              "type": "integer",
              "description": "目的地址取反(0:不取反, 1:取反)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "src_type": {
              "type": "integer",
              "description": "源类型(0:IP, 1:IP归属地)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "src_area_code": {
              "type": "string",
              "description": "源地区归属地代码",
              "example": ""
            },
            "dst_type": {
              "type": "integer",
              "description": "目的类型(0:IP, 1:IP归属地)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "dst_area_code": {
              "type": "string",
              "description": "目的地区归属地代码",
              "example": ""
            },
            "src6_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "dst6_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src6_mode": {
              "type": "integer",
              "description": "IPv6源后缀匹配(0:关闭, 1:开启)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "dst6_mode": {
              "type": "integer",
              "description": "IPv6目的后缀匹配(0:关闭, 1:开启)",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "src6_suffix": {
              "type": "string",
              "description": "IPv6后缀源地址",
              "example": ""
            },
            "dst6_suffix": {
              "type": "string",
              "description": "IPv6后缀目的地址",
              "example": ""
            },
            "prio": {
              "type": "integer",
              "description": "优先级(0-63, 0最高)",
              "minimum": 0,
              "maximum": 63,
              "example": 10
            },
            "protocol": {
              "type": "string",
              "description": "协议类型，IPv4支持：tcp/udp/tcp+udp/icmp/gre/any；IPv6支持：tcp/udp/icmpv6/any",
              "enum": [
                "tcp",
                "udp",
                "tcp+udp",
                "icmp",
                "gre",
                "any",
                "icmpv6"
              ],
              "example": "any"
            },
            "src_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "ip_type": {
              "type": "string",
              "description": "IP类型",
              "enum": [
                "4",
                "6"
              ],
              "example": "4"
            },
            "enabled": {
              "type": "string",
              "description": "策略状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "hylitest"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "example": "053"
            }
          },
          "additionalProperties": false
        },
        "CreateAclRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的ACL策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "AclRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/AclRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AclRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "ACL策略列表",
                  "items": {
                    "$ref": "#/components/schemas/AclRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": "192.168.9.169"
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "PortObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义端口列表",
              "items": {
                "type": "string"
              },
              "example": "80,443"
            },
            "object": {
              "type": "array",
              "description": "端口对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "工作时间段"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateAclRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "acl-rules",
        "x-displayName": "ACL访问控制",
        "description": "ACL访问控制策略管理，包括IPv4/IPv6地址、协议、端口过滤控制"
      }
    ]
  },
  "security/security-advanced.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "安全中心高级设置API",
      "version": "1.0.0",
      "summary": "安全中心高级设置管理",
      "description": "提供安全中心高级设置的配置功能，包括：\n- 网络安全防护设置\n- DOS攻击防护配置\n- 连接数限制设置\n- TCP最大报文长度配置\n- 各种高级安全参数管理\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/advanced/config": {
        "get": {
          "summary": "获取安全中心高级设置",
          "description": "获取当前配置的安全中心高级设置参数",
          "operationId": "getSecurityAdvancedConfig",
          "tags": [
            "security-advanced"
          ],
          "responses": {
            "200": {
              "description": "成功获取安全中心高级设置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SecurityAdvancedConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "noping_lan": 0,
                          "noping_wan": 1,
                          "notracert": 0,
                          "hijack_ping": 0,
                          "invalid": 0,
                          "dos_lan": 1,
                          "dos_lan_num": 300,
                          "tcp_mss": 1,
                          "tcp_mss_num": 1400
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新安全中心高级设置",
          "description": "更新安全中心的高级设置参数，包括各种网络安全防护和连接限制配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateSecurityAdvancedConfig",
          "tags": [
            "security-advanced"
          ],
          "requestBody": {
            "required": true,
            "description": "安全中心高级设置配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecurityAdvancedConfigInput"
                },
                "example": {
                  "noping_lan": 0,
                  "noping_wan": 1,
                  "notracert": 0,
                  "hijack_ping": 0,
                  "invalid": 1,
                  "dos_lan": 1,
                  "dos_lan_num": 500,
                  "tcp_mss": 1,
                  "tcp_mss_num": 1460
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如唯一性冲突）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SecurityAdvancedConfig": {
          "type": "object",
          "required": [
            "id"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "noping_lan": {
              "type": "integer",
              "description": "禁止内网Ping（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "noping_wan": {
              "type": "integer",
              "description": "禁止外网Ping（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "notracert": {
              "type": "integer",
              "description": "禁止tracert追踪（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "hijack_ping": {
              "type": "integer",
              "description": "劫持Ping（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "invalid": {
              "type": "integer",
              "description": "禁止无效链接（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "dos_lan": {
              "type": "integer",
              "description": "内网DOS防御（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "dos_lan_num": {
              "type": "integer",
              "description": "内网DOS连接数限制",
              "minimum": 1,
              "maximum": 10000,
              "default": 300,
              "example": 500
            },
            "tcp_mss": {
              "type": "integer",
              "description": "启用TCPMSS最大报文长度（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "tcp_mss_num": {
              "type": "integer",
              "description": "TCPMSS最大报文长度",
              "minimum": 500,
              "maximum": 1500,
              "default": 1400,
              "example": 1460
            }
          },
          "additionalProperties": false
        },
        "SecurityAdvancedConfigInput": {
          "required": [
            "noping_lan",
            "noping_wan",
            "notracert",
            "hijack_ping",
            "invalid",
            "dos_lan",
            "dos_lan_num",
            "tcp_mss",
            "tcp_mss_num"
          ],
          "type": "object",
          "properties": {
            "noping_lan": {
              "type": "integer",
              "description": "禁止内网Ping（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "noping_wan": {
              "type": "integer",
              "description": "禁止外网Ping（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "notracert": {
              "type": "integer",
              "description": "禁止tracert追踪（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "hijack_ping": {
              "type": "integer",
              "description": "劫持Ping（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "invalid": {
              "type": "integer",
              "description": "禁止无效链接（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "dos_lan": {
              "type": "integer",
              "description": "内网DOS防御（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "dos_lan_num": {
              "type": "integer",
              "description": "内网DOS连接数限制",
              "minimum": 1,
              "maximum": 10000,
              "default": 300,
              "example": 500
            },
            "tcp_mss": {
              "type": "integer",
              "description": "启用TCPMSS最大报文长度（0:禁用, 1:启用）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "tcp_mss_num": {
              "type": "integer",
              "description": "TCPMSS最大报文长度",
              "minimum": 500,
              "maximum": 1500,
              "default": 1400,
              "example": 1460
            }
          },
          "additionalProperties": false
        },
        "SecurityAdvancedConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "安全中心高级设置列表",
                  "items": {
                    "$ref": "#/components/schemas/SecurityAdvancedConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "security-advanced",
        "x-displayName": "安全中心高级设置",
        "description": "安全中心高级配置管理，包括网络安全防护和连接限制设置"
      }
    ]
  },
  "security/security-domain-blacklist.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "域名黑名单API",
      "version": "1.0.0",
      "summary": "域名黑名单策略管理",
      "description": "提供域名黑名单策略的完整管理功能，包括：\n- 创建、更新、删除域名黑名单策略\n- 启用/禁用域名黑名单策略\n- 支持域名组管理\n- 源IP地址过滤\n- 时间规则控制\n- 分类域名控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/domain-blacklist/rules": {
        "get": {
          "summary": "获取域名黑名单策略列表",
          "description": "获取域名黑名单策略列表，支持分页和过滤查询",
          "operationId": "getDomainBlacklistRules",
          "tags": [
            "domain-blacklist"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、domain_group、tagname等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=domain_group==购物网站\n- OR条件：filter=domain_group==购物网站,filter=domain_group==游戏网站\n- 域名组模糊匹配：filter=domain_group==*购物*\n- 规则名称过滤：filter=tagname==test_rule\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&domain_group==购物网站"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, domain_group等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "domain_group"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取域名黑名单策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DomainBlacklistRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建域名黑名单策略",
          "description": "创建新的域名黑名单策略，支持域名组过滤和时间规则控制\n",
          "operationId": "createDomainBlacklistRule",
          "tags": [
            "domain-blacklist"
          ],
          "requestBody": {
            "required": true,
            "description": "域名黑名单策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainBlacklistRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "",
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "domain_group": "购物网站",
                  "src_addr": {
                    "custom": [
                      "192.168.9.16"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "tagname": "11"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/domain-blacklist/rules/{id}": {
        "get": {
          "summary": "获取单个域名黑名单策略",
          "description": "根据ID获取指定的域名黑名单策略详情",
          "operationId": "getDomainBlacklistRule",
          "tags": [
            "domain-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名黑名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取域名黑名单策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DomainBlacklistRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新域名黑名单策略",
          "description": "完整更新指定的域名黑名单策略配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateDomainBlacklistRule",
          "tags": [
            "domain-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名黑名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "域名黑名单策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainBlacklistRuleInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用域名黑名单策略",
          "description": "切换域名黑名单策略的启用状态",
          "operationId": "toggleDomainBlacklistRule",
          "tags": [
            "domain-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名黑名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除域名黑名单策略",
          "description": "删除指定的域名黑名单策略",
          "operationId": "deleteDomainBlacklistRule",
          "tags": [
            "domain-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "域名黑名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "域名黑名单策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问域名黑名单策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "域名黑名单策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "规则名称重复"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DomainBlacklistRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "domain_group"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "domain_group": {
              "type": "string",
              "description": "域名分组，多个分组用逗号分隔。可选值：\n- **交通旅游**：旅游网站、旅行社、票务预订、酒店宾馆\n- **休闲娱乐**：动漫网站、娱乐时尚、小说网站、幽默笑话、收藏爱好、星座运势、游戏网站、社交网站、视频电影、音乐网站\n- **体育健身**：体育综合、极限运动、棋牌健身、球类运动、福彩体彩\n- **医疗健康**：健康保健、美容整形\n- **新闻媒体**：广播电视、新闻报刊\n- **生活服务**：宠物玩具、求职招聘、汽车网站、餐饮美食\n- **论坛门户**：博客网站、搜索引擎、网址导航、论坛综合\n- **购物网站**：团购网站、电商网站、购物分享、返利比价\n- **金融理财**：网贷平台、证券网站、金融财经、银行保险\n",
              "example": "购物网站"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "DomainBlacklistRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "domain_group"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "domain_group": {
              "type": "string",
              "description": "域名分组，多个分组用逗号分隔。可选值：\n- **交通旅游**：旅游网站、旅行社、票务预订、酒店宾馆\n- **休闲娱乐**：动漫网站、娱乐时尚、小说网站、幽默笑话、收藏爱好、星座运势、游戏网站、社交网站、视频电影、音乐网站\n- **体育健身**：体育综合、极限运动、棋牌健身、球类运动、福彩体彩\n- **医疗健康**：健康保健、美容整形\n- **新闻媒体**：广播电视、新闻报刊\n- **生活服务**：宠物玩具、求职招聘、汽车网站、餐饮美食\n- **论坛门户**：博客网站、搜索引擎、网址导航、论坛综合\n- **购物网站**：团购网站、电商网站、购物分享、返利比价\n- **金融理财**：网贷平台、证券网站、金融财经、银行保险\n",
              "example": "购物网站"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "CreateDomainBlacklistRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的域名黑名单策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "DomainBlacklistRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/DomainBlacklistRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DomainBlacklistRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "域名黑名单策略列表",
                  "items": {
                    "$ref": "#/components/schemas/DomainBlacklistRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": "192.168.9.16"
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateDomainBlacklistRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "domain-blacklist",
        "x-displayName": "域名黑名单",
        "description": "域名黑名单策略管理，包括域名组过滤、源地址控制和时间规则管理"
      }
    ]
  },
  "security/security-l2-route.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "网络分享控制API",
      "version": "1.0.0",
      "summary": "网络分享控制策略管理",
      "description": "提供网络分享控制策略的管理功能，包括：\n- 禁止二级路由配置\n- 二级路由IP地址设置\n- 自定义TTL值配置\n- 时间规则控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/secondary-route/config": {
        "get": {
          "summary": "获取网络分享控制策略",
          "description": "获取当前配置的网络分享控制策略设置",
          "operationId": "getSecondaryRouteConfig",
          "tags": [
            "peerconn"
          ],
          "responses": {
            "200": {
              "description": "成功获取网络分享控制策略",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SecondaryRouteConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "nol2rt": 0,
                          "nol2rt_ip": {
                            "custom": [
                              "192.168.9.168"
                            ],
                            "object": [
                              {
                                "type": 0,
                                "gp_name": "11",
                                "gid": "GPIP1"
                              }
                            ]
                          },
                          "ttl_num": 1,
                          "time": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新网络分享控制策略",
          "description": "更新网络分享控制策略配置，包括禁止二级路由、IP地址设置、TTL值等参数\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateSecondaryRouteConfig",
          "tags": [
            "peerconn"
          ],
          "requestBody": {
            "required": true,
            "description": "网络分享控制策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecondaryRouteConfigInput"
                },
                "example": {
                  "nol2rt": 0,
                  "nol2rt_ip": {
                    "custom": [
                      "192.168.9.168"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "ttl_num": 1,
                  "time": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如唯一性冲突）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SecondaryRouteConfig": {
          "type": "object",
          "required": [
            "id"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "nol2rt": {
              "type": "integer",
              "description": "禁止二级路由开关（0:允许, 1:禁止）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "nol2rt_ip": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "ttl_num": {
              "type": "integer",
              "description": "自定义TTL值",
              "minimum": 1,
              "maximum": 255,
              "example": 1
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "SecondaryRouteConfigInput": {
          "type": "object",
          "required": [
            "nol2rt",
            "nol2rt_ip",
            "ttl_num",
            "time"
          ],
          "properties": {
            "nol2rt": {
              "type": "integer",
              "description": "禁止二级路由开关（0:允许, 1:禁止）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "nol2rt_ip": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "ttl_num": {
              "type": "integer",
              "description": "自定义TTL值",
              "minimum": 1,
              "maximum": 255,
              "default": 1,
              "example": 1
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "SecondaryRouteConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "网络分享控制策略列表",
                  "items": {
                    "$ref": "#/components/schemas/SecondaryRouteConfig"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string",
                "pattern": "^([0-9]{1,3}\\\\.){3}[0-9]{1,3}$",
                "example": "192.168.9.168"
              }
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "工作时间段"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "peerconn",
        "x-displayName": "网络分享控制",
        "description": "网络分享控制策略管理，包括二级路由和TTL配置"
      }
    ]
  },
  "security/security-mac-comment.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "终端名称管理API",
      "version": "1.0.0",
      "summary": "终端设备名称管理",
      "description": "提供终端设备名称管理的完整功能，包括：\n- 创建、更新、删除终端设备名称\n- 根据MAC地址管理终端设备\n- 支持设备名称和备注信息管理\n- MAC地址唯一性验证\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/terminals": {
        "get": {
          "summary": "获取终端设备列表",
          "description": "获取终端设备列表，支持分页和过滤查询",
          "operationId": "getTerminals",
          "tags": [
            "mac-comment"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：mac、tagname、comment等\n使用示例：\n- 单条件：filter=mac==08:9b:4b:00:10:6d\n- AND条件：filter=mac==08:9b:4b:00:10:6d&filter=tagname==test11\n- OR条件：filter=tagname==test11,filter=tagname==device01\n- MAC前缀匹配：filter=mac==08:9b:4b:*\n- 设备名称模糊匹配：filter=tagname==*test*\n- 备注信息过滤：filter=comment!=空\n",
              "schema": {
                "type": "string"
              },
              "example": "mac==08:9b:4b:00:10:6d"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, mac, tagname等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "mac",
                  "tagname"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取终端设备列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/TerminalsResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建终端设备名称",
          "description": "创建新的终端设备名称记录，支持MAC地址、设备名称和备注信息\n",
          "operationId": "createTerminal",
          "tags": [
            "mac-comment"
          ],
          "requestBody": {
            "required": true,
            "description": "终端设备名称配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TerminalInput"
                },
                "example": {
                  "mac": "08:9b:4b:00:10:6d",
                  "tagname": "test11",
                  "comment": "comm_11"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/terminals/{id}": {
        "get": {
          "summary": "获取单个终端设备名称",
          "description": "根据ID获取指定的终端设备名称详情",
          "operationId": "getTerminal",
          "tags": [
            "mac-comment"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "终端设备ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取终端设备名称详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/TerminalResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新终端设备名称",
          "description": "完整更新指定的终端设备名称配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateTerminal",
          "tags": [
            "mac-comment"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "终端设备ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "终端设备名称更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TerminalInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除终端设备名称",
          "description": "删除指定的终端设备名称记录",
          "operationId": "deleteTerminal",
          "tags": [
            "mac-comment"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "终端设备ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "终端设备名称删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问终端设备名称"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "终端设备不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "MAC地址已存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "Terminal": {
          "type": "object",
          "required": [
            "id",
            "mac",
            "tagname"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "设备ID",
              "minimum": 1,
              "example": 2
            },
            "mac": {
              "type": "string",
              "description": "MAC地址（唯一）",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:6d"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "test11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "comm_11"
            }
          },
          "additionalProperties": false
        },
        "TerminalInput": {
          "type": "object",
          "required": [
            "mac",
            "tagname"
          ],
          "properties": {
            "mac": {
              "type": "string",
              "description": "MAC地址（唯一）",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:6d"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "minLength": 1,
              "maxLength": 15,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "test11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": "comm_11"
            }
          },
          "additionalProperties": false
        },
        "CreateTerminalResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的终端设备ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "TerminalResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/Terminal"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "TerminalsResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "终端设备列表",
                  "items": {
                    "$ref": "#/components/schemas/Terminal"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateTerminalResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "mac-comment",
        "x-displayName": "终端名称管理",
        "description": "终端设备名称管理，包括MAC地址、设备名称和备注信息管理"
      }
    ]
  },
  "security/security-peerconn.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "连接数限制API",
      "version": "1.0.0",
      "summary": "连接数限制策略管理",
      "description": "提供连接数限制策略的完整管理功能，包括：\n- 创建、更新、删除连接数限制策略\n- 启用/禁用连接数限制策略\n- 支持源IP地址过滤\n- 协议和端口过滤\n- 连接数阈值设置\n- 时间规则控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/peerconn/rules": {
        "get": {
          "summary": "获取连接数限制策略列表",
          "description": "获取连接数限制策略列表，支持分页和过滤查询",
          "operationId": "getPeerconnRules",
          "tags": [
            "conn-limit"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、protocol、limits、tagname、dst_port等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=protocol==tcp\n- OR条件：filter=protocol==tcp,filter=protocol==udp\n- 连接数范围：filter=limits>=100&filter=limits<=10000\n- 端口过滤：filter=dst_port==80\n- 协议类型：filter=protocol==tcp (TCP) 或 filter==udp (UDP) 或 filter==any (任意协议)\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&protocol==udp"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, limits等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "limits"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取连接数限制策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PeerconnRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建连接数限制策略",
          "description": "创建新的连接数限制策略，支持协议端口过滤和连接数阈值控制\n",
          "operationId": "createPeerconnRule",
          "tags": [
            "conn-limit"
          ],
          "requestBody": {
            "required": true,
            "description": "连接数限制策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeerconnRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "src_addr": {
                    "custom": [
                      "192.168.88.50",
                      "08:9b:4b:00:10:1e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "comment": "111",
                  "protocol": "udp",
                  "dst_port": {
                    "custom": [
                      "9000",
                      "10000-20000"
                    ],
                    "object": [
                      {
                        "gid": "PORTGP26",
                        "gp_name": "ip55",
                        "type": 3
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "limits": "10000",
                  "tagname": "conn_limit_44"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/peerconn/rules/{id}": {
        "get": {
          "summary": "获取单个连接数限制策略",
          "description": "根据ID获取指定的连接数限制策略详情",
          "operationId": "getPeerconnRule",
          "tags": [
            "conn-limit"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "连接数限制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取连接数限制策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PeerconnRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新连接数限制策略",
          "description": "完整更新指定的连接数限制策略配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePeerconnRule",
          "tags": [
            "conn-limit"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "连接数限制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "连接数限制策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PeerconnRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "src_addr": {
                    "custom": [
                      "192.168.88.50",
                      "08:9b:4b:00:10:1e"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "comment": "111",
                  "protocol": "udp",
                  "dst_port": {
                    "custom": [
                      "9000",
                      "10000-20000"
                    ],
                    "object": [
                      {
                        "gid": "PORTGP26",
                        "gp_name": "ip55",
                        "type": 3
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "limits": "10000",
                  "tagname": "conn_limit_44"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用连接数限制策略",
          "description": "切换连接数限制策略的启用状态",
          "operationId": "togglePeerconnRule",
          "tags": [
            "conn-limit"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "连接数限制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除连接数限制策略",
          "description": "删除指定的连接数限制策略",
          "operationId": "deletePeerconnRule",
          "tags": [
            "conn-limit"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "连接数限制策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "连接数限制策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问连接数限制策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "连接数限制策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "规则名称重复"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "PeerconnRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "limits"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "conn_limit_44"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "111"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "tcp",
                "udp",
                "any",
                "icmp",
                "gre"
              ],
              "example": "udp"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "limits": {
              "type": "integer",
              "description": "最大允许连接数限制",
              "minimum": 1,
              "maximum": 100000,
              "example": 10000
            },
            "src_addr_int": {
              "type": "integer",
              "description": "源地址整数值",
              "format": "int64",
              "example": 4294967295
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "PeerconnRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "limits",
            "protocol"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "conn_limit_44"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "111"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "protocol": {
              "type": "string",
              "description": "协议类型",
              "enum": [
                "tcp",
                "udp",
                "any",
                "icmp",
                "gre"
              ],
              "example": "udp"
            },
            "dst_port": {
              "$ref": "#/components/schemas/PortObject"
            },
            "limits": {
              "type": "integer",
              "description": "最大允许连接数限制",
              "minimum": 1,
              "maximum": 100000,
              "example": 10000
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "CreatePeerconnRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应代码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的连接数限制策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "PeerconnRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/PeerconnRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PeerconnRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "连接数限制策略列表",
                  "items": {
                    "$ref": "#/components/schemas/PeerconnRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": [
                "192.168.88.50",
                "08:9b:4b:00:10:1e"
              ]
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "PortObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义端口列表",
              "items": {
                "type": "string"
              },
              "example": [
                "9000",
                "10000-20000"
              ]
            },
            "object": {
              "type": "array",
              "description": "端口对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreatePeerconnRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "conn-limit",
        "x-displayName": "连接数限制",
        "description": "连接数限制策略管理，包括协议端口过滤、连接数阈值和时间规则控制"
      }
    ]
  },
  "security/security-url-black.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "URL黑白名单API",
      "version": "1.0.0",
      "summary": "URL黑白名单策略管理",
      "description": "提供URL黑白名单策略的完整管理功能，包括：\n- 创建、更新、删除URL黑白名单策略\n- 启用/禁用URL黑白名单策略\n- 支持黑白名单模式切换\n- 域名过滤控制\n- 源IP地址过滤\n- 时间规则控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/url-black/rules": {
        "get": {
          "summary": "获取URL黑白名单策略列表",
          "description": "获取URL黑白名单策略列表，支持分页和过滤查询",
          "operationId": "getUrlBlackRules",
          "tags": [
            "url-blacklist"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、mode、tagname、domain等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=mode==0\n- OR条件：filter=domain==baidu.com,filter=domain==google.com\n- 黑白名单模式：filter=mode==0 (黑名单) 或 filter=mode==1 (白名单)\n- 域名前缀匹配：filter=domain==*.example.com\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&mode==0"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, domain等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "domain"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL黑白名单策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlBlackRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建URL黑白名单策略",
          "description": "创建新的URL黑白名单策略，支持域名过滤和时间规则控制\n",
          "operationId": "createUrlBlackRule",
          "tags": [
            "url-blacklist"
          ],
          "requestBody": {
            "required": true,
            "description": "URL黑白名单策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlBlackRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "",
                  "domain": {
                    "custom": [
                      "restapi.amap.com",
                      "www.baidu.com"
                    ]
                  },
                  "src_addr": {
                    "custom": [
                      "192.168.9.16"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "mode": "0",
                  "tagname": "11"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/url-black/rules/{id}": {
        "get": {
          "summary": "获取单个URL黑白名单策略",
          "description": "根据ID获取指定的URL黑白名单策略详情",
          "operationId": "getUrlBlackRule",
          "tags": [
            "url-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL黑白名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL黑白名单策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlBlackRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新URL黑白名单策略",
          "description": "完整更新指定的URL黑白名单策略配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateUrlBlackRule",
          "tags": [
            "url-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL黑白名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "URL黑白名单策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlBlackRuleEditInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "",
                  "domain": {
                    "custom": [
                      "restapi.amap.com",
                      "www.baidu.com"
                    ]
                  },
                  "src_addr": {
                    "custom": [
                      "192.168.9.16"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  },
                  "mode": "0",
                  "tagname": "11"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用URL黑白名单策略",
          "description": "切换URL黑白名单策略的启用状态",
          "operationId": "toggleUrlBlackRule",
          "tags": [
            "url-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL黑白名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除URL黑白名单策略",
          "description": "删除指定的URL黑白名单策略",
          "operationId": "deleteUrlBlackRule",
          "tags": [
            "url-blacklist"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL黑白名单策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "URL黑白名单策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问URL黑白名单策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "URL黑白名单策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "规则名称重复"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UrlBlackRule": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "mode",
            "domain"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "mode": {
              "type": "integer",
              "description": "模式",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "domain": {
              "$ref": "#/components/schemas/DomainObject"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlBlackRuleInput": {
          "type": "object",
          "required": [
            "enabled",
            "tagname",
            "mode",
            "domain"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "11"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "mode": {
              "type": "string",
              "description": "模式",
              "enum": [
                "0",
                "1"
              ],
              "example": "0"
            },
            "domain": {
              "$ref": "#/components/schemas/DomainObject"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlBlackRuleEditInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "enabled",
            "comment",
            "domain",
            "src_addr",
            "mode",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": ""
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "11"
            },
            "mode": {
              "type": "string",
              "description": "模式（0=黑名单, 1=白名单）",
              "enum": [
                "0",
                "1"
              ],
              "example": "0"
            },
            "domain": {
              "$ref": "#/components/schemas/DomainObject"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "CreateUrlBlackRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的URL黑白名单策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "UrlBlackRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/UrlBlackRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UrlBlackRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "URL黑白名单策略列表",
                  "items": {
                    "$ref": "#/components/schemas/UrlBlackRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DomainObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义域名列表",
              "items": {
                "type": "string"
              },
              "example": [
                "restapi.amap.com",
                "www.baidu.com"
              ]
            },
            "object": {
              "type": "array",
              "description": "域名对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": [
                "192.168.9.16"
              ]
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateUrlBlackRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "url-blacklist",
        "x-displayName": "URL黑白名单",
        "description": "URL黑白名单策略管理，包括域名过滤、黑白名单模式和时间规则控制"
      }
    ]
  },
  "security/security-url-keywords.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "URL关键字替换API",
      "version": "1.0.0",
      "summary": "URL关键字替换策略管理",
      "description": "提供URL关键字替换策略的完整管理功能，包括：\n- 创建、更新、删除关键字替换策略\n- 启用/禁用关键字替换策略\n- 支持精确和模糊匹配模式\n- 源IP地址和URL过滤\n- 时间规则控制\n- 替换百分比设置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/url-keywords/rules": {
        "get": {
          "summary": "获取URL关键字替换策略列表",
          "description": "获取URL关键字替换策略列表，支持分页和过滤查询",
          "operationId": "getUrlKeywordRules",
          "tags": [
            "url-keywords"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、mode、ori_keyword、rep_keyword、prio、hit_rate等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=mode==exact\n- OR条件：filter=ori_keyword==test,filter=rep_keyword==replace\n- 优先级范围：filter=prio>=1&filter=prio<=32\n- 替换率过滤：filter=hit_rate>=50\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&mode==exact"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（prio, id）",
              "schema": {
                "type": "string",
                "enum": [
                  "prio",
                  "id"
                ],
                "default": "prio"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL关键字替换策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlKeywordRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建URL关键字替换策略",
          "description": "创建新的URL关键字替换策略，支持关键字匹配和替换功能\n",
          "operationId": "createUrlKeywordRule",
          "tags": [
            "url-keywords"
          ],
          "requestBody": {
            "required": true,
            "description": "URL关键字替换策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlKeywordRuleInput"
                },
                "example": {
                  "comment": "444",
                  "prio": 1,
                  "src_addr": "",
                  "src_url": "192.168.1.253",
                  "ori_keyword": "qwe",
                  "rep_keyword": "456",
                  "mode": "exact",
                  "hit_rate": 100,
                  "id": 1,
                  "enabled": "yes",
                  "excluded": "",
                  "tagname": "test1"
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/url-keywords/rules/{id}": {
        "get": {
          "summary": "获取单个URL关键字替换策略",
          "description": "根据ID获取指定的URL关键字替换策略详情",
          "operationId": "getUrlKeywordRule",
          "tags": [
            "url-keywords"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL关键字替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL关键字替换策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlKeywordRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新URL关键字替换策略",
          "description": "完整更新指定的URL关键字替换策略配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateUrlKeywordRule",
          "tags": [
            "url-keywords"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL关键字替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "URL关键字替换策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlKeywordRuleEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用URL关键字替换策略",
          "description": "切换URL关键字替换策略的启用状态",
          "operationId": "toggleUrlKeywordRule",
          "tags": [
            "url-keywords"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL关键字替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除URL关键字替换策略",
          "description": "删除指定的URL关键字替换策略",
          "operationId": "deleteUrlKeywordRule",
          "tags": [
            "url-keywords"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL关键字替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "URL关键字替换策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问URL关键字替换策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "URL关键字替换策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如优先级重复）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UrlKeywordRule": {
          "type": "object",
          "required": [
            "id",
            "prio",
            "enabled",
            "hit_rate",
            "mode"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "prio": {
              "type": "integer",
              "description": "优先级（0-63，0最高）",
              "minimum": 0,
              "maximum": 63,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "444"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "ori_keyword": {
              "type": "string",
              "description": "原始关键字",
              "example": "qwe"
            },
            "rep_keyword": {
              "type": "string",
              "description": "替换关键字",
              "example": "456"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "替换百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlKeywordRuleInput": {
          "type": "object",
          "required": [
            "prio",
            "enabled",
            "hit_rate",
            "mode",
            "src_url",
            "ori_keyword",
            "rep_keyword",
            "tagname"
          ],
          "properties": {
            "prio": {
              "type": "integer",
              "description": "优先级（0-63，0最高）",
              "minimum": 0,
              "maximum": 63,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": ""
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "ori_keyword": {
              "type": "string",
              "description": "原始关键字",
              "example": "qwe"
            },
            "rep_keyword": {
              "type": "string",
              "description": "替换关键字",
              "example": "456"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "替换百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlKeywordRuleEditInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "enabled",
            "prio",
            "src_addr",
            "src_url",
            "ori_keyword",
            "rep_keyword",
            "mode",
            "excluded",
            "hit_rate",
            "time",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 1
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "ori_keyword": {
              "type": "string",
              "description": "原始关键字（1-50字符）",
              "minLength": 1,
              "maxLength": 50,
              "example": "qwe"
            },
            "rep_keyword": {
              "type": "string",
              "description": "替换关键字（1-40字符）",
              "minLength": 1,
              "maxLength": 40,
              "example": "456"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "替换百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "test1"
            }
          },
          "additionalProperties": false
        },
        "CreateUrlKeywordRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的URL关键字替换策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "UrlKeywordRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/UrlKeywordRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UrlKeywordRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "URL关键字替换策略列表",
                  "items": {
                    "$ref": "#/components/schemas/UrlKeywordRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": "192.168.1.100"
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "工作时间段"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateUrlKeywordRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "url-keywords",
        "x-displayName": "URL关键字替换",
        "description": "URL关键字替换策略管理，包括关键字匹配、替换和时间规则控制"
      }
    ]
  },
  "security/security-url-redirect.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "URL跳转API",
      "version": "1.0.0",
      "summary": "URL跳转策略管理",
      "description": "提供URL跳转策略的完整管理功能，包括：\n- 创建、更新、删除URL跳转策略\n- 启用/禁用URL跳转策略\n- 支持源IP地址和URL过滤\n- 目标URL跳转配置\n- 时间规则控制\n- 跳转百分比设置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/url-redirect/rules": {
        "get": {
          "summary": "获取URL跳转策略列表",
          "description": "获取URL跳转策略列表，支持分页和过滤查询",
          "operationId": "getUrlRedirectRules",
          "tags": [
            "url-redirect"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、mode、src_url、dst_url、prio、hit_rate等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=mode==exact\n- OR条件：filter=src_url==192.168.1.1,filter=dst_url==192.168.1.2\n- 优先级范围：filter=prio>=1&filter=prio<=63\n- 跳转率过滤：filter=hit_rate>=80\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&mode==exact"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（prio, id, create_time等）",
              "schema": {
                "type": "string",
                "enum": [
                  "prio",
                  "id",
                  "create_time"
                ],
                "default": "prio"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL跳转策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlRedirectRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建URL跳转策略",
          "description": "创建新的URL跳转策略，支持源地址过滤和目标URL跳转功能\n",
          "operationId": "createUrlRedirectRule",
          "tags": [
            "url-redirect"
          ],
          "requestBody": {
            "required": true,
            "description": "URL跳转策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlRedirectRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "55",
                  "prio": 32,
                  "src_url": "192.168.1.253",
                  "dst_url": "192.168.3.169",
                  "mode": "exact",
                  "excluded": "",
                  "hit_rate": 100,
                  "src_addr": {
                    "custom": [
                      "192.168.9.16"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/url-redirect/rules/{id}": {
        "get": {
          "summary": "获取单个URL跳转策略",
          "description": "根据ID获取指定的URL跳转策略详情",
          "operationId": "getUrlRedirectRule",
          "tags": [
            "url-redirect"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL跳转策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL跳转策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlRedirectRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新URL跳转策略",
          "description": "完整更新指定的URL跳转策略配置\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateUrlRedirectRule",
          "tags": [
            "url-redirect"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL跳转策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "URL跳转策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlRedirectRuleEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用URL跳转策略",
          "description": "切换URL跳转策略的启用状态",
          "operationId": "toggleUrlRedirectRule",
          "tags": [
            "url-redirect"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL跳转策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除URL跳转策略",
          "description": "删除指定的URL跳转策略",
          "operationId": "deleteUrlRedirectRule",
          "tags": [
            "url-redirect"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL跳转策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "URL跳转策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问URL跳转策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "URL跳转策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如优先级重复）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UrlRedirectRule": {
          "type": "object",
          "required": [
            "id",
            "prio",
            "enabled",
            "hit_rate",
            "mode",
            "src_url",
            "dst_url"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 32
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头；同时作为规则备注（comment），两者含义相同",
              "example": "55"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "dst_url": {
              "type": "string",
              "description": "目的URL",
              "example": "192.168.3.169"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "跳转百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlRedirectRuleInput": {
          "type": "object",
          "required": [
            "tagname",
            "prio",
            "enabled",
            "hit_rate",
            "mode",
            "src_url",
            "dst_url"
          ],
          "properties": {
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 32
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头；同时作为规则备注（comment），两者含义相同",
              "example": ""
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "dst_url": {
              "type": "string",
              "description": "目的URL",
              "example": "192.168.3.169"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "跳转百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlRedirectRuleEditInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "tagname",
            "enabled",
            "prio",
            "src_addr",
            "src_url",
            "dst_url",
            "mode",
            "excluded",
            "hit_rate",
            "time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 32
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "dst_url": {
              "type": "string",
              "description": "目的URL",
              "example": "192.168.3.169"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "跳转百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头；同时作为规则备注（comment），两者含义相同",
              "example": "test1"
            }
          },
          "additionalProperties": false
        },
        "CreateUrlRedirectRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应代码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的URL跳转策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "UrlRedirectRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/UrlRedirectRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UrlRedirectRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "URL跳转策略列表",
                  "items": {
                    "$ref": "#/components/schemas/UrlRedirectRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": "192.168.9.16"
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "工作时间段"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateUrlRedirectRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "url-redirect",
        "x-displayName": "URL跳转",
        "description": "URL跳转策略管理，包括源地址过滤、目标URL配置和时间规则控制"
      }
    ]
  },
  "security/security-url-replace.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "URL参数替换API",
      "version": "1.0.0",
      "summary": "URL参数替换策略管理",
      "description": "提供URL参数替换策略的完整管理功能，包括：\n- 创建、更新、删除URL参数替换策略\n- 启用/禁用URL参数替换策略\n- 支持参数关键字匹配和替换\n- 源IP地址和URL过滤\n- 时间规则控制\n- 替换百分比设置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/security/url-replace/rules": {
        "get": {
          "summary": "获取URL参数替换策略列表",
          "description": "获取URL参数替换策略列表，支持分页和过滤查询",
          "operationId": "getUrlReplaceRules",
          "tags": [
            "url-replace"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：enabled、mode、param_keyword、rep_keyword、prio、hit_rate等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=mode==exact\n- OR条件：filter=param_keyword==test,filter=rep_keyword==replace\n- 优先级范围：filter=prio>=1&filter=prio<=63\n- 替换率过滤：filter=hit_rate>=75\n- 参数关键字：filter=param_keyword==query\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes&mode==exact"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（prio, id）",
              "schema": {
                "type": "string",
                "enum": [
                  "prio",
                  "id"
                ],
                "default": "prio"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL参数替换策略列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlReplaceRulesResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建URL参数替换策略",
          "description": "创建新的URL参数替换策略，支持参数匹配和替换功能\n",
          "operationId": "createUrlReplaceRule",
          "tags": [
            "url-replace"
          ],
          "requestBody": {
            "required": true,
            "description": "URL参数替换策略配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlReplaceRuleInput"
                },
                "example": {
                  "enabled": "yes",
                  "tagname": "test-rule",
                  "comment": "111",
                  "prio": 1,
                  "excluded": "",
                  "src_url": "192.168.1.253",
                  "mode": "exact",
                  "hit_rate": 100,
                  "rep_keyword": "aa",
                  "param_keyword": "query",
                  "src_addr": {
                    "custom": [
                      "192.168.9.16"
                    ],
                    "object": [
                      {
                        "type": 0,
                        "gp_name": "11",
                        "gid": "GPIP1"
                      }
                    ]
                  },
                  "time": {
                    "custom": [
                      {
                        "type": "weekly",
                        "weekdays": "1234567",
                        "start_time": "00:00",
                        "end_time": "20:00",
                        "comment": "test11"
                      },
                      {
                        "type": "date",
                        "start_time": "2026-05-01T08:00",
                        "end_time": "2026-05-10T08:00",
                        "comment": "test11"
                      }
                    ],
                    "object": [
                      {
                        "type": 4,
                        "gp_name": "11",
                        "gid": "TIMEGP1"
                      }
                    ]
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/security/url-replace/rules/{id}": {
        "get": {
          "summary": "获取单个URL参数替换策略",
          "description": "根据ID获取指定的URL参数替换策略详情",
          "operationId": "getUrlReplaceRule",
          "tags": [
            "url-replace"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL参数替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取URL参数替换策略详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlReplaceRuleResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新URL参数替换策略",
          "description": "完整更新指定的URL参数替换策略配置。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateUrlReplaceRule",
          "tags": [
            "url-replace"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL参数替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "URL参数替换策略更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlReplaceRuleEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用URL参数替换策略",
          "description": "切换URL参数替换策略的启用状态",
          "operationId": "toggleUrlReplaceRule",
          "tags": [
            "url-replace"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL参数替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "requestBody": {
            "required": true,
            "description": "策略状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "策略状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除URL参数替换策略",
          "description": "删除指定的URL参数替换策略",
          "operationId": "deleteUrlReplaceRule",
          "tags": [
            "url-replace"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "description": "URL参数替换策略ID",
              "schema": {
                "type": "integer",
                "minimum": 1
              }
            }
          ],
          "responses": {
            "200": {
              "description": "URL参数替换策略删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问URL参数替换策略"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "URL参数替换策略不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源冲突（如优先级重复）"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "UrlReplaceRule": {
          "type": "object",
          "required": [
            "id",
            "prio",
            "enabled",
            "hit_rate",
            "mode",
            "param_keyword",
            "rep_keyword"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "策略ID",
              "minimum": 1,
              "example": 1
            },
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "111"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "param_keyword": {
              "type": "string",
              "description": "参数关键字",
              "example": "query"
            },
            "rep_keyword": {
              "type": "string",
              "description": "替换值",
              "example": "aa"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "替换百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlReplaceRuleInput": {
          "type": "object",
          "required": [
            "prio",
            "enabled",
            "hit_rate",
            "mode",
            "param_keyword",
            "rep_keyword",
            "src_url",
            "tagname"
          ],
          "properties": {
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "111"
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "param_keyword": {
              "type": "string",
              "description": "参数关键字",
              "example": "query"
            },
            "rep_keyword": {
              "type": "string",
              "description": "替换值",
              "example": "aa"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "替换百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            }
          },
          "additionalProperties": false
        },
        "UrlReplaceRuleEditInput": {
          "type": "object",
          "description": "PUT 全量修改，所有字段均为必填，未修改的字段须传原值",
          "required": [
            "enabled",
            "prio",
            "src_addr",
            "src_url",
            "param_keyword",
            "rep_keyword",
            "mode",
            "excluded",
            "hit_rate",
            "time",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "规则状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "prio": {
              "type": "integer",
              "description": "优先级（1-63，1最高）",
              "minimum": 1,
              "maximum": 63,
              "example": 1
            },
            "src_addr": {
              "$ref": "#/components/schemas/AddressObject"
            },
            "src_url": {
              "type": "string",
              "description": "源URL",
              "example": "192.168.1.253"
            },
            "param_keyword": {
              "type": "string",
              "description": "参数关键字（1-40字符）",
              "minLength": 1,
              "maxLength": 40,
              "example": "query"
            },
            "rep_keyword": {
              "type": "string",
              "description": "替换值（1-40字符）",
              "minLength": 1,
              "maxLength": 40,
              "example": "aa"
            },
            "mode": {
              "type": "string",
              "description": "匹配模式",
              "enum": [
                "exact",
                "vague"
              ],
              "example": "exact"
            },
            "excluded": {
              "type": "string",
              "description": "排除条件",
              "example": ""
            },
            "hit_rate": {
              "type": "integer",
              "description": "替换百分比（1-100）",
              "minimum": 1,
              "maximum": 100,
              "example": 100
            },
            "time": {
              "$ref": "#/components/schemas/TimeObject"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "example": "test1"
            }
          },
          "additionalProperties": false
        },
        "CreateUrlReplaceRuleResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的URL参数替换策略ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "code",
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "UrlReplaceRuleResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/UrlReplaceRule"
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UrlReplaceRulesResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "URL参数替换策略列表",
                  "items": {
                    "$ref": "#/components/schemas/UrlReplaceRule"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AddressObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义地址列表",
              "items": {
                "type": "string"
              },
              "example": "192.168.9.16"
            },
            "object": {
              "type": "array",
              "description": "地址对象列表",
              "items": {
                "$ref": "#/components/schemas/NetworkObject"
              }
            }
          },
          "additionalProperties": false
        },
        "TimeObject": {
          "type": "object",
          "properties": {
            "custom": {
              "type": "array",
              "description": "自定义时间规则列表",
              "items": {
                "$ref": "#/components/schemas/TimeRule"
              }
            },
            "object": {
              "type": "array",
              "description": "时间对象列表",
              "items": {
                "$ref": "#/components/schemas/TimeObjectGroup"
              }
            }
          },
          "additionalProperties": false
        },
        "NetworkObject": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 0
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "GPIP1"
            }
          },
          "additionalProperties": false
        },
        "TimeObjectGroup": {
          "type": "object",
          "required": [
            "type",
            "gp_name",
            "gid"
          ],
          "properties": {
            "type": {
              "type": "integer",
              "description": "对象类型",
              "enum": [
                0,
                1,
                2,
                3,
                4,
                5,
                6
              ],
              "example": 4
            },
            "gp_name": {
              "type": "string",
              "description": "对象名称",
              "example": "11"
            },
            "gid": {
              "type": "string",
              "description": "对象ID",
              "example": "TIMEGP1"
            }
          },
          "additionalProperties": false
        },
        "TimeRule": {
          "type": "object",
          "required": [
            "type",
            "start_time",
            "end_time"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "时间规则类型",
              "enum": [
                "weekly",
                "date"
              ],
              "example": "weekly"
            },
            "start_time": {
              "type": "string",
              "description": "开始时间",
              "example": "00:00"
            },
            "end_time": {
              "type": "string",
              "description": "结束时间",
              "example": "20:00"
            },
            "weekdays": {
              "type": "string",
              "description": "星期几（1-7代表周一到周日）",
              "pattern": "^[1-7]+$",
              "example": "1234567"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "example": "test11"
            }
          },
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateUrlReplaceRuleResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "url-replace",
        "x-displayName": "URL参数替换",
        "description": "URL参数替换策略管理，包括参数匹配、替换和时间规则控制"
      }
    ]
  },
  "auth/auth-pppoe.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "PPPoE服务器管理API",
      "version": "1.0.0",
      "summary": "PPPoE服务器配置管理",
      "description": "提供PPPoE服务器的配置管理功能，包括：\n- PPPoE服务基础配置\n- 认证方式配置（本地账户/RADIUS）\n- 地址池和网络配置\n- 连接控制和限速设置\n- VLAN绑定和定时重启功能\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/network/pppoe/services": {
        "get": {
          "summary": "获取PPPoE服务器配置",
          "description": "获取当前PPPoE服务器的配置信息。\n包括服务状态、认证方式、网络配置、RADIUS设置等。\n",
          "operationId": "getPppoeServerConfig",
          "tags": [
            "pppoe-server"
          ],
          "responses": {
            "200": {
              "description": "成功获取PPPoE配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PppoeServerConfigResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "enabled": "no",
                          "server_name": "iKuai",
                          "force_verify_name": 0,
                          "server_ip": "10.1.1.1",
                          "dns1": "114.114.114.114",
                          "dns2": "119.29.29.29",
                          "authmode": 0,
                          "nas_identifier": "iKuai",
                          "nas_ip_address": "",
                          "radius_ip": "127.0.0.1",
                          "secret": "123",
                          "authport": 1812,
                          "accountport": 1813,
                          "comment": "",
                          "addr_pool": "10.1.1.2-10.1.1.254",
                          "interface": "lan1",
                          "rate_limit_lan": 1,
                          "drop_client": 1,
                          "force_pppoe": 0,
                          "enhance_check": 1,
                          "share_deny": 0,
                          "bind_vlan": 0,
                          "verify_vlan": 1,
                          "bind_iface": 0,
                          "mtu": 1480,
                          "mru": 1480,
                          "lcp_echo_interval": 10,
                          "lcp_echo_failure": 3,
                          "maxconnect": 0,
                          "restart_timer": 0,
                          "restart_week": "",
                          "restart_time": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新PPPoE服务器配置",
          "description": "更新PPPoE服务器的配置信息。\n支持更新认证方式、网络配置、RADIUS设置、连接控制等。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePppoeServerConfig",
          "tags": [
            "pppoe-server"
          ],
          "requestBody": {
            "required": true,
            "description": "PPPoE服务器配置数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PppoeServerConfigInput"
                },
                "example": {
                  "enabled": "no",
                  "server_name": "iKuai",
                  "force_verify_name": 0,
                  "server_ip": "10.1.1.1",
                  "dns1": "114.114.114.114",
                  "dns2": "119.29.29.29",
                  "authmode": 0,
                  "nas_identifier": "iKuai",
                  "nas_ip_address": "",
                  "radius_ip": "127.0.0.1",
                  "secret": "123",
                  "authport": 1812,
                  "accountport": 1813,
                  "addr_pool": "10.1.1.2-10.1.1.254",
                  "interface": "lan1",
                  "rate_limit_lan": 1,
                  "drop_client": 1,
                  "force_pppoe": 0,
                  "enhance_check": 1,
                  "share_deny": 0,
                  "bind_vlan": 0,
                  "verify_vlan": 1,
                  "bind_iface": 0,
                  "mtu": 1480,
                  "mru": 1480,
                  "lcp_echo_interval": 10,
                  "lcp_echo_failure": 3,
                  "maxconnect": 0,
                  "restart_timer": 0,
                  "restart_week": "",
                  "restart_time": ""
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "Success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "PppoeServerConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "server_name",
            "force_verify_name",
            "server_ip",
            "dns1",
            "dns2",
            "authmode",
            "nas_identifier",
            "nas_ip_address",
            "radius_ip",
            "secret",
            "authport",
            "accountport",
            "comment",
            "addr_pool",
            "interface",
            "rate_limit_lan",
            "drop_client",
            "force_pppoe",
            "enhance_check",
            "share_deny",
            "bind_vlan",
            "verify_vlan",
            "bind_iface",
            "mtu",
            "mru",
            "lcp_echo_interval",
            "lcp_echo_failure",
            "maxconnect",
            "restart_timer",
            "restart_week",
            "restart_time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "server_name": {
              "type": "string",
              "description": "服务端名称",
              "maxLength": 100,
              "example": "iKuai"
            },
            "force_verify_name": {
              "type": "integer",
              "description": "强制校验服务名称，0为不强制，1为强制",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "server_ip": {
              "type": "string",
              "description": "服务器地址",
              "example": "10.1.1.1"
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2",
              "example": "119.29.29.29"
            },
            "authmode": {
              "type": "integer",
              "description": "认证方式：0-本地账户，1-本地账户空密码，2-任意用户，3-RADIUS",
              "enum": [
                0,
                1,
                2,
                3
              ],
              "example": 0
            },
            "nas_identifier": {
              "type": "string",
              "description": "NAS标识（authmode=3时必填，1-60个字符）",
              "minLength": 1,
              "maxLength": 60,
              "example": "iKuai"
            },
            "nas_ip_address": {
              "type": "string",
              "description": "NAS IP地址（authmode=3时必填，合法IP）",
              "example": ""
            },
            "radius_ip": {
              "type": "string",
              "description": "RADIUS服务端IP（authmode=3时必填）",
              "example": "127.0.0.1"
            },
            "secret": {
              "type": "string",
              "description": "共享密钥（authmode=3时必填，1-60个字符）",
              "minLength": 1,
              "maxLength": 60,
              "example": "123"
            },
            "authport": {
              "type": "integer",
              "description": "认证端口（authmode=3时必填）",
              "minimum": 1,
              "maximum": 65535,
              "default": 1812,
              "example": 1812
            },
            "accountport": {
              "type": "integer",
              "description": "记账端口（authmode=3时必填）",
              "minimum": 1,
              "maximum": 65535,
              "default": 1813,
              "example": 1813
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "addr_pool": {
              "type": "string",
              "description": "客户端地址池，格式为IP范围，多个用逗号分隔",
              "example": "10.1.1.2-10.1.1.254"
            },
            "interface": {
              "type": "string",
              "description": "内网线路",
              "example": "lan1"
            },
            "rate_limit_lan": {
              "type": "integer",
              "description": "对内网访问限速，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "drop_client": {
              "type": "integer",
              "description": "禁止客户端互访，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "force_pppoe": {
              "type": "integer",
              "description": "强制拨号上网，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "enhance_check": {
              "type": "integer",
              "description": "加强断线检测，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "share_deny": {
              "type": "integer",
              "description": "共享数超出处理动作：0-踢掉，1-拒绝连接",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "bind_vlan": {
              "type": "integer",
              "description": "支持VLAN(QinQ)透传，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "verify_vlan": {
              "type": "integer",
              "description": "是否校验VLAN（依赖bind_vlan=1时生效），0为不校验，1为校验",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "bind_iface": {
              "type": "integer",
              "description": "支持绑定iface，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1480,
              "example": 1480
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1480,
              "example": 1480
            },
            "lcp_echo_interval": {
              "type": "integer",
              "description": "LCP echo间隔（秒）",
              "minimum": 1,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "lcp_echo_failure": {
              "type": "integer",
              "description": "LCP echo失败次数",
              "minimum": 1,
              "maximum": 60,
              "default": 3,
              "example": 3
            },
            "maxconnect": {
              "type": "integer",
              "description": "客户端最大连接时长（小时），0表示不限制",
              "minimum": 0,
              "maximum": 8760,
              "example": 0
            },
            "restart_timer": {
              "type": "integer",
              "description": "定时重启PPPoE服务，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "restart_week": {
              "type": "string",
              "description": "定时重启周期，由星期数字组成（1=周一...7=周日），如1234567表示每天，12345表示周一至周五。仅restart_timer=1时有效",
              "example": ""
            },
            "restart_time": {
              "type": "string",
              "description": "定时重启时间，格式HH:MM，多个用逗号分隔如06:00,18:00。仅restart_timer=1时有效",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "PppoeServerConfigInput": {
          "type": "object",
          "description": "PUT全量修改，条件字段（verify_vlan/restart_week/restart_time）及选输字段无需强制传入",
          "required": [
            "enabled",
            "force_verify_name",
            "server_ip",
            "dns1",
            "dns2",
            "authmode",
            "nas_identifier",
            "nas_ip_address",
            "radius_ip",
            "secret",
            "authport",
            "accountport",
            "addr_pool",
            "interface",
            "rate_limit_lan",
            "drop_client",
            "force_pppoe",
            "enhance_check",
            "share_deny",
            "bind_vlan",
            "verify_vlan",
            "bind_iface",
            "mtu",
            "mru",
            "lcp_echo_interval",
            "lcp_echo_failure",
            "maxconnect",
            "restart_timer",
            "comment"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "server_name": {
              "type": "string",
              "description": "服务端名称",
              "maxLength": 100,
              "default": "iKuai",
              "example": "iKuai"
            },
            "force_verify_name": {
              "type": "integer",
              "description": "强制校验服务名称，0为不强制，1为强制，不传则不修改",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "server_ip": {
              "type": "string",
              "description": "服务器地址，必须为合法IP",
              "example": "10.1.1.1"
            },
            "dns1": {
              "type": "string",
              "description": "DNS服务器1，必须为合法IP",
              "example": "114.114.114.114"
            },
            "dns2": {
              "type": "string",
              "description": "DNS服务器2，必须为合法IP",
              "example": "119.29.29.29"
            },
            "authmode": {
              "type": "integer",
              "description": "认证方式：0-本地账户，1-本地账户空密码，2-任意用户，3-RADIUS",
              "enum": [
                0,
                1,
                2,
                3
              ],
              "default": 0,
              "example": 0
            },
            "nas_identifier": {
              "type": "string",
              "description": "NAS标识（authmode=3时必填，1-60个字符）",
              "minLength": 1,
              "maxLength": 60,
              "example": "iKuai"
            },
            "nas_ip_address": {
              "type": "string",
              "description": "NAS IP地址（authmode=3时必填，合法IP）",
              "example": ""
            },
            "radius_ip": {
              "type": "string",
              "description": "RADIUS服务端IP（authmode=3时必填）",
              "example": "127.0.0.1"
            },
            "secret": {
              "type": "string",
              "description": "共享密钥（authmode=3时必填，1-60个字符）",
              "minLength": 1,
              "maxLength": 60,
              "example": "123"
            },
            "authport": {
              "type": "integer",
              "description": "认证端口（authmode=3时必填）",
              "minimum": 1,
              "maximum": 65535,
              "default": 1812,
              "example": 1812
            },
            "accountport": {
              "type": "integer",
              "description": "记账端口（authmode=3时必填）",
              "minimum": 1,
              "maximum": 65535,
              "default": 1813,
              "example": 1813
            },
            "addr_pool": {
              "type": "string",
              "description": "客户端地址池，格式为IP范围，多个用逗号分隔",
              "default": "10.1.1.2-10.1.1.254",
              "example": "10.1.1.2-10.1.1.254"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            },
            "interface": {
              "type": "string",
              "description": "内网线路",
              "default": "lan1",
              "example": "lan1"
            },
            "rate_limit_lan": {
              "type": "integer",
              "description": "对内网访问限速，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "drop_client": {
              "type": "integer",
              "description": "禁止客户端互访，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "force_pppoe": {
              "type": "integer",
              "description": "强制拨号上网，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "enhance_check": {
              "type": "integer",
              "description": "加强断线检测，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "share_deny": {
              "type": "integer",
              "description": "共享数超出处理动作：0-踢掉，1-拒绝连接",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "bind_vlan": {
              "type": "integer",
              "description": "支持VLAN(QinQ)透传，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "verify_vlan": {
              "type": "integer",
              "description": "是否校验VLAN（仅bind_vlan=1时必填），0为不校验，1为校验",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "bind_iface": {
              "type": "integer",
              "description": "支持绑定iface，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "mtu": {
              "type": "integer",
              "description": "MTU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1480,
              "example": 1480
            },
            "mru": {
              "type": "integer",
              "description": "MRU值",
              "minimum": 1000,
              "maximum": 1492,
              "default": 1480,
              "example": 1480
            },
            "lcp_echo_interval": {
              "type": "integer",
              "description": "LCP echo间隔（秒）",
              "minimum": 1,
              "maximum": 60,
              "default": 10,
              "example": 10
            },
            "lcp_echo_failure": {
              "type": "integer",
              "description": "LCP echo失败次数",
              "minimum": 1,
              "maximum": 60,
              "default": 3,
              "example": 3
            },
            "maxconnect": {
              "type": "integer",
              "description": "客户端最大连接时长（小时），0表示不限制",
              "minimum": 0,
              "maximum": 8760,
              "default": 0,
              "example": 0
            },
            "restart_timer": {
              "type": "integer",
              "description": "定时重启PPPoE服务，0为关闭，1为开启",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "restart_week": {
              "type": "string",
              "description": "定时重启周期，由星期数字组成（1=周一...7=周日），如1234567表示每天。仅restart_timer=1时必填",
              "example": ""
            },
            "restart_time": {
              "type": "string",
              "description": "定时重启时间，格式HH:MM，多个用逗号分隔如06:00,18:00。仅restart_timer=1时必填",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "PppoeServerConfigResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PppoeServerConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "Success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "pppoe-server",
        "x-displayName": "PPPoE服务器管理",
        "description": "PPPoE服务器的配置管理，包括认证、网络、连接控制和RADIUS设置"
      }
    ]
  },
  "auth/auth-web-services.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "WEB认证服务管理API",
      "version": "1.0.0",
      "summary": "WEB认证服务的完整管理功能",
      "description": "提供WEB认证服务的完整管理功能，包括：\n- WEB认证服务配置的查询和更新\n- 支持多种认证方式（微信、QQ、微博、手机号等）\n- 认证超时和空闲时间控制\n- 各认证方式独立超时配置\n- 各认证方式独立QoS限速\n- Radius和LDAP协议对接\n- 白名单和访问控制\n- 同步认证和HTTPS跳转\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/auth/web/services": {
        "get": {
          "summary": "获取WEB认证服务配置",
          "description": "获取当前WEB认证服务的配置信息。\n包括认证方式、超时设置、QoS限速、Radius/LDAP配置、白名单等。\n认证的配置需要确保云平台开启过认证。\n",
          "operationId": "getWebAuthServiceConfig",
          "tags": [
            "web-auth"
          ],
          "responses": {
            "200": {
              "description": "成功获取WEB认证服务配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebAuthServiceConfigResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "enabled": "no",
                          "max_time": 0,
                          "idle_time": 60,
                          "enc_ssid_noauth": 1,
                          "timer_restart": 0,
                          "timer_event": "",
                          "timer_restart_week": "1234567",
                          "timer_restart_time": "07:00",
                          "user_auth": 1,
                          "coupon_auth": 1,
                          "qq_auth": 0,
                          "weibo_auth": 0,
                          "phone_auth": 0,
                          "static_pwd": 1,
                          "nopasswd": 0,
                          "weixin": 0,
                          "weixin2": 0,
                          "weixin_mini": 0,
                          "facebook_auth": 0,
                          "twitter_auth": 0,
                          "google_auth": 0,
                          "redpacket_auth": 0,
                          "hotel_auth": 0,
                          "openapi_auth": 0,
                          "custom_auth": 0,
                          "custom_appkey": "",
                          "authip_mode": 0,
                          "allow_tryout": 0,
                          "tryout_time": 30,
                          "auto_auth": 0,
                          "ldap_auth": 0,
                          "popups": 1,
                          "popups_ios": 1,
                          "popups_android": 1,
                          "auto_auth_timeout": 1,
                          "api_switch": 0,
                          "api_url": "",
                          "passwd": "",
                          "ipgroup": "",
                          "noauth_mac": "",
                          "whitelist": "",
                          "whitelist_https": "",
                          "whiteip": "",
                          "api_radius": 0,
                          "imperceptible": 0,
                          "macbind_server": "",
                          "nasname": "iKuai",
                          "radius_ip": "127.0.0.1",
                          "radius_key": "123",
                          "radius_authport": 1812,
                          "radius_accountport": 1813,
                          "radius_interval": 60,
                          "radius_basip": "",
                          "api_ipchange_url": "",
                          "coupon_up": 0,
                          "coupon_down": 0,
                          "weixin_up": 0,
                          "weixin_down": 0,
                          "phone_up": 0,
                          "phone_down": 0,
                          "nopasswd_up": 0,
                          "nopasswd_down": 0,
                          "static_pwd_up": 0,
                          "static_pwd_down": 0,
                          "weibo_up": 0,
                          "weibo_down": 0,
                          "tryout_up": 0,
                          "tryout_down": 0,
                          "qq_up": 0,
                          "qq_down": 0,
                          "facebook_up": 0,
                          "facebook_down": 0,
                          "google_up": 0,
                          "google_down": 0,
                          "twitter_up": 0,
                          "twitter_down": 0,
                          "redpacket_up": 0,
                          "redpacket_down": 0,
                          "hotel_up": 0,
                          "hotel_down": 0,
                          "weixin_absorb": 0,
                          "https_redirect": 0,
                          "user_timeout": 0,
                          "coupon_timeout": 0,
                          "qq_timeout": 0,
                          "weibo_timeout": 0,
                          "phone_timeout": 0,
                          "static_timeout": 0,
                          "nopasswd_timeout": 0,
                          "weixin_timeout": 0,
                          "redpacket_timeout": 0,
                          "facebook_timeout": 0,
                          "google_timeout": 0,
                          "twitter_timeout": 0,
                          "tryout_timeout": 0,
                          "hotel_timeout": 0,
                          "user_max_time": 0,
                          "user_idle_time": 0,
                          "coupon_max_time": 0,
                          "coupon_idle_time": 0,
                          "qq_max_time": 0,
                          "qq_idle_time": 0,
                          "weibo_max_time": 0,
                          "weibo_idle_time": 0,
                          "phone_max_time": 0,
                          "phone_idle_time": 0,
                          "static_max_time": 0,
                          "static_idle_time": 0,
                          "nopasswd_max_time": 0,
                          "nopasswd_idle_time": 0,
                          "weixin_max_time": 0,
                          "weixin_idle_time": 0,
                          "facebook_max_time": 0,
                          "facebook_idle_time": 0,
                          "google_max_time": 0,
                          "google_idle_time": 0,
                          "twitter_max_time": 0,
                          "twitter_idle_time": 0,
                          "redpacket_max_time": 0,
                          "redpacket_idle_time": 0,
                          "tryout_max_time": 0,
                          "tryout_idle_time": 0,
                          "hotel_max_time": 0,
                          "hotel_idle_time": 0,
                          "uri_add_apinfo": 0,
                          "sync_switch": 0,
                          "interface": "lan1",
                          "group_key": "testing123",
                          "group_id": 0,
                          "ldap_usergroup": "",
                          "ldap_url": "",
                          "ldap_port": 389,
                          "ldap_mode": 0,
                          "ldap_base": "",
                          "ldap_cname": "cn",
                          "ldap_admin_dn": "",
                          "ldap_admin_passwd": "",
                          "proxy_service": 0,
                          "proxy_ipaddr": "",
                          "ldap_share_count": 0
                        }
                      ],
                      "interface": [
                        "lan1",
                        "lan2",
                        "lan3",
                        "wan1",
                        "vwan11"
                      ],
                      "template": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问WEB认证服务管理"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WebAuthServiceConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "max_time",
            "idle_time"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "max_time": {
              "type": "integer",
              "description": "重新认证超时时间（分钟），0表示不限制",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "idle_time": {
              "type": "integer",
              "description": "空闲时间自动下线（秒），0表示不限制",
              "minimum": 0,
              "default": 60,
              "example": 60
            },
            "enc_ssid_noauth": {
              "type": "integer",
              "description": "加密SSID免认证",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "timer_restart": {
              "type": "integer",
              "description": "定时重新认证（定时全部踢下线）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "timer_event": {
              "type": "string",
              "description": "定时事件，默认为空；设置为period表示时间段开启认证",
              "example": ""
            },
            "timer_restart_week": {
              "type": "string",
              "description": "定时重新认证周期（1-7代表周一到周日）",
              "pattern": "^[1-7]*$",
              "default": "1234567",
              "example": "1234567"
            },
            "timer_restart_time": {
              "type": "string",
              "description": "定时重新认证时间，timer_event为period时为时间范围如08:00-18:00",
              "default": "07:00",
              "example": "07:00"
            },
            "user_auth": {
              "type": "integer",
              "description": "用户密码认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "coupon_auth": {
              "type": "integer",
              "description": "优惠券认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "qq_auth": {
              "type": "integer",
              "description": "QQ认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weibo_auth": {
              "type": "integer",
              "description": "微博认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "phone_auth": {
              "type": "integer",
              "description": "手机认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "static_pwd": {
              "type": "integer",
              "description": "固定密码认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "nopasswd": {
              "type": "integer",
              "description": "一键认证（无密码）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weixin": {
              "type": "integer",
              "description": "微信认证",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 0
            },
            "weixin2": {
              "type": "integer",
              "description": "微信扫码认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weixin_mini": {
              "type": "integer",
              "description": "微信小程序认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "facebook_auth": {
              "type": "integer",
              "description": "Facebook认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "twitter_auth": {
              "type": "integer",
              "description": "Twitter认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "google_auth": {
              "type": "integer",
              "description": "Google认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "redpacket_auth": {
              "type": "integer",
              "description": "红包认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "hotel_auth": {
              "type": "integer",
              "description": "酒店认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "openapi_auth": {
              "type": "integer",
              "description": "OpenAPI认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "custom_auth": {
              "type": "integer",
              "description": "自定义认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "custom_appkey": {
              "type": "string",
              "description": "自定义认证appkey",
              "default": "",
              "example": ""
            },
            "authip_mode": {
              "type": "integer",
              "description": "认证IP方式（0全部IP认证，1部分IP认证）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "allow_tryout": {
              "type": "integer",
              "description": "允许试用",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "tryout_time": {
              "type": "integer",
              "description": "试用时长（分钟）",
              "minimum": 0,
              "default": 30,
              "example": 30
            },
            "auto_auth": {
              "type": "integer",
              "description": "开启自动认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "ldap_auth": {
              "type": "integer",
              "description": "LDAP协议认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "popups": {
              "type": "integer",
              "description": "开启portal弹窗",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "popups_ios": {
              "type": "integer",
              "description": "开启iOS系统弹窗",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "popups_android": {
              "type": "integer",
              "description": "开启安卓系统弹窗",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "auto_auth_timeout": {
              "type": "integer",
              "description": "自动认证有效时长（天）",
              "minimum": 0,
              "default": 1,
              "example": 1
            },
            "api_switch": {
              "type": "integer",
              "description": "第三方对接开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "api_url": {
              "type": "string",
              "description": "第三方对接跳转地址",
              "example": ""
            },
            "passwd": {
              "type": "string",
              "description": "固定密码（MD5哈希值）",
              "pattern": "^[a-fA-F0-9]{32}$",
              "example": ""
            },
            "ipgroup": {
              "type": "string",
              "description": "认证IP群组，多个用逗号分隔，格式为IP范围如192.168.1.1-192.168.1.254",
              "example": ""
            },
            "noauth_mac": {
              "type": "string",
              "description": "免认证MAC地址，多个用逗号分隔",
              "example": ""
            },
            "whitelist": {
              "type": "string",
              "description": "白名单域名（HTTP），多个用逗号分隔",
              "example": ""
            },
            "whitelist_https": {
              "type": "string",
              "description": "白名单域名（HTTPS），多个用逗号分隔",
              "example": ""
            },
            "whiteip": {
              "type": "string",
              "description": "白名单IP，多个用逗号分隔",
              "example": ""
            },
            "api_radius": {
              "type": "integer",
              "description": "开启Radius对接",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "imperceptible": {
              "type": "integer",
              "description": "Radius无感知认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "macbind_server": {
              "type": "string",
              "description": "MAC绑定服务器地址，为空时使用radius_ip",
              "example": ""
            },
            "nasname": {
              "type": "string",
              "description": "Radius NAS名称",
              "default": "iKuai",
              "example": "iKuai"
            },
            "radius_ip": {
              "type": "string",
              "description": "Radius服务器IP",
              "format": "ipv4",
              "default": "127.0.0.1",
              "example": "127.0.0.1"
            },
            "radius_key": {
              "type": "string",
              "description": "Radius共享密钥",
              "default": "123",
              "example": "123"
            },
            "radius_authport": {
              "type": "integer",
              "description": "Radius认证端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1812,
              "example": 1812
            },
            "radius_accountport": {
              "type": "integer",
              "description": "Radius记账端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1813,
              "example": 1813
            },
            "radius_interval": {
              "type": "integer",
              "description": "发送计费包间隔时长（秒）",
              "minimum": 1,
              "default": 60,
              "example": 60
            },
            "radius_basip": {
              "type": "string",
              "description": "Portal回调Radius IP",
              "example": ""
            },
            "api_ipchange_url": {
              "type": "string",
              "description": "用户IP变更上报地址",
              "example": ""
            },
            "coupon_up": {
              "type": "integer",
              "description": "优惠券认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "coupon_down": {
              "type": "integer",
              "description": "优惠券认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_up": {
              "type": "integer",
              "description": "微信认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_down": {
              "type": "integer",
              "description": "微信认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_up": {
              "type": "integer",
              "description": "手机认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_down": {
              "type": "integer",
              "description": "手机认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_up": {
              "type": "integer",
              "description": "一键认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_down": {
              "type": "integer",
              "description": "一键认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_pwd_up": {
              "type": "integer",
              "description": "固定密码认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_pwd_down": {
              "type": "integer",
              "description": "固定密码认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_up": {
              "type": "integer",
              "description": "微博认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_down": {
              "type": "integer",
              "description": "微博认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_up": {
              "type": "integer",
              "description": "试用认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_down": {
              "type": "integer",
              "description": "试用认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_up": {
              "type": "integer",
              "description": "QQ认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_down": {
              "type": "integer",
              "description": "QQ认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_up": {
              "type": "integer",
              "description": "Facebook认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_down": {
              "type": "integer",
              "description": "Facebook认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_up": {
              "type": "integer",
              "description": "Google认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_down": {
              "type": "integer",
              "description": "Google认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_up": {
              "type": "integer",
              "description": "Twitter认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_down": {
              "type": "integer",
              "description": "Twitter认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_up": {
              "type": "integer",
              "description": "红包认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_down": {
              "type": "integer",
              "description": "红包认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_up": {
              "type": "integer",
              "description": "酒店认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_down": {
              "type": "integer",
              "description": "酒店认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_absorb": {
              "type": "integer",
              "description": "微信吸粉（开启后自动启用weixin2扫码）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "https_redirect": {
              "type": "integer",
              "description": "HTTPS跳转portal页面",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "user_timeout": {
              "type": "integer",
              "description": "用户密码认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "coupon_timeout": {
              "type": "integer",
              "description": "优惠券认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "qq_timeout": {
              "type": "integer",
              "description": "QQ认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weibo_timeout": {
              "type": "integer",
              "description": "微博认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "phone_timeout": {
              "type": "integer",
              "description": "手机认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "static_timeout": {
              "type": "integer",
              "description": "固定密码认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "nopasswd_timeout": {
              "type": "integer",
              "description": "一键认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weixin_timeout": {
              "type": "integer",
              "description": "微信认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "redpacket_timeout": {
              "type": "integer",
              "description": "红包认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "facebook_timeout": {
              "type": "integer",
              "description": "Facebook认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "google_timeout": {
              "type": "integer",
              "description": "Google认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "twitter_timeout": {
              "type": "integer",
              "description": "Twitter认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "tryout_timeout": {
              "type": "integer",
              "description": "试用认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "hotel_timeout": {
              "type": "integer",
              "description": "酒店认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "user_max_time": {
              "type": "integer",
              "description": "用户密码认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "user_idle_time": {
              "type": "integer",
              "description": "用户密码认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "coupon_max_time": {
              "type": "integer",
              "description": "优惠券认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "coupon_idle_time": {
              "type": "integer",
              "description": "优惠券认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_max_time": {
              "type": "integer",
              "description": "QQ认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_idle_time": {
              "type": "integer",
              "description": "QQ认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_max_time": {
              "type": "integer",
              "description": "微博认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_idle_time": {
              "type": "integer",
              "description": "微博认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_max_time": {
              "type": "integer",
              "description": "手机认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_idle_time": {
              "type": "integer",
              "description": "手机认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_max_time": {
              "type": "integer",
              "description": "固定密码认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_idle_time": {
              "type": "integer",
              "description": "固定密码认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_max_time": {
              "type": "integer",
              "description": "一键认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_idle_time": {
              "type": "integer",
              "description": "一键认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_max_time": {
              "type": "integer",
              "description": "微信认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_idle_time": {
              "type": "integer",
              "description": "微信认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_max_time": {
              "type": "integer",
              "description": "Facebook认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_idle_time": {
              "type": "integer",
              "description": "Facebook认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_max_time": {
              "type": "integer",
              "description": "Google认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_idle_time": {
              "type": "integer",
              "description": "Google认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_max_time": {
              "type": "integer",
              "description": "Twitter认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_idle_time": {
              "type": "integer",
              "description": "Twitter认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_max_time": {
              "type": "integer",
              "description": "红包认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_idle_time": {
              "type": "integer",
              "description": "红包认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_max_time": {
              "type": "integer",
              "description": "试用认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_idle_time": {
              "type": "integer",
              "description": "试用认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_max_time": {
              "type": "integer",
              "description": "酒店认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_idle_time": {
              "type": "integer",
              "description": "酒店认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "uri_add_apinfo": {
              "type": "integer",
              "description": "portal页URL是否追加连接AP信息",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "sync_switch": {
              "type": "integer",
              "description": "同步认证开关（开启后需配置interface、group_key、group_id）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "同步认证网卡接口",
              "default": "lan1",
              "example": "lan1"
            },
            "group_key": {
              "type": "string",
              "description": "同步认证组密钥",
              "default": "testing123",
              "example": "testing123"
            },
            "group_id": {
              "type": "integer",
              "description": "同步认证组播ID",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "ldap_usergroup": {
              "type": "string",
              "description": "LDAP用户所在组路径",
              "example": ""
            },
            "ldap_url": {
              "type": "string",
              "description": "LDAP服务器地址",
              "example": ""
            },
            "ldap_port": {
              "type": "integer",
              "description": "LDAP端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 389,
              "example": 389
            },
            "ldap_mode": {
              "type": "integer",
              "description": "LDAP用户模式（0单用户组，1多用户组）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "ldap_base": {
              "type": "string",
              "description": "LDAP base_dn",
              "example": ""
            },
            "ldap_cname": {
              "type": "string",
              "description": "LDAP common name属性（cn或sAMAccountName）",
              "default": "cn",
              "example": "cn"
            },
            "ldap_admin_dn": {
              "type": "string",
              "description": "LDAP管理员全路径DN",
              "example": ""
            },
            "ldap_admin_passwd": {
              "type": "string",
              "description": "LDAP管理员密码",
              "example": ""
            },
            "ldap_share_count": {
              "type": "integer",
              "description": "LDAP允许同时上线个数（0表示不限制）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "proxy_service": {
              "type": "integer",
              "description": "HTTPS 443代理服务",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "proxy_ipaddr": {
              "type": "string",
              "description": "HTTPS代理IP地址",
              "format": "ipv4",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "WebAuthServiceConfigInput": {
          "type": "object",
          "required": [
            "enabled",
            "max_time",
            "idle_time"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "max_time": {
              "type": "integer",
              "description": "重新认证超时时间（分钟），0表示不限制",
              "minimum": 0,
              "default": 0,
              "example": 1200
            },
            "idle_time": {
              "type": "integer",
              "description": "空闲时间自动下线（秒），0表示不限制",
              "minimum": 0,
              "default": 60,
              "example": 60
            },
            "enc_ssid_noauth": {
              "type": "integer",
              "description": "加密SSID免认证",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "timer_restart": {
              "type": "integer",
              "description": "定时重新认证（定时全部踢下线）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "timer_event": {
              "type": "string",
              "description": "定时事件，默认为空；设置为period表示时间段开启认证",
              "example": ""
            },
            "timer_restart_week": {
              "type": "string",
              "description": "定时重新认证周期（1-7代表周一到周日）",
              "pattern": "^[1-7]*$",
              "default": "1234567",
              "example": "1234567"
            },
            "timer_restart_time": {
              "type": "string",
              "description": "定时重新认证时间，timer_event为period时为时间范围如08:00-18:00",
              "default": "07:00",
              "example": "07:00"
            },
            "user_auth": {
              "type": "integer",
              "description": "用户密码认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "coupon_auth": {
              "type": "integer",
              "description": "优惠券认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "qq_auth": {
              "type": "integer",
              "description": "QQ认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weibo_auth": {
              "type": "integer",
              "description": "微博认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "phone_auth": {
              "type": "integer",
              "description": "手机认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "redpacket_auth": {
              "type": "integer",
              "description": "红包认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "static_pwd": {
              "type": "integer",
              "description": "固定密码认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 1
            },
            "nopasswd": {
              "type": "integer",
              "description": "一键认证（无密码）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weixin": {
              "type": "integer",
              "description": "微信认证",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "weixin2": {
              "type": "integer",
              "description": "微信扫码认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weixin_mini": {
              "type": "integer",
              "description": "微信小程序认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "facebook_auth": {
              "type": "integer",
              "description": "Facebook认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "twitter_auth": {
              "type": "integer",
              "description": "Twitter认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "google_auth": {
              "type": "integer",
              "description": "Google认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "openapi_auth": {
              "type": "integer",
              "description": "OpenAPI认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "custom_auth": {
              "type": "integer",
              "description": "自定义认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "hotel_auth": {
              "type": "integer",
              "description": "酒店认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "custom_appkey": {
              "type": "string",
              "description": "自定义认证appkey",
              "example": ""
            },
            "authip_mode": {
              "type": "integer",
              "description": "认证IP方式（0全部IP认证，1部分IP认证）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "allow_tryout": {
              "type": "integer",
              "description": "允许试用",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "tryout_time": {
              "type": "integer",
              "description": "试用时长（分钟）",
              "minimum": 0,
              "default": 30,
              "example": 30
            },
            "auto_auth": {
              "type": "integer",
              "description": "开启自动认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "ldap_auth": {
              "type": "integer",
              "description": "LDAP协议认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "popups": {
              "type": "integer",
              "description": "开启portal弹窗",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "popups_ios": {
              "type": "integer",
              "description": "开启iOS系统弹窗",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "popups_android": {
              "type": "integer",
              "description": "开启安卓系统弹窗",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "auto_auth_timeout": {
              "type": "integer",
              "description": "自动认证有效时长（天）",
              "minimum": 0,
              "default": 1,
              "example": 1
            },
            "api_switch": {
              "type": "integer",
              "description": "第三方对接开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "api_url": {
              "type": "string",
              "description": "第三方对接跳转地址",
              "example": ""
            },
            "passwd": {
              "type": "string",
              "description": "固定密码（MD5哈希值）",
              "pattern": "^[a-fA-F0-9]{32}$",
              "example": "96e79218965eb72c92a549dd5a330112"
            },
            "ipgroup": {
              "type": "string",
              "description": "认证IP群组，多个用逗号分隔，格式为IP范围如192.168.1.1-192.168.1.254",
              "example": ""
            },
            "noauth_mac": {
              "type": "string",
              "description": "免认证MAC地址，多个用逗号分隔",
              "example": ""
            },
            "whitelist": {
              "type": "string",
              "description": "白名单域名（HTTP），多个用逗号分隔",
              "example": ""
            },
            "whitelist_https": {
              "type": "string",
              "description": "白名单域名（HTTPS），多个用逗号分隔",
              "example": ""
            },
            "whiteip": {
              "type": "string",
              "description": "白名单IP，多个用逗号分隔",
              "example": ""
            },
            "api_radius": {
              "type": "integer",
              "description": "开启Radius对接",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "imperceptible": {
              "type": "integer",
              "description": "Radius无感知认证",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "macbind_server": {
              "type": "string",
              "description": "MAC绑定服务器地址，为空时使用radius_ip",
              "example": ""
            },
            "nasname": {
              "type": "string",
              "description": "Radius NAS名称",
              "default": "iKuai",
              "example": "iKuai"
            },
            "radius_ip": {
              "type": "string",
              "description": "Radius服务器IP",
              "format": "ipv4",
              "example": "127.0.0.1"
            },
            "radius_key": {
              "type": "string",
              "description": "Radius共享密钥",
              "example": "123"
            },
            "radius_authport": {
              "type": "integer",
              "description": "Radius认证端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1812,
              "example": 1812
            },
            "radius_accountport": {
              "type": "integer",
              "description": "Radius记账端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 1813,
              "example": 1813
            },
            "radius_interval": {
              "type": "integer",
              "description": "发送计费包间隔时长（秒）",
              "minimum": 1,
              "default": 60,
              "example": 60
            },
            "radius_basip": {
              "type": "string",
              "description": "Portal回调Radius IP",
              "example": ""
            },
            "api_ipchange_url": {
              "type": "string",
              "description": "用户IP变更上报地址",
              "example": ""
            },
            "coupon_up": {
              "type": "integer",
              "description": "优惠券认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "coupon_down": {
              "type": "integer",
              "description": "优惠券认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_up": {
              "type": "integer",
              "description": "微信认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_down": {
              "type": "integer",
              "description": "微信认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_up": {
              "type": "integer",
              "description": "手机认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_down": {
              "type": "integer",
              "description": "手机认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_up": {
              "type": "integer",
              "description": "一键认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_down": {
              "type": "integer",
              "description": "一键认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_pwd_up": {
              "type": "integer",
              "description": "固定密码认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_pwd_down": {
              "type": "integer",
              "description": "固定密码认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_up": {
              "type": "integer",
              "description": "微博认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_down": {
              "type": "integer",
              "description": "微博认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_up": {
              "type": "integer",
              "description": "试用认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_down": {
              "type": "integer",
              "description": "试用认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_up": {
              "type": "integer",
              "description": "QQ认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_down": {
              "type": "integer",
              "description": "QQ认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_up": {
              "type": "integer",
              "description": "Facebook认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_down": {
              "type": "integer",
              "description": "Facebook认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_up": {
              "type": "integer",
              "description": "Google认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_down": {
              "type": "integer",
              "description": "Google认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_up": {
              "type": "integer",
              "description": "Twitter认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_down": {
              "type": "integer",
              "description": "Twitter认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_up": {
              "type": "integer",
              "description": "红包认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_down": {
              "type": "integer",
              "description": "红包认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_up": {
              "type": "integer",
              "description": "酒店认证上传限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_down": {
              "type": "integer",
              "description": "酒店认证下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_absorb": {
              "type": "integer",
              "description": "微信吸粉（开启后自动启用weixin2扫码）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "https_redirect": {
              "type": "integer",
              "description": "HTTPS跳转portal页面",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "user_timeout": {
              "type": "integer",
              "description": "用户密码认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "coupon_timeout": {
              "type": "integer",
              "description": "优惠券认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "qq_timeout": {
              "type": "integer",
              "description": "QQ认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weibo_timeout": {
              "type": "integer",
              "description": "微博认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "phone_timeout": {
              "type": "integer",
              "description": "手机认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "static_timeout": {
              "type": "integer",
              "description": "固定密码认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "nopasswd_timeout": {
              "type": "integer",
              "description": "一键认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "weixin_timeout": {
              "type": "integer",
              "description": "微信认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "redpacket_timeout": {
              "type": "integer",
              "description": "红包认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "facebook_timeout": {
              "type": "integer",
              "description": "Facebook认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "google_timeout": {
              "type": "integer",
              "description": "Google认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "twitter_timeout": {
              "type": "integer",
              "description": "Twitter认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "tryout_timeout": {
              "type": "integer",
              "description": "试用认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "hotel_timeout": {
              "type": "integer",
              "description": "酒店认证独立超时开关",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "user_max_time": {
              "type": "integer",
              "description": "用户密码认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "user_idle_time": {
              "type": "integer",
              "description": "用户密码认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "coupon_max_time": {
              "type": "integer",
              "description": "优惠券认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "coupon_idle_time": {
              "type": "integer",
              "description": "优惠券认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_max_time": {
              "type": "integer",
              "description": "QQ认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "qq_idle_time": {
              "type": "integer",
              "description": "QQ认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_max_time": {
              "type": "integer",
              "description": "微博认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weibo_idle_time": {
              "type": "integer",
              "description": "微博认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_max_time": {
              "type": "integer",
              "description": "手机认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "phone_idle_time": {
              "type": "integer",
              "description": "手机认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_max_time": {
              "type": "integer",
              "description": "固定密码认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "static_idle_time": {
              "type": "integer",
              "description": "固定密码认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_max_time": {
              "type": "integer",
              "description": "一键认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "nopasswd_idle_time": {
              "type": "integer",
              "description": "一键认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_max_time": {
              "type": "integer",
              "description": "微信认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "weixin_idle_time": {
              "type": "integer",
              "description": "微信认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_max_time": {
              "type": "integer",
              "description": "Facebook认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "facebook_idle_time": {
              "type": "integer",
              "description": "Facebook认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_max_time": {
              "type": "integer",
              "description": "Google认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "google_idle_time": {
              "type": "integer",
              "description": "Google认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_max_time": {
              "type": "integer",
              "description": "Twitter认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "twitter_idle_time": {
              "type": "integer",
              "description": "Twitter认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_max_time": {
              "type": "integer",
              "description": "红包认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "redpacket_idle_time": {
              "type": "integer",
              "description": "红包认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_max_time": {
              "type": "integer",
              "description": "试用认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "tryout_idle_time": {
              "type": "integer",
              "description": "试用认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_max_time": {
              "type": "integer",
              "description": "酒店认证重新认证超时（分钟）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "hotel_idle_time": {
              "type": "integer",
              "description": "酒店认证空闲超时下线（秒）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "uri_add_apinfo": {
              "type": "integer",
              "description": "portal页URL是否追加连接AP信息",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "sync_switch": {
              "type": "integer",
              "description": "同步认证开关（开启后需配置interface、group_key、group_id）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "interface": {
              "type": "string",
              "description": "同步认证网卡接口",
              "example": "lan1"
            },
            "group_key": {
              "type": "string",
              "description": "同步认证组密钥",
              "default": "testing123",
              "example": "testing123"
            },
            "group_id": {
              "type": "integer",
              "description": "同步认证组播ID",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "ldap_usergroup": {
              "type": "string",
              "description": "LDAP用户所在组路径",
              "example": ""
            },
            "ldap_url": {
              "type": "string",
              "description": "LDAP服务器地址",
              "example": ""
            },
            "ldap_port": {
              "type": "integer",
              "description": "LDAP端口",
              "minimum": 1,
              "maximum": 65535,
              "default": 389,
              "example": 389
            },
            "ldap_mode": {
              "type": "integer",
              "description": "LDAP用户模式（0单用户组，1多用户组）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "ldap_base": {
              "type": "string",
              "description": "LDAP base_dn",
              "example": ""
            },
            "ldap_cname": {
              "type": "string",
              "description": "LDAP common name属性（cn或sAMAccountName）",
              "default": "cn",
              "example": "cn"
            },
            "ldap_admin_dn": {
              "type": "string",
              "description": "LDAP管理员全路径DN",
              "example": ""
            },
            "ldap_admin_passwd": {
              "type": "string",
              "description": "LDAP管理员密码",
              "example": ""
            },
            "ldap_share_count": {
              "type": "integer",
              "description": "LDAP允许同时上线个数（0表示不限制）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "proxy_service": {
              "type": "integer",
              "description": "HTTPS 443代理服务",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "proxy_ipaddr": {
              "type": "string",
              "description": "HTTPS代理IP地址",
              "format": "ipv4",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "WebAuthServiceConfigResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WebAuthServiceConfig"
                  }
                },
                "interface": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "可用的网卡接口列表（wan和lan）",
                  "example": [
                    "lan1",
                    "lan2",
                    "wan1"
                  ]
                },
                "template": {
                  "type": "integer",
                  "description": "是否有自定义模板（0无，1有）",
                  "example": 1
                }
              },
              "required": [
                "data",
                "interface",
                "template"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "web-auth",
        "x-displayName": "WEB认证服务管理",
        "description": "WEB认证服务配置管理，支持多种认证方式、QoS限速、独立超时配置和Radius/LDAP协议对接"
      }
    ]
  },
  "auth/authusers.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "用户账号管理API",
      "version": "1.0.0",
      "summary": "用户账号的完整管理功能",
      "description": "提供用户账号的完整管理功能，包括：\n- 账号的添加、修改、删除\n- 账号的启用和停用\n- 账号查询（列表和单个查询）\n- 支持多种拨号类型：PPPoE、PPTP、L2TP、OpenVPN、WEB等\n- 支持MAC绑定、IP地址分配、限速配置\n- 支持套餐管理和VLAN绑定\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/auth/users": {
        "get": {
          "summary": "获取用户账号列表",
          "description": "获取所有用户账号列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listPPPUsers",
          "tags": [
            "auth-users"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==\"（等于）\n- \"!=\"（不等于）\n- \">\"（大于）\n- \">=\"（大于等于）\n- \"<\"（小于）\n- \"<=\"（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：username、ppptype、enabled、packages等\n使用示例：\n- 单条件：filter=enabled==yes\n- AND条件：filter=enabled==yes&filter=ppptype==pppoe\n- OR条件：filter=username==test1,filter=username==test2\n",
              "schema": {
                "type": "string"
              },
              "example": "enabled==yes"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, username, create_time等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "username",
                  "create_time",
                  "expires",
                  "start_time"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "desc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取用户账号列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UserListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "bind_ifname": "any",
                          "last_conntime": 1766484104,
                          "last_offtime": 0,
                          "duration": 5709,
                          "passwd": "test001",
                          "id": 3,
                          "enabled": "yes",
                          "comment": "",
                          "username": "test001",
                          "tagname": "test001",
                          "expires": 0,
                          "start_time": 1766483024,
                          "create_time": 1766483041,
                          "ppptype": "any",
                          "cardid": "",
                          "pppname": "",
                          "share": 10,
                          "auto_mac": 0,
                          "upload": 0,
                          "download": 0,
                          "ip_type": 0,
                          "src_addr": {
                            "custom": {}
                          },
                          "mac": "",
                          "address": "",
                          "name": "",
                          "phone": "",
                          "packages": 0,
                          "proxy_username": "",
                          "pppoev6_wan": "",
                          "auto_vlanid": 0,
                          "bind_vlanid": "0"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加用户账号",
          "description": "添加新的用户账号。\n支持多种拨号类型和配置选项。\n",
          "operationId": "createPPPUser",
          "tags": [
            "auth-users"
          ],
          "requestBody": {
            "required": true,
            "description": "用户账号数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserInput"
                },
                "example": {
                  "username": "testuser",
                  "passwd": "123456",
                  "enabled": "yes",
                  "ppptype": "any",
                  "comment": "测试账号",
                  "expires": 0,
                  "start_time": 1766483024,
                  "share": 1,
                  "auto_mac": 0,
                  "upload": 0,
                  "download": 0,
                  "ip_type": 0,
                  "src_addr": {
                    "custom": [
                      "10.10.1.1"
                    ]
                  },
                  "mac": "",
                  "address": "",
                  "name": "",
                  "phone": "",
                  "cardid": "",
                  "pppoev6_wan": "",
                  "packages": 0,
                  "bind_vlanid": "0",
                  "bind_ifname": "any",
                  "auto_vlanid": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/auth/users/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "用户账号ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 3
            }
          }
        ],
        "get": {
          "summary": "获取指定用户账号",
          "description": "根据ID获取单个用户账号的详细信息。\n需要提供有效的账号ID。\n",
          "operationId": "getPPPUser",
          "tags": [
            "auth-users"
          ],
          "responses": {
            "200": {
              "description": "成功获取用户账号详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UserResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "修改用户账号",
          "description": "修改指定用户账号的配置信息。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePPPUser",
          "tags": [
            "auth-users"
          ],
          "requestBody": {
            "required": true,
            "description": "用户账号更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserUpdateInput"
                },
                "example": {
                  "enabled": "yes",
                  "comment": "更新后的备注",
                  "expires": 0,
                  "start_time": 1766483024,
                  "share": 2,
                  "auto_mac": 0,
                  "upload": 100,
                  "download": 200,
                  "ip_type": 1,
                  "src_addr": {
                    "object": [
                      {
                        "gp_name": "000new11",
                        "type": 0,
                        "gid": "IPGP1"
                      }
                    ]
                  },
                  "mac": "",
                  "address": "",
                  "name": "",
                  "phone": "",
                  "cardid": "",
                  "pppoev6_wan": "",
                  "packages": 0,
                  "bind_vlanid": "0",
                  "bind_ifname": "any",
                  "auto_vlanid": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除用户账号",
          "description": "删除指定的用户账号。\n删除后账号将被永久移除，无法恢复。\n",
          "operationId": "deletePPPUser",
          "tags": [
            "auth-users"
          ],
          "responses": {
            "200": {
              "description": "用户账号删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问用户账号管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "用户账号不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "User": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "username",
            "passwd",
            "ppptype"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "账号ID",
              "minimum": 1,
              "example": 3
            },
            "enabled": {
              "type": "string",
              "description": "账号状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "测试账号"
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 64,
              "example": "test001"
            },
            "passwd": {
              "type": "string",
              "description": "密码（必填，最多64个字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "123456"
            },
            "expires": {
              "type": "integer",
              "description": "过期日期（时间戳）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "start_time": {
              "type": "integer",
              "description": "开始日期（时间戳）",
              "minimum": 0,
              "default": 0,
              "example": 1766483024
            },
            "create_time": {
              "type": "integer",
              "description": "创建时间（时间戳）",
              "minimum": 0,
              "readOnly": true,
              "example": 1766483041
            },
            "ppptype": {
              "type": "string",
              "description": "拨号类型：\n- any: 任意类型\n- pppoe: PPPoE拨号\n- pptp: PPTP拨号\n- l2tp: L2TP拨号\n- ovpn: OpenVPN拨号\n- web: WEB认证\n- pppoe_relay: PPPoE中继\n",
              "enum": [
                "any",
                "pppoe",
                "pptp",
                "l2tp",
                "ovpn",
                "web",
                "pppoe_relay",
                "ike"
              ],
              "example": "any"
            },
            "pppname": {
              "type": "string",
              "description": "PPPoE中继类型使用，选择外网接口",
              "example": "wan1"
            },
            "share": {
              "type": "integer",
              "description": "共享数",
              "minimum": 1,
              "default": 1,
              "example": 10
            },
            "auto_mac": {
              "type": "integer",
              "description": "自动绑定MAC",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "description": "上传限速（KB/s）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KB/s）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "ip_type": {
              "type": "integer",
              "description": "IP类型（0:固定IP，1:地址池）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src_addr": {
              "type": "object",
              "description": "固定IP或地址池配置。\n- ip_type=0时，使用custom格式，包含IP地址数组\n- ip_type=1时，使用object格式，包含地址池对象数组\n",
              "properties": {
                "custom": {
                  "type": "array",
                  "description": "自定义IP地址列表",
                  "items": {
                    "type": "string",
                    "format": "ipv4"
                  },
                  "example": [
                    "10.10.1.1"
                  ]
                },
                "object": {
                  "type": "array",
                  "description": "地址池对象列表",
                  "items": {
                    "type": "object",
                    "properties": {
                      "gp_name": {
                        "type": "string",
                        "description": "地址池名称",
                        "example": "000new11"
                      },
                      "type": {
                        "type": "integer",
                        "description": "地址池类型",
                        "enum": [
                          0,
                          1,
                          2,
                          3,
                          4,
                          5,
                          6
                        ],
                        "example": 0
                      },
                      "gid": {
                        "type": "string",
                        "description": "地址池组ID",
                        "example": "IPGP1"
                      }
                    },
                    "required": [
                      "gp_name",
                      "type",
                      "gid"
                    ]
                  }
                }
              },
              "additionalProperties": false,
              "example": {
                "custom": [
                  "10.10.1.1"
                ]
              }
            },
            "mac": {
              "type": "string",
              "description": "绑定MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": ""
            },
            "address": {
              "type": "string",
              "description": "住址",
              "maxLength": 512,
              "example": ""
            },
            "name": {
              "type": "string",
              "description": "姓名",
              "maxLength": 128,
              "example": ""
            },
            "phone": {
              "type": "string",
              "description": "手机号",
              "maxLength": 64,
              "example": ""
            },
            "cardid": {
              "type": "string",
              "description": "证件号码",
              "maxLength": 64,
              "example": ""
            },
            "pppoev6_wan": {
              "type": "string",
              "description": "PPPoE接口继承WAN的前缀",
              "example": ""
            },
            "packages": {
              "type": "integer",
              "description": "套餐类型（对应套餐功能的id，id=0表示自定义）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "bind_vlanid": {
              "type": "string",
              "description": "绑定VLANID（0表示不绑定，支持格式2000/2000.400，数字范围1-4090）",
              "pattern": "^(0|([1-9][0-9]{0,3}|[1-3][0-9]{4}|40[0-8][0-9]|4090)(\\/([1-9][0-9]{0,3}|[1-3][0-9]{4}|40[0-8][0-9]|4090)(\\.([1-9][0-9]{0,3}|[1-3][0-9]{4}|40[0-8][0-9]|4090))?)?)$",
              "example": "0"
            },
            "bind_ifname": {
              "type": "string",
              "description": "绑定网卡名称（any表示任意网卡）",
              "example": "any"
            },
            "auto_vlanid": {
              "type": "integer",
              "description": "开启自动绑定VLAN",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "tagname": {
              "type": "string",
              "description": "标识名称（支持中文/数字/字母/下划线/连字符，不能以符号开头，1-15字符）",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]{0,63}$",
              "example": "test001"
            },
            "proxy_username": {
              "type": "string",
              "description": "代拨账号",
              "example": ""
            },
            "last_conntime": {
              "type": "integer",
              "description": "最后一次连接时间（时间戳）",
              "minimum": 0,
              "readOnly": true,
              "example": 1766484104
            },
            "last_offtime": {
              "type": "integer",
              "description": "最后一次离线时间（时间戳）",
              "minimum": 0,
              "readOnly": true,
              "example": 0
            },
            "duration": {
              "type": "integer",
              "description": "连接时长（秒）",
              "minimum": 0,
              "readOnly": true,
              "example": 5709
            }
          },
          "additionalProperties": false
        },
        "UserInput": {
          "type": "object",
          "required": [
            "username",
            "passwd",
            "enabled",
            "ppptype",
            "packages",
            "upload",
            "download",
            "start_time",
            "expires",
            "share",
            "ip_type",
            "auto_mac",
            "auto_vlanid",
            "bind_vlanid",
            "bind_ifname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "账号状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "测试账号"
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 128,
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（必填，最多64个字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "123456"
            },
            "expires": {
              "type": "integer",
              "description": "过期日期（时间戳）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "start_time": {
              "type": "integer",
              "description": "开始日期（时间戳）",
              "minimum": 0,
              "default": 0,
              "example": 1766483024
            },
            "ppptype": {
              "type": "string",
              "description": "拨号类型",
              "enum": [
                "any",
                "pppoe",
                "pptp",
                "l2tp",
                "ovpn",
                "web",
                "pppoe_relay",
                "ike"
              ],
              "example": "pppoe"
            },
            "pppname": {
              "type": "string",
              "description": "PPPoE中继类型使用，选择外网接口",
              "example": "wan1"
            },
            "share": {
              "type": "integer",
              "description": "共享数",
              "minimum": 1,
              "default": 1,
              "example": 1
            },
            "auto_mac": {
              "type": "integer",
              "description": "自动绑定MAC",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "description": "上传限速（KB/s）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KB/s）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "ip_type": {
              "type": "integer",
              "description": "IP类型（0:固定IP，1:地址池）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "src_addr": {
              "type": "object",
              "description": "固定IP或地址池配置",
              "properties": {
                "custom": {
                  "type": "object"
                }
              },
              "additionalProperties": true,
              "example": {
                "custom": {}
              }
            },
            "mac": {
              "type": "string",
              "description": "绑定MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": ""
            },
            "address": {
              "type": "string",
              "description": "住址",
              "maxLength": 512,
              "example": ""
            },
            "name": {
              "type": "string",
              "description": "姓名",
              "maxLength": 128,
              "example": ""
            },
            "phone": {
              "type": "string",
              "description": "手机号",
              "maxLength": 64,
              "example": ""
            },
            "cardid": {
              "type": "string",
              "description": "证件号码",
              "maxLength": 64,
              "example": ""
            },
            "pppoev6_wan": {
              "type": "string",
              "description": "PPPoE接口继承WAN的前缀",
              "example": ""
            },
            "packages": {
              "type": "integer",
              "description": "套餐类型（对应套餐功能的id，id=0表示自定义）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "bind_vlanid": {
              "type": "string",
              "description": "绑定VLANID（0表示不绑定，支持格式2000/2000.400，数字范围1-4090）",
              "pattern": "^(0|([1-9][0-9]{0,3}|[1-3][0-9]{4}|40[0-8][0-9]|4090)(\\/([1-9][0-9]{0,3}|[1-3][0-9]{4}|40[0-8][0-9]|4090)(\\.([1-9][0-9]{0,3}|[1-3][0-9]{4}|40[0-8][0-9]|4090))?)?)$",
              "example": "0"
            },
            "bind_ifname": {
              "type": "string",
              "description": "绑定网卡名称（any表示任意网卡）",
              "example": "any"
            },
            "auto_vlanid": {
              "type": "integer",
              "description": "开启自动绑定VLAN",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "UserUpdateInput": {
          "type": "object",
          "required": [
            "username",
            "passwd",
            "enabled",
            "ppptype",
            "packages",
            "upload",
            "download",
            "start_time",
            "expires",
            "share",
            "ip_type",
            "auto_mac",
            "auto_vlanid",
            "bind_vlanid",
            "pppname",
            "pppoev6_wan",
            "bind_ifname",
            "src_addr",
            "mac",
            "address",
            "name",
            "phone",
            "cardid",
            "comment"
          ],
          "properties": {
            "username": {
              "type": "string",
              "description": "用户名（编辑页不可修改，需带回原值）",
              "minLength": 1,
              "maxLength": 64,
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（最多64个字符）",
              "minLength": 1,
              "maxLength": 64,
              "example": "newpassword"
            },
            "enabled": {
              "type": "string",
              "description": "账号状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "ppptype": {
              "type": "string",
              "description": "拨号类型",
              "enum": [
                "any",
                "pppoe",
                "pptp",
                "l2tp",
                "ovpn",
                "web",
                "pppoe_relay",
                "ike"
              ],
              "example": "any"
            },
            "packages": {
              "type": "integer",
              "description": "套餐类型（0表示自定义）",
              "minimum": 0,
              "example": 0
            },
            "upload": {
              "type": "integer",
              "description": "上传限速（KB/s）",
              "minimum": 0,
              "maximum": 999999,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KB/s）",
              "minimum": 0,
              "maximum": 999999,
              "example": 0
            },
            "start_time": {
              "type": "integer",
              "description": "开始日期（时间戳）",
              "minimum": 0,
              "example": 1766483024
            },
            "expires": {
              "type": "integer",
              "description": "过期日期（时间戳，0表示不过期）",
              "minimum": 0,
              "example": 0
            },
            "share": {
              "type": "integer",
              "description": "共享数",
              "minimum": 1,
              "maximum": 999,
              "example": 1
            },
            "ip_type": {
              "type": "integer",
              "description": "IP类型（0:固定IP，1:地址池）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "auto_mac": {
              "type": "integer",
              "description": "自动绑定MAC",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "auto_vlanid": {
              "type": "integer",
              "description": "开启自动绑定VLAN",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "bind_vlanid": {
              "type": "string",
              "description": "绑定VLANID（0表示不绑定）",
              "example": "0"
            },
            "pppname": {
              "type": "string",
              "description": "PPPoE中继类型使用，选择外网接口",
              "example": ""
            },
            "pppoev6_wan": {
              "type": "string",
              "description": "PPPoE接口继承WAN的前缀",
              "example": ""
            },
            "bind_ifname": {
              "type": "string",
              "description": "绑定网卡名称（any表示任意网卡）",
              "example": "any"
            },
            "src_addr": {
              "type": "object",
              "description": "固定IP或地址池配置",
              "additionalProperties": true,
              "example": {
                "custom": {}
              }
            },
            "mac": {
              "type": "string",
              "description": "绑定MAC地址",
              "example": ""
            },
            "address": {
              "type": "string",
              "description": "住址",
              "example": ""
            },
            "name": {
              "type": "string",
              "description": "姓名",
              "example": ""
            },
            "phone": {
              "type": "string",
              "description": "手机号",
              "example": ""
            },
            "cardid": {
              "type": "string",
              "description": "证件号码",
              "example": ""
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "UserResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UserListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "description": "PPP用户账号列表",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "auth-users",
        "x-displayName": "用户账号管理",
        "description": "用户账号管理，支持PPPoE、PPTP、L2TP、OpenVPN、WEB等多种拨号类型"
      }
    ]
  },
  "auth/online-users.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "认证用户管理API",
      "version": "1.0.0",
      "summary": "认证用户的完整管理功能",
      "description": "提供认证用户的完整管理功能，包括：\n- 认证用户列表查询\n- 断开认证用户连接\n- 支持分页、模糊匹配和过滤功能\n- 支持多种认证类型：PPPoE、PPTP、L2TP、OpenVPN、WEB、IPSec等\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/auth/online-users": {
        "get": {
          "summary": "获取认证用户列表",
          "description": "获取所有认证用户配置列表。\n支持分页、排序、模糊匹配和过滤功能。\n包括在线用户的详细信息，如认证时间、会话ID、IP地址、MAC地址等。\n",
          "operationId": "listAuthUsers",
          "tags": [
            "online-users"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==\"（等于）\n- \"!=\"（不等于）\n- \">\"（大于）\n- \">=\"（大于等于）\n- \"<\"（小于）\n- \"<=\"（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：username、name、ppptype、ip_addr、mac、auth_time、phone、interface、proxy_username、comment等\n",
              "schema": {
                "type": "string"
              },
              "example": "ppptype==pptp"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id、username、auth_time等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "username",
                  "ip_addr_int",
                  "auth_time"
                ],
                "default": "auth_time"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "desc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取认证用户列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AuthUserListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "username": "test001",
                          "ppptype": "pptp",
                          "auth_time": 1766483110,
                          "session": "1766483110220428830",
                          "id": 1,
                          "interface": "",
                          "pppdev": "ppp0",
                          "webid": 0,
                          "expires": 0,
                          "packages": 0,
                          "upload": 0,
                          "download": 0,
                          "proxy_username": "",
                          "pppoev6_wan": "",
                          "check_vlan_res": 1,
                          "ip_addr_int": "167772162",
                          "mac": "192.168.3.119",
                          "comment": "",
                          "name": "",
                          "phone": "",
                          "packname": "",
                          "ip_addr": "10.0.0.2"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/auth/online-users/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "认证用户ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定认证用户",
          "description": "根据ID获取单个认证用户的详细信息。\n需要提供有效的用户ID。\n",
          "operationId": "getAuthUser",
          "tags": [
            "online-users"
          ],
          "responses": {
            "200": {
              "description": "成功获取认证用户详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AuthUserResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "断开认证用户",
          "description": "断开指定认证用户的连接。\n删除后用户将被强制下线，需要重新认证。\n",
          "operationId": "deleteAuthUser",
          "tags": [
            "online-users"
          ],
          "responses": {
            "200": {
              "description": "认证用户断开成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问认证用户管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "认证用户不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AuthUser": {
          "type": "object",
          "required": [
            "id",
            "auth_time",
            "session",
            "username",
            "ppptype",
            "ip_addr",
            "mac"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "用户ID",
              "minimum": 1,
              "example": 1
            },
            "auth_time": {
              "type": "integer",
              "description": "认证时间（时间戳）",
              "minimum": 0,
              "example": 1766483110
            },
            "session": {
              "type": "string",
              "description": "SESSION会话ID",
              "example": "1766483110220428830"
            },
            "uid": {
              "type": "string",
              "description": "用户ID",
              "example": "user123"
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "minLength": 1,
              "maxLength": 64,
              "example": "test001"
            },
            "ppptype": {
              "type": "string",
              "description": "认证类型：\n- any: 任意认证\n- pppoe: PPPoE认证\n- pptp: PPTP认证\n- l2tp: L2TP认证\n- ovpn: OpenVPN认证\n- web: WEB认证\n- pppoe_relay: PPPoE中继\n- ike: IPSec认证\n",
              "enum": [
                "any",
                "pppoe",
                "pptp",
                "l2tp",
                "ovpn",
                "web",
                "pppoe_relay",
                "ike"
              ],
              "example": "pptp"
            },
            "pppdev": {
              "type": "string",
              "description": "PPPD设备（PPPD认证时必填）",
              "example": "ppp0"
            },
            "ip_addr": {
              "type": "string",
              "description": "客户端IP地址",
              "format": "ipv4",
              "example": "10.0.0.2"
            },
            "ip_addr_int": {
              "type": "string",
              "description": "客户端IP地址（整数格式）",
              "example": "167772162"
            },
            "upload": {
              "type": "integer",
              "description": "限速上行（kbps）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "限速下行（kbps）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "192.168.3.119"
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "example": "wan1"
            },
            "expires": {
              "type": "integer",
              "description": "过期时间（时间戳）",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "packages": {
              "type": "integer",
              "description": "套餐ID",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "packname": {
              "type": "string",
              "description": "套餐名称",
              "example": "基础套餐"
            },
            "phone": {
              "type": "string",
              "description": "手机号",
              "pattern": "^[0-9]{11}$",
              "example": "13800138000"
            },
            "name": {
              "type": "string",
              "description": "姓名",
              "example": "张三"
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "minLength": 0,
              "maxLength": 64,
              "pattern": "^[\\\\u4e00-\\\\u9fa5a-zA-Z0-9][\\\\u4e00-\\\\u9fa5a-zA-Z0-9_-]*$",
              "example": ""
            },
            "proxy_username": {
              "type": "string",
              "description": "代拨账号",
              "example": ""
            },
            "pppoev6_wan": {
              "type": "string",
              "description": "PPPoE接口继承WAN的前缀",
              "example": ""
            },
            "check_vlan_res": {
              "type": "integer",
              "description": "PPPoE的QinQ VLAN检测结果",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "webid": {
              "type": "integer",
              "description": "WEB认证类型ID（WEB认证时必填）",
              "minimum": 0,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "AuthUserResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AuthUser"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "AuthUserListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "description": "认证用户列表",
                  "items": {
                    "$ref": "#/components/schemas/AuthUser"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "online-users",
        "x-displayName": "认证用户管理",
        "description": "认证用户管理和连接控制，支持PPPoE、PPTP、L2TP、OpenVPN、WEB等多种认证方式"
      }
    ]
  },
  "auth/packages.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "套餐管理API",
      "version": "1.0.0",
      "summary": "套餐的完整管理功能",
      "description": "提供套餐的完整管理功能，包括：\n- 套餐的添加、修改、删除\n- 套餐的启用和停用\n- 套餐查询（列表和单个查询）\n- 支持套餐时间、价格、速率配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/auth/packages": {
        "get": {
          "summary": "获取套餐列表",
          "description": "获取所有套餐列表。\n支持分页、排序、模糊匹配和过滤功能。\n",
          "operationId": "listPackages",
          "tags": [
            "packages"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==\"（等于）\n- \"!=\"（不等于）\n- \">\"（大于）\n- \">=\"（大于等于）\n- \"<\"（小于）\n- \"<=\"（小于等于）\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,filter=field2==value2\n\n支持的字段：packname、price等\n使用示例：\n- 单条件：filter=packname==test\n- AND条件：filter=price>=100&filter=price<=500\n",
              "schema": {
                "type": "string"
              },
              "example": "packname==test"
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段（id, packname, price等）",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "packname",
                  "price",
                  "up_speed",
                  "down_speed"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式（asc:升序, desc:降序）",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "desc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取套餐列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PackageListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "packname": "test001",
                          "tagname": "test001",
                          "packtime": "12m",
                          "price": 100,
                          "up_speed": 500,
                          "down_speed": 500,
                          "comment": ""
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "添加套餐",
          "description": "添加新的套餐。\n支持配置套餐时间、价格和速率。\n",
          "operationId": "createPackage",
          "tags": [
            "packages"
          ],
          "requestBody": {
            "required": true,
            "description": "套餐数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageInput"
                },
                "example": {
                  "packname": "基础套餐",
                  "packtime": "3m",
                  "price": 100,
                  "up_speed": 500,
                  "down_speed": 1000,
                  "comment": "月度基础套餐"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/auth/packages/{id}": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "套餐ID",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "example": 1
            }
          }
        ],
        "get": {
          "summary": "获取指定套餐",
          "description": "根据ID获取单个套餐的详细信息。\n需要提供有效的套餐ID。\n",
          "operationId": "getPackage",
          "tags": [
            "packages"
          ],
          "responses": {
            "200": {
              "description": "成功获取套餐详情",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PackageResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "修改套餐",
          "description": "修改指定套餐的配置信息。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updatePackage",
          "tags": [
            "packages"
          ],
          "requestBody": {
            "required": true,
            "description": "套餐更新数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageInput"
                },
                "example": {
                  "packname": "升级套餐",
                  "packtime": "6m",
                  "price": 200,
                  "up_speed": 1000,
                  "down_speed": 2000,
                  "comment": "半年升级套餐"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除套餐",
          "description": "删除指定的套餐。\n删除后套餐将被永久移除，无法恢复。\n",
          "operationId": "deletePackage",
          "tags": [
            "packages"
          ],
          "responses": {
            "200": {
              "description": "套餐删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "message": "success"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问套餐管理"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "套餐不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "成功状态码，创建接口中为0",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "Package": {
          "type": "object",
          "required": [
            "id",
            "packname",
            "packtime",
            "price",
            "up_speed",
            "down_speed"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "套餐ID",
              "minimum": 1,
              "example": 1
            },
            "packname": {
              "type": "string",
              "description": "套餐名称（必填，最多15个字符）",
              "minLength": 1,
              "maxLength": 15,
              "example": "test001"
            },
            "tagname": {
              "type": "string",
              "description": "名称，支持中文、英文、数字、下划线和连字符，1-15个字符，不能以下划线或连字符开头",
              "maxLength": 15,
              "example": "test001"
            },
            "packtime": {
              "type": "string",
              "description": "套餐时间（格式：数字+时间单位）\n- 时间单位：m=月，d=天，h=小时\n- 数字范围：1-999，不能为前导零\n- 示例：3m=3个月，3d=3天，3h=3小时\n",
              "pattern": "^([1-9][0-9]{0,2})[mdh]$",
              "example": "12m"
            },
            "price": {
              "type": "integer",
              "description": "套餐价格",
              "minimum": 1,
              "maximum": 99999,
              "example": 100
            },
            "up_speed": {
              "type": "integer",
              "description": "上行速率（KB/s）",
              "minimum": 0,
              "maximum": 999999,
              "example": 500
            },
            "down_speed": {
              "type": "integer",
              "description": "下行速率（KB/s）",
              "minimum": 0,
              "maximum": 999999,
              "example": 500
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "PackageInput": {
          "type": "object",
          "required": [
            "packname",
            "packtime",
            "price",
            "up_speed",
            "down_speed"
          ],
          "properties": {
            "packname": {
              "type": "string",
              "description": "套餐名称（必填，最多15个字符）",
              "minLength": 1,
              "maxLength": 15,
              "example": "基础套餐"
            },
            "packtime": {
              "type": "string",
              "description": "套餐时间（格式：数字+时间单位）\n- 时间单位：m=月，d=天，h=小时\n- 数字范围：1-999，不能为前导零\n- 示例：3m=3个月，3d=3天，3h=3小时\n",
              "pattern": "^([1-9][0-9]{0,2})[mdh]$",
              "example": "3m"
            },
            "price": {
              "type": "integer",
              "description": "套餐价格",
              "minimum": 1,
              "maximum": 99999,
              "example": 100
            },
            "up_speed": {
              "type": "integer",
              "description": "上行速率（KB/s）",
              "minimum": 0,
              "maximum": 999999,
              "example": 500
            },
            "down_speed": {
              "type": "integer",
              "description": "下行速率（KB/s）",
              "minimum": 0,
              "maximum": 999999,
              "example": 1000
            },
            "comment": {
              "type": "string",
              "description": "备注信息，最多64个字符，不支持特殊字符",
              "maxLength": 64,
              "example": "月度基础套餐"
            }
          },
          "additionalProperties": false
        },
        "PackageResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Package"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PackageListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "description": "套餐列表",
                  "items": {
                    "$ref": "#/components/schemas/Package"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/SuccessResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "packages",
        "x-displayName": "套餐管理",
        "description": "套餐管理，支持套餐时间、价格、速率配置"
      }
    ]
  },
  "advanced/advanced-ftp-server.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "FTP服务管理API",
      "version": "1.0.0",
      "summary": "FTP服务的完整管理功能",
      "description": "提供FTP服务的完整管理功能，包括：\n- FTP服务开关、端口、外网访问配置\n- FTP用户增删改查\n- 用户权限和限速控制\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/advanced-service/ftp-config": {
        "get": {
          "summary": "获取FTP服务配置",
          "description": "获取当前FTP服务的配置信息，包括服务开关、端口和外网访问控制。",
          "operationId": "getFtpConfig",
          "tags": [
            "ftp-config"
          ],
          "responses": {
            "200": {
              "description": "成功获取FTP服务配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/FtpConfigResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "open_ftp": 0,
                      "ftp_port": 21,
                      "ftp_access": 1
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新FTP服务配置",
          "description": "全量更新FTP服务配置。所有字段均为必填，即使未修改也必须携带原值。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateFtpConfig",
          "tags": [
            "ftp-config"
          ],
          "requestBody": {
            "required": true,
            "description": "FTP服务配置（全量更新，所有字段必填，未修改的字段须传原值）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FtpConfigEditInput"
                },
                "example": {
                  "open_ftp": 1,
                  "ftp_port": 21,
                  "ftp_access": 1
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/advanced-service/ftp-users": {
        "get": {
          "summary": "获取FTP用户列表",
          "description": "获取FTP用户列表，支持分页、过滤和排序。",
          "operationId": "listFtpUsers",
          "tags": [
            "ftp-users"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "default": 1,
                "minimum": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "default": 20,
                "minimum": 1
              }
            },
            {
              "name": "key",
              "in": "query",
              "description": "搜索字段名，与pattern联合使用",
              "schema": {
                "type": "string",
                "enum": [
                  "username",
                  "enabled",
                  "permission",
                  "home_dir"
                ]
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "搜索关键词，与key联合使用",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "username",
                  "enabled"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取FTP用户列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/FtpUserListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "username": "testuser",
                          "tagname": "testuser",
                          "passwd": "123456",
                          "permission": "rw",
                          "home_dir": "/test-001",
                          "upload": 0,
                          "download": 0
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "新增FTP用户",
          "description": "创建新的FTP用户。tagname由系统自动设置为username的值，无需传入。\n\n`home_dir` 应先通过 `GET /api/v4.0/system/files?path=/` 查询可用存储目录，\n再从返回的 `results.data[].f_name` 组合为目录路径，例如 `/test-001`。\n",
          "operationId": "createFtpUser",
          "tags": [
            "ftp-users"
          ],
          "requestBody": {
            "required": true,
            "description": "FTP用户创建数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FtpUserCreateInput"
                },
                "example": {
                  "enabled": "yes",
                  "username": "testuser",
                  "passwd": "123456",
                  "permission": "rw",
                  "home_dir": "/test-001",
                  "upload": 0,
                  "download": 0
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "FTP用户创建成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "success",
                    "rowid": 1
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/advanced-service/ftp-users/{id}": {
        "put": {
          "summary": "更新FTP用户",
          "description": "全量更新FTP用户配置。所有字段均为必填，即使未修改也必须携带原值。tagname由系统自动设置为username的值。\n\n`home_dir` 应先通过 `GET /api/v4.0/system/files?path=/` 查询可用存储目录，\n再从返回的 `results.data[].f_name` 组合为目录路径，例如 `/test-001`。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateFtpUser",
          "tags": [
            "ftp-users"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/ftpUserIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "description": "FTP用户更新数据（全量更新，所有字段必填，未修改的字段须传原值）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FtpUserEditInput"
                },
                "example": {
                  "enabled": "yes",
                  "username": "testuser",
                  "passwd": "123456",
                  "permission": "rw",
                  "home_dir": "/test-001",
                  "upload": 0,
                  "download": 0,
                  "tagname": "testuser"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用FTP用户",
          "description": "快速启用或停用指定的FTP用户账户。",
          "operationId": "toggleFtpUser",
          "tags": [
            "ftp-users"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/ftpUserIdParam"
            }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "description": "用户状态",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除FTP用户",
          "description": "删除指定的FTP用户账户。",
          "operationId": "deleteFtpUser",
          "tags": [
            "ftp-users"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/ftpUserIdParam"
            }
          ],
          "responses": {
            "200": {
              "description": "FTP用户删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "ftpUserIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "FTP用户ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "响应状态码",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的记录ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误代码",
              "example": 3001
            },
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "详细错误信息",
              "items": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "description": "错误字段"
                  },
                  "type": {
                    "type": "string",
                    "description": "错误类型"
                  },
                  "msg": {
                    "type": "string",
                    "description": "错误消息"
                  }
                }
              }
            }
          },
          "required": [
            "code",
            "message"
          ]
        },
        "FtpConfigResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "open_ftp": {
                  "type": "integer",
                  "description": "FTP服务开关（0关闭，1开启）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 0
                },
                "ftp_port": {
                  "type": "integer",
                  "description": "FTP服务端口",
                  "example": 21
                },
                "ftp_access": {
                  "type": "integer",
                  "description": "是否允许外网访问（0不允许，1允许）",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 1
                }
              },
              "required": [
                "open_ftp",
                "ftp_port",
                "ftp_access"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "FtpConfigEditInput": {
          "type": "object",
          "description": "FTP服务配置全量编辑。所有字段均为必填，未修改的字段须传原值。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "required": [
            "open_ftp",
            "ftp_port",
            "ftp_access"
          ],
          "properties": {
            "open_ftp": {
              "type": "integer",
              "description": "FTP服务开关（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "ftp_port": {
              "type": "integer",
              "description": "FTP服务端口，范围1-65535，但排除600-799、1234-1240、12345、34567",
              "minimum": 1,
              "maximum": 65535,
              "example": 21
            },
            "ftp_access": {
              "type": "integer",
              "description": "是否允许外网访问（0不允许，1允许）",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "FtpUser": {
          "type": "object",
          "description": "FTP用户信息（GET返回）",
          "required": [
            "id",
            "enabled",
            "username",
            "tagname",
            "passwd",
            "permission",
            "home_dir"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "用户ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "用户状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "username": {
              "type": "string",
              "description": "用户名（唯一）",
              "maxLength": 15,
              "example": "testuser"
            },
            "tagname": {
              "type": "string",
              "description": "名称标签（系统自动设为username值）",
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（返回时为解密后的明文）",
              "example": "123456"
            },
            "permission": {
              "type": "string",
              "description": "读写权限（rw读写，ro只读）",
              "enum": [
                "rw",
                "ro"
              ],
              "example": "rw"
            },
            "home_dir": {
              "type": "string",
              "description": "用户目录。取值应来自 `GET /api/v4.0/system/files?path=/` 返回的存储目录路径",
              "example": "/test-001"
            },
            "upload": {
              "type": "integer",
              "description": "上传限速（KByte/s），0不限速",
              "minimum": 0,
              "maximum": 1000000000,
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KByte/s），0不限速",
              "minimum": 0,
              "maximum": 1000000000,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "FtpUserCreateInput": {
          "type": "object",
          "description": "FTP用户新增输入。tagname由系统自动设置为username，无需传入。",
          "required": [
            "enabled",
            "username",
            "passwd",
            "permission",
            "home_dir"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "用户状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "username": {
              "type": "string",
              "description": "用户名（唯一，不可重复）",
              "minLength": 1,
              "maxLength": 15,
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "123456"
            },
            "permission": {
              "type": "string",
              "description": "读写权限（rw读写，ro只读）",
              "enum": [
                "rw",
                "ro"
              ],
              "example": "rw"
            },
            "home_dir": {
              "type": "string",
              "description": "用户目录。先调用 `GET /api/v4.0/system/files?path=/` 获取可用目录，再填写对应目录路径；不可为 `/`，不可含 `..`",
              "example": "/test-001"
            },
            "upload": {
              "type": "integer",
              "description": "上传限速（KByte/s），0不限速",
              "minimum": 0,
              "maximum": 1000000000,
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KByte/s），0不限速",
              "minimum": 0,
              "maximum": 1000000000,
              "default": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "FtpUserEditInput": {
          "type": "object",
          "description": "FTP用户全量编辑。所有字段均为必填，未修改的字段须传原值。tagname由系统自动设为username值，但仍须传入。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "required": [
            "enabled",
            "username",
            "passwd",
            "permission",
            "home_dir",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "用户状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "username": {
              "type": "string",
              "description": "用户名（唯一，不可重复）",
              "minLength": 1,
              "maxLength": 15,
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码",
              "minLength": 1,
              "maxLength": 64,
              "example": "123456"
            },
            "permission": {
              "type": "string",
              "description": "读写权限（rw读写，ro只读）",
              "enum": [
                "rw",
                "ro"
              ],
              "example": "rw"
            },
            "home_dir": {
              "type": "string",
              "description": "用户目录。先调用 `GET /api/v4.0/system/files?path=/` 获取可用目录，再填写对应目录路径；不可为 `/`，不可含 `..`",
              "example": "/test-001"
            },
            "upload": {
              "type": "integer",
              "description": "上传限速（KByte/s），0不限速",
              "minimum": 0,
              "maximum": 1000000000,
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KByte/s），0不限速",
              "minimum": 0,
              "maximum": 1000000000,
              "default": 0,
              "example": 0
            },
            "tagname": {
              "type": "string",
              "description": "名称标签（系统自动设为username值，但须传入）",
              "example": "testuser"
            }
          },
          "additionalProperties": false
        },
        "FtpUserListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FtpUser"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 3001,
                "message": "请求参数不合法",
                "details": [
                  {
                    "field": "permission",
                    "type": "invalid",
                    "msg": "permission must be ro or rw"
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 404,
                "message": "资源不存在"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突（如用户名重复）",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 3001,
                "message": "请求参数不合法",
                "details": [
                  {
                    "field": "username",
                    "type": "unique",
                    "msg": "用户名已存在"
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误"
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "JWT认证令牌"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "ftp-config",
        "x-displayName": "FTP配置",
        "description": "FTP服务基础配置管理（开关、端口、外网访问）"
      },
      {
        "name": "ftp-users",
        "x-displayName": "FTP用户管理",
        "description": "FTP用户的增删改查操作"
      }
    ]
  },
  "advanced/advanced-http-server.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "HTTP服务器管理API",
      "version": "1.0.0",
      "summary": "HTTP服务器管理完整功能",
      "description": "提供HTTP服务器的完整管理功能，包括：\n- HTTP服务器的创建、查询、更新、删除\n- HTTP服务器启用/停用状态控制\n- 支持SSL加密、目录浏览、下载限速等配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/advanced-service/http-users": {
        "get": {
          "summary": "获取HTTP服务器列表",
          "operationId": "listHttpServerUsers",
          "tags": [
            "http-server"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "key",
              "in": "query",
              "description": "搜索字段名，与pattern联合使用",
              "schema": {
                "type": "string",
                "enum": [
                  "tagname",
                  "enabled",
                  "http_port",
                  "server_name"
                ]
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "搜索关键词，与key联合使用",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "tagname",
                  "http_port"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取HTTP服务器列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/HttpServerListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建HTTP服务器",
          "description": "创建HTTP服务器。\n\n`home_dir` 应先通过 `GET /api/v4.0/system/files?path=/` 查询可用存储目录，\n再从返回的 `results.data[].f_name` 组合为目录路径，例如 `/test-001`。\n",
          "operationId": "createHttpServerUser",
          "tags": [
            "http-server"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpServerCreateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/advanced-service/http-users/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/httpServerIdParam"
          }
        ],
        "put": {
          "summary": "更新HTTP服务器",
          "description": "全量更新HTTP服务器配置。所有字段均为必填，即使未修改也必须携带原值。\n\n`home_dir` 应先通过 `GET /api/v4.0/system/files?path=/` 查询可用存储目录，\n再从返回的 `results.data[].f_name` 组合为目录路径，例如 `/test-001`。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateHttpServerUser",
          "tags": [
            "http-server"
          ],
          "requestBody": {
            "required": true,
            "description": "全量更新，所有字段必填，未修改的字段须传原值",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpServerEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用HTTP服务器",
          "operationId": "patchHttpServerUser",
          "tags": [
            "http-server"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除HTTP服务器",
          "operationId": "deleteHttpServerUser",
          "tags": [
            "http-server"
          ],
          "responses": {
            "200": {
              "description": "删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "httpServerIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "HTTP服务器ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的记录ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "HttpServer": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "tagname",
            "http_port",
            "ssl_on",
            "autoindex",
            "download",
            "home_dir",
            "access"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "启用状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "服务器名称（唯一）",
              "example": "myhttp"
            },
            "http_port": {
              "type": "integer",
              "description": "HTTP端口",
              "minimum": 1,
              "maximum": 65535,
              "example": 8888
            },
            "server_name": {
              "type": "string",
              "description": "服务器域名（ServerName），可为空",
              "default": "",
              "example": ""
            },
            "ssl_on": {
              "type": "integer",
              "description": "是否开启SSL加密（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "autoindex": {
              "type": "integer",
              "description": "是否开启目录浏览（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "home_dir": {
              "type": "string",
              "description": "用户目录路径。取值应来自 `GET /api/v4.0/system/files?path=/` 返回的存储目录路径；不可为 `/`，不可含 `..`",
              "example": "/test-001"
            },
            "access": {
              "type": "integer",
              "description": "是否允许外网访问（0不允许，1允许）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "HttpServerCreateInput": {
          "type": "object",
          "description": "HTTP服务器创建输入",
          "required": [
            "enabled",
            "tagname",
            "http_port",
            "ssl_on",
            "autoindex",
            "download",
            "home_dir",
            "access"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "启用状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "服务器名称（唯一）",
              "example": "myhttp"
            },
            "http_port": {
              "type": "integer",
              "description": "HTTP端口",
              "minimum": 1,
              "maximum": 65535,
              "example": 8888
            },
            "server_name": {
              "type": "string",
              "description": "服务器域名（ServerName），可为空",
              "default": "",
              "example": ""
            },
            "ssl_on": {
              "type": "integer",
              "description": "是否开启SSL加密（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "autoindex": {
              "type": "integer",
              "description": "是否开启目录浏览（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 0,
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KByte/s），0不限速",
              "minimum": 0,
              "default": 0,
              "example": 0
            },
            "home_dir": {
              "type": "string",
              "description": "用户目录路径。先调用 `GET /api/v4.0/system/files?path=/` 获取可用目录，再填写对应目录路径；不可为 `/`，不可含 `..`",
              "example": "/test-001"
            },
            "access": {
              "type": "integer",
              "description": "是否允许外网访问（0不允许，1允许）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "HttpServerEditInput": {
          "type": "object",
          "description": "HTTP服务器全量编辑。所有字段均为必填，未修改的字段须传原值。\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "required": [
            "enabled",
            "tagname",
            "http_port",
            "server_name",
            "ssl_on",
            "autoindex",
            "download",
            "home_dir",
            "access"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "启用状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "tagname": {
              "type": "string",
              "description": "服务器名称（唯一）",
              "example": "myhttp"
            },
            "http_port": {
              "type": "integer",
              "description": "HTTP端口",
              "minimum": 1,
              "maximum": 65535,
              "example": 8888
            },
            "server_name": {
              "type": "string",
              "description": "服务器域名（ServerName），可为空",
              "example": ""
            },
            "ssl_on": {
              "type": "integer",
              "description": "是否开启SSL加密（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "autoindex": {
              "type": "integer",
              "description": "是否开启目录浏览（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 0
            },
            "download": {
              "type": "integer",
              "description": "下载限速（KByte/s），0不限速",
              "minimum": 0,
              "example": 0
            },
            "home_dir": {
              "type": "string",
              "description": "用户目录路径。先调用 `GET /api/v4.0/system/files?path=/` 获取可用目录，再填写对应目录路径；不可为 `/`，不可含 `..`",
              "example": "/test-001"
            },
            "access": {
              "type": "integer",
              "description": "是否允许外网访问（0不允许，1允许）",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "HttpServerListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "minimum": 0,
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/HttpServer"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突（如名称或端口+域名重复）",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "http-server",
        "x-displayName": "HTTP服务器管理",
        "description": "HTTP服务器的管理和配置，支持SSL、目录浏览、限速等功能"
      }
    ]
  },
  "advanced/advanced-samba.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "Samba服务管理API",
      "version": "1.0.0",
      "summary": "Samba服务配置管理",
      "description": "提供Samba服务的完整管理功能，包括：\n- Samba服务基础配置管理（单条记录，仅GET/PUT）\n- Samba共享目录用户的创建、查询、更新、删除\n- 共享目录和权限配置\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/advanced-service/samba-config": {
        "get": {
          "summary": "获取Samba服务基础配置",
          "operationId": "getSambaConfig",
          "tags": [
            "samba-service"
          ],
          "responses": {
            "200": {
              "description": "成功获取Samba配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SambaConfigResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 1,
                          "enabled": "no",
                          "workgroup": "WORKGROUP",
                          "wsdd2": 1,
                          "interface": "",
                          "access": 1
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新Samba服务基础配置",
          "description": "全量更新Samba服务基础配置。所有字段均为必填，即使未修改也必须携带原值。\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateSambaConfig",
          "tags": [
            "samba-service"
          ],
          "requestBody": {
            "required": true,
            "description": "全量更新，所有字段必填，未修改的字段须传原值",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SambaConfigEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/advanced-service/samba-users": {
        "get": {
          "summary": "获取Samba用户列表",
          "description": "获取Samba共享目录用户列表。注意：响应中数据键为dir_data，总数键为dir_total。",
          "operationId": "listSambaUsers",
          "tags": [
            "samba-users"
          ],
          "parameters": [
            {
              "name": "page",
              "in": "query",
              "description": "页码（从1开始）",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 1
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "每页记录数",
              "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 20
              }
            },
            {
              "name": "key",
              "in": "query",
              "description": "搜索字段名，与pattern联合使用",
              "schema": {
                "type": "string",
                "enum": [
                  "username",
                  "name",
                  "enabled",
                  "perm"
                ]
              }
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "搜索关键词，与key联合使用",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "order",
              "in": "query",
              "description": "排序字段",
              "schema": {
                "type": "string",
                "enum": [
                  "id",
                  "username",
                  "name"
                ],
                "default": "id"
              }
            },
            {
              "name": "order_by",
              "in": "query",
              "description": "排序方式",
              "schema": {
                "type": "string",
                "enum": [
                  "asc",
                  "desc"
                ],
                "default": "asc"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取Samba用户列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SambaUserListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "dir_total": 1,
                      "dir_data": [
                        {
                          "id": 1,
                          "enabled": "yes",
                          "username": "testuser",
                          "passwd": "123456",
                          "name": "share1",
                          "tagname": "share1",
                          "perm": "rw",
                          "guest": "yes",
                          "browseable": "",
                          "home_dir": "/test-001"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "post": {
          "summary": "创建Samba用户",
          "description": "创建Samba共享目录用户。tagname由系统自动设置为name的值，无需传入。\n\n`home_dir` 应先通过 `GET /api/v4.0/system/files?path=/` 查询可用存储目录。\n单个共享填写单个目录路径，例如 `/test-001`；\n多个共享时可使用逗号分隔多个目录路径，并与 `name` 一一对应。\n",
          "operationId": "createSambaUser",
          "tags": [
            "samba-users"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SambaUserCreateInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CreateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success",
                        "rowid": 1
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      },
      "/api/v4.0/advanced-service/samba-users/{id}": {
        "parameters": [
          {
            "$ref": "#/components/parameters/sambaUserIdParam"
          }
        ],
        "put": {
          "summary": "更新Samba用户",
          "description": "全量更新Samba用户配置。所有字段均为必填，即使未修改也必须携带原值。tagname由系统自动设为name值，但仍须传入。\n\n`home_dir` 应先通过 `GET /api/v4.0/system/files?path=/` 查询可用存储目录。\n单个共享填写单个目录路径，例如 `/test-001`；\n多个共享时可使用逗号分隔多个目录路径，并与 `name` 一一对应。\n",
          "operationId": "updateSambaUser",
          "tags": [
            "samba-users"
          ],
          "requestBody": {
            "required": true,
            "description": "全量更新，所有字段必填，未修改的字段须传原值",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SambaUserEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "409": {
              "$ref": "#/components/responses/Conflict"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "patch": {
          "summary": "启用/停用Samba用户",
          "operationId": "patchSambaUser",
          "tags": [
            "samba-users"
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "enabled"
                  ],
                  "properties": {
                    "enabled": {
                      "type": "string",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除Samba用户",
          "operationId": "deleteSambaUser",
          "tags": [
            "samba-users"
          ],
          "responses": {
            "200": {
              "description": "删除成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "404": {
              "$ref": "#/components/responses/NotFound"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "sambaUserIdParam": {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Samba用户ID",
          "schema": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "CreateResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            },
            "rowid": {
              "type": "integer",
              "description": "新创建的记录ID",
              "minimum": 1,
              "example": 1
            }
          },
          "required": [
            "message",
            "rowid"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SambaConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "workgroup",
            "wsdd2",
            "interface",
            "access"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "开启或关闭状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "workgroup": {
              "type": "string",
              "description": "工作组名称",
              "default": "WORKGROUP",
              "example": "WORKGROUP"
            },
            "wsdd2": {
              "type": "integer",
              "description": "启用网络发现（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            },
            "interface": {
              "type": "string",
              "description": "网络接口",
              "default": "",
              "example": ""
            },
            "access": {
              "type": "integer",
              "description": "是否允许外网访问（0不允许，1允许）",
              "enum": [
                0,
                1
              ],
              "default": 1,
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "SambaConfigEditInput": {
          "type": "object",
          "description": "Samba基础配置全量编辑。所有字段均为必填，未修改的字段须传原值。",
          "required": [
            "enabled",
            "workgroup",
            "wsdd2",
            "access"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "开启或关闭状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "workgroup": {
              "type": "string",
              "description": "工作组名称",
              "example": "WORKGROUP"
            },
            "wsdd2": {
              "type": "integer",
              "description": "启用网络发现（0关闭，1开启）",
              "enum": [
                0,
                1
              ],
              "example": 1
            },
            "access": {
              "type": "integer",
              "description": "是否允许外网访问（0不允许，1允许）",
              "enum": [
                0,
                1
              ],
              "example": 1
            }
          },
          "additionalProperties": false
        },
        "SambaConfigResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SambaConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "SambaUser": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "username",
            "passwd",
            "name",
            "tagname",
            "perm",
            "guest",
            "browseable",
            "home_dir"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "用户ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "开启或关闭状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "username": {
              "type": "string",
              "description": "用户名（唯一，不可为root）",
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（返回时为解密后明文）",
              "example": "123456"
            },
            "name": {
              "type": "string",
              "description": "共享名（唯一，多个用逗号分隔）",
              "example": "share1"
            },
            "tagname": {
              "type": "string",
              "description": "名称标签（系统自动设为name值）",
              "example": "share1"
            },
            "perm": {
              "type": "string",
              "description": "用户权限（rw读写，ro只读）",
              "enum": [
                "rw",
                "ro"
              ],
              "example": "rw"
            },
            "guest": {
              "type": "string",
              "description": "访客是否可以访问",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "browseable": {
              "type": "string",
              "description": "是否可浏览，多个用逗号分隔，对应每个共享名",
              "default": "",
              "example": ""
            },
            "home_dir": {
              "type": "string",
              "description": "共享目录路径。取值应来自 `GET /api/v4.0/system/files?path=/` 返回的存储目录；多个值用逗号分隔，并与每个共享名一一对应",
              "example": "/test-001"
            }
          },
          "additionalProperties": false
        },
        "SambaUserCreateInput": {
          "type": "object",
          "description": "Samba用户创建输入。tagname由系统自动设置为name的值，无需传入。",
          "required": [
            "enabled",
            "username",
            "passwd",
            "name",
            "perm",
            "home_dir",
            "guest",
            "browseable"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "开启或关闭状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "username": {
              "type": "string",
              "description": "用户名（唯一，不可为root）",
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（不可为空）",
              "example": "123456"
            },
            "name": {
              "type": "string",
              "description": "共享名（唯一，不可为空，多个用逗号分隔）",
              "example": "share1"
            },
            "perm": {
              "type": "string",
              "description": "用户权限（rw读写，ro只读）",
              "enum": [
                "rw",
                "ro"
              ],
              "default": "rw",
              "example": "rw"
            },
            "guest": {
              "type": "string",
              "description": "访客是否可以访问",
              "enum": [
                "yes",
                "no"
              ],
              "default": "yes",
              "example": "yes"
            },
            "browseable": {
              "type": "string",
              "description": "是否可浏览，多个用逗号分隔",
              "default": "",
              "example": ""
            },
            "home_dir": {
              "type": "string",
              "description": "共享目录路径。先调用 `GET /api/v4.0/system/files?path=/` 获取可用目录，再填写对应目录路径；不可为 `/`，不可含 `..`；多个值用逗号分隔",
              "example": "/test-001"
            }
          },
          "additionalProperties": false
        },
        "SambaUserEditInput": {
          "type": "object",
          "description": "Samba用户全量编辑。所有字段均为必填，未修改的字段须传原值。tagname由系统自动设为name值，但仍须传入。",
          "required": [
            "enabled",
            "username",
            "passwd",
            "name",
            "perm",
            "guest",
            "home_dir",
            "browseable",
            "tagname"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "开启或关闭状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "username": {
              "type": "string",
              "description": "用户名（唯一，不可为root）",
              "example": "testuser"
            },
            "passwd": {
              "type": "string",
              "description": "密码（不可为空）",
              "example": "123456"
            },
            "name": {
              "type": "string",
              "description": "共享名（唯一，不可为空）",
              "example": "share1"
            },
            "perm": {
              "type": "string",
              "description": "用户权限（rw读写，ro只读）",
              "enum": [
                "rw",
                "ro"
              ],
              "example": "rw"
            },
            "guest": {
              "type": "string",
              "description": "访客是否可以访问",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "browseable": {
              "type": "string",
              "description": "是否可浏览，多个用逗号分隔",
              "example": ""
            },
            "home_dir": {
              "type": "string",
              "description": "共享目录路径。先调用 `GET /api/v4.0/system/files?path=/` 获取可用目录，再填写对应目录路径；不可为 `/`，不可含 `..`",
              "example": "/test-001"
            },
            "tagname": {
              "type": "string",
              "description": "名称标签（系统自动设为name值，但须传入）",
              "example": "share1"
            }
          },
          "additionalProperties": false
        },
        "SambaUserListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "dir_total": {
                  "type": "integer",
                  "description": "总记录数",
                  "minimum": 0,
                  "example": 1
                },
                "dir_data": {
                  "type": "array",
                  "description": "用户列表",
                  "items": {
                    "$ref": "#/components/schemas/SambaUser"
                  }
                }
              },
              "required": [
                "dir_total",
                "dir_data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "CreateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/CreateResponse"
            },
            {
              "$ref": "#/components/schemas/CreateBusinessErrorResponse"
            }
          ],
          "description": "创建/添加操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：创建成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "CreateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突（如用户名或共享名重复）",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "samba-service",
        "x-displayName": "Samba服务管理",
        "description": "Samba服务基础配置管理"
      },
      {
        "name": "samba-users",
        "x-displayName": "Samba用户管理",
        "description": "Samba共享目录用户的增删改查"
      }
    ]
  },
  "advanced/advanced-snmpd.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "SNMP服务管理API",
      "version": "1.0.0",
      "summary": "SNMP服务配置管理",
      "description": "提供SNMP服务的配置管理功能，包括：\n- SNMP服务基础配置（单条记录，仅GET/PUT）\n- 支持SNMP v2c/v3版本\n- v3认证和加密配置（条件必填）\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      }
    ],
    "paths": {
      "/api/v4.0/advanced-service/snmpd-config": {
        "get": {
          "summary": "获取SNMP服务配置",
          "operationId": "getSnmpdConfig",
          "tags": [
            "snmp-service"
          ],
          "responses": {
            "200": {
              "description": "成功获取SNMP配置",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SnmpdConfigResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "put": {
          "summary": "更新SNMP服务配置",
          "description": "全量更新SNMP服务配置。所有15个字段均为必填，即使未修改也必须携带原值。\n条件必填规则：\n- version=2时：community必填\n- version=3时：username、security必填\n- security为authNoPriv时：auth_proto（MD5/SHA）、auth_pass（>=8字符）必填\n- security为authPriv时：auth_proto、auth_pass、priv_proto（DES/AES）、priv_pass（>=8字符）必填\n\n> **注意：** 本接口为全量修改，请求时需传入所有字段。无需修改的字段请保持原值或传空值，未传入的字段可能被重置。\n",
          "operationId": "updateSnmpdConfig",
          "tags": [
            "snmp-service"
          ],
          "requestBody": {
            "required": true,
            "description": "全量更新，所有字段必填，未修改的字段须传原值",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnmpdConfigEditInput"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UpdateOperationResponse"
                  },
                  "examples": {
                    "success": {
                      "summary": "业务成功",
                      "value": {
                        "code": 0,
                        "message": "success"
                      }
                    },
                    "bizErrorSimple": {
                      "summary": "业务失败，无明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法"
                      }
                    },
                    "bizErrorWithDetails": {
                      "summary": "业务失败，含字段明细",
                      "value": {
                        "code": 30001,
                        "message": "请求参数不合法",
                        "details": [
                          {
                            "field": "key1",
                            "type": "unique",
                            "msg": "详细的错误输出"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SnmpdConfig": {
          "type": "object",
          "required": [
            "id",
            "enabled",
            "listen_port",
            "version",
            "community",
            "rw"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "配置ID",
              "minimum": 1,
              "example": 1
            },
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "no"
            },
            "listen_port": {
              "type": "integer",
              "description": "SNMP监听端口，范围 2-65535，600-799 为系统保留不可用",
              "minimum": 2,
              "maximum": 65535,
              "default": 161,
              "example": 161
            },
            "syslocation": {
              "type": "string",
              "description": "物理位置信息",
              "default": "",
              "example": ""
            },
            "syscontact": {
              "type": "string",
              "description": "联系信息",
              "default": "",
              "example": ""
            },
            "sysname": {
              "type": "string",
              "description": "系统名称",
              "default": "",
              "example": ""
            },
            "version": {
              "type": "integer",
              "description": "SNMP版本（仅支持2和3）",
              "enum": [
                2,
                3
              ],
              "default": 2,
              "example": 2
            },
            "community": {
              "type": "string",
              "description": "团体名（v2使用），version=2时必填",
              "default": "public",
              "example": "public"
            },
            "source": {
              "type": "string",
              "description": "可访问的IP地址/网段",
              "default": "",
              "example": ""
            },
            "rw": {
              "type": "string",
              "description": "读写权限",
              "enum": [
                "ro",
                "rw"
              ],
              "default": "ro",
              "example": "ro"
            },
            "username": {
              "type": "string",
              "description": "用户名（v3使用），version=3时必填",
              "default": "",
              "example": ""
            },
            "security": {
              "type": "string",
              "description": "安全级别（v3使用），version=3时必填，取值为authNoPriv或authPriv",
              "enum": [
                "authNoPriv",
                "authPriv"
              ],
              "example": "authNoPriv"
            },
            "auth_proto": {
              "type": "string",
              "description": "认证模式（v3使用），security为authNoPriv或authPriv时必填",
              "enum": [
                "MD5",
                "SHA"
              ],
              "default": "",
              "example": ""
            },
            "auth_pass": {
              "type": "string",
              "description": "认证密码（v3使用），security为authNoPriv或authPriv时必填，8-30字符",
              "minLength": 8,
              "maxLength": 30,
              "default": "",
              "example": ""
            },
            "priv_proto": {
              "type": "string",
              "description": "加密模式（v3使用），security为authPriv时必填",
              "enum": [
                "DES",
                "AES"
              ],
              "default": "",
              "example": ""
            },
            "priv_pass": {
              "type": "string",
              "description": "加密密码（v3使用），security为authPriv时必填，8-30字符",
              "minLength": 8,
              "maxLength": 30,
              "default": "",
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "SnmpdConfigEditInput": {
          "type": "object",
          "description": "SNMP配置全量编辑。未修改的字段须传原值。\n条件必填规则：\n- version=2 时：community 必填\n- version=3 时：username 必填；security 必填（authNoPriv 或 authPriv）\n- security 为 authNoPriv 或 authPriv 时：auth_proto、auth_pass 必填\n- security 为 authPriv 时：priv_proto、priv_pass 必填\n",
          "required": [
            "enabled",
            "listen_port",
            "syslocation",
            "syscontact",
            "sysname",
            "version",
            "community",
            "source",
            "rw",
            "username",
            "security",
            "auth_proto",
            "auth_pass",
            "priv_proto",
            "priv_pass"
          ],
          "properties": {
            "enabled": {
              "type": "string",
              "description": "服务开启状态",
              "enum": [
                "yes",
                "no"
              ],
              "example": "yes"
            },
            "listen_port": {
              "type": "integer",
              "description": "SNMP监听端口，范围 1-65535，600-799 为系统保留不可用",
              "minimum": 2,
              "maximum": 65535,
              "example": 161
            },
            "syslocation": {
              "type": "string",
              "description": "物理位置信息",
              "example": ""
            },
            "syscontact": {
              "type": "string",
              "description": "联系信息",
              "example": ""
            },
            "sysname": {
              "type": "string",
              "description": "系统名称",
              "example": ""
            },
            "version": {
              "type": "integer",
              "description": "SNMP版本（仅支持2和3）",
              "enum": [
                2,
                3
              ],
              "example": 2
            },
            "community": {
              "type": "string",
              "description": "团体名（v2使用），version=2时不可为空",
              "example": "public"
            },
            "source": {
              "type": "string",
              "description": "可访问的IP地址/网段",
              "example": ""
            },
            "rw": {
              "type": "string",
              "description": "读写权限",
              "enum": [
                "ro",
                "rw"
              ],
              "example": "ro"
            },
            "username": {
              "type": "string",
              "description": "用户名（v3使用），version=3时不可为空",
              "example": ""
            },
            "security": {
              "type": "string",
              "description": "安全级别（v3使用），version=3时必须为authNoPriv或authPriv",
              "enum": [
                "authNoPriv",
                "authPriv"
              ],
              "example": "authNoPriv"
            },
            "auth_proto": {
              "type": "string",
              "description": "认证模式，security为authNoPriv或authPriv时必须为MD5或SHA",
              "enum": [
                "MD5",
                "SHA"
              ],
              "example": ""
            },
            "auth_pass": {
              "type": "string",
              "description": "认证密码，security为authNoPriv或authPriv时必填，8-30字符",
              "minLength": 8,
              "maxLength": 30,
              "example": ""
            },
            "priv_proto": {
              "type": "string",
              "description": "加密模式，security为authPriv时必须为DES或AES",
              "enum": [
                "DES",
                "AES"
              ],
              "example": ""
            },
            "priv_pass": {
              "type": "string",
              "description": "加密密码，security为authPriv时必填，8-30字符",
              "minLength": 8,
              "maxLength": 30,
              "example": ""
            }
          },
          "additionalProperties": false
        },
        "SnmpdConfigResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "example": 0
            },
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SnmpdConfig"
                  }
                }
              },
              "required": [
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UpdateOperationResponse": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/UpdateSuccessResponse"
            },
            {
              "$ref": "#/components/schemas/UpdateBusinessErrorResponse"
            }
          ],
          "description": "更新/状态变更操作的业务响应。\n请以返回体中的 `code` 判断本次操作是否成功：\n- `code = 0`：更新成功\n- `code != 0`：HTTP 请求成功，但内部业务处理失败\n"
        },
        "UpdateSuccessResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示更新成功",
              "const": 0,
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "操作结果消息",
              "example": "success"
            }
          },
          "additionalProperties": false
        },
        "UpdateBusinessErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，非0表示内部业务处理失败",
              "example": 30001,
              "not": {
                "const": 0
              }
            },
            "message": {
              "type": "string",
              "description": "业务错误消息",
              "example": "请求参数不合法"
            },
            "details": {
              "type": "array",
              "description": "业务校验错误明细，部分错误场景返回。\n`field`、`type`、`msg` 的具体内容由实际业务校验规则决定，不固定。\n",
              "items": {
                "$ref": "#/components/schemas/ValidationErrorDetail"
              }
            }
          },
          "additionalProperties": false
        },
        "ValidationErrorDetail": {
          "type": "object",
          "required": [
            "field",
            "type",
            "msg"
          ],
          "properties": {
            "field": {
              "type": "string",
              "description": "出错字段名。\n该值由具体业务决定，可能是单字段名，也可能是组合字段标识。\n",
              "example": "key1"
            },
            "type": {
              "type": "string",
              "description": "校验类型，由业务返回",
              "example": "unique"
            },
            "msg": {
              "type": "string",
              "description": "具体错误说明，由业务返回",
              "example": "详细的错误输出"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "snmp-service",
        "x-displayName": "SNMP服务管理",
        "description": "SNMP服务配置管理，支持v2c/v3版本和认证加密"
      }
    ]
  },
  "log/log-arp.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "ARP日志管理API",
      "version": "1.0.0",
      "summary": "ARP日志查询和管理",
      "description": "提供ARP日志的查询功能，包括：\n- ARP日志查询\n- 支持过滤和分页功能\n- 检测ARP地址欺骗事件\n- 日志时间戳和详细信息展示\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/arp": {
        "get": {
          "summary": "获取ARP日志列表",
          "description": "获取ARP日志记录列表。\n支持过滤和分页功能，可以查询ARP地址欺骗等安全事件。\n",
          "operationId": "listArpLogs",
          "tags": [
            "log-arp"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 content",
              "schema": {
                "type": "string"
              },
              "example": "content"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "地址欺骗"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=id==1\n- AND条件：filter=id>100&filter=timestamp<1736475000\n- OR条件：filter=content==欺骗,content==攻击\n- 时间范围：filter=timestamp>1736472000&filter=timestamp<1736475000\n",
              "schema": {
                "type": "string"
              },
              "example": "id==1"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取ARP日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/ArpLogListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "content": "检测到一个ARP地址欺骗在接口(eth0): 192.168.0.14 08:9b:4b:44:ec:b6->88:68:4b:e4:f8:ef",
                          "id": 1,
                          "timestamp": 1736472037
                        },
                        {
                          "content": "检测到一个ARP地址欺骗在接口(_vlan31): 192.168.31.6 24:14:07:0f:5c:f3->f2:a5:cf:d3:fd:6c",
                          "id": 2,
                          "timestamp": 1736472041
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "删除ARP日志",
          "description": "清空所有ARP日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearArpLogs",
          "tags": [
            "log-arp"
          ],
          "responses": {
            "200": {
              "description": "ARP日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段",
          "schema": {
            "type": "string",
            "enum": [
              "id",
              "timestamp"
            ],
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ArpLog": {
          "type": "object",
          "required": [
            "id",
            "content",
            "timestamp"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "content": {
              "type": "string",
              "description": "ARP日志内容",
              "maxLength": 500,
              "example": "检测到一个ARP地址欺骗在接口(eth0): 192.168.0.14 08:9b:4b:44:ec:b6->88:68:4b:e4:f8:ef"
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1736472037
            }
          },
          "additionalProperties": false
        },
        "ArpLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "description": "ARP日志记录列表",
                  "items": {
                    "$ref": "#/components/schemas/ArpLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-arp",
        "x-displayName": "ARP日志管理",
        "description": "ARP安全日志的查询和管理，包括ARP地址欺骗检测日志"
      }
    ]
  },
  "log/log-auth.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "认证日志管理API",
      "version": "1.0.0",
      "summary": "认证日志查询和管理",
      "description": "提供认证日志的查询功能，包括：\n- 用户认证日志查询\n- 支持过滤和分页功能\n- 多种认证类型支持（L2TP、PPTP、PPPoE等）\n- 认证结果和IP地址追踪\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/auth": {
        "get": {
          "summary": "获取认证日志列表",
          "description": "获取用户认证日志记录列表。\n支持过滤和分页功能，可以查询不同类型的VPN认证记录。\n",
          "operationId": "listAuthLogs",
          "tags": [
            "log-auth"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 username, macip, ip_addr",
              "schema": {
                "type": "string"
              },
              "example": "username,macip"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "test001"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=ppptype==l2tp\n- AND条件：filter=ppptype==l2tp&filter=result==认证成功\n- OR条件：filter=username==test001,username==test002\n- 时间范围：filter=timestamp>1736474000&filter=timestamp<1736528000\n",
              "schema": {
                "type": "string"
              },
              "example": "ppptype==l2tp"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取认证日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/AuthLogListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "id": 1,
                          "timestamp": 1736474741,
                          "username": "test001",
                          "macip": "123.116.190.223",
                          "ppptype": "l2tp",
                          "result": "认证成功",
                          "ip_addr": "192.168.30.101",
                          "webid": 0,
                          "event": "--",
                          "interface": "--"
                        },
                        {
                          "id": 2,
                          "timestamp": 1736527419,
                          "username": "test002",
                          "macip": "37.19.205.242",
                          "ppptype": "l2tp",
                          "result": "认证成功",
                          "ip_addr": "192.168.30.106",
                          "webid": 0,
                          "event": "--",
                          "interface": "--"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空认证日志",
          "description": "清空所有用户认证日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearAuthLogs",
          "tags": [
            "log-auth"
          ],
          "responses": {
            "200": {
              "description": "认证日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段",
          "schema": {
            "type": "string",
            "enum": [
              "id",
              "timestamp",
              "username"
            ],
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "请求参数错误"
                    }
                  }
                ]
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "未认证或凭证无效"
                    }
                  }
                ]
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "无权限访问"
                    }
                  }
                ]
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "资源不存在"
                    }
                  }
                ]
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ErrorResponse"
                  },
                  {
                    "example": {
                      "message": "服务器内部错误（查看服务器日志、修复异常）"
                    }
                  }
                ]
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "AuthLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "username",
            "macip",
            "ppptype",
            "result",
            "ip_addr",
            "webid",
            "event",
            "interface"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1736474741
            },
            "username": {
              "type": "string",
              "description": "认证用户名",
              "maxLength": 100,
              "example": "test001"
            },
            "macip": {
              "type": "string",
              "description": "客户端MAC地址或IP地址",
              "maxLength": 50,
              "example": "123.116.190.223"
            },
            "ppptype": {
              "type": "string",
              "description": "认证类型",
              "enum": [
                "l2tp",
                "pptp",
                "pppoe",
                "openvpn",
                "ikev2",
                "ssl",
                "web"
              ],
              "example": "l2tp"
            },
            "result": {
              "type": "string",
              "description": "认证结果",
              "maxLength": 50,
              "example": "认证成功"
            },
            "ip_addr": {
              "type": "string",
              "description": "分配的IP地址",
              "pattern": "^([0-9]{1,3}\\\\.){3}[0-9]{1,3}$",
              "example": "192.168.30.101"
            },
            "webid": {
              "type": "integer",
              "description": "Web认证标识",
              "minimum": 0,
              "example": 0
            },
            "event": {
              "type": "string",
              "description": "事件描述",
              "maxLength": 100,
              "example": "--"
            },
            "interface": {
              "type": "string",
              "description": "接口名称",
              "maxLength": 50,
              "example": "--"
            }
          },
          "additionalProperties": false
        },
        "AuthLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "description": "认证日志记录列表",
                  "items": {
                    "$ref": "#/components/schemas/AuthLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-auth",
        "x-displayName": "认证日志管理",
        "description": "用户认证日志的查询和管理，包括各种VPN和Web认证记录"
      }
    ]
  },
  "log/log-ddns.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "动态域名日志管理API",
      "version": "1.0.0",
      "summary": "动态域名日志查询和管理",
      "description": "提供动态域名日志的查询和管理功能，包括：\n- 动态域名日志查询\n- 支持过滤和分页功能\n- 动态域名解析状态记录\n- 日志时间戳和详细信息展示\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/ddns": {
        "get": {
          "summary": "获取动态域名日志列表",
          "description": "获取动态域名日志记录列表。\n支持过滤和分页功能，可以查询动态域名解析等记录。\n",
          "operationId": "listDdnsLogs",
          "tags": [
            "log-ddns"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=status==success\n- AND条件：filter=status==success&filter=domain==example.com\n- OR条件：filter=status==success,status==failure\n- 时间范围：filter=timestamp>1763450000&filter=timestamp<1763455000\n",
              "schema": {
                "type": "string"
              },
              "example": "status==success"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 domain, status, message",
              "schema": {
                "type": "string"
              },
              "example": "domain,status"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "example.com"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取动态域名日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DdnsLogListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空动态域名日志",
          "description": "清空所有动态域名日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearDdnsLogs",
          "tags": [
            "log-ddns"
          ],
          "responses": {
            "200": {
              "description": "动态域名日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "清空日志异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DdnsLogErrorResponse"
                  },
                  "example": {
                    "message": "清空动态域名日志异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、status等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DdnsLogErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "动态域名日志业务错误信息描述"
            }
          }
        },
        "DdnsLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DdnsLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DdnsLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "domain",
            "status",
            "ip_addr"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1761842271
            },
            "domain": {
              "type": "string",
              "description": "域名",
              "maxLength": 255,
              "example": "example.com"
            },
            "status": {
              "type": "string",
              "description": "解析状态",
              "enum": [
                "success",
                "failure",
                "pending"
              ],
              "example": "success"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.1.100"
            },
            "message": {
              "type": "string",
              "description": "详细信息",
              "maxLength": 500,
              "example": "解析成功"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-ddns",
        "x-displayName": "动态域名日志管理",
        "description": "动态域名日志的查询和管理，支持过滤、分页和清空功能"
      }
    ]
  },
  "log/log-dhcp.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "DHCP日志管理API",
      "version": "1.0.0",
      "summary": "DHCP日志查询和管理",
      "description": "提供DHCP日志的查询和管理功能，包括：\n- DHCP日志查询\n- 支持过滤和分页功能\n- DHCP协议类型记录（DHCPDISCOVER、DHCPOFFER、DHCPACK等）\n- 接口、IP地址、MAC地址信息记录\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/dhcp": {
        "get": {
          "summary": "获取DHCP日志列表",
          "description": "获取DHCP日志记录列表。\n支持过滤和分页功能，可以查询DHCP协议交互等记录。\n",
          "operationId": "listDhcpLogs",
          "tags": [
            "log-dhcp"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=msgtype==DHCPACK\n- AND条件：filter=msgtype==DHCPACK&filter=interface==lan1\n- OR条件：filter=msgtype==DHCPACK,msgtype==DHCPOFFER\n- MAC地址过滤：filter=mac==a6:8d:9a:61:96:90\n- 时间范围：filter=timestamp>1761842000&filter=timestamp<1761843000\n",
              "schema": {
                "type": "string"
              },
              "example": "msgtype==DHCPACK"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 msgtype, interface, ip_addr, mac",
              "schema": {
                "type": "string"
              },
              "example": "msgtype,interface"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "DHCPACK"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取DHCP日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpLogListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空DHCP日志",
          "description": "清空所有DHCP日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearDhcpLogs",
          "tags": [
            "log-dhcp"
          ],
          "responses": {
            "200": {
              "description": "DHCP日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "清空日志异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/DhcpLogErrorResponse"
                  },
                  "example": {
                    "message": "清空DHCP日志异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、msgtype、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "DhcpLogErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "DHCP日志业务错误信息描述"
            }
          }
        },
        "DhcpLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 3
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DhcpLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "DhcpLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "msgtype",
            "event",
            "interface",
            "ip_addr",
            "mac"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 4241
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1761842271
            },
            "msgtype": {
              "type": "string",
              "description": "DHCP消息类型",
              "enum": [
                "DHCPDISCOVER",
                "DHCPOFFER",
                "DHCPREQUEST",
                "DHCPACK",
                "DHCPNACK",
                "DHCPDECLINE",
                "DHCPRELEASE"
              ],
              "example": "DHCPACK"
            },
            "event": {
              "type": "string",
              "description": "事件描述",
              "maxLength": 255,
              "example": "--"
            },
            "interface": {
              "type": "string",
              "description": "网络接口",
              "maxLength": 50,
              "example": "lan1"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.9.106"
            },
            "mac": {
              "type": "string",
              "description": "MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "a6:8d:9a:61:96:90"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-dhcp",
        "x-displayName": "DHCP日志管理",
        "description": "DHCP日志的查询和管理，支持过滤、分页和清空功能"
      }
    ]
  },
  "log/log-message-center.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "消息中心API",
      "version": "1.0.0",
      "summary": "消息中心查询",
      "description": "提供消息中心的只读查询功能，包括：\n- 消息中心列表查询\n- 未读消息数量统计\n- 支持分页、排序、过滤和模糊搜索\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/message-center": {
        "get": {
          "summary": "获取消息中心列表",
          "description": "获取消息中心通知列表。\n支持按消息类型、已读状态、时间戳等字段过滤，也支持按标题、详情等字段模糊搜索。\n",
          "operationId": "listMessageCenterMessages",
          "tags": [
            "log-message-center"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊搜索字段名，与 pattern 联合使用，支持 title、detail",
              "schema": {
                "type": "string"
              },
              "example": "title,detail"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊搜索关键词，与 key 联合使用",
              "schema": {
                "type": "string"
              },
              "example": "升级"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取消息中心列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/MessageNotificationListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "id": 1,
                          "timestamp": 1778763600,
                          "title": "发现新版本",
                          "type": 1,
                          "detail": "检测到可升级版本 4.0.111",
                          "image": "",
                          "status": 0
                        },
                        {
                          "id": 2,
                          "timestamp": 1778756400,
                          "title": "自动备份成功",
                          "type": 2,
                          "detail": "配置文件自动备份已完成",
                          "image": "",
                          "status": 1
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序，desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "desc",
            "example": "desc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持 id、timestamp、type、status、title",
          "schema": {
            "type": "string",
            "default": "timestamp",
            "example": "timestamp"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配、范围匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n- \"：（包含）\"\n- \"!：（不包含）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 消息类型过滤：filter=type==1\n- 未读消息过滤：filter=status==0\n- 时间范围过滤：filter=timestamp>=1778760000&filter=timestamp<1778846400\n",
          "schema": {
            "type": "string"
          },
          "example": "status==0"
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求语法错误或参数不合法（检查请求参数、过滤条件或排序字段）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问消息中心"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "MessageNotificationListResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "results"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/MessageNotificationListResult"
            }
          },
          "additionalProperties": false
        },
        "MessageNotificationListResult": {
          "type": "object",
          "required": [
            "total",
            "data"
          ],
          "properties": {
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "符合过滤条件的消息总数",
              "minimum": 0,
              "example": 2
            },
            "data": {
              "type": "array",
              "description": "消息中心列表",
              "items": {
                "$ref": "#/components/schemas/MessageNotification"
              }
            }
          },
          "additionalProperties": false
        },
        "MessageNotification": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "title",
            "type",
            "detail",
            "image",
            "status"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "消息ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "消息产生时间戳",
              "example": 1778763600
            },
            "title": {
              "type": "string",
              "description": "消息标题",
              "maxLength": 255,
              "example": "发现新版本"
            },
            "type": {
              "type": "integer",
              "description": "消息类型，1-路由，2-业务，3-固件，4-官方通知",
              "enum": [
                1,
                2,
                3,
                4
              ],
              "example": 1
            },
            "detail": {
              "type": "string",
              "description": "消息详情",
              "maxLength": 2000,
              "example": "检测到可升级版本 4.0.111"
            },
            "image": {
              "type": "string",
              "description": "文案图片路径，空字符串表示无图片",
              "maxLength": 500,
              "example": ""
            },
            "status": {
              "type": "integer",
              "description": "阅读状态，0-未读，1-已读",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求参数错误"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer <token>\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-message-center",
        "x-displayName": "消息中心",
        "description": "消息中心列表和未读数量查询"
      }
    ]
  },
  "log/log-notice.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "推送通知日志管理API",
      "version": "1.0.0",
      "summary": "推送通知日志查询和管理",
      "description": "提供推送通知日志的查询和管理功能，包括：\n- 推送通知日志查询\n- 支持过滤和分页功能\n- 通知类型记录\n- IP地址和事件描述信息记录\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/notice": {
        "get": {
          "summary": "获取推送通知日志列表",
          "description": "获取推送通知日志记录列表。\n支持过滤和分页功能，可以查询各类推送通知记录。\n",
          "operationId": "listNoticeLogs",
          "tags": [
            "log-notice"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=type==email\n- AND条件：filter=type==email&filter=ip_addr==192.168.1.100\n- OR条件：filter=type==email,type==sms\n- 事件过滤：filter=event==通知发送成功\n- 时间范围：filter=timestamp>1762342000&filter=timestamp<1762343000\n",
              "schema": {
                "type": "string"
              },
              "example": "type==email"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 type, ip_addr, event",
              "schema": {
                "type": "string"
              },
              "example": "type,event"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "通知"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取推送通知日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NoticeLogListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空推送通知日志",
          "description": "清空所有推送通知日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearNoticeLogs",
          "tags": [
            "log-notice"
          ],
          "responses": {
            "200": {
              "description": "推送通知日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "清空日志异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/NoticeLogErrorResponse"
                  },
                  "example": {
                    "message": "清空推送通知日志异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、type、ip_addr等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "NoticeLogErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "推送通知日志业务错误信息描述"
            }
          }
        },
        "NoticeLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NoticeLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "NoticeLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "type",
            "ip_addr",
            "event"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1762342517
            },
            "type": {
              "type": "string",
              "description": "通知类型",
              "maxLength": 100,
              "example": "email"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.1.100"
            },
            "event": {
              "type": "string",
              "description": "事件描述",
              "maxLength": 500,
              "example": "通知发送成功"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-notice",
        "x-displayName": "推送通知日志管理",
        "description": "推送通知日志的查询和管理，支持过滤、分页和清空功能"
      }
    ]
  },
  "log/log-pppoe.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "外网拨号日志管理API",
      "version": "1.0.0",
      "summary": "外网拨号日志查询和管理",
      "description": "提供外网拨号日志的查询和管理功能，包括：\n- 外网拨号日志查询\n- 支持过滤和分页功能\n- 拨号接口和连接状态记录\n- PPPD进程和会话信息记录\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/pppoe": {
        "get": {
          "summary": "获取外网拨号日志列表",
          "description": "获取外网拨号日志记录列表。\n支持过滤和分页功能，可以查询PPP连接状态等信息。\n",
          "operationId": "listPppoeLogs",
          "tags": [
            "log-pppoe"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=interface==adsl1\n- AND条件：filter=interface==adsl1&filter=content==pppd\n- OR条件：filter=interface==adsl1,interface==wan2_1\n- 内容过滤：filter=content==Connected\n- 时间范围：filter=timestamp>1762342000&filter=timestamp<1762343000\n",
              "schema": {
                "type": "string"
              },
              "example": "interface==adsl1"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 interface, content",
              "schema": {
                "type": "string"
              },
              "example": "interface,content"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "pppd"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取外网拨号日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PppoeLogListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空外网拨号日志",
          "description": "清空所有外网拨号日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearPppoeLogs",
          "tags": [
            "log-pppoe"
          ],
          "responses": {
            "200": {
              "description": "外网拨号日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "清空日志异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/PppoeLogErrorResponse"
                  },
                  "example": {
                    "message": "清空外网拨号日志异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、interface等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "PppoeLogErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "外网拨号日志业务错误信息描述"
            }
          }
        },
        "PppoeLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 3
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PppoeLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "PppoeLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "interface",
            "content"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1762342517
            },
            "interface": {
              "type": "string",
              "description": "拨号接口",
              "maxLength": 50,
              "example": "adsl1"
            },
            "content": {
              "type": "string",
              "description": "日志内容",
              "maxLength": 1000,
              "example": "pppd 2.4.7 started by root, uid 0"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-pppoe",
        "x-displayName": "外网拨号日志管理",
        "description": "外网拨号日志的查询和管理，支持过滤、分页和清空功能"
      }
    ]
  },
  "log/log-system.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "系统日志管理API",
      "version": "1.0.0",
      "summary": "系统日志查询和管理",
      "description": "提供系统日志的查询和管理功能，包括：\n- 系统日志查询\n- 支持过滤和分页功能\n- 系统运行状态和事件记录\n- 日志时间戳和详细信息展示\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/system": {
        "get": {
          "summary": "获取系统日志列表",
          "description": "获取系统日志记录列表。\n支持过滤和分页功能，可以查询系统运行状态等记录。\n",
          "operationId": "listSystemLogs",
          "tags": [
            "log-system"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=level==error\n- AND条件：filter=level==error&filter=module==system\n- OR条件：filter=level==error,level==warning\n- 模块过滤：filter=module==kernel\n- 时间范围：filter=timestamp>1763450000&filter=timestamp<1763455000\n",
              "schema": {
                "type": "string"
              },
              "example": "level==error"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 level, module, message, process",
              "schema": {
                "type": "string"
              },
              "example": "level,module"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "error"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取系统日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemLogListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空系统日志",
          "description": "清空所有系统日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearSystemLogs",
          "tags": [
            "log-system"
          ],
          "responses": {
            "200": {
              "description": "系统日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "清空日志异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SystemLogErrorResponse"
                  },
                  "example": {
                    "message": "清空系统日志异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、level、module等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "SystemLogErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "系统日志业务错误信息描述"
            }
          }
        },
        "SystemLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 25
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SystemLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "SystemLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "level",
            "module",
            "message"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763450144
            },
            "level": {
              "type": "string",
              "description": "日志级别",
              "enum": [
                "debug",
                "info",
                "warning",
                "error",
                "critical"
              ],
              "example": "info"
            },
            "module": {
              "type": "string",
              "description": "系统模块",
              "maxLength": 100,
              "example": "kernel"
            },
            "message": {
              "type": "string",
              "description": "日志消息",
              "maxLength": 1000,
              "example": "系统启动完成"
            },
            "process": {
              "type": "string",
              "description": "进程名称",
              "maxLength": 100,
              "example": "systemd"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-system",
        "x-displayName": "系统日志管理",
        "description": "系统日志的查询和管理，支持过滤、分页和清空功能"
      }
    ]
  },
  "log/log-terminal-presence.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "终端上下线日志API",
      "version": "1.0.0",
      "summary": "终端上下线日志查询",
      "description": "提供终端上下线日志的查询功能，包括：\n- 终端上线、下线记录查询\n- 支持分页、排序和过滤功能\n- 支持按时间范围查询\n- 支持按终端信息进行模糊匹配\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/terminal-presence": {
        "get": {
          "summary": "获取终端上下线日志列表",
          "description": "获取终端上下线日志记录列表。\n支持分页、排序、过滤、时间范围查询和模糊匹配。\n",
          "operationId": "listTerminalPresenceLogs",
          "tags": [
            "log-terminal-presence"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=ip_addr==192.168.1.100\n- AND条件：filter=ip_addr==192.168.1.100&filter=mac==08:9b:4b:00:10:6e\n- OR条件：filter=systype==Windows,systype==Android\n- 时间范围：filter=timestamp>1761842000&filter=timestamp<1761843000\n",
              "schema": {
                "type": "string"
              },
              "example": "ip_addr==192.168.1.100"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 mac, ip_addr, systype, devtype, client_model, comment, username, termname",
              "schema": {
                "type": "string"
              },
              "example": "ip_addr,mac,username"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "192.168.1"
            },
            {
              "name": "starttime",
              "in": "query",
              "description": "查询开始时间，Unix 时间戳，非必填，用于限定查询时间范围",
              "required": false,
              "schema": {
                "type": "integer",
                "format": "int64"
              },
              "example": 1761842000
            },
            {
              "name": "stoptime",
              "in": "query",
              "description": "查询结束时间，Unix 时间戳，非必填，用于限定查询时间范围",
              "required": false,
              "schema": {
                "type": "integer",
                "format": "int64"
              },
              "example": 1761843000
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取终端上下线日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/TerminalPresenceLogListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 1,
                      "data": [
                        {
                          "comment": "",
                          "id": 47,
                          "timestamp": 1778232965,
                          "logout_time": 1778233560,
                          "online_time": 595,
                          "ip_addr": "192.168.99.102",
                          "username": "",
                          "mac": "68:da:73:a1:d9:01",
                          "total_up": 743721,
                          "total_down": 1953505,
                          "ipv4_gnames": "",
                          "date_time": "2026-05-08 17:36:05",
                          "termname": "",
                          "mac_gnames": "",
                          "ipv6_gnames": "",
                          "icon": "1_102",
                          "auth": 0,
                          "systype": "MacOS",
                          "today_total": 0,
                          "devtype": "Apple",
                          "vlan_id": 0,
                          "client_model": "",
                          "client_typeid": 102000104
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "desc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、logout_time、date_time、online_time、ip_addr、mac等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "TerminalPresenceLogListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应信息",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 1
                },
                "data": {
                  "type": "array",
                  "description": "终端上下线日志列表",
                  "items": {
                    "$ref": "#/components/schemas/TerminalPresenceLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "TerminalPresenceLog": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "example": 47
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "上线时间，Unix 时间戳",
              "example": 1778232965
            },
            "logout_time": {
              "type": "integer",
              "format": "int64",
              "description": "下线时间，Unix 时间戳，未下线时可能为0",
              "example": 1778233560
            },
            "date_time": {
              "type": "string",
              "description": "日志时间文本",
              "example": "2026-05-08 17:36:05"
            },
            "online_time": {
              "type": "integer",
              "format": "int64",
              "description": "在线时长，单位秒",
              "example": 595
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IP地址",
              "format": "ipv4",
              "example": "192.168.99.102"
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "68:da:73:a1:d9:01"
            },
            "total_up": {
              "type": "integer",
              "format": "int64",
              "description": "上行流量，单位字节",
              "example": 743721
            },
            "total_down": {
              "type": "integer",
              "format": "int64",
              "description": "下行流量，单位字节",
              "example": 1953505
            },
            "auth": {
              "type": "integer",
              "description": "认证方式或认证状态",
              "example": 0
            },
            "systype": {
              "type": "string",
              "description": "终端系统类型",
              "example": "MacOS"
            },
            "devtype": {
              "type": "string",
              "description": "终端设备类型",
              "example": "Apple"
            },
            "client_model": {
              "type": "string",
              "description": "终端型号",
              "example": ""
            },
            "client_typeid": {
              "type": "integer",
              "description": "终端类型ID",
              "example": 102000104
            },
            "comment": {
              "type": "string",
              "description": "终端备注",
              "example": ""
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "example": ""
            },
            "termname": {
              "type": "string",
              "description": "终端名称",
              "example": ""
            },
            "icon": {
              "type": "string",
              "description": "终端图标",
              "example": "1_102"
            },
            "ipv4_gnames": {
              "type": "string",
              "description": "终端所属IPv4地址组名称",
              "example": ""
            },
            "mac_gnames": {
              "type": "string",
              "description": "终端所属MAC地址组名称",
              "example": ""
            },
            "ipv6_gnames": {
              "type": "string",
              "description": "终端所属IPv6地址组名称",
              "example": ""
            },
            "today_total": {
              "type": "integer",
              "format": "int64",
              "description": "当日累计流量，单位字节",
              "example": 0
            },
            "vlan_id": {
              "type": "integer",
              "description": "VLAN ID",
              "example": 0
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-terminal-presence",
        "x-displayName": "终端上下线日志",
        "description": "终端上线、下线日志的查询，支持过滤、分页、时间范围和模糊匹配"
      }
    ]
  },
  "log/log-url-visits.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "网址浏览记录API",
      "version": "1.0.0",
      "summary": "网址浏览记录查询",
      "description": "提供网址浏览记录的查询功能，包括：\n- 终端访问网址记录查询\n- 支持分页查询\n- 支持按时间范围查询\n- 支持按关键词搜索\n- 支持清空全部记录\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/url-visits": {
        "get": {
          "summary": "获取网址浏览记录列表",
          "description": "获取终端网址浏览记录列表。\n支持分页、时间范围查询和关键词搜索。\nlimit 默认 20，最大 500，超过最大值时按 500 处理。\n未传入时间范围时默认查询当天 00:00 至当前时间；最大查询跨度为 7 天，超出时自动按 stoptime 向前截取 7 天。\n当 limit、starttime 或 stoptime 不符合查询约束时，接口不会直接返回参数错误，而是按上述规则自动调整后再查询。\n时间范围较大时，请使用分页参数分批获取，避免单次返回数据过大。\n",
          "operationId": "listUrlVisitLogs",
          "tags": [
            "log-url-visits"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "搜索关键词，根据索引自动匹配终端 IP、MAC、访问主机名或终端备注",
              "schema": {
                "type": "string"
              },
              "example": "example.com"
            },
            {
              "name": "starttime",
              "in": "query",
              "description": "查询开始时间，Unix 时间戳，非必填；缺失、格式不合法或晚于 stoptime 时，服务端会自动调整为 stoptime 所在日期的 00:00",
              "required": false,
              "schema": {
                "type": "integer",
                "format": "int64"
              },
              "example": 1761842000
            },
            {
              "name": "stoptime",
              "in": "query",
              "description": "查询结束时间，Unix 时间戳，非必填；缺失、格式不合法或晚于当前时间时，服务端会自动调整为当前时间",
              "required": false,
              "schema": {
                "type": "integer",
                "format": "int64"
              },
              "example": 1761843000
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取网址浏览记录列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/UrlVisitLogListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "data": [
                        {
                          "id": 2001,
                          "timestamp": 1761842271,
                          "ip_addr": "192.168.1.100",
                          "mac": "08:9b:4b:00:10:6e",
                          "host": "www.example.com",
                          "uri": "/news/detail?id=1",
                          "comment": "办公终端",
                          "appname": "浏览器",
                          "icon": "browser",
                          "client_model": "ThinkPad",
                          "client_type": "PC"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空网址浏览记录",
          "description": "清空网址浏览记录。\n本接口用于清空全部网址浏览记录，不支持按时间范围清空。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearUrlVisitLogs",
          "tags": [
            "log-url-visits"
          ],
          "responses": {
            "200": {
              "description": "网址浏览记录清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数，默认 20，最大 500；超过最大值时服务端按 500 处理",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 20,
            "example": 20
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应信息",
              "example": "Success"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "additionalProperties": false
        },
        "UrlVisitLogListResponse": {
          "type": "object",
          "properties": {
            "code": {
              "type": "integer",
              "description": "状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应信息",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "description": "网址浏览记录列表",
                  "items": {
                    "$ref": "#/components/schemas/UrlVisitLog"
                  }
                }
              },
              "required": [
                "data"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "code",
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "UrlVisitLog": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "记录ID",
              "example": 2001
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "访问时间，Unix 时间戳",
              "example": 1761842271
            },
            "ip_addr": {
              "type": "string",
              "description": "终端IP地址",
              "format": "ipv4",
              "example": "192.168.1.100"
            },
            "mac": {
              "type": "string",
              "description": "终端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:00:10:6e"
            },
            "host": {
              "type": "string",
              "description": "访问主机名",
              "example": "www.example.com"
            },
            "uri": {
              "type": "string",
              "description": "访问URI",
              "example": "/news/detail?id=1"
            },
            "comment": {
              "type": "string",
              "description": "终端备注",
              "example": "办公终端"
            },
            "appname": {
              "type": "string",
              "description": "应用名称",
              "example": "浏览器"
            },
            "icon": {
              "type": "string",
              "description": "应用或终端图标",
              "example": "browser"
            },
            "client_model": {
              "type": "string",
              "description": "终端型号",
              "example": "ThinkPad"
            },
            "client_type": {
              "type": "string",
              "description": "终端类型",
              "example": "PC"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-url-visits",
        "x-displayName": "网址浏览记录",
        "description": "网址浏览记录的查询和清空，支持分页、时间范围和关键词搜索"
      }
    ]
  },
  "log/log-warnings.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "告警信息API",
      "version": "1.0.0",
      "summary": "告警信息查询",
      "description": "提供告警信息的只读查询功能，包括：\n- 告警信息列表查询\n- 支持分页、排序、过滤和模糊搜索\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/warnings": {
        "get": {
          "summary": "获取告警信息列表",
          "description": "获取设备告警信息列表。\n支持按告警类型、告警事件、告警等级、已读状态、时间戳等字段过滤。\n",
          "operationId": "listWarnings",
          "tags": [
            "log-warnings"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "$ref": "#/components/parameters/filterParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊搜索字段名，与 pattern 联合使用，支持 event、title、detail、customize",
              "schema": {
                "type": "string"
              },
              "example": "title,detail"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊搜索关键词，与 key 联合使用",
              "schema": {
                "type": "string"
              },
              "example": "CPU"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取告警信息列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WarningListResponse"
                  },
                  "example": {
                    "code": 0,
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "id": 1,
                          "timestamp": 1778763600,
                          "event": "CPU",
                          "title": "CPU使用率过高",
                          "type": 1,
                          "level": 2,
                          "detail": "CPU使用率持续超过阈值",
                          "customize": "",
                          "status": 0
                        },
                        {
                          "id": 2,
                          "timestamp": 1778756400,
                          "event": "AP_CHUTIL",
                          "title": "AP信道利用率过高",
                          "type": 2,
                          "level": 1,
                          "detail": "AP信道利用率超过阈值",
                          "customize": "00:11:22:33:44:55",
                          "status": 1
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序，desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "desc",
            "example": "desc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持 id、timestamp、type、event、level、status、title",
          "schema": {
            "type": "string",
            "default": "timestamp",
            "example": "timestamp"
          }
        },
        "filterParam": {
          "name": "filter",
          "in": "query",
          "description": "过滤条件，支持精确匹配、范围匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n- \"：（包含）\"\n- \"!：（不包含）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 告警类型过滤：filter=type==1\n- 告警事件过滤：filter=event==CPU\n- 告警等级过滤：filter=level==2\n- 未读告警过滤：filter=status==0\n- 时间范围过滤：filter=timestamp>=1778760000&filter=timestamp<1778846400\n",
          "schema": {
            "type": "string"
          },
          "example": "status==0"
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 400,
                "message": "请求语法错误或参数不合法（检查请求参数、过滤条件或排序字段）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 401,
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 403,
                "message": "无权限访问告警信息"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "code": 500,
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "WarningListResponse": {
          "type": "object",
          "required": [
            "code",
            "message",
            "results"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "业务状态码，0表示成功",
              "example": 0
            },
            "message": {
              "type": "string",
              "description": "响应消息",
              "example": "Success"
            },
            "results": {
              "$ref": "#/components/schemas/WarningListResult"
            }
          },
          "additionalProperties": false
        },
        "WarningListResult": {
          "type": "object",
          "required": [
            "total",
            "data"
          ],
          "properties": {
            "total": {
              "type": "integer",
              "format": "int64",
              "description": "符合过滤条件的告警总数",
              "minimum": 0,
              "example": 2
            },
            "data": {
              "type": "array",
              "description": "告警信息列表",
              "items": {
                "$ref": "#/components/schemas/WarningInfo"
              }
            }
          },
          "additionalProperties": false
        },
        "WarningInfo": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "event",
            "title",
            "type",
            "level",
            "detail",
            "customize",
            "status"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "告警ID",
              "minimum": 1,
              "example": 1
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "告警产生时间戳",
              "example": 1778763600
            },
            "event": {
              "type": "string",
              "description": "告警事件标识",
              "maxLength": 100,
              "example": "CPU"
            },
            "title": {
              "type": "string",
              "description": "告警标题",
              "maxLength": 255,
              "example": "CPU使用率过高"
            },
            "type": {
              "type": "integer",
              "description": "告警类型，1-路由，2-AP，3-交换机，4-周边设备，5-其他",
              "enum": [
                1,
                2,
                3,
                4,
                5
              ],
              "example": 1
            },
            "level": {
              "type": "integer",
              "description": "告警等级",
              "enum": [
                1,
                2,
                3
              ],
              "example": 2
            },
            "detail": {
              "type": "string",
              "description": "告警详情",
              "maxLength": 2000,
              "example": "CPU使用率持续超过阈值"
            },
            "customize": {
              "type": "string",
              "description": "自定义内容，CPU温度告警时为温度字段名，AP告警时为AP MAC地址，其他场景为空字符串",
              "maxLength": 255,
              "example": ""
            },
            "status": {
              "type": "integer",
              "description": "阅读状态，0-未读，1-已读",
              "enum": [
                0,
                1
              ],
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "错误码",
              "example": 400
            },
            "message": {
              "type": "string",
              "description": "错误信息",
              "example": "请求参数错误"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer <token>\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-warnings",
        "x-displayName": "告警信息",
        "description": "告警信息列表查询"
      }
    ]
  },
  "log/log-web-activity.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "WEB操作日志管理API",
      "version": "1.0.0",
      "summary": "用户WEB操作日志查询和管理",
      "description": "提供用户WEB操作日志的查询和管理功能，包括：\n- 用户WEB操作日志查询\n- 支持过滤和分页功能\n- 用户登录、配置操作等记录\n- IP地址和操作事件信息记录\n"
    },
    "servers": [
      {
        "url": "https://api.example.com/api/v4",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/web_activity": {
        "get": {
          "summary": "获取WEB操作日志列表",
          "description": "获取用户WEB操作日志记录列表。\n支持过滤和分页功能，可以查询用户登录、配置操作等记录。\n",
          "operationId": "listWebActivityLogs",
          "tags": [
            "log-web-activity"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=event==登录\n- AND条件：filter=event==登录&filter=username==admin\n- OR条件：filter=event==登录,event==登出\n- 用户过滤：filter=username==admin\n- IP地址过滤：filter=ip_addr==192.168.99.101\n- 时间范围：filter=timestamp>1763779000&filter=timestamp<1763780000\n",
              "schema": {
                "type": "string"
              },
              "example": "event==登录"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 username, ip_addr, function, event",
              "schema": {
                "type": "string"
              },
              "example": "username,event"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "登录"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取WEB操作日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebActivityLogListResponse"
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空WEB操作日志",
          "description": "清空所有WEB操作日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearWebActivityLogs",
          "tags": [
            "log-web-activity"
          ],
          "responses": {
            "200": {
              "description": "WEB操作日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "description": "清空日志异常",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WebActivityLogErrorResponse"
                  },
                  "example": {
                    "message": "清空WEB操作日志异常"
                  }
                }
              }
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 50,
            "example": 50
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向，asc为升序（默认），desc为降序",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段，支持id、timestamp、username、event等字段",
          "schema": {
            "type": "string",
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求语法错误或参数不合法（检查请求体/参数、JSON 格式）"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效（需登录/刷新 token）"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问（检查授权、权限配置）"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在（检查 URL、路由、资源是否已删除）"
              }
            }
          }
        },
        "Conflict": {
          "description": "资源冲突",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源冲突（如唯一性冲突，需调整请求逻辑）"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WebActivityLogErrorResponse": {
          "type": "object",
          "required": [
            "message"
          ],
          "properties": {
            "message": {
              "type": "string",
              "description": "WEB操作日志业务错误信息描述"
            }
          }
        },
        "WebActivityLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "总记录数",
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WebActivityLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        },
        "WebActivityLog": {
          "type": "object",
          "required": [
            "id",
            "timestamp",
            "username",
            "ip_addr",
            "function",
            "event"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 363
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763779604
            },
            "username": {
              "type": "string",
              "description": "用户名",
              "maxLength": 100,
              "example": "admin"
            },
            "ip_addr": {
              "type": "string",
              "description": "IP地址",
              "format": "ipv4",
              "example": "192.168.99.101"
            },
            "function": {
              "type": "string",
              "description": "功能模块",
              "maxLength": 100,
              "example": "--"
            },
            "event": {
              "type": "string",
              "description": "操作事件",
              "maxLength": 200,
              "example": "登录"
            }
          },
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-web-activity",
        "x-displayName": "WEB操作日志管理",
        "description": "用户WEB操作日志的查询和管理，支持过滤、分页和清空功能"
      }
    ]
  },
  "log/log-wireless-client.yaml": {
    "openapi": "3.1.0",
    "info": {
      "title": "无线终端日志管理API",
      "version": "1.0.0",
      "summary": "无线终端日志查询和管理",
      "description": "提供无线终端日志的查询功能，包括：\n- 无线客户端连接/断开日志查询\n- 支持过滤和分页功能\n- AP设备和信号强度信息\n- 连接状态和错误追踪\n"
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "生产环境"
      },
      {
        "url": "https://192.168.9.1",
        "description": "测试环境"
      }
    ],
    "paths": {
      "/api/v4.0/log/wireless": {
        "get": {
          "summary": "获取无线终端日志列表",
          "description": "获取无线终端连接/断开日志记录列表。\n支持过滤和分页功能，可以查询客户端的连接状态和信号信息。\n",
          "operationId": "listWirelessLogs",
          "tags": [
            "log-wireless-client"
          ],
          "parameters": [
            {
              "$ref": "#/components/parameters/pageParam"
            },
            {
              "$ref": "#/components/parameters/limitParam"
            },
            {
              "$ref": "#/components/parameters/orderParam"
            },
            {
              "$ref": "#/components/parameters/orderByParam"
            },
            {
              "name": "key",
              "in": "query",
              "description": "模糊匹配字段列表，支持 mac, ssid, errmsg, mac_comment, apmac_comment",
              "schema": {
                "type": "string"
              },
              "example": "mac,ssid"
            },
            {
              "name": "pattern",
              "in": "query",
              "description": "模糊匹配内容",
              "schema": {
                "type": "string"
              },
              "example": "5G:IK-Work"
            },
            {
              "name": "filter",
              "in": "query",
              "description": "过滤条件，支持精确匹配和多条件组合。\n\n支持的操作符：\n- \"==（等于）\"\n- \"!=（不等于）\"\n- \">（大于）\"\n- \">=（大于等于）\"\n- \"<（小于）\"\n- \"<=（小于等于）\"\n\n多条件连接语法：\n- AND逻辑：filter=field1==value1&filter=field2==value2\n- OR逻辑：filter=field1==value1,field2==value2\n\n使用示例：\n- 单条件：filter=action==login\n- AND条件：filter=action==login&filter=signal>-50\n- OR条件：filter=mac==de:8e:d0:1f:c1:d6,mac==46:61:43:b4:f6:07\n- 时间范围：filter=timestamp>1763450000&filter=timestamp<1763455000\n- MAC地址过滤：filter=apmac==08:9b:4b:11:22:33\n",
              "schema": {
                "type": "string"
              },
              "example": "action==login"
            }
          ],
          "responses": {
            "200": {
              "description": "成功获取无线终端日志列表",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/WirelessLogListResponse"
                  },
                  "example": {
                    "message": "Success",
                    "results": {
                      "total": 2,
                      "data": [
                        {
                          "action": "login",
                          "id": 1,
                          "timestamp": 1763450144,
                          "mac": "de:8e:d0:1f:c1:d6",
                          "apmac": "08:9b:4b:11:22:33",
                          "bssid": "08:9b:4b:33:44:55",
                          "ssid": "5G:IK-Work",
                          "errmsg": "成功",
                          "signal": -48,
                          "mac_comment": "--",
                          "apmac_comment": "销售-X7",
                          "errid": 0
                        },
                        {
                          "action": "logout",
                          "id": 2,
                          "timestamp": 1763450154,
                          "mac": "46:61:43:b4:f6:07",
                          "apmac": "08:9b:4b:11:22:33",
                          "bssid": "08:9b:4b:33:44:55",
                          "ssid": "5G:IK-Work",
                          "errmsg": "成功",
                          "signal": 0,
                          "mac_comment": "--",
                          "apmac_comment": "销售-X7",
                          "errid": 0
                        }
                      ]
                    }
                  }
                }
              }
            },
            "400": {
              "$ref": "#/components/responses/BadRequest"
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        },
        "delete": {
          "summary": "清空无线终端日志",
          "description": "清空所有无线终端连接日志记录。\n此操作不可恢复，请谨慎操作。\n",
          "operationId": "clearWirelessLogs",
          "tags": [
            "log-wireless-client"
          ],
          "responses": {
            "200": {
              "description": "无线终端日志清空成功",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessResponse"
                  }
                }
              }
            },
            "401": {
              "$ref": "#/components/responses/Unauthorized"
            },
            "403": {
              "$ref": "#/components/responses/Forbidden"
            },
            "500": {
              "$ref": "#/components/responses/InternalServerError"
            }
          },
          "security": [
            {
              "bearerAuth": []
            }
          ]
        }
      }
    },
    "components": {
      "parameters": {
        "pageParam": {
          "name": "page",
          "in": "query",
          "description": "页码（从1开始）",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "example": 1
          }
        },
        "limitParam": {
          "name": "limit",
          "in": "query",
          "description": "每页记录数",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "default": 20,
            "example": 20
          }
        },
        "orderParam": {
          "name": "order",
          "in": "query",
          "description": "排序方向",
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "asc",
            "example": "asc"
          }
        },
        "orderByParam": {
          "name": "order_by",
          "in": "query",
          "description": "排序字段",
          "schema": {
            "type": "string",
            "enum": [
              "id",
              "timestamp",
              "mac",
              "ssid"
            ],
            "default": "id",
            "example": "timestamp"
          }
        }
      },
      "responses": {
        "BadRequest": {
          "description": "请求语法错误或参数不合法",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "请求参数错误"
              }
            }
          }
        },
        "Unauthorized": {
          "description": "未认证或凭证无效",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "未认证或凭证无效"
              }
            }
          }
        },
        "Forbidden": {
          "description": "无权限访问",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "无权限访问"
              }
            }
          }
        },
        "NotFound": {
          "description": "资源不存在",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "资源不存在"
              }
            }
          }
        },
        "InternalServerError": {
          "description": "服务器内部错误",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              },
              "example": {
                "message": "服务器内部错误（查看服务器日志、修复异常）"
              }
            }
          }
        }
      },
      "schemas": {
        "SuccessResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "ErrorResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "错误信息"
            }
          },
          "required": [
            "message"
          ],
          "additionalProperties": false
        },
        "WirelessLog": {
          "type": "object",
          "required": [
            "id",
            "action",
            "timestamp",
            "mac",
            "apmac",
            "bssid",
            "ssid",
            "errmsg",
            "signal",
            "mac_comment",
            "apmac_comment",
            "errid"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "日志记录ID",
              "minimum": 1,
              "example": 1
            },
            "action": {
              "type": "string",
              "description": "连接动作",
              "enum": [
                "login",
                "logout",
                "connect",
                "disconnect",
                "auth",
                "deauth"
              ],
              "example": "login"
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "时间戳（Unix时间戳）",
              "example": 1763450144
            },
            "mac": {
              "type": "string",
              "description": "客户端MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "de:8e:d0:1f:c1:d6"
            },
            "apmac": {
              "type": "string",
              "description": "AP设备MAC地址",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:11:22:33"
            },
            "bssid": {
              "type": "string",
              "description": "BSSID（AP的MAC地址）",
              "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
              "example": "08:9b:4b:33:44:55"
            },
            "ssid": {
              "type": "string",
              "description": "WiFi网络名称",
              "maxLength": 100,
              "example": "5G:IK-Work"
            },
            "errmsg": {
              "type": "string",
              "description": "错误消息或状态描述",
              "maxLength": 200,
              "example": "成功"
            },
            "signal": {
              "type": "integer",
              "description": "信号强度（dBm）",
              "minimum": -100,
              "maximum": 0,
              "example": -48
            },
            "mac_comment": {
              "type": "string",
              "description": "MAC地址备注",
              "maxLength": 100,
              "example": "--"
            },
            "apmac_comment": {
              "type": "string",
              "description": "AP设备备注",
              "maxLength": 100,
              "example": "销售-X7"
            },
            "errid": {
              "type": "integer",
              "description": "错误代码（0表示成功）",
              "minimum": 0,
              "example": 0
            }
          },
          "additionalProperties": false
        },
        "WirelessLogListResponse": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "example": "Success"
            },
            "results": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "integer",
                  "description": "返回记录总数",
                  "minimum": 0,
                  "example": 2
                },
                "data": {
                  "type": "array",
                  "description": "无线终端日志记录列表",
                  "items": {
                    "$ref": "#/components/schemas/WirelessLog"
                  }
                }
              },
              "required": [
                "total",
                "data"
              ]
            }
          },
          "required": [
            "message",
            "results"
          ],
          "additionalProperties": false
        }
      },
      "securitySchemes": {
        "bearerAuth": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "JWT",
          "description": "使用JWT Bearer Token进行认证。\n在请求头中添加: Authorization: Bearer MTk2MTUwN2QtNzhkNS00NmEwLTljMWYt\n"
        }
      }
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "tags": [
      {
        "name": "log-wireless-client",
        "x-displayName": "无线终端日志管理",
        "description": "无线终端连接日志的查询和管理，包括客户端连接状态和信号信息"
      }
    ]
  }
}