# 洲明智能大屏设计与走线控制器 API (Unilumin Smart GTM LED Tool APIs)
> 版本: v2.4.0 | 更新时间: 2026-08-22
> 生产环境 Base URL: `https://unilumin-gtm.com`
> 本地开发 Base URL: `http://127.0.0.1:8080`

## 1. 核心系统物理约束与行业算法规范（必读）

### 1.1 2D 箱体排列坐标系规范
- **原点 (0, 0)**: 位于屏幕**左下角 (Bottom-Left)**；
- **X 轴**: 向**右**递增 (单位: mm)；
- **Y 轴**: 向**上**递增 (单位: mm，`y=0` 对应屏幕最底部箱体)；
- 传入 `custom_arrangement` 时，系统将严格 100% 按照传入的每个箱体 `(x, y, width, height)` 坐标进行拓扑走线、过箱线扣减与出图。

### 1.2 动态网口带宽带载计算公式 (千兆以太网口基准有效带宽 936 Mbps，60Hz 8bit 基准 650,000 像素)
$$\text{单网口最大带载像素} = \left\lfloor \frac{936{,}000{,}000}{\text{bpp} \times \text{FrameRate}} \right\rfloor$$

| 刷新率 (`refresh_rate`) | 色深 (`bit_depth`) | HDR (`hdr`) | 像素位数 (bpp) | 单网口带载上限 | 业务场景说明 |
| :--- | :--- | :--- | :---: | :---: | :--- |
| **60Hz** (默认) | **8bit** (默认) | **false** (默认) | 24 | **650,000 px** | 标准常规视频带载（向下兼容） |
| **120Hz** | 8bit | false | 24 | **325,000 px** | 高刷视频，单口带载减半 |
| **60Hz** | 10bit | false / true | 32 | **487,500 px** | 10bit 高色深或开启 HDR |
| **120Hz** | 10bit | false / true | 32 | **243,750 px** | 120Hz 10bit 高刷高动态 |
| **60Hz** | 12bit | false | 48 | **325,000 px** | 12bit 专业广播级色深 |
| **120Hz** | 12bit | false | 48 | **162,500 px** | 120Hz 12bit 极限带载 |

> 💡 **容错与默认机制**：`refresh_rate`, `bit_depth`, `hdr` 均为可选参数。未传时自动采用 `60Hz + 8bit + SDR`（650,000 像素），绝不会报错。若开启 `hdr=true` 但传了 `bit_depth=8`，系统会自动升级按 10bit（bpp=32）带载折算。

---

## 核心设计与走线 API (Core APIs)
针对 LED 大屏的发送卡选型计算、电源进线计算与信号电源全流程生成。

### `POST /api/calculate_sending_card` - 发送卡选型与信号走线计算
输入屏幕尺寸、分辨率与箱体信息，自动分配信号走线网口回路、匹配最优发送卡/拼控机箱及板卡组合，并返回 Top-3 候选推荐方案与线缆 BOM。

