From 9e5d6866176599463c37ca0484845e8bd005b8fc Mon Sep 17 00:00:00 2001
From: ila <2+ila@noreply.git.ilapage.cn>
Date: Thu, 3 Sep 2026 10:36:56 +0800
Subject: [PATCH] docs: document secure device identity recovery (#201)

---
 Android-Agent-API-Contract.-.md => unnamed.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 rename Android-Agent-API-Contract.-.md => unnamed.md (97%)

diff --git a/Android-Agent-API-Contract.-.md b/unnamed.md
similarity index 97%
rename from Android-Agent-API-Contract.-.md
rename to unnamed.md
index 1499754..018fc17 100644
--- a/Android-Agent-API-Contract.-.md
+++ b/unnamed.md
@@ -860,3 +860,15 @@ Agent 只比较整数 `versionCode`。设备有活动任务时禁止检查、下
 既有 SYB 商品列表与详情响应增加以下只读字段：`aiConfirmed`、可空 `aiConfidence`、可空 `aiReason`、可空 `aiConfirmedAt`。`aiInputFingerprint` 仅用于服务端并发和漂移校验，禁止通过 API 返回。`parseStatus` / `parseNote` 继续表示确定性解析器结果，`manuallyConfirmed` 继续只表示人工确认。
 
 采购预检把仍命中关联蝦皮当前候选的 `aiConfirmed=true` 视为可信目标规格；候选消失、关联变化或来源重导入使其失效，并返回重新解析/人工修正原因。该能力不新增 Android 接口或 Agent 字段，不创建采购任务或订单。
+
+## 设备身份恢复（#201）
+
+```http
+POST /api/admin/v1/devices/{deviceId}/identity-reset
+POST /api/agent/v1/register
+X-GoAuto-Device-Recovery-Code: <one-time-code>
+```
+
+仅管理员可以对未停用的既有设备发起身份重置。服务端立即使旧 Device Token 无效，并生成 10 分钟内仅能使用一次的恢复码；恢复码只在该管理员操作的响应中返回一次，服务端仅保存不可逆摘要，管理端设备列表、日志、任务接口和 Android 本地持久化均不得保存或返回原文。管理员将恢复码经受控人工渠道输入同一安装实例的 Agent 设置页。
+
+Agent 携带既有 Token（可已失效）及恢复码重新调用注册接口。服务端必须同时校验同一 `installId`、未停用状态、恢复码摘要、未过期和未使用；成功后使用原 `deviceId` 写入新 Token 摘要并返回一次新 Token，清除恢复码摘要和有效期。旧 Token 与恢复码都立即失效，已分配的 pending 采集或采购任务保持原 `deviceId`，不创建替代设备记录。缺少或错误恢复码仍为 `DEVICE_INSTALL_ID_CONFLICT`；过期码为 `DEVICE_RECOVERY_EXPIRED`；停用设备为 `DEVICE_DISABLED`。