{
  "openapi": "3.0.3",
  "info": {
    "title": "ZJY-TTS-003 CH32V208 HTTP API 开发文档",
    "version": "1.0.0",
    "description": "面向客户业务集成的 HTTP 接口合同，包含电话、短信、执行结果和相关业务配置。"
  },
  "servers": [
    {
      "url": "http://{device-ip}",
      "variables": {
        "device-ip": {
          "default": "192.168.1.108",
          "description": "ZJY-TTS-003 设备 IPv4 地址"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "设备状态与配置"
    },
    {
      "name": "告警任务"
    },
    {
      "name": "LTE 状态与配置"
    },
    {
      "name": "电话与短信"
    },
    {
      "name": "短信收件箱"
    },
    {
      "name": "执行记录"
    },
    {
      "name": "TTS 发音词典"
    },
    {
      "name": "SIM 余额"
    }
  ],
  "security": [],
  "paths": {
    "/api/status/version": {
      "get": {
        "tags": [
          "设备状态与配置"
        ],
        "summary": "获取 MCU 与 LTE 聚合版本",
        "description": "获取 MCU 与 LTE 聚合版本。",
        "operationId": "get_api_status_version",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "mcu": {
                      "version": "2.0.7"
                    },
                    "module": {
                      "ver": "V5.0.0JY",
                      "sys": "2.0.11",
                      "imei": "860000000000000",
                      "cap": 1,
                      "cobs": 1,
                      "link": "cobs"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/queue/add": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "加入电话队列",
        "description": "加入电话队列。 出现 src/rid/ref/exp 任一字段就进入防重复模式，并强制要求 src+rid+exp；(src,rid) 与短信共用全局幂等空间。",
        "operationId": "post_api_module_queue_add",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "added": true,
                    "id": "CALL_1786579200_1",
                    "target": "13800138000",
                    "mode": "4g",
                    "priority": 100,
                    "queue_size": 1,
                    "ts": 1786579200,
                    "src": "A1B2C3D4E5F6",
                    "rid": 1,
                    "ref": "alarm-42"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "pattern": "^[0-9]{3,13}$",
                    "description": "目标号码；可恢复任务队列正式合同要求 3–13 位纯数字。"
                  },
                  "tts": {
                    "type": "string",
                    "description": "接通后播放的可选 TTS 文本。"
                  },
                  "mode": {
                    "type": "string",
                    "default": "4g",
                    "enum": [
                      "4g",
                      "tel"
                    ],
                    "description": "呼叫通道：4g 或 tel；mode 优先于 type。"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "4g",
                      "tel"
                    ],
                    "description": "mode 的可选别名；两者同时出现时使用 mode。"
                  },
                  "pri": {
                    "type": "integer",
                    "default": 100,
                    "minimum": 0,
                    "description": "优先级，数字越小越先执行；同优先级按来源轮转。pri 优先于 priority。"
                  },
                  "priority": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "pri 的可选别名；两者同时出现时使用 pri。"
                  },
                  "src": {
                    "type": "string",
                    "pattern": "^[0-9A-Fa-f]{12}$",
                    "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。"
                  },
                  "rid": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4294967295,
                    "description": "来源内 uint32 请求号；与 src 组成电话/SMS 共用的全局幂等键。"
                  },
                  "ref": {
                    "type": "string",
                    "description": "可选关联值，仅透传到队列和记录，不参与幂等判断。"
                  },
                  "exp": {
                    "type": "integer",
                    "minimum": 1704067200,
                    "description": "Unix UTC 绝对过期秒，不是 TTL；必须晚于 LTE 当前时间且不能超出 ct/st 允许窗口加 300 秒。"
                  }
                },
                "required": [
                  "num"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/queue/stat": {
      "get": {
        "tags": [
          "告警任务"
        ],
        "summary": "获取电话队列统计",
        "description": "获取电话队列统计。",
        "operationId": "get_api_module_queue_stat",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "pending": 1,
                    "size": 1,
                    "cur_num": ""
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/queue/list": {
      "get": {
        "tags": [
          "告警任务"
        ],
        "summary": "获取电话队列列表",
        "description": "获取电话队列列表。",
        "operationId": "get_api_module_queue_list",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cnt": 1,
                    "total": 1,
                    "offset": 1,
                    "list": [
                      {
                        "num": "13800138000",
                        "pri": 100,
                        "sta": 0,
                        "src": "A1B2C3D4E5F6",
                        "rid": 1,
                        "ref": "alarm-42",
                        "exp": 1786579800
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "src",
            "in": "query",
            "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Fa-f]{12}$"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "从 1 开始的结果偏移。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "返回条数，默认 20，范围 1–50。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            }
          }
        ]
      }
    },
    "/api/module/queue/current": {
      "get": {
        "tags": [
          "告警任务"
        ],
        "summary": "获取当前电话动作",
        "description": "获取当前电话动作。",
        "operationId": "get_api_module_queue_current",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "exists": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "src",
            "in": "query",
            "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Fa-f]{12}$"
            }
          }
        ]
      }
    },
    "/api/module/queue/hangup": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "挂断当前电话",
        "description": "挂断当前电话。 不清等待队列；无当前通话时为 code=3/reason=no_call。",
        "operationId": "post_api_module_queue_hangup",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "hangup": true,
                    "target": "13800138000",
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/queue/delete": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "取消单个电话动作",
        "description": "取消单个电话动作。 二选一：num，或 src+rid。告警任务已经开始时返回 code=5/already_started；按 key 取消器不校验电话/SMS通道。",
        "operationId": "post_api_module_queue_delete",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "removed": true,
                    "src": "A1B2C3D4E5F6",
                    "rid": 1
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "pattern": "^[0-9]{3,13}$",
                    "description": "按号码删除该号码的第一个等待电话；不能与防重复任务键 语义混淆。"
                  },
                  "src": {
                    "type": "string",
                    "pattern": "^[0-9A-Fa-f]{12}$",
                    "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。"
                  },
                  "rid": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4294967295,
                    "description": "来源内 uint32 请求号；与 src 组成电话/SMS 共用的全局幂等键。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/module/queue/delete_all": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "按号码取消全部等待电话",
        "description": "按号码取消全部等待电话。 只删除等待项，不挂断当前通话。",
        "operationId": "post_api_module_queue_delete_all",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "removed_cnt": 2,
                    "target": "13800138000",
                    "queue_size": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "pattern": "^[0-9]{3,13}$",
                    "description": "目标号码；可恢复任务队列正式合同要求 3–13 位纯数字。"
                  }
                },
                "required": [
                  "num"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/queue/clear": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "清空等待电话队列",
        "description": "清空等待电话队列。 不挂断当前电话；告警任务写入取消终态。",
        "operationId": "post_api_module_queue_clear",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cleared": true,
                    "removed_cnt": 2,
                    "queue_size": 0,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/smsq/add": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "加入短信队列",
        "description": "加入短信队列。 出现 src/rid/ref/exp 任一字段就进入防重复模式，并强制要求 src+rid+exp；(src,rid) 与电话共用全局幂等空间。",
        "operationId": "post_api_module_smsq_add",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "added": true,
                    "id": "SMS_1786579200_1",
                    "target": "13800138000",
                    "priority": 100,
                    "content_len": 12,
                    "queue_size": 1,
                    "ts": 1786579200,
                    "src": "A1B2C3D4E5F6",
                    "rid": 2,
                    "ref": "alarm-42"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "pattern": "^[0-9]{3,13}$",
                    "description": "目标号码；可恢复任务队列正式合同要求 3–13 位纯数字。"
                  },
                  "msg": {
                    "type": "string",
                    "description": "短信正文首选字段；当前可省略为空。msg 优先于 content。"
                  },
                  "content": {
                    "type": "string",
                    "description": "msg 的可选别名；两者同时出现时使用 msg。"
                  },
                  "pri": {
                    "type": "integer",
                    "default": 100,
                    "minimum": 0,
                    "description": "优先级，数字越小越先执行；同优先级按来源轮转。pri 优先于 priority。"
                  },
                  "priority": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "pri 的可选别名；两者同时出现时使用 pri。"
                  },
                  "src": {
                    "type": "string",
                    "pattern": "^[0-9A-Fa-f]{12}$",
                    "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。"
                  },
                  "rid": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4294967295,
                    "description": "来源内 uint32 请求号；与 src 组成电话/SMS 共用的全局幂等键。"
                  },
                  "ref": {
                    "type": "string",
                    "description": "可选关联值，仅透传到队列和记录，不参与幂等判断。"
                  },
                  "exp": {
                    "type": "integer",
                    "minimum": 1704067200,
                    "description": "Unix UTC 绝对过期秒，不是 TTL；必须晚于 LTE 当前时间且不能超出 ct/st 允许窗口加 300 秒。"
                  }
                },
                "required": [
                  "num"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/smsq/stat": {
      "get": {
        "tags": [
          "告警任务"
        ],
        "summary": "获取短信队列统计",
        "description": "获取短信队列统计。",
        "operationId": "get_api_module_smsq_stat",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "size": 1,
                    "has_cur": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/smsq/list": {
      "get": {
        "tags": [
          "告警任务"
        ],
        "summary": "获取短信队列列表",
        "description": "获取短信队列列表。 列表不返回短信正文。",
        "operationId": "get_api_module_smsq_list",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cnt": 1,
                    "total": 1,
                    "offset": 1,
                    "list": [
                      {
                        "num": "13800138000",
                        "pri": 100,
                        "sta": 0,
                        "src": "A1B2C3D4E5F6",
                        "rid": 2,
                        "ref": "alarm-42",
                        "exp": 1786582800
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "src",
            "in": "query",
            "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Fa-f]{12}$"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "从 1 开始的结果偏移。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "返回条数，默认 20，范围 1–50。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            }
          }
        ]
      }
    },
    "/api/module/smsq/clear": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "清空等待短信队列",
        "description": "清空等待短信队列。 不影响当前正在发送的短信。",
        "operationId": "post_api_module_smsq_clear",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cleared": true,
                    "removed_cnt": 2,
                    "queue_size": 0,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/smsq/delete": {
      "post": {
        "tags": [
          "告警任务"
        ],
        "summary": "取消单个短信动作",
        "description": "取消单个短信动作。 二选一：id，或 src+rid。按 key 取消器不校验电话/SMS 通道。",
        "operationId": "post_api_module_smsq_delete",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "removed": true,
                    "id": "SMS_1786579200_1"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_]+$",
                    "description": "按 ID 删除等待短信；只允许字母、数字、下划线。"
                  },
                  "src": {
                    "type": "string",
                    "pattern": "^[0-9A-Fa-f]{12}$",
                    "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。"
                  },
                  "rid": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4294967295,
                    "description": "来源内 uint32 请求号；与 src 组成电话/SMS 共用的全局幂等键。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/module/sys/ping": {
      "get": {
        "tags": [
          "LTE 状态与配置"
        ],
        "summary": "检查 LTE 命令链路",
        "description": "检查 LTE 命令链路。",
        "operationId": "get_api_module_sys_ping",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "pong": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/sys/version": {
      "get": {
        "tags": [
          "LTE 状态与配置"
        ],
        "summary": "获取 LTE 版本与能力",
        "description": "获取 LTE 版本与能力。",
        "operationId": "get_api_module_sys_version",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "ver": "V5.0.0JY",
                    "sys": "2.0.11",
                    "imei": "860000000000000",
                    "cap": 1,
                    "cobs": 1,
                    "link": "cobs"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/sys/signal": {
      "get": {
        "tags": [
          "LTE 状态与配置"
        ],
        "summary": "获取 LTE 信号和线路状态",
        "description": "获取 LTE 信号和线路状态。",
        "operationId": "get_api_module_sys_signal",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "rssi": 20,
                    "sys_sta": 4,
                    "net_mode": "4G",
                    "mnc": "00",
                    "iccid": "",
                    "call_result": 0,
                    "unread_sms": 0,
                    "tel_line": 1,
                    "sim_card": 1
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/config/basic": {
      "get": {
        "tags": [
          "LTE 状态与配置"
        ],
        "summary": "获取 LTE 基本身份",
        "description": "获取 LTE 基本身份。 只返回 ver/sys/imei，不是全部电话配置。",
        "operationId": "get_api_module_config_basic",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "ver": "V5.0.0JY",
                    "sys": "2.0.11",
                    "imei": "860000000000000"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/config/all": {
      "get": {
        "tags": [
          "LTE 状态与配置"
        ],
        "summary": "获取 LTE 全部电话配置",
        "description": "获取 LTE 全部电话配置。",
        "operationId": "get_api_module_config_all",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "call_interval": 30,
                    "hook_hold_time": 1000,
                    "dtmf_level": 5,
                    "dtmf_wait": 500,
                    "dtmf_interval": 300,
                    "tts_level": 5,
                    "tts_wait": 500,
                    "tts_interval": 1000,
                    "tts_speed": 50,
                    "tts_count": 1,
                    "conn_check": 1,
                    "call_list_cnt": 10,
                    "first_dtmf_interval": 500,
                    "no_answer_timeout": 30000
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/config/set": {
      "post": {
        "tags": [
          "LTE 状态与配置"
        ],
        "summary": "保存 LTE 电话配置",
        "description": "保存 LTE 电话配置。 至少提供一个字段。set_count 是识别到的字段数；底层拒绝越界时仍可能计数。HTTP 不能设置 call_list_cnt/no_answer_timeout。",
        "operationId": "post_api_module_config_set",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "set_count": 2
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "call_interval": {
                    "type": "integer",
                    "minimum": 20,
                    "maximum": 250,
                    "description": "两次呼叫之间的间隔，单位秒。"
                  },
                  "hook_hold_time": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4000,
                    "description": "摘机保持时间，单位毫秒；公开合同要求非负。"
                  },
                  "dtmf_level": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 7,
                    "description": "DTMF 音量级别。"
                  },
                  "dtmf_wait": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4000,
                    "description": "DTMF 播放前等待，单位毫秒。"
                  },
                  "dtmf_interval": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 2000,
                    "description": "DTMF 间隔，单位毫秒。"
                  },
                  "tts_level": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 7,
                    "description": "TTS 音量级别，范围 0–7。"
                  },
                  "tts_wait": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 4000,
                    "description": "TTS 播放前等待，单位毫秒。"
                  },
                  "tts_interval": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000,
                    "description": "TTS 播放间隔，单位毫秒。"
                  },
                  "tts_speed": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "TTS 语速。"
                  },
                  "tts_count": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10,
                    "description": "TTS 播放次数。"
                  },
                  "conn_check": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ],
                    "description": "是否启用连接检查：0=关闭，1=启用。"
                  },
                  "first_dtmf_interval": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 2000,
                    "description": "第一次 DTMF 前间隔，单位毫秒。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/module/call/dial": {
      "post": {
        "tags": [
          "电话与短信"
        ],
        "summary": "立即排队 4G 呼叫",
        "description": "立即排队 4G 呼叫。",
        "operationId": "post_api_module_call_dial",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "dialing": true,
                    "target": "13800138000",
                    "mode": "4g",
                    "has_tts": true,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "minLength": 1,
                    "description": "目标号码；接口只检查非空，客户端应限制为 3–13 位数字。"
                  },
                  "tts": {
                    "type": "string",
                    "description": "接通后播放的可选 TTS 文本；响应成功不表示已接通。"
                  }
                },
                "required": [
                  "num"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/call/tel": {
      "post": {
        "tags": [
          "电话与短信"
        ],
        "summary": "立即排队固话呼叫",
        "description": "立即排队固话呼叫。",
        "operationId": "post_api_module_call_tel",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "dialing": true,
                    "target": "13800138000",
                    "mode": "tel",
                    "has_tts": false,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "minLength": 1,
                    "description": "目标号码，必须非空；建议限制为 3–13 位数字。"
                  },
                  "tts": {
                    "type": "string",
                    "description": "接通后播放的可选 TTS 文本。"
                  }
                },
                "required": [
                  "num"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/call/dial_confirm": {
      "post": {
        "tags": [
          "电话与短信"
        ],
        "summary": "发起按键确认 4G 电话",
        "description": "发起按键确认 4G 电话。",
        "operationId": "post_api_module_call_dial_confirm",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "dialing": true,
                    "target": "13800138000",
                    "mode": "4g",
                    "has_tts": true,
                    "has_confirm_sms": true,
                    "dtmf_timeout": 10,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "minLength": 1,
                    "description": "被叫号码，必须非空。"
                  },
                  "tts": {
                    "type": "string",
                    "description": "接通后播放的 TTS 文本。"
                  },
                  "dtmf_timeout": {
                    "type": "integer",
                    "default": 10,
                    "minimum": 1,
                    "maximum": 60,
                    "description": "等待按键的秒数，默认 10，范围 1–60。"
                  },
                  "confirm_sms_content": {
                    "type": "string",
                    "description": "按键 1 后排队发送的确认短信正文；省略则不发确认短信。"
                  },
                  "confirm_sms_num": {
                    "type": "string",
                    "description": "确认短信目标号码；省略时使用被叫号码。"
                  }
                },
                "required": [
                  "num"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/sms/send": {
      "post": {
        "tags": [
          "电话与短信"
        ],
        "summary": "立即排队发送短信",
        "description": "立即排队发送短信。",
        "operationId": "post_api_module_sms_send",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "sent": true,
                    "target": "13800138000",
                    "len": 12,
                    "encoding": "utf8",
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "string",
                    "minLength": 1,
                    "description": "短信目标号码，必须非空。"
                  },
                  "content": {
                    "type": "string",
                    "minLength": 1,
                    "description": "短信正文，不能为空；sent=true 只表示进入发送队列。"
                  },
                  "encoding": {
                    "type": "string",
                    "default": "utf8",
                    "enum": [
                      "utf8",
                      "ucs2"
                    ],
                    "description": "正文编码；只有精确 ucs2 才转换，其他值按 utf8 处理。"
                  }
                },
                "required": [
                  "num",
                  "content"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/inbox/stat": {
      "get": {
        "tags": [
          "短信收件箱"
        ],
        "summary": "获取短信收件箱统计",
        "description": "获取短信收件箱统计。",
        "operationId": "get_api_module_inbox_stat",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cnt": 3,
                    "max": 30,
                    "unread": 1
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/inbox/list": {
      "get": {
        "tags": [
          "短信收件箱"
        ],
        "summary": "分页获取短信收件箱",
        "description": "分页获取短信收件箱。 当前没有 unread 过滤参数；列表只返回 10 个 UTF-8 字符的 preview。",
        "operationId": "get_api_module_inbox_list",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cnt": 1,
                    "total": 3,
                    "offset": 1,
                    "list": [
                      {
                        "id": 15,
                        "num": "10086",
                        "preview": "余额20.00元",
                        "ts": 1786579200,
                        "read": false
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "description": "从 1 开始的结果偏移；省略或小于 1 时使用 1。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1,
              "maximum": 65535
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "返回条数，默认 10，范围 1–20。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 20
            }
          }
        ]
      }
    },
    "/api/module/inbox/read": {
      "get": {
        "tags": [
          "短信收件箱"
        ],
        "summary": "读取短信正文并标记已读",
        "description": "读取短信正文并标记已读。",
        "operationId": "get_api_module_inbox_read",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "id": 15,
                    "num": "10086",
                    "content": "余额20.00元",
                    "ts": 1786579200,
                    "read": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "description": "收件箱短信 ID；读取成功会持久化标记为已读。",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            }
          }
        ]
      }
    },
    "/api/module/inbox/delete": {
      "post": {
        "tags": [
          "短信收件箱"
        ],
        "summary": "删除收件箱短信",
        "description": "删除收件箱短信。 三选一：id、all=true、read_only=true。",
        "operationId": "post_api_module_inbox_delete",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "deleted": true,
                    "mode": "single",
                    "id": 15
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535,
                    "description": "删除单条短信的 ID；有效 id 的优先级高于 all/read_only。"
                  },
                  "all": {
                    "type": "boolean",
                    "description": "1 或 true 表示删除全部短信。"
                  },
                  "read_only": {
                    "type": "boolean",
                    "description": "1 或 true 表示只删除已读短信。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/module/inbox/mark": {
      "post": {
        "tags": [
          "短信收件箱"
        ],
        "summary": "标记短信已读",
        "description": "标记短信已读。 二选一：id 或 all=true。",
        "operationId": "post_api_module_inbox_mark",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "marked": true,
                    "mode": "single",
                    "id": 15
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535,
                    "description": "要标记的单条短信 ID。"
                  },
                  "all": {
                    "type": "boolean",
                    "description": "1 或 true 表示全部标为已读。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/module/stat/all": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "获取 LTE 业务综合统计",
        "description": "获取 LTE 业务综合统计。",
        "operationId": "get_api_module_stat_all",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "queue": {
                      "pending": 0,
                      "size": 0,
                      "cur_num": ""
                    },
                    "records": {
                      "c4g": 1,
                      "tel": 0,
                      "sms_s": 2,
                      "sms_r": 3,
                      "total": 6,
                      "max": 30
                    },
                    "sms": {
                      "queue_size": 0,
                      "has_cur": false
                    },
                    "inbox": {
                      "cnt": 3,
                      "max": 30,
                      "unread": 1
                    },
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/record/stat": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "获取四类记录数量",
        "description": "获取四类记录数量。",
        "operationId": "get_api_module_record_stat",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "c4g": 1,
                    "tel": 0,
                    "sms_s": 2,
                    "sms_r": 3,
                    "total": 6,
                    "max": 30
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/record/rate": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "获取单类成功率",
        "description": "获取单类成功率。",
        "operationId": "get_api_module_record_rate",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "ok": 9,
                    "err": 1,
                    "total": 10,
                    "rate": 90
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "记录类型：1=4G电话，2=固话，3=发送短信，4=接收短信。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "enum": [
                1,
                2,
                3,
                4
              ]
            }
          }
        ]
      }
    },
    "/api/module/record/list": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "分页获取单类记录",
        "description": "分页获取单类记录。 短信 cnt 在列表中最多是 60 字节预览。",
        "operationId": "get_api_module_record_list",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cnt": 1,
                    "total": 1,
                    "offset": 1,
                    "list": [
                      {
                        "id": 1,
                        "num": "13800138000",
                        "res": 12,
                        "dir": 0,
                        "ts": 1786579200,
                        "dur": 30,
                        "src": "A1B2C3D4E5F6",
                        "rid": 1,
                        "ref": "alarm-42"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "记录类型：1=4G电话，2=固话，3=发送短信，4=接收短信。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "enum": [
                1,
                2,
                3,
                4
              ]
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "从 1 开始的结果偏移。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "返回条数，默认 10；HTTP 层最大 15。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 15
            }
          },
          {
            "name": "src",
            "in": "query",
            "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Fa-f]{12}$"
            }
          }
        ]
      }
    },
    "/api/module/record/get": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "按号码获取最近记录",
        "description": "按号码获取最近记录。 固定返回前 10 条；当前 HTTP 不读取 limit/count/offset。",
        "operationId": "get_api_module_record_get",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cnt": 1,
                    "total": 1,
                    "offset": 1,
                    "list": [
                      {
                        "id": 1,
                        "num": "13800138000",
                        "res": 12,
                        "dir": 0,
                        "ts": 1786579200,
                        "dur": 30
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "num",
            "in": "query",
            "description": "目标号码；可恢复任务队列正式合同要求 3–13 位纯数字。",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{3,13}$"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "记录类型：1=4G电话，2=固话，3=发送短信，4=接收短信。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "enum": [
                1,
                2,
                3,
                4
              ]
            }
          },
          {
            "name": "src",
            "in": "query",
            "description": "告警任务来源标识，固定 12 位十六进制；不是鉴权凭据。",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9A-Fa-f]{12}$"
            }
          }
        ]
      }
    },
    "/api/module/record/fail": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "获取单类失败分类",
        "description": "获取单类失败分类。",
        "operationId": "get_api_module_record_fail",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "net": 1,
                    "dev": 0,
                    "remote": 2,
                    "timeout": 1,
                    "other": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "记录类型：1=4G电话，2=固话，3=发送短信，4=接收短信。",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "enum": [
                1,
                2,
                3,
                4
              ]
            }
          }
        ]
      }
    },
    "/api/module/record/report": {
      "get": {
        "tags": [
          "执行记录"
        ],
        "summary": "获取全量记录汇总",
        "description": "获取全量记录汇总。 无业务参数；返回全部记录汇总。",
        "operationId": "get_api_module_record_report",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "c4g": {
                      "ok": 9,
                      "err": 1,
                      "rate": 90,
                      "total": 10
                    },
                    "tel": {
                      "ok": 0,
                      "err": 0,
                      "rate": 0,
                      "total": 0
                    },
                    "sms_s": {
                      "ok": 2,
                      "err": 0,
                      "rate": 100,
                      "total": 2
                    },
                    "sms_r": {
                      "total": 3
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/tts/get": {
      "get": {
        "tags": [
          "TTS 发音词典"
        ],
        "summary": "获取 TTS 多音字词典",
        "description": "获取 TTS 多音字词典。",
        "operationId": "get_api_module_tts_get",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "default_dict": {
                      "重庆": "重 qing"
                    },
                    "user_dict": {},
                    "default_count": 1,
                    "user_count": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/tts/set": {
      "post": {
        "tags": [
          "TTS 发音词典"
        ],
        "summary": "新增或覆盖用户 TTS 词条",
        "description": "新增或覆盖用户 TTS 词条。 当前没有条目数或长度上限；文本含引号/反斜杠时受 JSON 拼接缺陷影响。",
        "operationId": "post_api_module_tts_set",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "updated": true,
                    "user_count": 1
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string",
                    "minLength": 1,
                    "description": "要匹配的原文，不能为空；用户词条覆盖同名默认词条。"
                  },
                  "val": {
                    "type": "string",
                    "description": "同音替换文本，字段必须存在但当前允许空值。"
                  }
                },
                "required": [
                  "key",
                  "val"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/tts/del": {
      "post": {
        "tags": [
          "TTS 发音词典"
        ],
        "summary": "删除用户 TTS 词条",
        "description": "删除用户 TTS 词条。",
        "operationId": "post_api_module_tts_del",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "deleted": true,
                    "user_count": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string",
                    "minLength": 1,
                    "description": "要删除的用户词条原文；不能删除内置默认词典。"
                  }
                },
                "required": [
                  "key"
                ]
              }
            }
          }
        }
      }
    },
    "/api/module/tts/clear": {
      "post": {
        "tags": [
          "TTS 发音词典"
        ],
        "summary": "清空用户 TTS 词典",
        "description": "清空用户 TTS 词典。 无参数；只清用户词典，保留内置默认词典。",
        "operationId": "post_api_module_tts_clear",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "cleared": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/balance/info": {
      "get": {
        "tags": [
          "SIM 余额"
        ],
        "summary": "获取最近 SIM 余额结果",
        "description": "获取最近 SIM 余额结果。",
        "operationId": "get_api_module_balance_info",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "balance": 20.0,
                    "trigger": "manual",
                    "ts": 1786579200,
                    "sms_id": 15
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/balance/get": {
      "get": {
        "tags": [
          "SIM 余额"
        ],
        "summary": "获取 SIM 余额任务配置",
        "description": "获取 SIM 余额任务配置。",
        "operationId": "get_api_module_balance_get",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "enabled": 1,
                    "interval_hours": 24,
                    "threshold": 10,
                    "query_num": "10086",
                    "query_text": "CXYE",
                    "reply_num": "10086",
                    "parse_keyword": "余额",
                    "parse_end_keyword": "元",
                    "alarm_numbers": [
                      "13800138000"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/balance/set": {
      "post": {
        "tags": [
          "SIM 余额"
        ],
        "summary": "保存 SIM 余额任务配置",
        "description": "保存 SIM 余额任务配置。 至少提供一个字段；enabled=1 会建立周期网络侧短信动作，可能计费。",
        "operationId": "post_api_module_balance_set",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "enabled": 1,
                    "interval_hours": 24,
                    "threshold": 10,
                    "query_num": "10086",
                    "query_text": "CXYE",
                    "reply_num": "10086",
                    "parse_keyword": "余额",
                    "parse_end_keyword": "元",
                    "alarm_numbers": [
                      "13800138000"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "是否启用周期余额查询；true/1 启用，其他值归一为 0。启用后会周期发送运营商短信。"
                  },
                  "interval_hours": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 720,
                    "description": "自动查询周期，单位小时；保存时钳制到 1–720。"
                  },
                  "threshold": {
                    "type": "number",
                    "minimum": 0,
                    "description": "低余额告警阈值，单位元，可带小数，必须非负。"
                  },
                  "query_num": {
                    "type": "string",
                    "description": "运营商查询短信的目标号码；启用或手动查询时与 query_text 都应非空。"
                  },
                  "query_text": {
                    "type": "string",
                    "description": "发送给运营商的余额查询指令。"
                  },
                  "reply_num": {
                    "type": "string",
                    "description": "期望回复号码；空表示不限制，比较时忽略空白、横杠和 +86。"
                  },
                  "parse_keyword": {
                    "type": "string",
                    "description": "余额数值之前的关键字；空时尝试常见余额关键字，再退回首个数字。"
                  },
                  "parse_end_keyword": {
                    "type": "string",
                    "description": "余额数值之后的可选截断关键字。"
                  },
                  "alarm_numbers": {
                    "type": "string",
                    "description": "低余额告警号码列表，以逗号、分号或换行分隔；优先于 alarm_num。"
                  },
                  "alarm_num": {
                    "type": "string",
                    "description": "alarm_numbers 的单号码别名；有 alarm_numbers 时忽略。"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/module/balance/query": {
      "post": {
        "tags": [
          "SIM 余额"
        ],
        "summary": "手动发送余额查询短信",
        "description": "手动发送余额查询短信。 无参数；只表示查询短信已发出，不等待回复，也不触发低余额告警。",
        "operationId": "post_api_module_balance_query",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "querying": true,
                    "mode": "manual",
                    "trigger": "manual",
                    "target": "10086",
                    "timeout_ms": 10000,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/module/balance/test": {
      "post": {
        "tags": [
          "SIM 余额"
        ],
        "summary": "发送余额查询并测试告警",
        "description": "发送余额查询并测试告警。 无参数；余额解析成功后忽略阈值，向配置的告警号码发送测试短信。",
        "operationId": "post_api_module_balance_test",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功或异步动作已接受；仍需检查 JSON code。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonEnvelope"
                },
                "example": {
                  "code": 0,
                  "msg": "ok",
                  "data": {
                    "querying": true,
                    "mode": "test",
                    "trigger": "alarm_test",
                    "target": "10086",
                    "timeout_ms": 10000,
                    "ts": 1786579200
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "JsonEnvelope": {
        "type": "object",
        "required": [
          "code",
          "msg"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "0=成功；LTE 业务错误可为1..5；MCU错误常等于HTTP状态。"
          },
          "msg": {
            "type": "string",
            "description": "人类可读结果。程序还应读取 data.reason/data.err。"
          },
          "data": {
            "description": "端点特有数据，详见对应 Markdown 章节和响应示例."
          }
        },
        "additionalProperties": true
      },
      "HttpError": {
        "type": "object",
        "required": [
          "code",
          "msg"
        ],
        "properties": {
          "code": {
            "type": "integer"
          },
          "msg": {
            "type": "string"
          },
          "data": {}
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "BadRequest": {
        "description": "参数缺失、格式错误或当前状态不允许。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/HttpError"
            },
            "example": {
              "code": 400,
              "msg": "Invalid parameter"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "MCU↔LTE 发送、通信、上下文或普通等待失败。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/HttpError"
            },
            "example": {
              "code": 503,
              "msg": "Module communication failed"
            }
          }
        }
      }
    }
  }
}