#### 请求参数 (Request Body JSON):
| 字段名 | 类型 | 必填 | 默认值 | 说明与取值范围 |
|---|---|:---:|:---:|---|
| `screen_width` | `number` | ✅ | - | 屏幕物理总宽度 (mm)，必须 > 0 |
| `screen_height` | `number` | ✅ | - | 屏幕物理总高度 (mm)，必须 > 0 |
| `resolution_width` | `integer` | ✅ | - | 屏幕水平像素点数，必须 > 0 |
| `resolution_height` | `integer` | ✅ | - | 屏幕垂直像素点数，必须 > 0 |
| `box_info` | `object` | ✅ | - | 箱体规格对象，包含 widths, heights, counts 三个等长数组 |
| `custom_arrangement` | `Array<object> | string` | 否 | - | 前端精确箱体 2D 排布坐标列表（推荐）。原点在左下角，传入后严格按此坐标走线出图。 |
| `card_type` | `string` | 否 | `sync` | 发送卡类型：sync(同步卡) 或 async(异步卡) 可选: ['sync', 'async'] |
| `card_brand` | `string` | 否 | `Unilumin` | 发送卡品牌 可选: ['Unilumin', 'Colorlight', 'Brompton'] |
| `loop_backup` | `boolean` | 否 | `False` | 是否开启环路备份（开启后网口数加倍，并启用备份编号） |
| `backup_numbering_mode` | `string` | 否 | `sequential` | 备份编号模式：sequential(顺番编号) 或 paired(成对编号) 可选: ['sequential', 'paired'] |
| `wiring_direction` | `string` | 否 | `horizontal` | 信号走线方向 可选: ['horizontal', 'vertical'] |
| `horizontal_flow_direction` | `string` | 否 | - | 水平走线流向偏好 可选: ['left_to_right', 'right_to_left', 'center_to_sides'] |
| `refresh_rate` | `string | number` | 否 | `60` | 视频刷新率 (Hz)。刷新率翻倍网口带载减半。 可选: ['60', '120'] |
| `bit_depth` | `string | number` | 否 | `8` | 视频色深比特数：8bit (常规), 10bit (高色深), 12bit (广播级) 可选: ['8', '10', '12'] |
| `hdr` | `boolean | string` | 否 | `False` | 是否开启 HDR。开启时色深强制至少按 10bit 折算带宽。 |
| `coverage_mode` | `string` | 否 | `4k` | 4K 分区模式：4k(标准3840x2160分块) 或 economic(经济模式) 可选: ['4k', 'economic'] |
| `specified_card_model` | `string` | 否 | - | 显式指定的发送卡型号（如 'H2', 'VX600PRO'），指定后强制校验并采用该型号 |
| `product_name` | `string` | 否 | `UMini5W` | 产品名称（用于自带线材扣减、走线偏好匹配及生成物料清单） |
| `required_input_requirements_json` | `Array<object> | string` | 否 | - | 复杂输入接口需求列表（H/X 系列拼控机箱） |
| `required_output_requirements_json` | `Array<object> | string` | 否 | - | 复杂输出接口需求列表（H/X 系列拼控机箱） |
| `generate_image` | `boolean` | 否 | `False` | 是否在服务端生成并返回信号走线图 PNG 访问地址 |
| `language` | `string` | 否 | `zh` | 返回文本语言 可选: ['zh', 'en'] |
| `region` | `string` | 否 | `distributor` | 业务区域（distributor/general/UK/SS），影响推荐白名单 |

#### 请求示例 (JSON):
```json
{
  "screen_width": 3000.0,
  "screen_height": 1687.5,
  "resolution_width": 2400,
  "resolution_height": 1350,
  "card_type": "sync",
  "card_brand": "Unilumin",
  "loop_backup": false,
  "backup_numbering_mode": "sequential",
  "wiring_direction": "horizontal",
  "refresh_rate": "60",
  "bit_depth": "8",
  "hdr": false,
  "coverage_mode": "4k",
  "specified_card_model": null,
  "product_name": "UMini5W",
  "required_input_requirements_json": [
    {
      "interface": "hdmi_2_0",
      "count": 2
    }
  ],
  "required_output_requirements_json": [
    {
      "interface": "rj45",
      "count": 16
    }
  ],
  "generate_image": false,
  "language": "zh",
  "region": "distributor"
}
```

#### 响应示例 (JSON):
```json
{
  "success": true,
  "card_found": true,
  "total_pixels": 3240000,
  "total_ports_needed": 5,
  "total_cables_needed": 5,
  "total_pass_through_cables": 20,
  "card_info": {
    "model": "VX600PRO",
    "ports": 6,
    "total_capacity": 3900000,
    "port_capacity": 650000,
    "usage_rate": "83.08%",
    "required_cards": 1,
    "brand": "Unilumin",
    "card_type": "sync"
  },
  "wiring_diagram_url": "/user_data/images/output_signal_screen_1.png"
}
```

---

### `POST /api/calculate_power_wiring` - 纯电源走线图与进线回路计算
输入屏幕尺寸、总功率、实际电流与电压，自动计算电源回路进线数、过箱电源线数、生成进线方向元数据与电源走线图。

#### 请求参数 (Request Body JSON):
| 字段名 | 类型 | 必填 | 默认值 | 说明与取值范围 |
|---|---|:---:|:---:|---|
| `product_name` | `string` | 否 | `UMini5W` | 产品名称（用于加载专用电源拓扑） |
| `screen_width` | `number` | ✅ | - | 屏幕物理总宽度 (mm) |
| `screen_height` | `number` | ✅ | - | 屏幕物理总高度 (mm) |
| `resolution_width` | `integer` | ✅ | - | 水平分辨率 (px) |
| `resolution_height` | `integer` | ✅ | - | 垂直分辨率 (px) |
| `box_info` | `object` | ✅ | - | 箱体规格信息 |
| `total_power` | `number` | ✅ | - | 屏幕总功率 (W) |
| `actual_current` | `number` | ✅ | - | 实际电流 (A) |
| `voltage` | `number` | ✅ | - | 供电电压 (V) |
| `power_wiring_flow_direction` | `string` | 否 | `bottom_to_top` | 电源走线流向（下进线/上进线） 可选: ['bottom_to_top', 'top_to_bottom'] |
| `product_certification` | `string` | 否 | - | 产品/箱体认证（如 'CE' 触发禁用 T 型线） |

