platforms/docs/开发日志_设备分组_20260911.md

# 设备分组开发日志

操作时间：2026-09-11 16:00—17:00  
操作类型：新增、扩展  
影响模块：用户端设备、平台产品归属、远程 PostgreSQL

## 操作前状态

图08没有独立页面，图34的“设备分组”仅弹出暂未开放提示。产品档案已有本人归属和设备分类，但没有用户分组资料或归组字段。在线状态、安全检查、扫码添加和远程控制没有可用物联网接口。

## 具体操作

- 新增 `user_device_group`，保存本人分组名称、顺序和新增幂等号；为每个字段及表补充中文数据库注释。
- 为 `product_info` 增加 `device_group_id`。平台转移产品归属时自动清空旧用户分组，避免新用户继承旧分组。
- 新增本人分组列表、新建、改名、删除和设备归组接口。所有查询都从登录令牌确定用户，客户端传入其他用户标识无效。
- 删除分组时在同一事务内把组内设备移回未分组；分组新增限制20个，同名和幂等重放返回稳定错误码。
- 新增图08页面，完成新建、编辑、删除、查看组内设备及设备归组。群控、安全检查明确提示“暂未开放”。
- 图34改为真实分组卡片，并按设计稿补齐统计图标、分隔线和427像素Web手机画布；最终轮继续收紧搜索框、筛选控件和统计卡高度。

## 代码变更

- `backend/api/internal/models/user_device_group.go`：设备分组模型。
- `backend/api/internal/models/product_info.go`：产品归组字段。
- `backend/api/internal/logic/client/user/device_groups.go`：分组与设备归组业务。
- `backend/api/internal/routers/client.go`：五条分组相关路由。
- `backend/api/cmd/cli/device_group_migration.go`：独立可重复远程迁移。
- `apps/user_app/lib/ui/features/profile/device_groups_page.dart`：图08页面。
- `apps/user_app/lib/ui/features/profile/devices_page.dart`：图34分组布局。
- `apps/user_app/lib/domain/models/device_group.dart`、`data/repositories/client_repository.dart`：分组模型与接口适配。
- `apps/user_app/lib/app/app.dart`、`app/router.dart`：427像素Web预览画布和页面路由。

## 操作后状态

用户可创建、改名和删除本人分组，并把本人启用的智能阀或报警器移入或移出分组。删除分组后设备自动回到未分组。页面不展示虚构在线、离线、安全或控制结果。

## 验证结果

- 远程迁移 `migrate-device-groups` 成功，未启动本机 PostgreSQL、Redis 或 Docker。
- `go test ./...`、`go vet ./...` 和API构建全量通过；新增输入边界、本人隔离、响应白名单和路由检查。
- Flutter `analyze` 无问题；设备与分组9项定向测试通过，320/390/430宽度及1.3倍文字无溢出；全量159项Flutter测试通过。
- Web Release 使用浏览器API地址构建成功。
- 内置浏览器真实完成：创建“厨房”→测试设备归组→改名“厨房组”→删除→设备回到未分组。测试分组已删除，测试设备已恢复停用，最终为0设备、0分组。
- 视觉证据：`视觉验收/08-设备分组_并排对照_20260911.jpg`、`视觉验收/34-我的设备_并排对照_20260911.jpg`。

## 风险评估

遥测、安全检查、扫码添加和远程控制仍缺服务端及厂商能力，页面明确显示暂未开放。源图是5台设备和3个分组，当前远程测试结束后为空状态，无法进行同内容像素验收，因此图08、34仍为视觉验收阻塞状态。