Files
lpt-be/src/main/java/com/guo/learningprogresstracker/service/impl/AiUsageServiceImpl.java
T
cat-shark 1ba3ae5a04 feat: 用量统计支持用户维度报表
- 新增 ai_usage_records.user_id 与 (user_id, occurred_at) 索引,NULL 表示未归属
- 归属标记跟着请求走:AiServiceClient 提交任务时带上顶层 callerRef(当前用户 id),
  lpt-ai 原样透传,上报后落到 user_id。取不到身份就不带,绝不让 AI 调用因此失败
- breakdown 支持 groupBy=user,新增 label(登录名,未归属为「未归属」);
  summary/series/breakdown 支持 userId 过滤
2026-10-10 20:28:04 +08:00

353 lines
16 KiB
Java
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package com.guo.learningprogresstracker.service.impl;
import cn.dev33.satoken.stp.StpUtil;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.guo.learningprogresstracker.common.TenantContext;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageBalance;
import com.guo.learningprogresstracker.dto.AiUsageBreakdownItem;
import com.guo.learningprogresstracker.dto.AiUsageBreakdownRow;
import com.guo.learningprogresstracker.dto.AiUsageIngestResult;
import com.guo.learningprogresstracker.dto.AiUsageSeriesPoint;
import com.guo.learningprogresstracker.dto.AiUsageSummary;
import com.guo.learningprogresstracker.dto.AiUsageSummaryRow;
import com.guo.learningprogresstracker.dto.request.AiUsageQuery;
import com.guo.learningprogresstracker.dto.request.AiUsageRecordRequest;
import com.guo.learningprogresstracker.entity.AiUsageRecordEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.mapper.AiUsageRecordMapper;
import com.guo.learningprogresstracker.service.AiUsageService;
import com.guo.learningprogresstracker.service.UserService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.stream.Collectors;
/**
* AI 用量统计实现。
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class AiUsageServiceImpl implements AiUsageService {
/** 契约 2.2:不传时间范围时看最近 30 天 */
private static final Duration DEFAULT_RANGE = Duration.ofDays(30);
private static final String BUCKET_DAY = "day";
private static final String BUCKET_HOUR = "hour";
private static final String GROUP_BY_TASK_TYPE = "taskType";
private static final String GROUP_BY_MODEL = "model";
private static final String GROUP_BY_USER = "user";
/** 未归属({@code user_id} 为 null)在面板上的展示名;契约 v2 第 4.2 节要求它单独可见 */
private static final String UNASSIGNED_LABEL = "未归属";
private final AiUsageRecordMapper aiUsageRecordMapper;
private final UserService userService;
private final AiUsageProperties properties;
private final AiUsageClient aiUsageClient;
// ============ 落库 ============
@Override
@Transactional(rollbackFor = Exception.class)
public AiUsageIngestResult ingest(List<AiUsageRecordRequest> records) throws ErrorParameterException {
if (records == null || records.isEmpty()) {
return new AiUsageIngestResult(0, 0);
}
// 先解析成实体:时间格式不对要在这里响亮失败,而不是写进半条脏数据
List<AiUsageRecordEntity> entities = new ArrayList<>(records.size());
for (AiUsageRecordRequest record : records) {
entities.add(toEntity(record));
}
Set<String> knownRecordIds = findExistingRecordIds(entities);
// 上报接口没有登录态(/internal/** 已排除 Sa-Token),公共字段填充去取 StpUtil 会抛异常;
// 这里显式声明「没有用户身份」,该表是系统级表,created_by 只是审计列,留空即可。
return TenantContext.callAs(null, null, () -> insertSkippingDuplicates(entities, knownRecordIds));
}
/** 批量取已存在的 recordId:这些就是本次要跳过的重复上报 */
private Set<String> findExistingRecordIds(List<AiUsageRecordEntity> entities) {
List<String> recordIds = entities.stream()
.map(AiUsageRecordEntity::getRecordId)
.collect(Collectors.toList());
return aiUsageRecordMapper.selectList(Wrappers.<AiUsageRecordEntity>lambdaQuery()
.select(AiUsageRecordEntity::getRecordId)
.in(AiUsageRecordEntity::getRecordId, recordIds))
.stream()
.map(AiUsageRecordEntity::getRecordId)
.collect(Collectors.toSet());
}
/**
* 逐条插入,跳过重复。
*
* <p>已在库里的、以及同一批里重复出现的 recordId 都算 duplicated;库里的唯一索引是最终防线,
* 并发下撞上它同样按「重复上报不报错」处理,不让整批数据白报。</p>
*/
private AiUsageIngestResult insertSkippingDuplicates(List<AiUsageRecordEntity> entities,
Set<String> knownRecordIds) {
Set<String> seen = new HashSet<>(knownRecordIds);
int accepted = 0;
int duplicated = 0;
for (AiUsageRecordEntity entity : entities) {
if (!seen.add(entity.getRecordId())) {
duplicated++;
continue;
}
try {
aiUsageRecordMapper.insert(entity);
accepted++;
} catch (DuplicateKeyException e) {
duplicated++;
}
}
if (duplicated > 0) {
log.info("AI 用量上报:落库 {} 条,跳过重复 {} 条", accepted, duplicated);
}
return new AiUsageIngestResult(accepted, duplicated);
}
private AiUsageRecordEntity toEntity(AiUsageRecordRequest record) throws ErrorParameterException {
AiUsageRecordEntity entity = new AiUsageRecordEntity();
entity.setRecordId(record.getRecordId());
entity.setOccurredAt(parseUtc(record.getOccurredAt()));
entity.setTaskType(record.getTaskType());
entity.setTaskId(record.getTaskId());
// 归属标记原样落库:lpt-ai 不解释它的含义,这里也不校验它是否真是个存在的用户——
// 查不到用户名时面板回退显示用户 id(见 breakdown),比把整条用量丢掉强
entity.setUserId(record.getCallerRef());
entity.setModel(record.getModel());
entity.setAttempts(record.getAttempts());
entity.setIsLlmCall(record.getIsLlmCall());
entity.setUsageSource(record.getUsageSource());
entity.setPromptTokens(record.getPromptTokens());
entity.setCompletionTokens(record.getCompletionTokens());
entity.setTotalTokens(record.getTotalTokens());
entity.setCacheHitTokens(record.getCacheHitTokens());
entity.setCacheMissTokens(record.getCacheMissTokens());
entity.setReasoningTokens(record.getReasoningTokens());
entity.setCostUsd(record.getCostUsd());
entity.setPricingVersion(record.getPricingVersion());
entity.setPeak(record.getPeak());
entity.setDurationMs(record.getDurationMs());
entity.setStatus(record.getStatus());
entity.setErrorCode(record.getErrorCode());
return entity;
}
/** 契约 1:occurredAt 是 ISO 8601 UTC 字符串,落库统一换算成 UTC 的本地时间 */
private static LocalDateTime parseUtc(String occurredAt) throws ErrorParameterException {
try {
return OffsetDateTime.parse(occurredAt.trim())
.withOffsetSameInstant(ZoneOffset.UTC)
.toLocalDateTime();
} catch (DateTimeParseException e) {
throw new ErrorParameterException("上报数据里的时间格式不对,需要 ISO 8601 UTC 时间");
}
}
// ============ 权限 ============
@Override
public boolean isAdmin() {
List<String> adminUsernames = properties.getAdminUsernames();
if (adminUsernames == null || adminUsernames.isEmpty()) {
return false;
}
// 登录态里是用户 id,白名单配的是用户名,需要这一次转换
String userName = userService.getUserNameById(StpUtil.getLoginIdAsString());
return userName != null && adminUsernames.contains(userName);
}
// ============ 聚合查询 ============
@Override
public AiUsageSummary summary(AiUsageQuery query) {
ResolvedFilter filter = resolve(query);
AiUsageSummaryRow row = aiUsageRecordMapper.selectSummary(
filter.from(), filter.to(), filter.taskType(), filter.model(), filter.userId());
Integer p95DurationMs = aiUsageRecordMapper.selectP95DurationMs(
filter.from(), filter.to(), filter.taskType(), filter.model(), filter.userId());
long cacheHitTokens = nullToZero(row.getCacheHitTokens());
long cacheMissTokens = nullToZero(row.getCacheMissTokens());
long cacheTotal = cacheHitTokens + cacheMissTokens;
BigDecimal costUsd = nullToZero(row.getCostUsd());
AiUsageSummary summary = new AiUsageSummary();
summary.setTotalCalls(nullToZero(row.getTotalCalls()));
summary.setSuccessCalls(nullToZero(row.getSuccessCalls()));
summary.setFailedCalls(nullToZero(row.getFailedCalls()));
summary.setPromptTokens(nullToZero(row.getPromptTokens()));
summary.setCompletionTokens(nullToZero(row.getCompletionTokens()));
summary.setTotalTokens(nullToZero(row.getTotalTokens()));
summary.setCacheHitTokens(cacheHitTokens);
summary.setCacheMissTokens(cacheMissTokens);
// 分母为 0 时给 null 而不是 0:面板要能区分「没数据」和「命中率为零」
summary.setCacheHitRate(cacheTotal == 0 ? null : (double) cacheHitTokens / cacheTotal);
summary.setCostUsd(costUsd);
summary.setCostCny(costUsd.multiply(properties.getUsdToCny()));
summary.setAvgDurationMs(row.getAvgDurationMs() == null ? null : Math.round(row.getAvgDurationMs()));
summary.setP95DurationMs(p95DurationMs == null ? null : p95DurationMs.longValue());
summary.setUnreportedUsageCalls(nullToZero(row.getUnreportedUsageCalls()));
return summary;
}
@Override
public List<AiUsageSeriesPoint> series(AiUsageQuery query) throws ErrorParameterException {
ResolvedFilter filter = resolve(query);
String bucket = requireBucket(query == null ? null : query.getBucket());
return aiUsageRecordMapper.selectSeries(
filter.from(), filter.to(), filter.taskType(), filter.model(), filter.userId(), bucket)
.stream()
.map(row -> {
AiUsageSeriesPoint point = new AiUsageSeriesPoint();
point.setBucket(row.getBucket());
point.setCalls(nullToZero(row.getCalls()));
point.setSuccessCalls(nullToZero(row.getSuccessCalls()));
point.setFailedCalls(nullToZero(row.getFailedCalls()));
point.setPromptTokens(nullToZero(row.getPromptTokens()));
point.setCompletionTokens(nullToZero(row.getCompletionTokens()));
point.setCostUsd(nullToZero(row.getCostUsd()));
return point;
})
.collect(Collectors.toList());
}
@Override
public List<AiUsageBreakdownItem> breakdown(AiUsageQuery query) throws ErrorParameterException {
ResolvedFilter filter = resolve(query);
String groupBy = requireGroupBy(query == null ? null : query.getGroupBy());
List<AiUsageBreakdownRow> rows = aiUsageRecordMapper.selectBreakdown(
filter.from(), filter.to(), filter.taskType(), filter.model(), filter.userId(), groupBy);
// groupBy=user 的分组键是用户 id,前端要显示登录名;一次批量查完,不要按分组逐条查
Map<String, String> userNames = GROUP_BY_USER.equals(groupBy) ? loadUserNames(rows) : Map.of();
return rows.stream()
.map(row -> toBreakdownItem(row, groupBy, userNames))
.collect(Collectors.toList());
}
/** 分组键就是用户 id:去重后一次查完登录名(未归属的 null 键不参与查询) */
private Map<String, String> loadUserNames(List<AiUsageBreakdownRow> rows) {
Set<String> userIds = rows.stream()
.map(AiUsageBreakdownRow::getGroupKey)
.filter(Objects::nonNull)
.collect(Collectors.toSet());
return userService.getUserNamesByIds(userIds);
}
private static AiUsageBreakdownItem toBreakdownItem(AiUsageBreakdownRow row, String groupBy,
Map<String, String> userNames) {
String key = row.getGroupKey();
AiUsageBreakdownItem item = new AiUsageBreakdownItem();
item.setKey(key);
item.setLabel(breakdownLabel(key, groupBy, userNames));
item.setCalls(nullToZero(row.getCalls()));
item.setSuccessCalls(nullToZero(row.getSuccessCalls()));
item.setFailedCalls(nullToZero(row.getFailedCalls()));
item.setPromptTokens(nullToZero(row.getPromptTokens()));
item.setCompletionTokens(nullToZero(row.getCompletionTokens()));
item.setCacheHitTokens(nullToZero(row.getCacheHitTokens()));
item.setCostUsd(nullToZero(row.getCostUsd()));
item.setAvgDurationMs(row.getAvgDurationMs() == null
? null : Math.round(row.getAvgDurationMs()));
return item;
}
/**
* 分组的展示名(契约 v2 第 4.2 节)。
*
* <p>非 user 分组下 label 就是 key:前端统一渲染 {@code label} 即可,不必按维度分支。
* user 分组下换成登录名;未归属(key 为 null)显示「未归属」,否则归属链路断了也看不出来;
* 查不到登录名时回退成用户 id,总比整行显示空白强。</p>
*/
private static String breakdownLabel(String key, String groupBy, Map<String, String> userNames) {
if (!GROUP_BY_USER.equals(groupBy)) {
return key;
}
if (key == null) {
return UNASSIGNED_LABEL;
}
return userNames.getOrDefault(key, key);
}
@Override
public AiUsageBalance balance() {
return aiUsageClient.fetchBalance();
}
/** 查询条件:时间范围补默认值(最近 30 天),并把 epoch millis 换算成 UTC 的本地时间 */
private ResolvedFilter resolve(AiUsageQuery query) {
Long from = query == null ? null : query.getFrom();
Long to = query == null ? null : query.getTo();
Instant now = Instant.now();
LocalDateTime fromTime = from == null
? LocalDateTime.ofInstant(now.minus(DEFAULT_RANGE), ZoneOffset.UTC)
: LocalDateTime.ofInstant(Instant.ofEpochMilli(from), ZoneOffset.UTC);
LocalDateTime toTime = to == null
? LocalDateTime.ofInstant(now, ZoneOffset.UTC)
: LocalDateTime.ofInstant(Instant.ofEpochMilli(to), ZoneOffset.UTC);
return new ResolvedFilter(fromTime, toTime,
query == null ? null : query.getTaskType(),
query == null ? null : query.getModel(),
query == null ? null : query.getUserId());
}
private static String requireBucket(String bucket) throws ErrorParameterException {
if (bucket == null || bucket.isBlank()) {
return BUCKET_DAY;
}
String value = bucket.trim();
if (!BUCKET_DAY.equals(value) && !BUCKET_HOUR.equals(value)) {
throw new ErrorParameterException("分桶粒度只支持 day 或 hour");
}
return value;
}
private static String requireGroupBy(String groupBy) throws ErrorParameterException {
if (groupBy == null || groupBy.isBlank()) {
return GROUP_BY_TASK_TYPE;
}
String value = groupBy.trim();
if (!GROUP_BY_TASK_TYPE.equals(value) && !GROUP_BY_MODEL.equals(value) && !GROUP_BY_USER.equals(value)) {
throw new ErrorParameterException("分组维度只支持 taskType、model 或 user");
}
return value;
}
private static long nullToZero(Long value) {
return value == null ? 0L : value;
}
private static BigDecimal nullToZero(BigDecimal value) {
return value == null ? BigDecimal.ZERO : value;
}
/** 解析后的查询条件(时间已转成 UTC 本地时间) */
private record ResolvedFilter(LocalDateTime from, LocalDateTime to, String taskType, String model, String userId) {
}
}