#### 请求示例 (JSON):
```json
{
  "product_name": "UMini5W",
  "screen_width": 3000.0,
  "screen_height": 1687.5,
  "resolution_width": 2400,
  "resolution_height": 1350,
  "total_power": 2100.0,
  "actual_current": 14.0,
  "voltage": 220.0,
  "power_wiring_flow_direction": "bottom_to_top"
}
```

#### 响应示例 (JSON):
```json
{
  "success": true,
  "power_lines_count": 2,
  "power_pass_through_cables": 14,
  "power_direction_meta": {
    "entry_axis": "horizontal",
    "entry_side": "right",
    "labels": {
      "entry_side_zh": "右进线",
      "flow_entry_zh": "下进线"
    }
  },
  "power_stat_cards": [
    {
      "label": "电源进线数",
      "value": 2
    },
    {
      "label": "左右过箱线",
      "value": 14
    },
    {
      "label": "上下过箱线",
      "value": 0
    }
  ],
  "power_diagram_url": "/user_data/images/output_power_wiring_screen_1.png"
}
```

---

## CPQ 对外集成 API (CPQ APIs)
专为 CPQ / ERP / CRM 报价系统设计的解耦式信号走线图、发送卡选型与配置字典接口。

### `POST /api/cpq/signal_diagram` - CPQ 纯信号走线图生成 (无需发送卡)
轻量级纯信号走线接口，不依赖发送卡选型库，快速返回网线数量、过箱线与 PNG 走线图。

#### 请求参数 (Request Body JSON):
| 字段名 | 类型 | 必填 | 默认值 | 说明与取值范围 |
|---|---|:---:|:---:|---|
| `screen_width` | `number` | ✅ | - | 屏幕宽度 (mm) |
| `screen_height` | `number` | ✅ | - | 屏幕高度 (mm) |
| `resolution_width` | `integer` | ✅ | - | 水平分辨率 (px) |
| `resolution_height` | `integer` | ✅ | - | 垂直分辨率 (px) |
| `box_info` | `object` | ✅ | - | 箱体规格对象 |
| `custom_arrangement` | `Array<object> | string` | 否 | - | 精确箱体 2D 排布坐标列表 |
| `wiring_direction` | `string` | 否 | `horizontal` | 信号走线方向 可选: ['horizontal', 'vertical'] |
| `loop_backup` | `boolean` | 否 | `False` | 是否开启环路备份 |
| `refresh_rate` | `string | number` | 否 | `60` | 视频刷新率 (Hz) 可选: ['60', '120'] |
| `bit_depth` | `string | number` | 否 | `8` | 视频色深比特数 可选: ['8', '10', '12'] |
| `hdr` | `boolean | string` | 否 | `False` | 是否开启 HDR |
| `product_name` | `string` | 否 | - | 产品名称 |
| `language` | `string` | 否 | `zh` | 语言 可选: ['zh', 'en'] |

#### 请求示例 (JSON):
```json
{
  "screen_width": 2439.68,
  "screen_height": 1372.32,
  "resolution_width": 1920,
  "resolution_height": 1080,
  "wiring_direction": "horizontal",
  "loop_backup": false,
  "refresh_rate": "60",
  "bit_depth": "8",
  "hdr": false,
  "language": "zh"
}
```

#### 响应示例 (JSON):
```json
{
  "success": true,
  "total_pixels": 2073600,
  "total_ports_needed": 4,
  "total_cables_needed": 4,
  "total_pass_through_cables": 12,
  "horizontal_pass_through": 8,
  "vertical_pass_through": 4,
  "wiring_diagram_url": "/user_data/images/output_signal_screen_1.png"
}
```

---

### `POST /api/cpq/calculate_sending_card` - CPQ 发送卡选型计算与板卡清单
专为报价系统设计的发送卡推荐接口，返回主控机箱与输入/输出/选配板卡的结构化清单 (cardList) 及 Top-3 方案。

