Fal Consumption Audit

---
name: fal-consumption-audit
description: 审计 fal 账号消耗与用户扣费的一致性。查询 fal 官方账单，交叉比对 fal_tasks 中的用户消耗，汇总积分/现金明细，检测异常。当用户提到"消耗审计"、"账单核对"、"fal 对账"、"用量异常"时使用此 skill。
---

# Fal 消耗审计

## 审计目标

核对三层数据的一致性，发现差异和异常：

```
fal 官方账单（实际成本）
       ↕ 比对
fal_tasks 任务表（系统记录）
       ↕ 比对
用户积分/现金明细（用户扣费）
```

## 审计流程

复制此清单跟踪进度：

```
Task Progress:
- [ ] Step 1: 查询 fal 官方账单
- [ ] Step 2: 查询 fal_tasks 任务明细
- [ ] Step 3: 按用户聚合消耗
- [ ] Step 4: 比对用户积分/现金明细
- [ ] Step 5: 异常检测 & 输出报告
```

---

## Step 1: 查询 fal 官方账单

调用 fal Platform API 获取每个 fal 账号的实际消耗。

**API**: `GET https://api.fal.ai/v1/models/usage`

**认证**: `Authorization: Key {fal_api_key}`

**关键参数**:

| 参数 | 值 | 说明 |
|------|-----|------|
| `expand` | `["time_series", "auth_method", "summary"]` | 包含按时间和汇总数据 |
| `timeframe` | `day` | 按天聚合 |
| `start` | 审计开始日期 | ISO8601 格式 |
| `end` | 审计结束日期 | ISO8601 格式 |

**数据来源**: `FalAccount` 表（`ts_fal_account`），取最新插入的 20 个账号（按 id 倒序，不过滤 status）

```
FalAccount 关键字段:
  id          - 账号ID
  api_key     - fal API 密钥（用于调用 Usage API + 关联 FalTasks）
  balance     - 当前余额
  status      - 1=正常 0=禁用

查询: FalAccount.select().order_by(FalAccount.id.desc()).limit(20)
```

**输出**: 每个 fal 账号 → 各模型的 cost(USD) 和 quantity

---

## Step 2: 查询 fal_tasks 任务明细

从 `FalTasks` 表查询同一时间段内，每个 fal key 被哪些用户使用。

**数据来源**: `FalTasks` 表（`ts_fal_tasks`）

```
FalTasks 关键字段:
  user_id     - 发起任务的用户ID（核心关联字段）
  api_key     - 使用的 fal API 密钥（与 FalAccount.api_key 关联）
  app_name    - fal 模型名称（如 fal-ai/flux/schnell）
  money       - 向用户收取的金额（系统内积分，单位：分）
  cost_money  - fal 实际成本
  status      - 任务状态
  is_refund   - 是否退款（0=否 1=是）
  created_at  - 创建时间
```

**查询逻辑**:

```
SELECT
  api_key,
  user_id,
  app_name,
  COUNT(*) as task_count,
  SUM(money) as total_charged,        -- 向用户收的
  SUM(cost_money) as total_cost,      -- fal 实际成本
  SUM(CASE WHEN is_refund=1 THEN 1 ELSE 0 END) as refund_count
FROM ts_fal_tasks
WHERE created_at BETWEEN {start} AND {end}
GROUP BY api_key, user_id, app_name
ORDER BY total_charged DESC
```

---

## Step 3: 按用户聚合消耗

将 Step 2 的结果按 `user_id` 聚合，得到每个用户的消耗全貌。

**聚合维度**:

| 维度 | 说明 |
|------|------|
| 用户总消耗 | SUM(money) — 用户在 fal_tasks 中被收取的总积分 |
| 用户实际成本 | SUM(cost_money) — 对应的 fal 实际成本 |
| 用户任务数 | COUNT(*) — 总任务数 |
| 用户退款数 | SUM(is_refund=1) — 退款任务数 |
| 使用的 fal 账号 | GROUP_CONCAT(DISTINCT api_key) — 用了几个 fal 账号 |
| 使用的模型 | GROUP_CONCAT(DISTINCT app_name) — 用了哪些模型 |

---

## Step 4: 比对用户积分/现金明细

对 Step 3 中每个用户，查询其积分明细和现金明细进行交叉验证。

**积分明细表**: `PointsDetail`（`ts_points_detail`）

```
PointsDetail 关键字段:
  user_id        - 用户ID
  points         - 积分变动（正=增加，负=减少）
  title          - 交易说明（包含任务描述）
  source_type    - 来源类型：recharge/consume/gift/refund
  balance_before - 交易前余额
  balance_after  - 交易后余额
  created_at     - 创建时间
```

**现金明细表**: `FinancialTransactions`（`ts_financial_transactions`）

```
FinancialTransactions 关键字段:
  user_id          - 用户ID
  money            - 交易金额（单位：分，正=收入，负=支出）
  title            - 交易标题
  transaction_type - 0=充值/退款 1=消耗 3=智能体收益
  is_cash          - 0=否 1=是（现金交易）
  time             - 时间戳
```

**查询逻辑**:

对每个用户，分别查询审计时间段内的：

