From c1994ad0488bac38ec4066c97dadb600f97b8636 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Sun, 28 Jun 2026 23:43:37 +0800 Subject: [PATCH] =?UTF-8?q?docs(design):=20devices=20=E8=A1=A8=E8=A1=A5?= =?UTF-8?q?=E5=85=A8=E5=AD=97=E6=AE=B5=20+=20name=E6=9D=A5=E6=BA=90/?= =?UTF-8?q?=E4=B8=89=E6=97=B6=E9=97=B4=E6=88=B3/=E6=8C=89=E8=AE=BE?= =?UTF-8?q?=E5=A4=87=E9=99=90=E7=99=BB=E5=BD=95=E6=95=B0=20=E9=87=8A?= =?UTF-8?q?=E7=96=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §3.2 列出 devices 完整 9 列(含来源迁移 + platform CHECK 需加 linux); 新增 §3.2.1:① name 由客户端 device_info_plus 按平台取(主机名/机型)上报; ② created_at/last_seen/最后登录(session) 三时间戳辨析;③ 设备身份键 (user_id,uuid) + RegisterIfAbsent maxDevices 作「按设备控制登录数」抓手 (累计 vs 同时在线两种口径)。 Co-Authored-By: Claude Opus 4.8 --- docs/device-session-management-design.html | 69 ++++++++++++++++++++-- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/docs/device-session-management-design.html b/docs/device-session-management-design.html index ddf6337..731b14f 100644 --- a/docs/device-session-management-design.html +++ b/docs/device-session-management-design.html @@ -141,15 +141,74 @@ INDEX (user_id), INDEX (device_id), UNIQUE (refresh_jti) -

3.2 devices 表加列（同迁移）

+

3.2 devices 表（完整字段）

+

既有 7 列（000001 建表 + 000015 加 dp_uuid）+ 本方案新增 2 列（000016）。完整 schema：

+
+devices(
+  id          INTEGER PK AUTOINCREMENT,         -- 000001  内部自增主键
+  uuid        TEXT NOT NULL UNIQUE,             -- 000001  客户端生成的稳定设备 UUID（API 对外用它）
+  user_id     NOT NULL,                         -- 000001  FK users.id（设备归属用户）
+  name        TEXT NOT NULL,                    -- 000001  设备名（主机名/机型，≤64 runes）
+  platform    TEXT NOT NULL CHECK(...),         -- 000001  ios|android|windows|macos|linux *
+  last_seen   DATETIME NULL,                    -- 000001  数据面最后活跃（connect + ReportUsage touch）→ 在线判定
+  created_at  DATETIME NOT NULL,                -- 000001  设备首次注册时间
+  dp_uuid     CHAR(36) NULL UNIQUE,             -- 000015  每设备数据面凭证（sing-box VLESS user uuid）
+  client_version    TEXT NULL,                  -- 000016  最近上报的客户端版本（列表展示）         ← 新增
+  totp_trusted_until DATETIME NULL              -- 000016  预留:2FA「信任设备」过期点;清除登录时清空 ← 新增
+)
+INDEX (user_id)              -- 000001
+UNIQUE INDEX (dp_uuid)       -- 000015（NULL 不冲突，存量待回填）
+
- + - - + + + + + + + + + +
列类型用途
列类型来源用途
client_versionTEXT NULL该设备最近上报的客户端版本，列表展示
totp_trusted_untilDATETIME NULL预留：未来 2FA「信任设备」过期点；清除登录信息时一并清空
idINTEGER PK000001内部自增主键（sessions/usage_device_daily 用 device_id 引用它）
uuidTEXT UNIQUE000001客户端生成的稳定设备 UUID；/v1/me/devices/{uuid} 路径参数即它
user_idFK users.id000001设备归属用户
nameTEXT000001设备名（主机名/机型，normalizeName 截断 ≤64 runes）
platformTEXT CHECK000001平台枚举。*现有 CHECK 仅 4 值，需 000016 放宽加 linux
last_seenDATETIME NULL000001数据面最后活跃；<3min=在线。由 connect + ReportUsage touch
created_atDATETIME000001设备首次注册时间（≠最后登录，后者取 session.created_at）
dp_uuidCHAR(36) NULL UNIQUE000015每设备数据面凭证；EnsureDeviceDpUUID 首连铸入，作 sing-box VLESS user uuid
client_versionTEXT NULL000016 新增该设备最近上报的客户端版本，列表展示
totp_trusted_untilDATETIME NULL000016 新增预留：未来 2FA「信任设备」过期点；清除登录信息时一并清空
-

既有列：uuid / user_id / name / platform / last_seen / created_at / dp_uuid(000015)。设备「最后登录时间」= 该设备最近一条 session.created_at（不复用 last_seen，后者是数据面活跃度）。

+

*platform CHECK 放宽：000001 的约束是 CHECK(platform IN ('ios','android','windows','macos'))，不含 linux，但桌面客户端支持 Linux。000016 需重建该约束加入 'linux'（SQLite 改 CHECK 要走「建新表→拷数据→换名」；MySQL 同步改）。

+ +

3.2.1 字段释疑（name 来源 / 三个时间戳 / 设备 id 与限额）

+ +
+① name 怎么来：由客户端在登录/注册时填好上报（不是服务端造）。客户端用 device_info_plus 按平台取一个可读名： + + + + + + + + +
平台取值示例
macOS / Linux主机名（Platform.localHostname）Wangjia-MacBook-Pro
Windows计算机名（WindowsDeviceInfo.computerName）DESKTOP-7F3K
iOS设备名/机型（IosDeviceInfo.name 或 .utsname.machine）iPhone 15
Android厂商 + 机型（manufacturer + model）Xiaomi 13
+服务端 RegisterIfAbsent 经 normalizeName 截断 ≤64 runes 存库。后续可允许用户在「我的设备」里改名（PATCH，二期可选）。 +
+ +
+② 三个时间戳别混——分别答「装没装过 / 此刻在不在用 / 上次什么时候登的」： + +
+ +
+③ 设备 id 与「按设备控制登录数」（你提的将来需求，本设计已为其留好抓手）： + +

3.3 usage_device_daily（已存在，本方案使其真正写入）