绑定设备到个人空间#

验证状态：已源码核验、未联调（无 app 调用图）；services 基线：源码归纳 @ 2026-09-14

用途与场景#

把一台设备绑定到当前用户个人空间，生成该用户的设备直接拥有投影。App 扫码/蓝牙配对绑定向导的核心写端点：携带设备号与绑定授权码发起绑定；授权码非法、设备不存在、已被占用等场景有具名错误出口。绑定为投影复制而非设备搬运——库存侧投影不因此转移。概念（授权码 V1/V2、设备归属转移绑定、设备强制绑定）见账号与个人空间。

App 现役依据#

判定证据	内容
旧 app 文档收录记录	旧 app 文档仓在 docs/api/main-api/device/data-acquisition-device/bindForPersonalSpace/ 收录本端点，属 App 既有调用面
两代分工语义	/v1/retail 第二代无 bind 对应物；绑定写路径现役只有本端点
后端持续维护迹象	绑定主链路实现（归属转移顺序合同、库存租户守卫）持续修复中，2026-09 仍有维护提交

端点#

POST /main-service/main-api/device/data-acquisition-device/bindForPersonalSpace — 把一台设备绑定到当前用户个人空间，生成该用户的设备直接拥有投影。

端点全量事实（参数、请求/响应字段、错误码、权限点）见清单层 device · data-acquisition-device 采集设备；业务语义（wire 惯例、限频、租户声明等）见设备业务 · data-acquisition-device 采集设备。

动线与完成判据#

授权码按 V2 优先识别（前缀 V2 + 以设备号结尾 + 32 位 + 校验码段，只依赖设备号）、不满足 V2 判定的一律按 V1 校验（用户名参与运算，同一台设备对不同用户算出的 V1 授权码不同）——双版本规则细节见设备业务 · data-acquisition-device 采集设备。

status=200 且 data.state=bind、data.tenantId 为当前租户，表示投影已建立。触发归属转移时（force=true 或授权码变化），同一物理设备在全部非库存租户中的旧投影与分享记录已先退场对账（平台顺序合同），然后才创建本投影。

错误与边界#

业务失败均为业务拒绝族，error 为异常消息原文（判定口径见错误响应差异）。现行错误码清单（service ）：

error 原文	触发条件
Illegal authorization code	V1 比对不匹配；或 V2 判定命中但长度≠32 / 校验码不符
Inventory tenant cannot perform device binding	当前租户为设备库存租户 pcm（库存租户禁绑守卫）
The data collection device does not exist	设备号在库无任何投影行，或无设备库存租户 pcm 行
The data acquisition device has been bound	已存在唯一直接拥有投影、授权码未变化、且该投影就在当前租户（重复绑定）
The data acquisition device has been bound by someone else	直接拥有投影在他人租户；或无唯一直接拥有投影但存在其他非库存投影；或新投影写入撞活动设备号唯一索引

Bean Validation 失败（deviceNo/authorizationCode 缺失或超长）走请求校验出口（请求校验族，判定口径见错误响应差异）。

force 与冲突的判定顺序：force=true 直接进入设备强制绑定（归属转移，显式触发）；否则若存在唯一直接拥有投影——授权码变化触发归属转移绑定（V2 忽略大小写比较、V1 严格比较），授权码未变化按上表「已绑定」两分支拒绝。归属转移执行时先退场旧投影与活跃分享并通知相关用户刷新设备列表，再创建新投影；退场对账失败则整个绑定失败，不留半旧半新的投影组合。

旧 app 文档的「Tenant id is default」错误码已不存在（库存租户 default→pcm 迁移），本页不收录。

调用关系与资源清理#

无客户端长连接资源需要释放。归属转移会异步通知受影响用户（分享目标、原属主，排除 admin 与当前用户）刷新其设备列表；App 侧在绑定成功后应重新拉取设备列表，不应假设旧租户数据迁移。

已知缺口#

未执行真实联调：归属转移的退场对账时序、通知到达延迟、设备侧授权码更换后旧授权码的失效窗口均无 App 实测佐证。App 侧对上表五个业务错误码之外应保留未知码兜底分支。