Pangolin · 「我的设备」管理 + 控制面会话 + 数据面按设备记账 · 2026-06-28
+ +devices 表、每设备数据面凭证 dp_uuid、
+usage_device_daily、设备列表/删除接口都在——但 RegisterIfAbsent 生产代码从不调用，
+导致 devices 表永远是空的，整条每设备链路退回账户级。本方案 = 打通三条已存在的链路 + 新增 sessions 表，
+让设备/会话/每设备流量三件事一次成型。
+排查三端（控制面 Go / 数据面 sing-box / 客户端 Flutter）后的对照：
+| 能力 | 现状 | 位置 | 缺口 |
|---|---|---|---|
| devices 表 + 列表/删除接口 | 已建 | migrations/*/000001、internal/devices/{store,service,handler}.go、GET/DELETE /v1/me/devices | 表始终为空（无人写入） |
设备隐式注册 RegisterIfAbsent | 未接线 | devices/service.go | 已实现，生产请求路径从不调用（仅单测用） |
每设备数据面凭证 dp_uuid | 就绪未生效 | migrations/*/000015、nodes/store.go: EnsureDeviceDpUUID | 依赖 device 行存在；表空 → 退回账户级 users.dp_uuid |
每设备用量表 usage_device_daily | 就绪未生效 | migrations/*/000015、nodes/store.go: AccumulateDeviceUsage | 因 deviceID 永为 0 → 从不写入 |
| sing-box 按 dp_uuid 计量 | 已建 | agentd/render.go、usage_v2ray.go | 无（已按 user>>>{dp_uuid}>>>traffic 计量、reset 取增量） |
| 会话（JWT + Redis 白名单） | 已建 | auth/token.go（access 15min / refresh 30day） | 会话不绑设备 → 无法「按设备强制退出」 |
| 客户端「我的设备」页 | 已建 | widgets/account_screens.dart: DevicesScreen | 无在线状态/客户端版本；操作仅「移除」 |
| 客户端设备身份 | 硬编码 | connection_provider.dart: _kDeviceId='mac-001' | 固定值；版本（appVersionProvider 有）没上报 |
RegisterIfAbsent 没被调用 → devices 表空 → EnsureDeviceDpUUID 找不到设备行 → 退回账户级 dp_uuid → UserDeviceByDpUUID 返回 deviceID=0 → AccumulateDeviceUsage 被 if deviceID>0 跳过 → usage_device_daily 永远空。补上「登录即注册设备」这一步，整条链路自洽。
+devices.last_seen 在阈值内（建议 3 分钟）才算「在线」，另列「最后登录时间」。sessions 表（DB，可查历史、能按设备精准吊销），保留 Redis 白名单做快速校验。三支柱：设备身份（客户端稳定 UUID + 上报元数据）→ 会话（每次登录建 session 绑设备）→ 每设备流量（设备注册后 dp_uuid 自然铺开）。
+
+ CLIENT (Flutter) CONTROL PLANE (Go) AGENT + SING-BOX
+ ─────────────── ────────────────── ────────────────
+ device_id (UUID v4, POST /auth/login|register
+ secure storage) ──▶ body: device{id,name, ┌───────────────┐
+ name / platform / platform,client_version} │ devices 表 │
+ client_version (上报) │ ├─ RegisterIfAbsent ──────────────▶│ (终于被填充) │
+ │ └─ TokenManager.Issue └───────┬───────┘
+ │ └─ INSERT sessions(jti,device) │
+ │ EnsureDeviceDpUUID
+ POST /v1/nodes/{id}/connect ─▶ ConnectNode 铸 per-device dp_uuid
+ body: {device_id} │ └─ EnsureDeviceDpUUID ────推 Hub──▶ 下发 sing-box
+ │ (命中 device 行) VLESS user.uuid=dp_uuid
+ │ │
+ ◀── ReportUsage(dp_uuid,up,down) ── sing-box 按 dp_uuid 计量
+ │ UserDeviceByDpUUID→(user,device) user>>>{dp_uuid}>>>traffic
+ │ ├─ AccumulateUsage (账户级 usage_daily)
+ │ ├─ AccumulateDeviceUsage(设备级 usage_device_daily)
+ GET /v1/me/devices ◀───────────┤ └─ touch devices.last_seen ← 驱动「在线」判定
+ {name,platform,client_version, │
+ online,last_login} │ POST /v1/me/devices/{uuid}/logout → 吊销 session（强制退出）
+ │ DELETE /v1/me/devices/{uuid} → 删设备+吊销会话+吊销 dp_uuid
+
+
+sessions 表（migration 000016，mysql + sqlite）每次登录一条；绑定设备与 refresh-token JTI，支撑「按设备强制退出 / 最后登录 / 会话历史」。SQL 走中性方言（不用 NOW()/UTC_TIMESTAMP()，时间 Go 端算好传参）。
+sessions( + id INTEGER PK AUTOINCREMENT, + user_id NOT NULL, -- FK users.id + device_id NOT NULL, -- FK devices.id（会话归属哪台设备） + refresh_jti TEXT NOT NULL UNIQUE,-- 绑定当前 refresh token 的 JTI + client_ip TEXT, -- 登录来源 IP + client_version TEXT, -- 登录时客户端版本（历史留痕） + created_at DATETIME NOT NULL, -- 登录时间（设备「最后登录」取最近一条） + last_active DATETIME, -- refresh 轮换时更新 + revoked_at DATETIME NULL -- 强制退出/登出置位；非空=已失效 +) +INDEX (user_id), INDEX (device_id), UNIQUE (refresh_jti) ++
| 时机 | 对 sessions 的动作 |
|---|---|
| 登录 / 注册 | TokenManager.Issue 同事务 INSERT 一条（写 device_id / jti / ip / version / created_at） |
| 刷新令牌 | rotation：更新该行 refresh_jti（新 jti）+ last_active |
| 登出 | 按 refresh-jti 置 revoked_at=now + Redis 删 jti |
| 强制退出 | 按 device_id 把该设备所有未撤销 session 置 revoked_at + Redis 删各 jti |
devices 表加列（同迁移）| 列 | 类型 | 用途 |
|---|---|---|
client_version | TEXT NULL | 该设备最近上报的客户端版本，列表展示 |
totp_trusted_until | DATETIME NULL | 预留：未来 2FA「信任设备」过期点；清除登录信息时一并清空 |
既有列：uuid / user_id / name / platform / last_seen / created_at / dp_uuid(000015)。设备「最后登录时间」= 该设备最近一条 session.created_at（不复用 last_seen，后者是数据面活跃度）。
usage_device_daily（已存在，本方案使其真正写入）+usage_device_daily(user_id, device_id, date, bytes_up, bytes_down, minutes_used) + PK(device_id, date) -- 增量累加：bytes_up = bytes_up + EXCLUDED.bytes_up ++
账户总流量 = 账户级 usage_daily（AccumulateUsage 始终写）；设备明细 = usage_device_daily（AccumulateDeviceUsage，deviceID>0 时写）。二者由同一份 ReportUsage 增量同时落库。
| 端点 | 变化 |
|---|---|
POST /auth/loginPOST /auth/register | 请求体增 device:{id,name,platform,client_version} → 触发 RegisterIfAbsent + 建 session |
POST /auth/refresh | 更新 session.last_active + jti 轮换（同步换 session.refresh_jti） |
POST /auth/logout | 按 refresh-jti 置 session.revoked_at（+ Redis 删，已有） |
GET /v1/me/devices | 响应每项增 client_version / online(bool) / last_login(RFC3339) |
POST /v1/me/devices/{uuid}/logout | 新 强制退出：吊销该设备所有 session |
DELETE /v1/me/devices/{uuid} | 增强：吊销 session + 真实吊销 dp_uuid（落地 CredentialRevoker，当前是 NoopRevoker） |
devices.last_seen 距今 < 阈值（建议 3 分钟）。connect 时 touch；② ReportUsage 时 touch——连着时每 ~60s 一次。当前 handler_grpc.go: ReportUsage 解析 dp_uuid→(user,device) 后只累流量、不 touch last_seen，需补这一步。last_seen < 3min → 绿点「在线」；否则灰点「离线」，并显示「最后登录 · {time}」。| 强制退出 | 清除登录信息 | |
|---|---|---|
| 端点 | POST …/devices/{uuid}/logout | DELETE …/devices/{uuid} |
| 会话 | 吊销该设备所有 session（revoked_at + Redis 删 jti） | 同左（一并吊销） |
| devices 行 | 保留（仍在列表，转「离线/已退出」） | 删除 |
| 数据面凭证 dp_uuid | 不动（重登后仍可用） | 吊销：经 nodes.Hub 给各节点推 upsert 去掉该 dp_uuid 的 sing-box user |
| 效果 | 该设备下次 refresh 失败 → 需重新登录 | 设备从信任列表彻底剔除 |
| 未来 2FA | — | 同时清 totp_trusted_until → 重登需重做 2FA |
本机：列表高亮「本机」；本机一般不显示「强制退出」（或显示「退出登录」= 本地 logout）。删除/退出他机需二次确认弹窗（危险样式）。
+ +沿用既有 DevicesScreen 卡片列表，行内信息扩展 + 行尾操作。颜色/字号/间距全走唯一真相源 token（pangolin_theme），不硬编码。
+┌─────────────────────────────────────────────────────────────┐ +│ [▦] MacBook Pro ● 在线 [ ⋯ ] │ ⋯ 菜单: +│ macOS · v1.0.10 · 本机 │ ├ 强制退出 +├─────────────────────────────────────────────────────────────┤ └ 清除登录信息 +│ [▦] iPhone 15 ○ 离线 [ ⋯ ] │ +│ iOS · v1.0.9 · 最后登录 2 小时前 │ +├─────────────────────────────────────────────────────────────┤ +│ [▦] Windows-PC ○ 离线 [ ⋯ ] │ +│ windows · v1.0.10 · 最后登录 3 天前 │ +└─────────────────────────────────────────────────────────────┘ + PRO 套餐最多 5 台设备同时在线 · 已用 3 / 5 ++
Device 加 clientVersion / online(bool) / lastLogin(DateTime?)。_kDeviceId='mac-001'，首启生成 UUID v4 存 flutter_secure_storage；登录/注册请求体带 device:{id,name,platform,client_version}。account_api 加 forceLogout(uuid)；devicesProvider 加对应方法（remove 已有）。app_text.dart + strings_{zh,en}.dart），脱敏不含红线词。P1 · 设备注册打通 — 客户端稳定 device_id + 登录上报元数据；控制面接线 RegisterIfAbsent。
产出：「我的设备」列表显示真实登录过的设备（最大缺口闭合）。
P2 · sessions 表 + 在线/最后登录 — migration 000016；Issue/Refresh/Logout 写 session；ReportUsage touch last_seen；GET /devices 返回 online/last_login/client_version。
P3 · 两个操作 — 强制退出端点 + 清除增强（session 吊销 + CredentialRevoker 真实吊销 dp_uuid）。
P4 · 每设备流量验证 — 端到端确认 usage_device_daily 填充 + 统计页设备下拉接真数据（对接已有 deviceUsageProvider，呼应统计整改 #10）。
P5 · （未来）2FA 信任设备 — 清除登录信息联动 2FA 重验（totp_trusted_until）。
关联：统计体系整改（#5）（每设备归因 / 统计页设备下拉）· 功能 × 测试覆盖清单（设备/会话验收）。本文为设计方案；实现按 P1–P5 后续单独排期。
+ +