下属生成统计 · SQL聚合深读时序图

01 总调用链

四个 API 独立查询：前端并发请求，Gateway 各自执行授权与 SQL；BFF 不逐用户相加，也不共享数据库快照。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

浏览器 Promise.all([ overview, trends, breakdowns, tasks ])

每个请求：load_analytics_access → _filtered_task_query
  overview   → _task_metrics → 汇总 SQL + 运行/用户 SQL + 分位数 SQL
  trends     → _task_metrics → 按时区 GROUP BY 时间桶
  breakdowns → _task_metrics → 8 组 GROUP BY 通过 UNION ALL 返回
  tasks      → COUNT 全范围 → 当前页 OFFSET/LIMIT → 当前页账单回填

BFF：返回值透传，并为用户榜/明细补姓名。

这一步具体意味着什么

这是一组独立 API，不存在一个先执行再共享给其他 API 的总聚合缓存。
下拉选择账号改变 target_user_id，只缩小已授权任务集合。
图中的四路 SQL 分段是解释顺序，不代表并发请求之间的调度先后。

固定提交源码

Web AdminAnalyticsDashboard.tsx:453–491；Gateway analytics/admin_routes.py:1020–1614。

02 过滤与计费

先筛任务，再把每个任务引用的已结算计费分项关联进来。metric_tasks 是查询内 CTE，不是额外落库的统计表。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

-- 等价结构示意；真实代码通过 SQLAlchemy 构造参数化 SQL
WITH RECURSIVE analytics_descendants AS (
  SELECT user_id FROM user_hierarchy
  WHERE parent_user_id = :actor AND status = 'active'
  UNION
  SELECT h.user_id FROM user_hierarchy h
  JOIN analytics_descendants d ON h.parent_user_id = d.user_id
  WHERE h.status = 'active'
), filtered_tasks AS (
  SELECT t.* FROM analytics_generation_tasks t
  WHERE t.service_client_id = :project
    AND t.user_id IN (:current_authorized_descendant_subquery)
    AND t.task_created_at >= :start_at
    AND t.task_created_at < :end_at
    -- 可选：t.user_id = :target_user_id；其他媒体/状态/来源条件
    -- 已接入集中可见性的项目：记录规则优先，其次用户规则，默认 show
), metric_tasks AS (
  SELECT t.*, COALESCE(i.settled_credits, 0) AS settled_credits
  FROM filtered_tasks t
  LEFT JOIN billing_authorization_items i
    ON i.id = t.billing_item_id
   AND i.service_client_id = t.service_client_id
   AND i.business_task_id = t.task_id
   AND i.status = 'settled'
)
SELECT ... FROM metric_tasks;

这一步具体意味着什么

filtered_tasks 是为解释而起的名字；真实实现先构造 Select，再将其 subquery() 传给 _task_metrics。
普通管理员范围为当前 active 递归下属并受 explicit 范围约束，排除本人；超管不附加下属限制。
请求指定 target_user_id 时先验证目标归属，越界直接 404，不能仅靠 WHERE 返回空数据。
LEFT JOIN 保留无已结算账单的任务，其积分为 0；不是 SUM 全部账单，也不是从 UsageEvent 计算。
集中可见性未接入的项目不额外过滤；已接入项目检查归属冲突，再过滤 show/hide。

固定提交源码

Gateway analytics/access.py:25–61；analytics/admin_routes.py:1144–1260。

03 概览 COUNT / SUM

总览由三组查询完成：任务/积分汇总、匹配运行的用户与运行计数、终态耗时分位数。成功率不是成功任务除以全部任务。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

-- SQL①：WITH metric_tasks AS (...)
SELECT
  COUNT(*) AS task_count,
  COUNT(*) FILTER (WHERE status = 'succeeded') AS succeeded,
  COUNT(*) FILTER (WHERE status IN ('succeeded','failed')) AS terminal,
  COUNT(*) FILTER (WHERE status = 'reconciling') AS reconciling,
  COALESCE(SUM(output_count) FILTER (WHERE status = 'succeeded'), 0) AS outputs,
  COALESCE(SUM(settled_credits), 0) AS credits,
  COUNT(total_duration_ms) FILTER (WHERE status IN ('succeeded','failed')) AS duration_count,
  SUM(total_duration_ms) FILTER (WHERE status IN ('succeeded','failed')) AS duration_sum,
  MAX(updated_at) AS freshness