#### 请求参数 (Request Body JSON):
| 字段名 | 类型 | 必填 | 默认值 | 说明与取值范围 |
|---|---|:---:|:---:|---|
| `screen_width` | `number` | ✅ | - | 屏幕宽度 (mm) |
| `screen_height` | `number` | ✅ | - | 屏幕高度 (mm) |
| `resolution_width` | `integer` | ✅ | - | 水平分辨率 (px) |
| `resolution_height` | `integer` | ✅ | - | 垂直分辨率 (px) |
| `box_info` | `object` | ✅ | - | 箱体规格对象 |
| `card_type` | `string` | 否 | `sync` | 发送卡类型 可选: ['sync', 'async'] |
| `card_brand` | `string` | 否 | `Nova` | CPQ 控制器品牌 可选: ['Nova', 'Colorlight', 'Brompton'] |
| `plug_standard` | `string` | 否 | - | 插头制式 可选: ['国标', '美标', '欧标', '英标'] |
| `refresh_rate` | `string | number` | 否 | `60` | 视频刷新率 (Hz) |
| `bit_depth` | `string | number` | 否 | `8` | 视频色彩比特数 |
| `hdr` | `boolean` | 否 | `False` | 是否开启 HDR |
| `multi_screen_configs` | `Array<object>` | 否 | - | 多屏幕模式配置列表 |

#### 请求示例 (JSON):
```json
{
  "screen_width": 3840.0,
  "screen_height": 2160.0,
  "resolution_width": 1920,
  "resolution_height": 1080,
  "card_type": "sync",
  "card_brand": "Nova",
  "refresh_rate": "60",
  "bit_depth": "8",
  "hdr": false
}
```

#### 响应示例 (JSON):
```json
{
  "success": true,
  "card_found": true,
  "card_info": {
    "model": "H2",
    "code": "SPJX0034",
    "brand": "Nova",
    "parsed": {
      "mainController": {
        "name": "H2",
        "quantity": 1
      },
      "cardList": [
        {
          "type": "mainController",
          "typeDisplay": "主控制器",
          "model": "H2",
          "quantity": 1,
          "code": "SPJX0034"
        },
        {
          "type": "inputCard",
          "typeDisplay": "输入板卡",
          "model": "H_1xHDMI2.0+1xDP1.2 input card",
          "quantity": 1,
          "code": "SPBK0047"
        },
        {
          "type": "outputCard",
          "typeDisplay": "输出板卡",
          "model": "H_16xNetwork port + 2xOptical port sending card",
          "quantity": 1,
          "code": "SPBK0057"
        }
      ]
    }
  },
  "recommendations": [
    {
      "rank": 1,
      "model": "H2",
      "usage_rate": "42.50%"
    },
    {
      "rank": 2,
      "model": "VX1000PRO",
      "usage_rate": "61.20%"
    }
  ]
}
```

---

### `GET /api/cpq/brands` - 获取 CPQ 可用发送卡品牌列表
查询当前系统支持的发送卡品牌清单。

#### 响应示例 (JSON):
```json
{
  "success": true,
  "brands": [
    "Nova",
    "Colorlight",
    "Brompton",
    "Unilumin"
  ]
}
```

---

### `GET /api/cpq/available_cards` - 查询可用发送卡库清单
支持按品牌、区域、同步/异步筛选发送卡库。

#### 查询参数 (Query Parameters):
| 参数名 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `brand` | `string` | 否 | 品牌名称筛选 (如 'Nova') |
| `region` | `string` | 否 | 区域筛选 (如 'global', 'china_mainland') |
| `card_type` | `string` | 否 | 类型筛选 ('sync' / 'async') |

#### 响应示例 (JSON):
```json
{
  "success": true,
  "cards": [
    {
      "model": "VX400PRO",
      "brand": "Nova",
      "ports": 4,
      "total_capacity": 2600000
    },
    {
      "model": "VX600PRO",
      "brand": "Nova",
      "ports": 6,
      "total_capacity": 3900000
    },
    {
      "model": "VX1000PRO",
      "brand": "Nova",
      "ports": 10,
      "total_capacity": 6500000
    }
  ]
}
```

---

### `POST /run_signal_wiring` - 全功能信号与电源联合走线及 CAD/PDF 全套图纸生成 (All-in-One)
系统核心计算引擎接口。一次性完成信号走线回路、电源进线与过箱线计算、4K分块拼控、控制器选型，并联合生成全套高清走线图 (images)、AutoCAD DXF 矢量工程图纸 (cad_files) 与工程级矢量 PDF 打印图纸 (cad_pdf_files)。

