docs: 记录设备能力迁移排错 (#92)

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: 3523b7cd1f126ebc3ef77414cb6d658103f2491d
-synchronized_at: 2026-08-15T01:13:11Z
+wiki_revision: a169b2323323d9de6304e9b430ddbe9888ea1d25
+synchronized_at: 2026-08-15T07:16:25Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -116,3 +116,21 @@ synchronized_at: 2026-08-15T01:13:11Z
 | viewer 看得到页面但不能保存 | 符合只读权限；由 implementation_operator、site_admin 或 admin 完成配置。 |
 | 键盘无法操作顶点 | Tab 聚焦画布或编号顶点；Enter/Space 添加中心点，方向键移动，Delete/Backspace 删除。检查浏览器焦点轮廓是否可见。 |
 <!-- sense-area:end -->
+
+<!-- sense-capabilities-jsonb:start -->
+## Sense 旧设备能力字段迁移排错
+
+启动迁移出现 `字段 "capabilities" 的默认值不能转换成类型 jsonb (SQLSTATE 42804)`，表示数据库仍保留旧版 `sense_devices.capabilities text DEFAULT ''`，而当前 GoAdmin 派生模型要求 JSONB。不要跳过迁移、删除设备记录或只手工删除默认值；旧单值数据仍可能在下一步转换失败。
+
+工单 #92 的兼容迁移会在同一事务内锁定设备表并先验证全部旧值：空值转为 `[]`，`video`、`radar`、`contact`、`button`、`wearable`、`other` 等旧单值转为 JSON 数组，合法 JSON 数组保持数组。未知值或非数组 JSON 会拒绝迁移并整体回滚，不输出具体业务值。
+
+处理步骤：
+
+1. 停止所有连接该 Sense 数据库的服务实例。
+2. 使用 `backup-sense.bat` 创建 PostgreSQL custom-format 备份，并确认备份文件可读取。
+3. 部署包含 #92 的新 `sense.exe` 后重新运行 `migrate-sense.bat` 或正常启动。
+4. 若提示“unsupported legacy data”，不要直接改表；保留错误、恢复测试副本并由维护人员确认旧能力语义。
+5. 迁移成功后确认设备仍存在、能力标签正确，再启动其他实例。
+
+正式数据库未备份时不得执行该结构迁移。需要回退版本时停止服务并从迁移前备份恢复，不把 JSONB 反向猜测为旧文本。
+<!-- sense-capabilities-jsonb:end -->