# Data Model: 设备信任免绑手机号

**Date**: 2026-09-20 | **Spec**: [spec.md](spec.md)

## 新增实体：InfoUserDevice（表 `info_user_device`）

一台设备一行，`device_id` 主键；记录该设备**最近一次**手机号验证通过的登录。

| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| device_id | VARCHAR(64) | PK，NOT NULL | 设备唯一标识（App 首启生成持久化，≤64） |
| phone | VARCHAR(20) | NOT NULL | 最近一次验证通过的手机号（账号主键，越南 +84） |
| user_id | BIGINT | NOT NULL | phone 对应的 info_user.user_id |
| create_time | DATETIME | NULL | 首次建立信任时间 |
| update_time | DATETIME | NULL | 最近一次登录刷新时间 |

**DDL（写入 `updatesql/sql.md`，人工执行）：**

```sql
-- 2026-09-20 设备绑定手机号信任表（同设备三方登录免绑，029-device-trust-phone-bind）
CREATE TABLE info_user_device (
  device_id   VARCHAR(64) NOT NULL COMMENT '设备唯一标识(App首启生成持久化)',
  phone       VARCHAR(20) NOT NULL COMMENT '本设备最近一次验证通过的手机号',
  user_id     BIGINT NOT NULL COMMENT '对应用户ID(info_user.user_id)',
  create_time DATETIME DEFAULT NULL COMMENT '首次建立信任时间',
  update_time DATETIME DEFAULT NULL COMMENT '最近一次登录刷新时间',
  PRIMARY KEY (device_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='设备-手机号信任表(029)';
```

### 校验与写入规则

- 写入前置校验（Service 层）：deviceId 非空且长度 ≤64，否则跳过记录（不报错，静默降级）；phone、userId 必须来自**已验证通过的登录成功路径**。
- **Upsert 语义**：`selectById(deviceId)` 命中 → 更新 phone/user_id/update_time（共用设备换号 = 最近一次覆盖）；未命中 → insert，create_time = update_time = now。
- 删除：本期不提供解除信任接口（YAGNI）；误绑可通过确认框取消避免，后续需要再加。

### 状态迁移（单行生命周期）

```text
[不存在] --首次验证登录(带deviceId)--> [信任 phone_A]
[信任 phone_A] --phone_B 在本设备登录成功--> [信任 phone_B]（覆盖）
[信任 phone_X] --同号再次登录--> [信任 phone_X]（仅刷新 update_time）
```

## 复用/扩展：临时凭证（Redis）

| Key | 值 | TTL | 写入点 | 消费点 |
|---|---|---|---|---|
| `oauth:bind:{tempKey}` | `provider@providerUid`（**现状不变**） | 5 min | oauthLogin / LINE 回调 未绑定分支 | oauthBindPhone / oauthDeviceConfirm |
| `oauth:bind:dev:{tempKey}`（**新增**） | `deviceId`（仅 deviceConfirm 分支写入） | 5 min | oauthLogin / LINE 回调 未绑定且设备有信任 | oauthDeviceConfirm |

- 两个 key 同 TTL 写入；`oauthDeviceConfirm` 消费时要求两键齐全，且 `dev` 值与入参 deviceId 相等，否则按"凭证与设备不匹配"拒绝。
- 确认成功后两个 key 一并删除（与 oauthBindPhone 删除现有 key 一致）。

## 复用不变：InfoUserOauth（表 `info_user_oauth`）

`UNIQUE(provider, provider_uid)` 语义不变。一键确认 = 向此表新增记录（provider + providerUid → 设备信任手机号对应 userId），插入逻辑与 `oauthBindPhone` 相同。

## 脱敏规则（maskedPhone）

复用现有 `maskPhone`：长度 ≥8 时返回 `前3位 + "****" + 后4位`（如 `098****4321`）；长度不足 8 原样返回。DeviceTrustService 提供该方法，InfoUserController 现有私有实现改调共用（行为不变）。

## 新增消息 key（i18n 资源文件，多语言）

| key | 用途 |
|---|---|
| `no.oauth.device.confirm` | deviceConfirm 分支的成功提示语 |
| `no.oauth.device.mismatch` | 确认接口：tempKey 非设备确认凭证 / dev 键缺失 / deviceId 不匹配 / 设备信任记录不存在 |