ADMIN_TOOLS.md

# 🔧 管理员工具

## 用户配额管理

### 📝 脚本: `admin_adjust_user_quota.py`

用于调整用户的每日调用次数配额。

---

## 🚀 使用方法

### 1. 查看用户状态

```bash
export HF_TOKEN='your_hf_token_here'
python admin_adjust_user_quota.py <username> show
```

**示例**:
```bash
python admin_adjust_user_quota.py learnmlf show
```

**输出**:
```
============================================================
📊 用户状态: learnmlf
============================================================
日期: 2026-01-09
已用次数: 3/4
剩余次数: 1
状态: ✅ 可用
============================================================
```

---

### 2. 重置用户配额（给满4次）

```bash
python admin_adjust_user_quota.py <username> reset
```

**作用**: 将用户今天的已用次数设为0，相当于给他4次新配额

**示例**:
```bash
python admin_adjust_user_quota.py learnmlf reset
```

**流程**:
1. 显示当前状态
2. 要求确认（输入 `yes`）
3. 重置为0
4. 显示更新后的状态

---

### 3. 设置已用次数

```bash
python admin_adjust_user_quota.py <username> set <count>
```

**作用**: 直接设置用户今天已用的次数

**示例**:
```bash
# 设置为已用2次（剩余2次）
python admin_adjust_user_quota.py learnmlf set 2

# 设置为已用0次（剩余4次）
python admin_adjust_user_quota.py learnmlf set 0
```

---

### 4. 增加额外配额

```bash
python admin_adjust_user_quota.py <username> add <extra_count>
```

**作用**: 给用户增加额外的调用次数（超过默认的4次）

**示例**:
```bash
# 给用户额外增加2次配额
python admin_adjust_user_quota.py learnmlf add 2

# 如果用户原本已用3次，增加2次后，变为已用1次（相当于总共6次配额）
```

**逻辑**:
- 原理：减少已用次数 = 增加剩余次数
- 如果用户已用3次，增加2次配额后，已用次数变为1次
- 用户实际可用：4 - 1 = 3次（比重置多2次）

---

## 📊 使用场景

### 场景1: 用户配额用完了，但需要紧急使用

```bash
# 快速重置，给他4次新配额
python admin_adjust_user_quota.py user123 reset
```

### 场景2: VIP用户，给他每天8次配额

```bash
# 假设他今天用了2次，给他增加4次额外配额
python admin_adjust_user_quota.py vip_user add 4
# 结果：已用次数从2变为-2，相当于还能用6次（总共8次）
```

### 场景3: 用户误操作浪费了配额

```bash
# 重置给他4次新配额
python admin_adjust_user_quota.py user456 reset
```

### 场景4: 查看用户使用情况

```bash
# 查看某个用户今天用了多少次
python admin_adjust_user_quota.py user789 show
```

---

## 🔐 安全注意事项

1. **HF_TOKEN 权限**: 需要对 Dataset 有写入权限的 Token
2. **确认操作**: 所有修改操作都需要输入 `yes` 确认
3. **不可撤销**: 修改后立即生效，无法撤销（但可以再次调整）
4. **日期隔离**: 每天的配额独立，修改今天的不影响昨天/明天

---

## 📂 数据存储位置

```
HF Dataset: learnmlf/video-evaluations
├── call_counts/
│   └── 2026-01-09/
│       └── username.json  ← 这个文件被修改
```

**文件格式**:
```json
{
  "user": "username",
  "date": "2026-01-09",
  "count": 2,
  "last_updated": "2026-01-09T12:34:56",
  "note": "Set to 2 by admin"
}
```

---

## 💡 常见问题

### Q: 增加配额会影响其他天吗？
A: 不会。每天的配额独立存储，只影响当天。

### Q: 可以给用户设置负数吗？
A: 可以，使用 `add` 命令增加足够多次数即可。负数意味着用户有"额外"配额。

### Q: 用户看得到管理员的调整吗？
A: 用户只能看到剩余次数，看不到 `note` 字段的备注。

### Q: 如何批量调整多个用户？
A: 可以写个 bash 循环：
```bash
for user in user1 user2 user3; do
    python admin_adjust_user_quota.py $user reset
done
```

---

## 🔄 与应用的集成

用户在前端看到的次数会**实时更新**：
- 应用从 `call_counts/{date}/{username}.json` 读取
- 管理员修改文件后，用户刷新页面即可看到新配额
- 无需重启应用

---

## 📝 日志

所有修改都会在 `note` 字段留下记录：
- `"Reset by admin"` - 管理员重置
- `"Set to X by admin"` - 管理员设置为X
- `"Added X extra calls by admin (was Y)"` - 管理员增加X次（原来是Y）