feat: 新增 AI 用量落库与统计接口

- 新增 ai_usage_records 表(系统级表,不按租户过滤)与幂等上报接口
- 新增按时间/任务类型/模型的汇总、趋势、明细查询,仅白名单用户可见
- 登录响应返回 aiAdmin,供前端决定是否展示入口
This commit is contained in:
2026-10-10 18:46:01 +08:00
parent 02d5c24946
commit 650b0956de
39 changed files with 2355 additions and 15 deletions
@@ -0,0 +1,307 @@
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.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.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 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());
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());
Integer p95DurationMs = aiUsageRecordMapper.selectP95DurationMs(
filter.from(), filter.to(), filter.taskType(), filter.model());
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(), 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());
return aiUsageRecordMapper.selectBreakdown(
filter.from(), filter.to(), filter.taskType(), filter.model(), groupBy)
.stream()
.map(row -> {
AiUsageBreakdownItem item = new AiUsageBreakdownItem();
item.setKey(row.getGroupKey());
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;
})
.collect(Collectors.toList());
}
@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());
}
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)) {
throw new ErrorParameterException("分组维度只支持 taskType 或 model");
}
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) {
}
}