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 官方用量

运行方式

# 审计今天
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