FROM metric_tasks;

-- SQL②：运行必须能匹配 filtered task 的非空 run_id 与相同所有者
SELECT COUNT(DISTINCT r.user_id), COUNT(*)
FROM analytics_generation_runs r
WHERE r.service_client_id = :project
  AND r.run_id IN (
    SELECT t.run_id FROM (:filtered_task_select) t
    WHERE t.run_id IS NOT NULL AND t.run_id <> '' AND t.user_id = r.user_id
  );

-- SQL③：WITH metric_tasks AS (...)
SELECT percentile_disc(0.50) WITHIN GROUP (ORDER BY total_duration_ms),
       percentile_disc(0.95) WITHIN GROUP (ORDER BY total_duration_ms)
FROM metric_tasks
WHERE status IN ('succeeded','failed') AND total_duration_ms IS NOT NULL;

-- Gateway 只用汇总标量组装响应
success_rate = succeeded / terminal              -- terminal=0 则 0
average_duration_ms = round(duration_sum / duration_count) -- 无样本则 null

这一步具体意味着什么

任务总数包含 reconciling、执行中等状态；成功率分母只含 succeeded 与 failed。
成功产出只累计成功任务的 output_count；积分累计所有过滤任务关联到的已结算分项。
活跃用户来自匹配运行的 DISTINCT run.user_id；无有效运行的任务不贡献该指标。
概览平均耗时、P50/P95只包含终态且耗时非空的样本。
这些 SQL 可重复引用同一构造表达式，但各次 execute 仍是独立查询，不应理解成 CTE 先执行一次。

固定提交源码

Gateway analytics/admin_routes.py:1063–1140。

04 分桶与分组

趋势按时间桶聚合；分布对 8 个维度各自 GROUP BY，再用 UNION ALL 形成一个带 dimension 字段的结果集。各维度不能相加当总任务数。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

-- trends：WITH metric_tasks AS (...)
SELECT date_trunc(:granularity, task_created_at, :timezone) AS bucket,
       COUNT(*) AS task_count,
       COUNT(*) FILTER (WHERE status='succeeded') AS succeeded,
       COUNT(*) FILTER (WHERE status='failed') AS failed,
       COUNT(*) FILTER (WHERE status='reconciling') AS reconciling,
       COALESCE(SUM(output_count) FILTER (WHERE status='succeeded'),0) AS outputs,
       COALESCE(SUM(settled_credits),0) AS credits,
       COUNT(total_duration_ms) AS duration_count,
       COALESCE(SUM(total_duration_ms),0) AS duration_sum
FROM metric_tasks GROUP BY bucket;
-- 返回后计算 round(duration_sum/duration_count)，并按桶标签排序

-- breakdowns：同一 metric_tasks，以下模板重复 8 个维度
SELECT 'model' AS dimension, COALESCE(NULLIF(model,''),'unknown') AS key,
       COUNT(*) AS task_count,
       COALESCE(SUM(output_count) FILTER (WHERE status='succeeded'),0) AS output_count,
       SUM(settled_credits) AS settled_credits, MAX(task_created_at) AS last_created
FROM metric_tasks GROUP BY key
UNION ALL
SELECT 'provider' AS dimension, ... FROM metric_tasks GROUP BY key
UNION ALL
... -- media_type / operation / status / failure_stage / failure_code / user_id

-- failure_stage、failure_code 分支另加 WHERE status='failed' AND 字段非空
-- SQL结果排序：dimension, task_count DESC, last_created DESC, key
-- Gateway拆成8组，用户榜另排：settled_credits DESC, task_count DESC, user_id

这一步具体意味着什么