#### 请求参数 (Request Body JSON):
| 字段名 | 类型 | 必填 | 默认值 | 说明与取值范围 |
|---|---|:---:|:---:|---|
| `screen_widths` | `number | string` | ✅ | - | 屏幕物理总宽度 (mm) |
| `screen_heights` | `number | string` | ✅ | - | 屏幕物理总高度 (mm) |
| `resolution_widths` | `integer | string` | ✅ | - | 水平分辨率 (px) |
| `resolution_heights` | `integer | string` | ✅ | - | 垂直分辨率 (px) |
| `box_widths` | `number | string` | ✅ | - | 箱体物理宽度 (mm) |
| `box_heights` | `number | string` | ✅ | - | 箱体物理高度 (mm) |
| `box_counts` | `integer | string` | ✅ | - | 箱体数量 |
| `total_powers` | `number | string` | 否 | `2000` | 屏幕总功率 (W) |
| `actual_currents` | `number | string` | 否 | `15` | 实际工作电流 (A) |
| `voltages` | `number | string` | 否 | `220` | 供电电压 (V) |
| `generate_image` | `string` | 否 | `true` | 是否生成走线图与 CAD 图纸 ('true'/'false') |
| `generate_cad` | `string` | 否 | `true` | 是否生成 AutoCAD DXF 与矢量 PDF 图纸 ('true'/'false') |
| `card_brand` | `string` | 否 | `Unilumin` | 发送卡品牌 ('Unilumin', 'Colorlight', 'Brompton') |
| `refresh_rates` | `string` | 否 | `60` | 刷新率 ('60'/'120') |
| `bit_depths` | `string` | 否 | `8` | 色深 ('8'/'10'/'12') |
| `wiring_directions` | `string` | 否 | `horizontal` | 走线方向 ('horizontal'/'vertical') |

#### 请求示例 (JSON):
```json
{
  "screen_widths": 3840,
  "screen_heights": 2160,
  "resolution_widths": 1920,
  "resolution_heights": 1080,
  "box_widths": 480,
  "box_heights": 270,
  "box_counts": 64,
  "total_powers": 2000,
  "actual_currents": 15,
  "voltages": 220,
  "generate_image": "true",
  "generate_cad": "true",
  "card_brand": "Unilumin",
  "refresh_rates": "60",
  "bit_depths": "8",
  "wiring_directions": "horizontal"
}
```

#### 响应示例 (JSON):
```json
{
  "success": true,
  "images": [
    "/user_data/{user_id}/images/output_signal_wiring_screen_1.png",
    "/user_data/{user_id}/images/output_power_wiring_screen_1.png"
  ],
  "cad_files": [
    "/user_data/{user_id}/cad/output_signal_wiring_screen_1.dxf",
    "/user_data/{user_id}/cad/output_power_wiring_screen_1.dxf",
    "/user_data/{user_id}/cad/output_combined_wiring_screen_1.dxf"
  ],
  "cad_pdf_files": [
    "/user_data/{user_id}/cad/output_signal_wiring_screen_1.pdf",
    "/user_data/{user_id}/cad/output_power_wiring_screen_1.pdf",
    "/user_data/{user_id}/cad/output_combined_wiring_screen_1.pdf"
  ],
  "artifacts": {
    "cad": {
      "combined": [
        "/user_data/{user_id}/cad/output_combined_wiring_screen_1.dxf"
      ],
      "power": [
        "/user_data/{user_id}/cad/output_power_wiring_screen_1.dxf"
      ],
      "signal": [
        "/user_data/{user_id}/cad/output_signal_wiring_screen_1.dxf"
      ]
    },
    "images": {
      "signal": [
        "/user_data/{user_id}/images/output_signal_wiring_screen_1.png"
      ],
      "power": [
        "/user_data/{user_id}/images/output_power_wiring_screen_1.png"
      ]
    },
    "pdf": {
      "combined": [
        "/user_data/{user_id}/cad/output_combined_wiring_screen_1.pdf"
      ],
      "power": [
        "/user_data/{user_id}/cad/output_power_wiring_screen_1.pdf"
      ],
      "signal": [
        "/user_data/{user_id}/cad/output_signal_wiring_screen_1.pdf"
      ]
    }
  },
  "card_info": {
    "model": "VX600PRO",
    "ports": 6,
    "usage_rate": "53.17%"
  }
}
```

---

### `GET /api/cpq/plug_standards` - 查询支持的电源插头标准
获取可选的电源线插头规格列表（如国标、美标、欧标、英标）。

#### 响应示例 (JSON):
```json
{
  "success": true,
  "plug_standards": [
    "国标",
    "美标",
    "欧标",
    "英标"
  ]
}
```

---