# 付费用户数据迁移报告

> 生成时间: 2026-03-13
> 脚本: `scripts/export_paid_users.sh`
> 输出: `scripts/output/paid_users_migration.sql` (3189 行)

---

## 1. 数据总览

### 源库统计

| 指标 | 全量 | 付费用户筛选后 | 丢弃 |
|------|-----:|---------------:|-----:|
| 用户 (user) | 1,864 | **482** | 1,382 (74%) |
| 登录方式 (user_auth_methods) | 2,041 | **598** | 1,443 |
| 设备 (user_device) | 1,415 | **496** | 919 |
| 订单 (order) | — | **1,669** | — |
| 已完成订单 (status=3) | 1,806 | — | — |
| 订阅 (user_subscribe) | 1,588 | **526** | 1,062 |
| IAP 交易 (apple_iap_transactions) | 168 | **29** | 139 |
| 系统日志 (system_logs) | 20,264 | **4,830** | 15,434 |
| 套餐定义 (subscribe) | 1 | **1** (全量) | — |
| 支付方式 (payment) | 4 | **4** (全量) | — |
| 系统配置 (system) | 53 | **53** (全量) | — |

### 新增数据（迁移脚本自动生成）

| 指标 | 数量 | 说明 |
|------|-----:|------|
| 家庭组 (user_family) | **482** | 每个付费用户 1 个 |
| 家庭成员 (user_family_members) | **482 + 24** | 482 家主 + 24 拆分设备 |
| 新用户 (拆分设备) | **24** | 多设备用户第 2 个设备→独立用户 |

### 幽灵用户

| 类型 | 数量 | 处理 |
|------|-----:|------|
| 有订单/IAP 但 user 表不存在 | **82** | **已排除**（INNER JOIN user） |
| user_id=0 的脏数据 | 若干 | **已排除**（WHERE user_id > 0） |

---

## 2. 付费用户定义

```sql
SELECT DISTINCT t.uid FROM (
  SELECT user_id AS uid FROM `order` WHERE status=3 AND user_id > 0
  UNION
  SELECT user_id AS uid FROM apple_iap_transactions WHERE user_id > 0
) t
INNER JOIN user u ON u.id = t.uid
ORDER BY t.uid;
```

**逻辑分析：**

1. **子查询 1** — `order WHERE status=3`：查找所有已完成支付的订单（status=3 = 支付完成），提取 `user_id`
2. **子查询 2** — `apple_iap_transactions`：查找所有 Apple IAP 交易记录的 `user_id`
3. **UNION**：合并去重，满足**任一条件**即为付费用户
4. **WHERE user_id > 0**：排除 `user_id=0` 的脏数据
5. **INNER JOIN user**：只保留在 `user` 表中**实际存在**的用户（排除 82 个幽灵用户）

**结果**：564 个候选 → 排除 82 幽灵 → **482 个有效付费用户**

---

## 3. 脚本分步 SQL 逻辑分析

### Step 1: 查询付费用户 ID

见上方"付费用户定义"。输出为换行分隔的 ID 列表，转为逗号分隔用于后续 WHERE IN。

### Step 2: SQL 文件头

```sql
SET NAMES utf8mb4;              -- 确保中文字符正确
SET FOREIGN_KEY_CHECKS = 0;     -- 禁用外键检查，允许无序插入
SET UNIQUE_CHECKS = 0;          -- 禁用唯一键检查，加速批量插入
SET AUTOCOMMIT = 0;             -- 开启事务模式
CREATE DATABASE IF NOT EXISTS `ppanel` ...;
USE `ppanel`;
```

**目的**：创建安全的导入环境，避免外键/唯一键冲突导致中断。

### Step 3: 导出表结构（DDL）

```bash
mysqldump --no-data --skip-add-drop-table \
  user user_auth_methods user_device \
  order user_subscribe apple_iap_transactions \
  subscribe payment system system_logs
```

**逻辑**：
- `--no-data`：只导出 CREATE TABLE 语句，不含数据
- `--skip-add-drop-table`：不生成 `DROP TABLE IF EXISTS`，避免误删新库已有表
- 后处理 `sed` 将 `CREATE TABLE` 改为 `CREATE TABLE IF NOT EXISTS`
- **手动追加** `user_family` 和 `user_family_members` DDL（新系统表，源库可能没有）

**涉及 12 张表**：
| 表 | 类型 |
|----|------|
| user | 用户主表 |
| user_auth_methods | 登录方式（email/device/telephone） |
| user_device | 设备记录 |
| order | 订单 |
| user_subscribe | 用户订阅 |
| apple_iap_transactions | Apple IAP 交易 |
| subscribe | 套餐定义（全量配置表） |
| payment | 支付方式（全量配置表） |
| system | 系统配置（全量配置表） |
| system_logs | 系统日志 |
| user_family | 家庭组（新表，手动 DDL） |
| user_family_members | 家庭成员（新表，手动 DDL） |

