{
  "openapi": "3.0.3",
  "info": {
    "title": "设备激活数据查询与删除接口",
    "version": "3.0.0",
    "description": "支持多条件模糊组合查询；Token 与日期为两个独立请求头。激活时间对应 created_at。"
  },
  "paths": {
    "/healthz": {
      "get": {
        "summary": "数据库健康检查",
        "responses": {
          "200": {"description": "数据库连接正常"},
          "503": {"description": "数据库连接异常"}
        }
      }
    },
    "/api/v1/devices/activation/search": {
      "get": {
        "summary": "组合查询设备激活数据",
        "description": "填写的条件使用 AND 组合。imei、phone_model、system_version 为包含式模糊匹配；oversea、lock_state 为精确匹配；activation_time 转换为 created_at 时间范围。至少填写一个条件。",
        "security": [{"bearerAuth": [], "dateHeader": []}],
        "parameters": [
          {"name": "imei", "in": "query", "schema": {"type": "string", "pattern": "^[0-9]+$", "minLength": 6, "maxLength": 36}, "example": "3456567801"},
          {"name": "phone_model", "in": "query", "schema": {"type": "string", "maxLength": 128}, "example": "VTL-202402"},
          {"name": "system_version", "in": "query", "schema": {"type": "string", "maxLength": 128}, "example": "15.0.0"},
          {"name": "oversea", "in": "query", "schema": {"type": "integer"}, "example": 2},
          {"name": "lock_state", "in": "query", "schema": {"type": "integer"}, "example": 1},
          {"name": "activation_time", "in": "query", "description": "支持 YYYY、YYYY-MM、YYYY-MM-DD、YYYY-MM-DD HH、YYYY-MM-DD HH:mm、YYYY-MM-DD HH:mm:ss", "schema": {"type": "string"}, "example": "2026-08-24"}
        ],
        "responses": {
          "200": {"description": "返回激活状态、数量和设备数组；无记录时 message 为未有激活数据", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SearchResponse"}}}},
          "400": {"description": "查询条件缺失或格式错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}},
          "401": {"description": "Token 或日期字段错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}},
          "500": {"description": "数据库查询失败", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}
        }
      }
    },
    "/api/v1/devices/delete-by-imei": {
      "post": {
        "summary": "按非完整 IMEI 删除所有匹配记录",
        "security": [{"bearerAuth": [], "dateHeader": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["imei"],
                "properties": {"imei": {"type": "string", "pattern": "^[0-9]+$", "minLength": 6, "maxLength": 36, "example": "3456567801"}}
              }
            }
          }
        },
        "responses": {
          "200": {"description": "删除完成，或返回未有激活数据", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeleteResponse"}}}},
          "400": {"description": "请求参数错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}},
          "401": {"description": "Token 或日期字段错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}},
          "409": {"description": "记录变化，整批操作回滚", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}},
          "500": {"description": "数据库或事务错误", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "config.env 中的基础 API_TOKEN，不拼接日期"
      },
      "dateHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Auth-Date",
        "description": "独立日期字段，格式 0102；当前值 0928"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {"error": {"type": "string"}}
      },
      "Device": {
        "type": "object",
        "properties": {
          "device_id": {"type": "string"},
          "public_pem": {"type": "string"},
          "imei": {"type": "string"},
          "phone_model": {"type": "string"},
          "system_version": {"type": "string"},
          "android_version": {"type": "string"},
          "oversea": {"type": "integer", "format": "int64"},
          "language": {"type": "string"},
          "lock_state": {"type": "integer", "format": "int64"},
          "created_at": {"type": "string", "nullable": true, "example": "2026-08-24 03:00:31"},
          "updated_at": {"type": "string", "nullable": true},
          "lock_time": {"type": "string", "nullable": true},
          "un_lock_time": {"type": "string", "nullable": true},
          "register_id": {"type": "string"},
          "app_version": {"type": "integer", "format": "int64"},
          "app_version_name": {"type": "string"},
          "app_version_flavor": {"type": "string"}
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["activated", "count", "message", "data"],
        "properties": {
          "activated": {"type": "boolean"},
          "count": {"type": "integer"},
          "message": {"type": "string"},
          "data": {"type": "array", "items": {"$ref": "#/components/schemas/Device"}}
        }
      },
      "DeleteResponse": {
        "type": "object",
        "required": ["deleted", "affected_rows", "imeis"],
        "properties": {
          "deleted": {"type": "boolean"},
          "affected_rows": {"type": "integer"},
          "imeis": {"type": "array", "items": {"type": "string"}},
          "message": {"type": "string"}
        }
      }
    }
  }
}