```
-- 积分消耗汇总
SELECT
  user_id,
  SUM(CASE WHEN source_type='consume' THEN ABS(points) ELSE 0 END) as points_consumed,
  SUM(CASE WHEN source_type='refund' THEN points ELSE 0 END) as points_refunded,
  SUM(CASE WHEN source_type='recharge' THEN points ELSE 0 END) as points_recharged,
  COUNT(*) as transaction_count
FROM ts_points_detail
WHERE user_id = {uid} AND created_at BETWEEN {start} AND {end}

-- 现金消耗汇总
SELECT
  user_id,
  SUM(CASE WHEN transaction_type=1 THEN ABS(money) ELSE 0 END) as cash_consumed,
  SUM(CASE WHEN transaction_type=0 AND money>0 THEN money ELSE 0 END) as cash_recharged,
  COUNT(*) as transaction_count
FROM ts_financial_transactions
WHERE user_id = {uid} AND time BETWEEN {start} AND {end}
```

---

## Step 5: 异常检测 & 输出报告

### 异常检测规则

| 编号 | 规则 | 判定条件 | 严重等级 |
|:---:|------|----------|:--------:|
| A1 | **fal 成本 vs 系统记录偏差** | abs(fal官方cost - fal_tasks.cost_money之和) / fal官方cost > 10% | HIGH |
| A2 | **用户被收费但 fal 无记录** | fal_tasks 有记录但 fal Usage API 中无对应模型消耗 | HIGH |
| A3 | **fal 有消耗但用户未被收费** | fal Usage API 有消耗但 fal_tasks 中无对应任务 | HIGH |
| A4 | **收费与扣费不一致** | fal_tasks.money 之和 ≠ PointsDetail consume 之和 | MEDIUM |
| A5 | **异常退款** | 退款金额 > 当日消耗总额的 30% | MEDIUM |
| A6 | **单用户消耗异常** | 用户当日消耗 > 历史日均消耗的 5 倍 | LOW |
| A7 | **零成本任务** | fal_tasks.money=0 且 cost_money>0（白嫖） | MEDIUM |
| A8 | **fal 账号余额预警** | FalAccount.balance < 1.0 USD | LOW |

### 报告输出格式（终端）

```
============================================================
  Fal 消耗审计报告
  审计日期: 2026-02-06
  审计范围: 2026-02-06 00:00:00 ~ 2026-02-06 23:59:59
============================================================

  ━━━ 第一层：Fal 官方账单 ━━━

  账号ID  余额(USD)  官方消耗(USD)  模型数  请求数
  ─────  ─────────  ────────────  ──────  ──────
     5      12.30         99.92      18    1049
    12      45.60          8.50       5     120
  ─────  ─────────  ────────────  ──────  ──────
  合计                    108.42      --    1169

  ━━━ 第二层：系统任务记录 (fal_tasks) ━━━

  fal账号ID  用户ID  用户名   模型              任务数  收费(积分)  fal成本(USD)
  ────────  ──────  ──────  ────────────────  ──────  ─────────  ──────────
     5       101    张三     sora-2/i2v          50      5000       5.00
     5       102    李四     kling/v2.1/i2v      30      8400      28.00
     5       103    王五     seedream/v4/t2i     20       600       0.60
    12       101    张三     flux/schnell        80       800       0.80
  ────────  ──────  ──────  ────────────────  ──────  ─────────  ──────────
  合计                                         180     14800      34.40

  ━━━ 第三层：用户扣费核对 ━━━

  用户ID  用户名   fal任务收费  积分消耗  现金消耗  积分充值  差异(积分)  状态
  ──────  ──────  ──────────  ────────  ────────  ────────  ─────────  ────
   101    张三        5800      5600       200      1000         0     OK
   102    李四        8400      8400         0         0         0     OK
   103    王五         600       400       200         0         0     OK

  ━━━ 异常告警 ━━━

  [HIGH]  A1: fal账号5 官方成本$99.92 vs 系统记录$34.40，偏差65.6%
  [MEDIUM] A7: 用户103 有3笔任务 money=0 但 cost_money>0
  [LOW]   A8: fal账号23 余额 $0.15，低于阈值

============================================================
  审计完成
  正常: 2 | 告警: 3 | 严重: 1
============================================================
```

## 数据关联关系图

```
FalAccount (ts_fal_account)
  │ api_key
  ├──────→ fal Usage API (官方账单, 按 api_key 查)
  │
  └──────→ FalTasks (ts_fal_tasks)
              │ api_key = FalAccount.api_key
              │ user_id → 关联到用户
              │
              └──→ User (ts_users)
                    │ id = FalTasks.user_id
                    │
                    ├──→ PointsDetail (ts_points_detail)
                    │     user_id = User.id
                    │     source_type = 'consume' / 'refund'
                    │
                    └──→ FinancialTransactions (ts_financial_transactions)
                          user_id = User.id
                          transaction_type = 1 (消耗)
```

## 脚本位置

实现脚本写在: `translate_api/app/coze/fal_balance.py`

已有的可复用函数:
- `query_fal_usage(api_key, start, end, timeframe)` — 查询 fal 官方用量

## 运行方式

```bash
# 审计今天
python fal_balance.py audit

# 审计指定日期
python fal_balance.py audit --start 2026-02-01 --end 2026-02-06

# 只审计指定 fal 账号
python fal_balance.py audit --ids 5 12

# 只审计指定用户
python fal_balance.py audit --user-ids 101 102
```

## 补充资料

- fal Usage API 文档: https://docs.fal.ai/platform-apis/v1/models/usage
- 数据模型定义: [reference.md](reference.md)