### Step 4: 全量配置表数据

```bash
for TBL in subscribe payment system; do
  mysqldump --no-create-info --complete-insert --skip-extended-insert "${TBL}"
done
```

**逻辑**：
- `--no-create-info`：只导出 INSERT，不重复 DDL
- `--complete-insert`：生成包含列名的完整 INSERT（兼容性更好）
- `--skip-extended-insert`：每行一条 INSERT（便于阅读和调试）
- 这三张表**不按用户过滤**，全量导出

**数据量**：subscribe 1 条 + payment 4 条 + system 53 条 = 58 条

### Step 5: 付费用户关联数据

```bash
export_table_by_user_ids() {
  mysqldump --no-create-info --complete-insert \
    --where="${COL} IN (${PAID_ID_LIST})" "${TBL}"
}
```

逐表使用 `--where` 子句过滤：

| 表 | 过滤列 | 导出数量 | SQL 逻辑 |
|----|--------|---------|---------|
| `user` | `id` | 482 | `WHERE id IN (1,5,7,...)` — 只导出付费用户的用户记录 |
| `user_auth_methods` | `user_id` | 598 | `WHERE user_id IN (...)` — 付费用户的所有登录方式 |
| `user_device` | `user_id` | 496 | `WHERE user_id IN (...)` — 付费用户的所有设备 |
| `order` | `user_id` | 1,669 | `WHERE user_id IN (...)` — 付费用户的**所有**订单（含未完成） |
| `user_subscribe` | `user_id` | 526 | `WHERE user_id IN (...)` — 付费用户的订阅记录 |
| `apple_iap_transactions` | `user_id` | 29 | `WHERE user_id IN (...)` — 付费用户的 IAP 交易 |

**注意**：`order` 表导出的是付费用户的**全部订单**（1,669 条），不仅仅是 status=3 的。这是合理的——保留用户完整的订单历史。

### Step 6: 系统日志

```sql
mysqldump --where="object_id IN (${PAID_ID_LIST})" system_logs
```

**逻辑**：`system_logs.object_id` 记录的是操作对象 ID，通常是 user_id。按付费用户 ID 过滤。

**注意**：`object_id` 不一定都是 user_id（不同 type 含义不同），可能多导或少导少量记录，影响不大。

**数据量**：4,830 条

### Step 7: 家庭组初始化

```sql
-- 对每个付费用户执行：
INSERT INTO user_family (owner_user_id, max_members, status, created_at, updated_at)
VALUES ({user_id}, 2, 1, NOW(), NOW());

INSERT INTO user_family_members (family_id, user_id, role, status, join_source, joined_at, ...)
VALUES (LAST_INSERT_ID(), {user_id}, 1, 1, 'migration', NOW(), NOW(), NOW());
```

**逻辑分析**：

1. 遍历 482 个付费用户 ID
2. 为每个用户创建 **1 个家庭组**（`user_family`）
   - `owner_user_id` = 该用户 ID
   - `max_members = 2`（默认最多 2 人）
   - `status = 1`（活跃）
3. 将该用户添加为**家主**（`user_family_members`）
   - `family_id = LAST_INSERT_ID()` — 引用刚插入的家庭组 ID
   - `role = 1`（家主）
   - `status = 1`（活跃）
   - `join_source = 'migration'`（标记来源为迁移）

**LAST_INSERT_ID() 链式调用**：MySQL 保证 `LAST_INSERT_ID()` 返回同一连接中最后一次 AUTO_INCREMENT 的值，在顺序执行的 SQL 中是安全的。

### Step 8: 多设备用户拆分

**背景**：旧系统中同一 user_id 可以有多个设备。新系统要求每个设备 = 独立用户，通过家庭组关联。

**查询多设备用户的第二个设备**：

```sql
SELECT ud.user_id, ud.id, ud.Identifier, ud.user_agent, ud.created_at, ua.id
FROM user_device ud
INNER JOIN user_auth_methods ua
  ON ua.user_id = ud.user_id
  AND ua.auth_type = 'device'
  AND ua.auth_identifier = ud.Identifier
WHERE ud.user_id IN (
  -- 找到有 >1 个设备的付费用户
  SELECT user_id FROM user_device
  WHERE user_id IN ({paid_ids})
  GROUP BY user_id HAVING COUNT(*) > 1
)
AND ud.id NOT IN (
  -- 排除每个用户的第一个设备（MIN(id) = 最早注册的设备）
  SELECT MIN(id) FROM user_device
  WHERE user_id IN (...多设备用户...)
  GROUP BY user_id
)
```

