vent_agent_2.0/docs/postman/main-fan-file-download.postman_collection.json

{
  "info": {
    "_postman_id": "bed94f6b-a870-4530-8f66-d6794e6f3c3f",
    "name": "文件下载接口（主通风机报告资料采集）",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "description": "按当前项目 extensions/main_fan/crawler_reports.py 的实际调用整理，共 5 个接口。\n\n导入：在 Eolink 的数据导入入口选择 Postman 格式，选择此 JSON 文件。请求参数、JSON 请求体和示例响应均已写入；示例响应仅展示客户端依赖的字段，不代表线上实测结果或完整返回结构。\n\n调用顺序：01 查询矿井 → 填写同一行的 mine_name/dept_id → 02 同步资料类型 → 03 查询资料类型 → 填写 file_name_id → 04 发起采集 → 填写 task_id → 05 查询任务进度。\n\n本文件包含集合变量。若 Eolink 未自动导入集合变量，请按各请求描述在项目环境中创建同名变量，或把 {{变量名}} 替换为实际值。mine_name、dept_id、file_name_id、task_id 留空，须按前序响应填写，不能直接发送带空变量的后续请求。year、file_name_id 必须为整数，dry_run 必须为 true/false，JSON 请求体中这三个变量不带引号。\n\nbase_url 默认 http://10.244.3.155:19010；如果服务仅监听服务器回环，只能在该服务器使用 http://127.0.0.1:19010 或经已有的网络转发访问。此地址属于资料采集服务，不加 /api 前缀，也不使用 VentAgent 的 8080 端口。当前客户端未发送认证头，因此集合使用 No Auth；若实际部署增加认证，请按服务方约定配置。\n\n采集完成后文件由资料采集服务保存至 /home/chief/source_data/{mine_name}/{year}/{report_type}/。VentAgent 从只读挂载目录 /data/source_data/ 复制 PDF。当前接入代码未定义直接返回文件流的 HTTP 下载接口；不要将 /crawl/{task_id} 当作 PDF 下载地址。目录内可能含同年度往期资料，文件月份和归属需核对原文。\n\n此文件仅整理请求，未调用真实采集服务。"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "http://10.244.3.155:19010",
      "type": "string",
      "description": "资料采集服务地址，不带末尾斜杠；同机回环部署可改为 http://127.0.0.1:19010。"
    },
    {
      "key": "mine_name",
      "value": "",
      "type": "string",
      "description": "先调用查询矿井接口，从 data.mines 复制目标矿井全称，与 dept_id 必须来自同一行。"
    },
    {
      "key": "dept_id",
      "value": "",
      "type": "string",
      "description": "先调用查询矿井接口，从目标矿井行复制 dept_id，按字符串填写。"
    },
    {
      "key": "year",
      "value": "2026",
      "type": "string",
      "description": "资料年份，四位整数；必须与 period 的年份一致。"
    },
    {
      "key": "period",
      "value": "2026-10",
      "type": "string",
      "description": "采集月份，格式 YYYY-MM；示例值请按实际需要修改。"
    },
    {
      "key": "doc_type_keyword",
      "value": "通风机",
      "type": "string",
      "description": "查询资料类型时的名称筛选词。"
    },
    {
      "key": "report_type",
      "value": "通风机性能测定报告",
      "type": "string",
      "description": "需要的资料类型全称，用于在 data.items 中核对 level3。"
    },
    {
      "key": "file_name_id",
      "value": "",
      "type": "string",
      "description": "从资料类型查询响应中，复制 level3 等于 report_type 的唯一一行的 file_name_id；填整数，不带引号。"
    },
    {
      "key": "task_id",
      "value": "",
      "type": "string",
      "description": "从发起采集响应的 data.task_id 复制，供查询任务进度使用。"
    },
    {
      "key": "dry_run",
      "value": "false",
      "type": "string",
      "description": "false 表示实际采集；作为 JSON 布尔值使用，不带引号。"
    }
  ],
  "auth": {
    "type": "noauth"
  },
  "item": [
    {
      "name": "01 查询矿井列表",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/mines?with_tree=0",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "mines"
          ],
          "query": [
            {
              "key": "with_tree",
              "value": "0",
              "description": "按当前客户端传 0。"
            }
          ]
        },
        "description": "第一步。返回 data.mines 数组。选定目标矿井，将同一行的 mine_name（全称）与 dept_id 写入环境变量，后续请求必须使用这对值。当前调用只依赖 data.mines，不依赖部门树字段。",
        "auth": {
          "type": "noauth"
        }
      },
      "response": [
        {
          "name": "响应结构示意（非实测，字段以实际服务为准）",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{base_url}}/mines?with_tree=0",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "mines"
              ],
              "query": [
                {
                  "key": "with_tree",
                  "value": "0",
                  "description": "按当前客户端传 0。"
                }
              ]
            },
            "description": "第一步。返回 data.mines 数组。选定目标矿井，将同一行的 mine_name（全称）与 dept_id 写入环境变量，后续请求必须使用这对值。当前调用只依赖 data.mines，不依赖部门树字段。",
            "auth": {
              "type": "noauth"
            }
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "cookie": [],
          "body": "{\n  \"data\": {\n    \"mines\": [\n      {\n        \"mine_name\": \"<实际矿井全称>\",\n        \"dept_id\": \"<实际部门编号>\"\n      }\n    ]\n  }\n}"
        }
      ]
    },
    {
      "name": "02 同步目标矿井资料类型",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "Content-Type",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/doc-types/sync",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "doc-types",
            "sync"
          ]
        },
        "description": "先填写 mine_name、dept_id、year。请求体为 JSON；year 为整数，dept_id 为字符串。用于同步本矿本年度的资料类型，成功后再查询资料类型列表。HTTP 409 表示同步仍在运行，稍后重试；不能当作同步完成。",
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"mine_name\": \"{{mine_name}}\",\n  \"dept_id\": \"{{dept_id}}\",\n  \"year\": {{year}}\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": []
    },
    {
      "name": "03 查询报告资料类型",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/doc-types?mine={{mine_name}}&year={{year}}&name={{doc_type_keyword}}",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "doc-types"
          ],
          "query": [
            {
              "key": "mine",
              "value": "{{mine_name}}",
              "description": "与第一步同一行的矿井全称。"
            },
            {
              "key": "year",
              "value": "{{year}}",
              "description": "四位年份，与 period 一致。"
            },
            {
              "key": "name",
              "value": "{{doc_type_keyword}}",
              "description": "名称筛选词，默认通风机。"
            }
          ]
        },
        "description": "mine 为矿井全称，不是 dept_id。year 与后续采集月份一致，name 为资料类型名称筛选词（默认通风机）。从 data.items 中查找 level3 与 {{report_type}} 完全相等的唯一一行，把该行 file_name_id 填入同名变量。类型编号按矿井和年份动态查询，不沿用其他矿的示例编号。",
        "auth": {
          "type": "noauth"
        }
      },
      "response": [
        {
          "name": "响应结构示意（非实测，字段以实际服务为准）",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{base_url}}/doc-types?mine={{mine_name}}&year={{year}}&name={{doc_type_keyword}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "doc-types"
              ],
              "query": [
                {
                  "key": "mine",
                  "value": "{{mine_name}}",
                  "description": "与第一步同一行的矿井全称。"
                },
                {
                  "key": "year",
                  "value": "{{year}}",
                  "description": "四位年份，与 period 一致。"
                },
                {
                  "key": "name",
                  "value": "{{doc_type_keyword}}",
                  "description": "名称筛选词，默认通风机。"
                }
              ]
            },
            "description": "mine 为矿井全称，不是 dept_id。year 与后续采集月份一致，name 为资料类型名称筛选词（默认通风机）。从 data.items 中查找 level3 与 {{report_type}} 完全相等的唯一一行，把该行 file_name_id 填入同名变量。类型编号按矿井和年份动态查询，不沿用其他矿的示例编号。",
            "auth": {
              "type": "noauth"
            }
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "cookie": [],
          "body": "{\n  \"data\": {\n    \"items\": [\n      {\n        \"level3\": \"通风机性能测定报告\",\n        \"file_name_id\": \"<实际整数类型编号>\"\n      }\n    ]\n  }\n}"
        }
      ]
    },
    {
      "name": "04 发起报告采集与文件下载任务",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "Content-Type",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/crawl",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "crawl"
          ]
        },
        "description": "填写 mine_name、dept_id、year、file_name_id、period。每次提交一个矿、一种资料类型、一个月份。file_name_ids 是整数数组；当前流程传一个动态取得的编号。period 格式为 YYYY-MM，year 与 period 的年份必须一致。dry_run=false 为实际采集。成功响应的 data.task_id 填入 task_id 变量，再查询进度。HTTP 409 表示服务忙；当前接入不假定 409 一定返回任务编号，等待后仅重试相同参数。该接口返回任务信息，文件由服务端后台保存。",
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"mine_name\": \"{{mine_name}}\",\n  \"dept_id\": \"{{dept_id}}\",\n  \"year\": {{year}},\n  \"file_name_ids\": [{{file_name_id}}],\n  \"period\": \"{{period}}\",\n  \"dry_run\": {{dry_run}}\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [
        {
          "name": "响应结构示意（非实测，字段以实际服务为准）",
          "originalRequest": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{base_url}}/crawl",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "crawl"
              ]
            },
            "description": "填写 mine_name、dept_id、year、file_name_id、period。每次提交一个矿、一种资料类型、一个月份。file_name_ids 是整数数组；当前流程传一个动态取得的编号。period 格式为 YYYY-MM，year 与 period 的年份必须一致。dry_run=false 为实际采集。成功响应的 data.task_id 填入 task_id 变量，再查询进度。HTTP 409 表示服务忙；当前接入不假定 409 一定返回任务编号，等待后仅重试相同参数。该接口返回任务信息，文件由服务端后台保存。",
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"mine_name\": \"{{mine_name}}\",\n  \"dept_id\": \"{{dept_id}}\",\n  \"year\": {{year}},\n  \"file_name_ids\": [{{file_name_id}}],\n  \"period\": \"{{period}}\",\n  \"dry_run\": {{dry_run}}\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "cookie": [],
          "body": "{\n  \"data\": {\n    \"task_id\": \"<实际任务编号>\"\n  }\n}"
        }
      ]
    },
    {
      "name": "05 查询采集任务进度",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{base_url}}/crawl/{{task_id}}",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "crawl",
            "{{task_id}}"
          ]
        },
        "description": "task_id 来自第 04 步成功响应。读取 data.status：queued/pending/running 为等待或执行中，按项目默认约 3 秒间隔继续查询；done 为完成；partial/failed 为终态失败，不能当作完整资料采集成功。项目默认等待上限 900 秒。完成后原件位于服务端 /home/chief/source_data/{{mine_name}}/{{year}}/{{report_type}}/；此接口返回 JSON 状态，不返回文件二进制。",
        "auth": {
          "type": "noauth"
        }
      },
      "response": [
        {
          "name": "响应结构示意（非实测，字段以实际服务为准）",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{base_url}}/crawl/{{task_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "crawl",
                "{{task_id}}"
              ]
            },
            "description": "task_id 来自第 04 步成功响应。读取 data.status：queued/pending/running 为等待或执行中，按项目默认约 3 秒间隔继续查询；done 为完成；partial/failed 为终态失败，不能当作完整资料采集成功。项目默认等待上限 900 秒。完成后原件位于服务端 /home/chief/source_data/{{mine_name}}/{{year}}/{{report_type}}/；此接口返回 JSON 状态，不返回文件二进制。",
            "auth": {
              "type": "noauth"
            }
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "cookie": [],
          "body": "{\n  \"data\": {\n    \"status\": \"done\"\n  }\n}"
        }
      ]
    }
  ]
}