From a3731ce11c562860c0ab0c53f477ae2706617444 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Sun, 28 Jun 2026 23:46:37 +0800
Subject: [PATCH] =?UTF-8?q?docs(design):=20=E8=A1=A5=20device=20uuid=20?=
 =?UTF-8?q?=E7=94=9F=E6=88=90=E6=9C=BA=E5=88=B6(=E9=9A=8F=E6=9C=BAUUIDv4+?=
 =?UTF-8?q?=E5=AE=89=E5=85=A8=E5=AD=98=E5=82=A8+=E9=87=8D=E8=A3=85?=
 =?UTF-8?q?=E5=BD=B1=E5=93=8D)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§3.2.1 ④:uuid=客户端首启 Uuid().v4() 随机生成、立即写 flutter_secure_storage
跨重启恒定;不绑硬件ID(五端唯一可靠合规);各平台安全区存储 + 卸载重装影响
(iOS Keychain 保留/Android 清);对设备计数的含义。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/device-session-management-design.html | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/device-session-management-design.html b/docs/device-session-management-design.html
index 731b14f..98712f5 100644
--- a/docs/device-session-management-design.html
+++ b/docs/device-session-management-design.html
@@ -204,12 +204,22 @@ UNIQUE INDEX (dp_uuid)       -- 000015（NULL 不冲突，存量待回填）
 <div class="card root">
 <b>③ 设备 id 与「按设备控制登录数」</b>（你提的将来需求，本设计已为其留好抓手）：
 <ul>
-<li><b>设备身份键</b> = <code>(user_id, devices.uuid)</code>。<code>uuid</code> 由客户端生成、持久化在 <code>flutter_secure_storage</code>，同一台机器重装 app 内仍稳定 → 一台真实设备恒等于一行 <code>devices</code>，不会因重登重复计数。</li>
+<li><b>设备身份键</b> = <code>(user_id, devices.uuid)</code>。<code>uuid</code> 是客户端首启生成的随机 UUID v4，持久化在 <code>flutter_secure_storage</code>；同一安装内跨重启/更新恒定 → 一台真机恒等一行 <code>devices</code>，不因重登重复计数（生成方式见下 ④）。</li>
 <li><b>限额抓手已就绪</b>：<code>RegisterIfAbsent(userID, deviceUUID, name, platform, <u>maxDevices</u>)</code> 在注册新设备时已会<b>按套餐上限校验设备数</b>（<code>maxDevices</code> 来自计划：免费 1 / PRO 5，对应 <code>Me.devicesMax</code>）。超限时拒绝注册新设备（返回「设备数已达上限」），即「按设备控制用户能登录的设备数」。</li>
 <li><b>两种限额口径</b>（将来按需选）：<b>(a) 累计设备数</b>——devices 行数 ≤ 上限（当前 RegisterIfAbsent 口径，超了要先「清除登录信息」踢掉旧设备）；<b>(b) 同时在线/登录数</b>——以 <code>sessions</code>（未撤销）或 <code>last_seen</code> 在线数为准，限「并发」而非「累计」。<code>sessions</code> 表 + <code>devices.id</code> 同时支持这两种统计。</li>
 </ul>
 </div>
 
+<div class="card">
+<b>④ <code>uuid</code> 怎么生成</b>（替换现有硬编码 <code>_kDeviceId='mac-001'</code>）：
+<ul>
+<li><b>随机 UUID v4</b>，不绑硬件标识——客户端首启用安全随机数生成（Dart <code>uuid</code> 包的 <code>Uuid().v4()</code>，128 位随机），<u>立即写入 <code>flutter_secure_storage</code></u>（key 如 <code>device_id</code>）；之后每次启动先读，读到就复用。</li>
+<li><b>为什么不用硬件 ID</b>：iOS 无稳定硬件序列号、Android 限制 <code>ANDROID_ID</code>、桌面 MAC 地址易变/隐私敏感——「随机 UUID + 安全存储持久化」是跨五端唯一可靠且合规的做法。</li>
+<li><b>存储位置</b>=各平台安全区：iOS/macOS Keychain、Android Keystore 加密的 EncryptedSharedPreferences、Windows DPAPI 凭据库。普通卸载重装的影响：<span class="warn-c">iOS Keychain 通常<b>跨重装保留</b>（uuid 不变）；Android 卸载即清</span>（重装会得新 uuid，算一台新设备）。</li>
+<li><b>对设备计数的含义</b>：正常使用（重启/更新）uuid 恒定，计数准；卸载重装在部分平台会多记一台——故「累计设备数」超限时需用户「清除登录信息」手动清旧设备，或将来加「30 天未活跃自动回收」。</li>
+</ul>
+</div>
+
 <h3>3.3 <code>usage_device_daily</code>（已存在，本方案使其真正写入）</h3>
 <pre>
 usage_device_daily(user_id, device_id, date, bytes_up, bytes_down, minutes_used)