**逻辑分析**：

1. **识别多设备用户**：`GROUP BY user_id HAVING COUNT(*) > 1` → 找到 24 个用户
2. **保留第一个设备**：`MIN(id)` = 最早注册的设备，保留在原 user 上
3. **INNER JOIN user_auth_methods**：通过 `auth_type='device'` + `auth_identifier=Identifier` 关联设备的登录方式记录
4. **输出**：每个需要拆分的设备的完整信息

**对每个需要拆分的设备生成 SQL**：

```sql
-- 1. 创建新用户（无密码无邮箱的纯设备用户）
INSERT INTO user (password, algo, salt, enable, is_admin, created_at, updated_at)
VALUES ('', 'default', 'default', 1, 0, '{device_created}', NOW());
SET @new_user_id = LAST_INSERT_ID();

-- 2. 将设备记录转移到新用户
UPDATE user_device SET user_id = @new_user_id WHERE id = {device_id};

-- 3. 将设备的 auth_method 转移到新用户
UPDATE user_auth_methods SET user_id = @new_user_id WHERE id = {auth_method_id};

-- 4. 将新用户加入原用户的家庭组
INSERT INTO user_family_members (family_id, user_id, role, status, join_source, ...)
VALUES (
  (SELECT id FROM user_family WHERE owner_user_id = {owner_uid}),
  @new_user_id, 2, 1, 'migration_split', ...
);
```

**处理流程**：
```
原 user(id=100, 2 个设备)
  ├─ device_1 (id=50, MIN) → 保留在 user 100 上（已是家主）
  └─ device_2 (id=51)      → 创建新 user(id=NEW)
                              → UPDATE user_device SET user_id=NEW WHERE id=51
                              → UPDATE user_auth_methods SET user_id=NEW WHERE id=...
                              → INSERT user_family_members(family_id=..., user_id=NEW, role=2)
```

**结果**：24 个设备被拆分为独立用户，并加入原用户的家庭组作为 member。

### 文件尾

```sql
SET FOREIGN_KEY_CHECKS = 1;   -- 恢复外键检查
SET UNIQUE_CHECKS = 1;        -- 恢复唯一键检查
COMMIT;                        -- 提交事务
```

---

## 4. 数据完整性校验点

| 校验项 | 预期值 | 说明 |
|--------|--------|------|
| 导入后 user 数 | 482 + 24 = **506** | 482 原始 + 24 拆分 |
| user_family 数 | **482** | 每个付费用户 1 个家庭组 |
| user_family_members 数 | **506** | 482 家主 + 24 成员 |
| 每个 family 的成员数 | 1 或 2 | 无拆分=1，有拆分=2 |
| role=1 的成员数 | **482** | 每个家庭只有 1 个家主 |
| role=2 的成员数 | **24** | 拆分设备的新用户 |
| user_device.user_id 无孤儿 | 全部指向存在的 user | 拆分后 device 指向新 user |
| user_auth_methods.user_id 无孤儿 | 全部指向存在的 user | 拆分后 auth 指向新 user |

---

## 5. 风险与缓解

| 风险 | 级别 | 缓解措施 |
|------|------|----------|
| 新库已有数据，ID 冲突 | 高 | 新库应为空库；或改用 `INSERT IGNORE` |
| `refer_code` 唯一键冲突 | 中 | 迁移用户保留原值，新库确保无重复 |
| `LAST_INSERT_ID()` 链断裂 | 低 | SQL 文件必须**顺序执行**，不可并行 |
| 设备拆分后原用户订阅归属 | 低 | 订阅保留在原 user 上，新 user 通过家庭组共享 |
| `system_logs.object_id` 语义不一致 | 低 | 不同 type 的 object_id 含义不同，可能多导 |

---

## 6. 导入命令

```bash
docker exec -i <新容器> mysql -uroot -p<密码> < scripts/output/paid_users_migration.sql
```

---

## 7. 不导出的表（已丢弃）

| 表 | 原因 |
|----|------|
| traffic_log | 体积大，非必要 |
| ads / announcement / coupon / document | 0 条或非用户数据 |
| nodes / servers / server / server_group | 节点配置，不随用户迁移 |
| ticket / ticket_follow | 工单数据 |
| task | 0 条 |
| schema_migrations | 迁移记录 |
| log_message / application_versions | 0 条 |
| subscribe_application | 应用配置 |
| user_device_online_record | 0 条 |