From 998e0badf80c066a52a525c04e9171d9bfe72d84 Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Thu, 30 Apr 2026 17:45:31 +0800
Subject: [PATCH] Add device assignment board design spec

---
 ...26-04-30-device-assignment-board-design.md | 271 ++++++++++++++++++
 1 file changed, 271 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-30-device-assignment-board-design.md

diff --git a/docs/superpowers/specs/2026-04-30-device-assignment-board-design.md b/docs/superpowers/specs/2026-04-30-device-assignment-board-design.md
new file mode 100644
index 0000000..9095d5d
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-30-device-assignment-board-design.md
@@ -0,0 +1,271 @@
+# 设备分配看板设计
+
+日期：2026-04-30
+
+## 背景
+
+当前“设备分配”页面延续了传统的“列表 + 详情表单”结构，但这类结构不适合当前业务目标。
+
+对设备分配来说，用户最关心的不是单条分配记录的编辑细节，而是整体分配态势：
+
+- 一共有多少识别单元
+- 一共有多少设备
+- 已分配多少识别单元
+- 还有多少识别单元未分配
+- 每台设备分配了多少识别单元
+- 哪些设备接近上限、已经满载、或者处于空闲
+- 在给定设备承载上限的前提下，如何快速自动平均分配
+
+因此，这个页面应从“表单页”转为“分配看板”。
+
+## 目标
+
+设备分配页需要回答四个问题：
+
+1. 当前整体分配情况如何
+2. 哪些设备负载偏高，哪些设备空闲
+3. 哪些识别单元还未分配
+4. 如何基于设备上限快速自动平均分配，并允许少量手工调整
+
+## 非目标
+
+本次不做以下内容：
+
+- 不做复杂拖拽交互
+- 不做实时设备性能采样驱动的智能调度
+- 不做按设备型号自动推算上限
+- 不修改设备最终运行配置 JSON 合同
+- 不引入新的底层部署引擎
+
+## 页面定位
+
+“设备分配”页面是一个调度和部署看板，不是传统资产详情页。
+
+它的核心职责是：
+
+- 展示识别单元与设备之间的承载关系
+- 辅助用户快速完成平均分配
+- 让未分配、超载、空闲这些问题一眼可见
+
+## 信息架构
+
+页面从上到下分为四个区域：
+
+1. 分配概览
+2. 操作区
+3. 设备分配看板
+4. 未分配识别单元
+
+## 一、分配概览
+
+页面顶部显示 6 个关键统计值：
+
+- 识别单元总数
+- 设备总数
+- 已分配识别单元
+- 未分配识别单元
+- 平均每台设备负载
+- 超载设备数
+
+说明：
+
+- “已分配识别单元”按是否被任一设备分配计算
+- “未分配识别单元”按未出现在任何设备分配中的识别单元计算
+- “平均每台设备负载”按 `已分配识别单元 / 设备总数` 计算，保留 1 位小数
+- “超载设备数”按当前页面设定的“每台设备最大单元数”判断
+
+这些统计值用于快速判断整体均衡情况。
+
+## 二、操作区
+
+操作区位于概览下方，采用一行布局，包含：
+
+- 每台设备最大单元数滑块
+- 自动平均分配
+- 清空分配
+- 保存设备分配
+
+### 每台设备最大单元数
+
+- 类型：滑块
+- 默认值：4
+- 范围：1 到 8
+- 右侧显示当前值，例如：`4 路/台`
+
+这是页面级控制参数，不直接写入设备运行配置，只影响当前页面的自动分配和负载判断。
+
+### 自动平均分配
+
+点击后执行自动分配算法：
+
+1. 收集所有识别单元
+2. 收集所有设备
+3. 清空当前页面中的暂存分配结果
+4. 按设备当前已分配数量从少到多依次分配
+5. 单台设备不超过当前滑块上限
+6. 剩余放不下的识别单元保留在“未分配识别单元”区域
+
+目标是：
+
+- 尽量平均
+- 不超过上限
+- 剩余明确可见
+
+自动分配完成后，页面显示轻量提示，例如：
+
+`已按每台最多 4 路完成自动分配，剩余 3 路未分配。`
+
+### 清空分配
+
+清空当前页面暂存的所有设备分配，不立即落库。
+
+### 保存设备分配
+
+将当前页面中的设备分配关系统一保存到数据库。
+
+## 三、设备分配看板
+
+页面主体改为卡片式设备板，而不是传统表格。
+
+每台设备显示为一张卡片，卡片内容包括：
+
+- 设备名称
+- 设备 ID
+- 当前分配数量，例如 `3 / 4`
+- 当前状态
+- 已分配的识别单元标签列表
+
+### 设备状态
+
+基于当前“每台设备最大单元数”计算：
+
+- `0`：空闲
+- `1` 到 `上限 - 1`：正常
+- `= 上限`：满载
+- `> 上限`：超载
+
+### 排序规则
+
+卡片按以下优先级排序：
+
+1. 超载
+2. 满载
+3. 正常
+4. 空闲
+
+同类内再按设备名称或设备 ID 排序。
+
+这样最需要关注的设备会优先显示。
+
+### 视觉形式
+
+每张设备卡片建议包含：
+
+- 状态标签
+- 负载数字
+- 简短负载条
+- 识别单元标签块
+
+这已经构成足够直观的图形化表达，不需要第一版引入复杂图表。
+
+## 四、未分配识别单元
+
+单独放在页面下方或右侧，作为一个明确区域。
+
+显示：
+
+- 未分配识别单元数量
+- 未分配识别单元列表
+
+若没有未分配单元，则显示：
+
+`已全部分配`
+
+这个区域用于快速暴露“还有哪些识别单元没有落到任何设备上”。
+
+## 手工调整
+
+第一版不做拖拽。
+
+手工调整采用轻量操作方式：
+
+- 在设备卡片中的识别单元标签上，支持“移出”
+- 在未分配识别单元列表中，支持“加入某设备”
+- 在设备卡片上，支持“从未分配中加入”
+
+也可以支持简单的“移动到其他设备”菜单，但不要求第一版一步到位。
+
+原则是：
+
+- 先保证清楚和稳定
+- 再考虑拖拽式优化
+
+## 数据模型要求
+
+本页使用现有底层对象，不新增新的核心存储结构：
+
+- 识别单元：`recognition_units`
+- 设备分配：`device_assignments`
+
+页面上的“每台设备最大单元数”是 UI 级暂存参数，不要求本次入库。
+
+保存时，仅保存：
+
+- 每台设备对应的识别单元列表
+- 描述信息
+
+不修改设备最终运行配置的生成合同。
+
+## 页面与详情页关系
+
+设备分配页负责整体看板和编辑。
+
+设备详情页只做状态展示：
+
+- 当前设备分配了多少识别单元
+- 当前设备对应哪个场景模板
+
+设备详情页不再承担分配编辑职责。
+
+## 错误处理
+
+需要处理这些情况：
+
+- 没有设备：页面显示空状态，并禁用自动分配/保存
+- 没有识别单元：页面显示空状态，并禁用自动分配
+- 某识别单元引用缺失：在卡片或未分配区显示异常标记
+- 保存失败：保留当前页面暂存状态，并提示错误
+
+## 测试
+
+至少覆盖以下测试：
+
+1. 统计信息正确
+2. 自动平均分配在不同设备/单元数量组合下结果正确
+3. 超载、满载、空闲状态判定正确
+4. 未分配识别单元列表正确
+5. 保存设备分配后，数据库中的 `device_assignments` 正确更新
+6. 设备详情页和预览页仍能读取保存后的分配结果
+
+## 实施建议
+
+建议按以下顺序实施：
+
+1. 后端补充分配统计与自动分配计算
+2. 改造设备分配页面为“概览 + 操作区 + 看板 + 未分配区”
+3. 接入保存逻辑
+4. 最后补样式和状态表现
+
+## 结论
+
+设备分配页应从“单条配置表单”转为“分配看板”。
+
+核心不是编辑细节，而是：
+
+- 看清楚总量
+- 看清楚负载
+- 看清楚未分配
+- 一键自动平均分配
+- 再做少量手工修正
+
+这会比当前的列表/勾选模式更符合实际使用场景，也更适合 32 路视频、多台边缘设备的部署方式。