docs: 记录并归档工单 #56

2026-08-13 22:38:31 +08:00
parent 8e3a25d1d6
commit a9f8a558de
4 changed files with 83 additions and 4 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 06b68d16bf907decdaf85a813d417896f7920f4c
-synchronized_at: 2026-08-13T14:06:00Z
+wiki_revision: f9c089d2b993478e586f4abdb1845952a3cd3c51
+synchronized_at: 2026-08-13T14:37:00Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -97,3 +97,7 @@ synchronized_at: 2026-08-13T14:06:00Z
 - **close**：只有处置人或管理员可以完成；必须选择“确认有危险、误报、现场正常、无法确认”之一，可附备注。相同重复请求幂等，其他改变结果的请求被拒绝。
 - **审计事实**：成功生命周期事实只追加；失败、重复和拒绝尝试写入安全审计，但不记录令牌、密码或连接密钥。
 <!-- bell-mvp:end -->
+## 设备编辑请求边界
+
+- 新建设备请求显式提交名称、安装位置、设备类型和能力；编辑设备请求只提交名称、安装位置、能力和版本，不提交新建专用的 `modality` 或响应中的只读字段。
+- 设备名称和安装位置允许 UTF-8 中文；后端继续严格拒绝未知 JSON 字段，前端必须使用字段白名单构造请求，不得直接展开整个表单或响应对象。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: b70e92180546609cb9b3b05b2c13c1a49676c03b
-synchronized_at: 2026-08-13T14:05:00Z
+wiki_revision: 7deb549d8b0ae87cdca0c7494e36150d261248a1
+synchronized_at: 2026-08-13T14:37:00Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -76,3 +76,8 @@ synchronized_at: 2026-08-13T14:05:00Z

 `demo` 只用于临时查看。生产数据持久性、真实设备和媒体链路不能用 demo 验证替代。
 <!-- sense-windows-package:end -->
+## 设备管理
+
+| 现象 | 处理 |
+|---|---|
+| 编辑设备时提示“请求内容格式不正确” | 中文名称和安装位置本身受支持。检查 PATCH payload 是否误带只允许新建时提交的 `modality` 或其他未知字段；编辑请求应只包含 `name`、`location`、`capabilities`、`version`。不要通过放宽后端未知字段校验绕过前端契约错误。 |
@@ -0,0 +1,66 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-56-修复设备编辑请求包含新建专用字段
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-56-%E4%BF%AE%E5%A4%8D%E8%AE%BE%E5%A4%87%E7%BC%96%E8%BE%91%E8%AF%B7%E6%B1%82%E5%8C%85%E5%90%AB%E6%96%B0%E5%BB%BA%E4%B8%93%E7%94%A8%E5%AD%97%E6%AE%B5.-
+wiki_revision: 212cf0a998afb41adfb1d671df07a1362580ea9e
+synchronized_at: 2026-08-13T14:37:31Z
+<!-- gitea-wiki-mirror:end -->
+
+# 56 修复设备编辑请求包含新建专用字段
+
+- 类型：缺陷
+- 所属 Epic：#7
+- 所属 MVP / 版本：#8
+- 状态：待验收
+- 日期：2026-08-13
+- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/56
+- Wiki 页面：Task-56-修复设备编辑请求包含新建专用字段
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+用户在设备管理编辑中文安装位置时收到“请求内容格式不正确”。中文 UTF-8 并非根因；前端编辑请求展开了整个表单，把只允许新建时提交的 `modality` 发送到严格拒绝未知字段的 PATCH 接口。目标是让新建和编辑请求分别遵循明确字段白名单，并用可运行测试固定契约。
+
+## 最终方案
+
+- 提取纯 payload 构造函数，避免页面直接展开表单对象。
+- 新建请求显式包含 `name`、`location`、`modality`、`capabilities`。
+- 编辑请求显式仅包含 `name`、`location`、`capabilities`、`version`。
+- 使用 Node 内置测试运行器验证中文值原样保留、新建包含设备类型、编辑排除设备类型和只读 ID。
+- 后端 `DisallowUnknownFields` 保持不变，继续把未知字段视为契约错误。
+
+## 修改文件
+
+- `Sense/ui/src/views/sense/device/Devices.vue`：分别构建设备新建和编辑请求。
+- `Sense/ui/src/views/sense/device/devicePayload.mjs`：设备请求字段白名单。
+- `Sense/ui/tests/devicePayload.test.mjs`：中文值和字段边界测试。
+- `Sense/ui/package.json`：增加设备 payload 测试命令。
+- Wiki 业务规则与故障排查页面。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 编辑设备保存中文安装位置 | 通过，PATCH 返回 200 |
+| 保存后回读中文安装位置 | 通过，回读为“教学楼一楼东门” |
+| 编辑请求排除 modality 和只读字段 | 通过，单元测试验证 |
+| 新建请求保留 modality | 通过，单元测试验证 |
+| 后端严格未知字段策略保持不变 | 通过，未修改后端解析逻辑 |
+
+## 测试
+
+- `corepack pnpm@9.15.1 test:device-payload`：2 项通过。
+- `corepack pnpm@9.15.1 lint`：0 error，806 个既有 warning。
+- `corepack pnpm@9.15.1 build`：通过，3 个既有体积 warning。
+- `go test ./...`：通过。
+- Go 1.26.5 Windows 重新打包并启动：通过。
+- 真实 PostgreSQL API：白名单 PATCH 保存成功，GET 回读中文位置成功。
+- **未验证部分**：最终浏览器点击“保存”的视觉交互由用户验收；请求构造、真实 API 保存和回读已自动验证。
+
+## 遗留问题
+
+- 严格 Harness 仍受既有 #44 归档缺少“最终方案”章节影响。
+
+## 相关提交
+
+- `8e3a25d` 修复设备编辑请求字段并增加契约测试。
@@ -147,6 +147,10 @@
    {
      "page": "Task-54-修复实时监看按需拉流循环等待",
      "path": "docs/task/54-修复实时监看按需拉流循环等待.md"
+    },
+    {
+      "page": "Task-56-修复设备编辑请求包含新建专用字段",
+      "path": "docs/task/56-修复设备编辑请求包含新建专用字段.md"
    }
  ]
 }