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 records) throws ErrorParameterException { if (records == null || records.isEmpty()) { return new AiUsageIngestResult(0, 0); } // 先解析成实体:时间格式不对要在这里响亮失败,而不是写进半条脏数据 List entities = new ArrayList<>(records.size()); for (AiUsageRecordRequest record : records) { entities.add(toEntity(record)); } Set knownRecordIds = findExistingRecordIds(entities); // 上报接口没有登录态(/internal/** 已排除 Sa-Token),公共字段填充去取 StpUtil 会抛异常; // 这里显式声明「没有用户身份」,该表是系统级表,created_by 只是审计列,留空即可。 return TenantContext.callAs(null, null, () -> insertSkippingDuplicates(entities, knownRecordIds)); } /** 批量取已存在的 recordId:这些就是本次要跳过的重复上报 */ private Set findExistingRecordIds(List entities) { List recordIds = entities.stream() .map(AiUsageRecordEntity::getRecordId) .collect(Collectors.toList()); return aiUsageRecordMapper.selectList(Wrappers.lambdaQuery() .select(AiUsageRecordEntity::getRecordId) .in(AiUsageRecordEntity::getRecordId, recordIds)) .stream() .map(AiUsageRecordEntity::getRecordId) .collect(Collectors.toSet()); } /** * 逐条插入,跳过重复。 * *

已在库里的、以及同一批里重复出现的 recordId 都算 duplicated;库里的唯一索引是最终防线, * 并发下撞上它同样按「重复上报不报错」处理,不让整批数据白报。

*/ private AiUsageIngestResult insertSkippingDuplicates(List entities, Set knownRecordIds) { Set 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 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 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 breakdown(AiUsageQuery query) throws ErrorParameterException { ResolvedFilter filter = resolve(query); String groupBy = requireGroupBy(query == null ? null : query.getGroupBy()); List rows = aiUsageRecordMapper.selectBreakdown( filter.from(), filter.to(), filter.taskType(), filter.model(), filter.userId(), groupBy); // groupBy=user 的分组键是用户 id,前端要显示登录名;一次批量查完,不要按分组逐条查 Map 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 loadUserNames(List rows) { Set 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 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 节)。 * *

非 user 分组下 label 就是 key:前端统一渲染 {@code label} 即可,不必按维度分支。 * user 分组下换成登录名;未归属(key 为 null)显示「未归属」,否则归属链路断了也看不出来; * 查不到登录名时回退成用户 id,总比整行显示空白强。

*/ private static String breakdownLabel(String key, String groupBy, Map 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) { } }