控制台 · 设备管理
设备管理是 Web 控制台里使用频率最高的页面：接入、检索、启停、删除设备都在这里完成。这页按"打开页面 → 找到设备 → 做出变更"的顺序讲清每个操作，并说明界面动作对应到哪条 API——方便你在页面上点不动时，知道日志和接口层面到底发生了什么。
你在这里：栈已起、驱动已就绪，想在界面上管理设备而不是调 API。接入流程的完整语境（含属性含义）见设备接入流程；设备的字段与 API 语义见设备概念。
打开页面
登录后进入 设备管理（导航：设备管理）。页面由三部分组成：
- 工具栏：检索与筛选（见下）、新增、导入；
- 设备卡片列表：每台设备一张卡，卡上直接提供 启用/停用、删除；
- 分页与排序：底部分页器的每页条数默认按视口能放下几列自适应，也可以手动改；工具栏可刷新、按列排序。
找到设备：筛选与检索
工具栏提供三类过滤条件，组合生效：
| 条件 | 说明 |
|---|---|
| 设备名称 | 按名称模糊检索 |
| 驱动 | 下拉选择驱动（选项来自驱动字典，可刷新重载） |
| 启用状态 | 分段选择：全部 / 启用 / 停用 |
检索走的是管理中心的设备分页接口（POST /device/list 语义），结果按当前租户隔离——你永远看不到其他租户的设备。
新增一台设备
- 工具栏点 新增，弹出表单；
- 填写设备名称、选择驱动与模板（Profile）——这两项决定设备能承载哪些位号与指令（见模板）；
- 按驱动的属性定义补全连接配置（如 Modbus 的 host/port）：属性从哪来看属性与配置；
- 保存。新设备默认进入启用/停用状态取决于表单选择，未接入真实设备前可先停用。
创建动作对应 POST /device/add（返回新建实体含 id——见设备概念的 API 表）。
批量导入（XLSX）
工具栏的 导入 背后是一套异步流程，不是同步返回：
- 下载模板：
POST /api/v3/manager/device/export/import_template，请求体给driverId+profileId，返回按该驱动/模板定制的 XLSX（device-import-template-v1.xlsx）。模板跟驱动绑定——驱动接什么属性，模板就有什么列。 - 填表上传：
POST /api/v3/manager/device/import，multipart 两部分：request（JSON，仍是driverId+profileId）和file（XLSX，不超过 20 MB）；请求头带Idempotency-Key——同 key 同内容重传返回原操作，同 key 不同内容直接拒。 - 轮询结果：上传返回 202 加
Location（操作查询地址）。对GET /api/v3/manager/operations/get_by_id?id=<operationId>轮询，状态PENDING/RUNNING走到SUCCEEDED/FAILED，逐行校验的失败原因在result/error字段里。操作状态落dc3_operation表（见数据库结构参考）。
CLI 把这几步包成了两条命令：
| 动作 | 命令 / 接口 |
|---|---|
| 下载模板 | dc3 device import-template --driver-id <id> --profile-id <id> --output <file>；接口 POST …/device/export/import_template |
| 上传并等结果 | dc3 device import <file> --driver-id <id> --profile-id <id>（默认轮询到终态，--no-wait 只提交；--idempotency-key 可指定幂等键）；接口 POST …/device/import |
没有设备导出接口，只有模板导出。要留数据，先做位号值导出或数据库备份（见 FAQ）。
启用 / 停用 / 删除
设备卡片上直接操作：
- 停用：设备退出采集（位号不再更新），配置保留，随时可重新启用；
- 启用：恢复采集，驱动重新建立连接；
- 删除：移除设备及其关联配置，不可撤销——删除前确认位号数据是否已导出（历史位号值按保留策略独立留存，不随设备删除立即消失，但查询入口会失去设备维度）。
设备详情
点击卡片进入设备详情，五个页签：
| 页签 | 内容 |
|---|---|
| 仪表盘 | 该设备的实时状态与关键指标总览，排查"这台设备怎么样"的第一屏 |
| 关联位号 | 该设备下全部位号的清单与状态，可由此跳到位号配置 |
| 关联指令 | 该设备绑定的指令（自定义指令）清单 |
| 关联事件 | 该设备上报的事件（dc3_event 定义的外部事件）记录入口 |
| 设备数据 | 该设备位号值的查询入口（最新值/历史值），对应位号数据能力 |
详情页是排查"这台设备为什么不采数"的起点：驱动名加载失败会在页内提示（通常是驱动已离线或被删除）。
界面动作与 API 的对应
| 界面动作 | API（经网关） | 语义 |
|---|---|---|
| 检索/筛选 | POST …/device/list | 分页查询，租户隔离 |
| 新增 | POST …/device/add | 建设备，返回新建实体（含 id） |
| 编辑 | POST …/device/update | 改名称/模板/配置 |
| 启用/停用 | POST …/device/update（enableFlag） | 切换启用状态 |
| 删除 | POST …/device/delete | 删除设备 |
界面上每一步都能用 curl 复刻——鉴权与请求形态见 API 文档。
延伸阅读
- 设备接入流程 — 从选驱动到出数据的完整语境
- 设备概念 — 字段、状态机与 API 语义
- 控制台 · 位号与模板 — 定义设备的数据能力
- 数据与命令 — 设备接入后怎么查值、下命令
- 故障排查 — 设备不在线、采不到值的定位路径