PostgreSQL 在数据库执行 date_trunc 与 GROUP BY；不是把全部任务拿回前端按天分桶。
趋势平均耗时包含所有状态的非空耗时，与 overview 的终态分母不同；按当前实现如实展示。
单任务在模型、供应商、用户等每个维度各贡献一次，UNION ALL 并不把八种维度当同一维度合并。
一般维度空值/空串归入 unknown；失败维度仅统计明确失败且有失败字段的记录。

固定提交源码

Gateway analytics/admin_routes.py:1433–1507、1554–1614。

05 分页与积分

任务明细不是先拿一页再统计总数。它先对整个过滤范围 COUNT，再取当前页，最后仅为当前页补账单积分。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

-- tasks，不走 metric_tasks 总量CTE
SELECT COUNT(*) FROM (:filtered_task_select) AS filtered;
SELECT ... FROM analytics_generation_tasks
WHERE :same_authorization_and_filters
ORDER BY task_created_at DESC, task_id
OFFSET (:page-1)*:page_size LIMIT :page_size;

-- 只查询这一页引用的已结算计费分项，每批至多500个ID
SELECT id,service_client_id,business_task_id,settled_credits
FROM billing_authorization_items
WHERE status='settled' AND id IN (:current_page_billing_item_ids);
-- Gateway再核对 (service_client_id,task_id,billing_item_id) 三元组
-- 本页未匹配积分默认0；BFF补用户姓名，不改变total

-- 可选 runs 端点：先按运行分组，再计数/分页
SELECT run_id,user_id,COUNT(*),COUNT(*) FILTER (WHERE status='succeeded'),...
FROM (:filtered_task_select) AS t
WHERE run_id IS NOT NULL AND run_id<>''
GROUP BY run_id,user_id;
-- 与run表按 run_id 和 user_id 同时JOIN，并检查项目
-- COUNT 分组后的运行 → ORDER BY first_seen_at DESC,run_id → OFFSET/LIMIT

这一步具体意味着什么

total 与 items.length 是不同概念；page_size 只限制 items，不改变完整范围 total。
任务列表 output_count 原样显示单任务投影；成功产出汇总才附带 succeeded 条件。
普通列表不加载任务正文；超管隐藏口径的额外摘要/可见性说明不在本图主线。
runs 不是首屏四路 Promise.all 的默认请求；它的 total 是运行数，而不是任务数。

固定提交源码

Gateway analytics/admin_routes.py:613–644、1322–1375、1682–1706。

06 详情素材

保留原有详情与素材预览图：先个人授权，再用服务身份读取资产并签发短期下载地址。本轮只细化统计聚合，不改业务实现。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

个人 Bearer → 当前任务范围与素材关联
BFF 检查素材确属任务 → 服务 assets.get
比对资产 owner 与任务 user、检查图片/视频 MIME
服务 download → 短期签名 URL → 浏览器从私有 COS 加载

这一步具体意味着什么

服务凭证不会进入浏览器。
撤权阻止后续取签；已下载内容和尚未到期旧签名不被即时撤回。

固定提交源码

详见该原生图说明卡中的固定提交源码引用。

07 归属撤权

保留原有归属撤权图：历史查询按当前管理关系授权；旧管理员后续请求404，前端收到拒绝后清敏，并最多一次自动复核scope。

SQL 与口径对照

结构示意与源码等价，不是抓取的生产 SQL；参数均为占位符。

变更 parent_user_id 并提交
下一次请求重新解析当前权限和递归下属
旧管理员不在范围 → 404 → 前端清敏
新管理员在当前范围 → 可读接管前历史

这一步具体意味着什么

不是服务端推送即时清屏。
不搬钱包，不重写历史事实；只改变当前授权关系。

固定提交源码

详见该原生图说明卡中的固定提交源码引用。

下属生成统计 · 把“聚合”展开到 SQL

01 总调用链

02 过滤与计费

03 概览 COUNT / SUM

04 分桶与分组

06 详情素材

07 归属撤权

手算一次：同一天、都已通过授权过滤的四条示例任务

任务 / 用户	状态	产出	已结算积分	耗时
A / 用户甲	succeeded	2	10	1秒
B / 用户甲	failed	0	3	3秒
C / 用户乙	reconciling	0	0	10秒
D / 用户乙	succeeded	1	5	NULL