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,29 @@
package com.guo.learningprogresstracker.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import java.math.BigDecimal;
import java.util.List;
/**
* AI 用量统计配置。
*/
@Data
@Configuration
@ConfigurationProperties(prefix = "lpt.ai-usage")
public class AiUsageProperties {
/** 可见「AI 用量统计」入口的用户名白名单(按 {@code user.user_name} 精确匹配) */
private List<String> adminUsernames = List.of("admin");
/** lpt-ai 上报用量时携带的令牌;为空表示不校验 */
private String reportToken = "";
/** 代理查询上游余额的超时(秒) */
private int balanceTimeoutSeconds = 10;
/** 费用展示用的美元兑人民币汇率:{@code costCny = costUsd × 该值} */
private BigDecimal usdToCny = BigDecimal.valueOf(7);
}
@@ -23,13 +23,18 @@ import java.util.List;
public class MybatisPlusConfig {
/**
* 不需要租户过滤的表(仅排除不含 created_by 的系统表)
* 不需要租户过滤的表(仅排除不含 created_by 或不该按 created_by 过滤的表)
*
* <p>{@code ai_usage_records} 是系统级表:记录由 lpt-ai 通过内部接口上报,请求里没有登录用户,
* created_by 只是审计列;用量又是运维口径——管理员要看的是**全部**调用。
* 若按 created_by 过滤,每个人只能看到自己触发的那几次调用,面板等于永远空的。</p>
*/
private static final List<String> EXCLUDE_TABLES = Arrays.asList(
"user",
"flyway_schema_history",
"databasechangelog",
"databasechangeloglock"
"databasechangeloglock",
"ai_usage_records"
);
@Bean
@@ -28,7 +28,9 @@ public class WebMvcConfig implements WebMvcConfigurer {
StpUtil.checkLogin();
}))
.addPathPatterns("/**")
.excludePathPatterns("/login");
// /login:登录接口本身不能要求登录态;
// /internal/**:服务间接口(lpt-ai 用量上报),调用方没有登录态,改用 x-api-token 自校验
.excludePathPatterns("/login", "/internal/**");
}
@Override
@@ -0,0 +1,72 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.AiUsageBalance;
import com.guo.learningprogresstracker.dto.AiUsageBreakdownItem;
import com.guo.learningprogresstracker.dto.AiUsagePermission;
import com.guo.learningprogresstracker.dto.AiUsageSeriesPoint;
import com.guo.learningprogresstracker.dto.AiUsageSummary;
import com.guo.learningprogresstracker.dto.request.AiUsageQuery;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.AiUsageService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
/**
* 「AI 用量统计」面板查询接口(契约 2)。
*
* <p>用量记录是系统级数据,只有白名单用户能看:{@code permission} 用 {@code allowed=false}
* 让前端静默隐藏入口,其余接口直接拒绝,避免入口藏起来了、接口却谁都能拉。</p>
*/
@RestController
@RequestMapping("/ai/usage")
@RequiredArgsConstructor
public class AiUsageController {
private static final String NO_PERMISSION_MESSAGE = "没有查看权限";
private final AiUsageService aiUsageService;
/** 当前用户能否查看用量面板;非白名单返回 200 + allowed=false */
@GetMapping("/permission")
public CommonResult<AiUsagePermission> permission() {
return CommonResult.success(new AiUsagePermission(aiUsageService.isAdmin()));
}
@GetMapping("/summary")
public CommonResult<AiUsageSummary> summary(AiUsageQuery query) {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.summary(query));
}
@GetMapping("/series")
public CommonResult<List<AiUsageSeriesPoint>> series(AiUsageQuery query) throws ErrorParameterException {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.series(query));
}
@GetMapping("/breakdown")
public CommonResult<List<AiUsageBreakdownItem>> breakdown(AiUsageQuery query) throws ErrorParameterException {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.breakdown(query));
}
/** 上游余额;lpt-ai 未配置或查询失败时返回 {@code configured=false},不算错误 */
@GetMapping("/balance")
public CommonResult<AiUsageBalance> balance() {
if (!aiUsageService.isAdmin()) {
return CommonResult.error(NO_PERMISSION_MESSAGE);
}
return CommonResult.success(aiUsageService.balance());
}
}
@@ -0,0 +1,62 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageIngestResult;
import com.guo.learningprogresstracker.dto.request.AiUsageRecordRequest;
import com.guo.learningprogresstracker.dto.request.AiUsageReportRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.AiUsageService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
/**
* lpt-ai 用量上报(契约 1)。
*
* <p>这是服务间接口,不是用户接口:调用方是 lpt-ai 进程,没有登录态,
* 因此 {@code /internal/**} 已在 {@code WebMvcConfig} 中排除 Sa-Token 登录校验,
* 改用 {@code x-api-token} 与 {@code lpt.ai-usage.report-token} 比对(配置为空表示不校验)。</p>
*/
@RestController
@RequestMapping("/internal/ai-usage")
@RequiredArgsConstructor
public class AiUsageInternalController {
/** 契约 1:单次最多 200 条 */
static final int MAX_RECORDS_PER_REPORT = 200;
private final AiUsageService aiUsageService;
private final AiUsageProperties properties;
/**
* 上报用量记录。
*
* <p>按 {@code recordId} 幂等:重复上报不报错,只在结果里体现为 {@code duplicated}。</p>
*/
@PostMapping("/records")
public CommonResult<AiUsageIngestResult> report(
@RequestHeader(name = "x-api-token", required = false) String apiToken,
@Valid @RequestBody AiUsageReportRequest request) throws ErrorParameterException {
if (!isTokenAccepted(apiToken)) {
return CommonResult.error("上报令牌不正确");
}
List<AiUsageRecordRequest> records = request.getRecords();
if (records.size() > MAX_RECORDS_PER_REPORT) {
return CommonResult.error("单次最多上报 " + MAX_RECORDS_PER_REPORT + " 条记录");
}
return CommonResult.success(aiUsageService.ingest(records));
}
/** 契约 1:report-token 为空表示 lpt-ai 未启用令牌校验,直接放行 */
private boolean isTokenAccepted(String apiToken) {
String expected = properties.getReportToken();
return expected == null || expected.isBlank() || expected.equals(apiToken);
}
}
@@ -1,8 +1,10 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.LoginResult;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.dto.request.LoginBody;
import com.guo.learningprogresstracker.exception.AppException;
import com.guo.learningprogresstracker.service.AiUsageService;
import com.guo.learningprogresstracker.service.LoginService;
import com.guo.learningprogresstracker.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
@@ -20,14 +22,17 @@ public class LoginController {
private final LoginService loginService;
private final UserService userServiceImpl;
private final AiUsageService aiUsageService;
@Operation(summary = "登录API")
@PostMapping("/login")
public CommonResult<String> login(@RequestBody LoginBody loginBody) throws AppException {
public CommonResult<LoginResult> login(@RequestBody LoginBody loginBody) throws AppException {
String userId = userServiceImpl.authenticate(loginBody.getUsername(), loginBody.getPassword());
String token = loginService.login(userId);
// 用量面板的入口是否显示由服务端白名单决定,前端只读这个布尔值
boolean aiAdmin = aiUsageService.isAdmin();
//todo 参数传递未加密
return CommonResult.success("登录成功!", token);
return CommonResult.success("登录成功!", new LoginResult(token, aiAdmin));
}
@Operation(summary = "退出登录API")
@@ -0,0 +1,35 @@
package com.guo.learningprogresstracker.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;
/**
* DeepSeek 账户余额(契约 2.5,{@code GET /ai/usage/balance})。
*
* <p>由 lpt-be 代理 lpt-ai 的 {@code GET /admin/usage/balance};上游未配置或调用失败时只有
* {@code configured=false} 一个字段,因此这里用 {@code NON_NULL} 让其余字段直接不出现,
* 与契约给的响应体形状一致。</p>
*/
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class AiUsageBalance {
/** 上游是否可用:false 表示 lpt-ai 未配置 API Key 或本次查询失败 */
private boolean configured;
private String currency;
private String totalBalance;
private String grantedBalance;
private String toppedUpBalance;
/** 上游取数时间(ISO 8601 UTC) */
private String fetchedAt;
/** 上游不可用时的唯一响应:{@code {"configured": false}} */
public static AiUsageBalance notConfigured() {
return new AiUsageBalance();
}
}
@@ -0,0 +1,32 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量按任务类型 / 模型分组的一项(契约 2.4,{@code GET /ai/usage/breakdown})。
*/
@Data
public class AiUsageBreakdownItem {
/** 分组键:{@code groupBy=taskType} 时是任务类型,{@code groupBy=model} 时是模型名 */
private String key;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long cacheHitTokens;
private BigDecimal costUsd;
/** 平均调用耗时(毫秒);该分组无调用时为 null */
private Long avgDurationMs;
}
@@ -0,0 +1,32 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量按任务类型 / 模型分组的聚合结果(Mapper 层直接映射,契约 2.4)。
*/
@Data
public class AiUsageBreakdownRow {
/** 分组键:{@code groupBy=taskType} 时是任务类型,{@code groupBy=model} 时是模型名 */
private String groupKey;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long cacheHitTokens;
private BigDecimal costUsd;
/** SQL 的 AVG 结果,由 service 取整后返回 */
private Double avgDurationMs;
}
@@ -0,0 +1,18 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 用量上报结果(契约 1):本次请求实际落库与因幂等跳过的条数。
*/
@Data
@AllArgsConstructor
public class AiUsageIngestResult {
/** 本次新落库的条数 */
private int accepted;
/** 因 {@code recordId} 已存在而跳过的条数 */
private int duplicated;
}
@@ -0,0 +1,18 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 当前用户能否查看「AI 用量统计」(契约 2.1,{@code GET /ai/usage/permission})。
*
* <p>非白名单也返回 HTTP 200 + {@code allowed=false},前端据此静默隐藏入口,
* 不需要为一个「看不见的按钮」处理报错。</p>
*/
@Data
@AllArgsConstructor
public class AiUsagePermission {
/** 用户名是否命中 {@code lpt.ai-usage.admin-usernames} */
private boolean allowed;
}
@@ -0,0 +1,27 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量趋势的一个分桶(契约 2.3,{@code GET /ai/usage/series})。
*/
@Data
public class AiUsageSeriesPoint {
/** day:{@code yyyy-MM-dd};hour:{@code yyyy-MM-dd HH:00} */
private String bucket;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private BigDecimal costUsd;
}
@@ -0,0 +1,30 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量趋势的分桶聚合结果(Mapper 层直接映射,契约 2.3)。
*
* <p>{@code bucket} 是计算列(按天/按小时格式化后的字符串),必须由显式
* {@code <resultMap>} 映射。</p>
*/
@Data
public class AiUsageSeriesRow {
/** day:{@code yyyy-MM-dd};hour:{@code yyyy-MM-dd HH:00} */
private String bucket;
private Long calls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private BigDecimal costUsd;
}
@@ -0,0 +1,47 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* AI 用量汇总(契约 2.2,{@code GET /ai/usage/summary})。
*
* <p>只统计真正消耗 LLM 的调用({@code is_llm_call = 1})。</p>
*/
@Data
public class AiUsageSummary {
private Long totalCalls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long totalTokens;
private Long cacheHitTokens;
private Long cacheMissTokens;
/** 缓存命中率 = 命中 /(命中 + 未命中);分母为 0 时为 null(不是 0,避免被读成「命中率为零」) */
private Double cacheHitRate;
private BigDecimal costUsd;
/** 按 {@code lpt.ai-usage.usd-to-cny} 换算的展示金额 */
private BigDecimal costCny;
/** 平均调用耗时(毫秒);无调用时为 null */
private Long avgDurationMs;
/** P95 调用耗时(毫秒,最近秩法);无调用时为 null */
private Long p95DurationMs;
/** 上游没上报 token 的调用数({@code prompt_tokens IS NULL}),面板据此显示「未上报」 */
private Long unreportedUsageCalls;
}
@@ -0,0 +1,39 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
import java.math.BigDecimal;
/**
* 用量汇总的聚合结果(Mapper 层直接映射,契约 2.2)。
*
* <p>列名与属性不一致(别名、计算列),因此由 {@code AiUsageRecordMapper.xml} 的显式
* {@code <resultMap>} 承载映射,不依赖下划线转驼峰。</p>
*/
@Data
public class AiUsageSummaryRow {
private Long totalCalls;
private Long successCalls;
private Long failedCalls;
private Long promptTokens;
private Long completionTokens;
private Long totalTokens;
private Long cacheHitTokens;
private Long cacheMissTokens;
/** 未上报用量的调用数({@code prompt_tokens IS NULL}) */
private Long unreportedUsageCalls;
private BigDecimal costUsd;
/** SQL 的 AVG 结果,由 service 取整后返回 */
private Double avgDurationMs;
}
@@ -0,0 +1,20 @@
package com.guo.learningprogresstracker.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
/**
* 登录结果。
*
* <p>除 token 外额外下发 {@code aiAdmin}:前端据此决定是否显示「AI 用量统计」入口
* (契约 5,白名单口径在服务端,前端不自己判断)。</p>
*/
@Data
@AllArgsConstructor
public class LoginResult {
private String token;
/** 该用户是否在 {@code lpt.ai-usage.admin-usernames} 白名单里 */
private boolean aiAdmin;
}
@@ -0,0 +1,28 @@
package com.guo.learningprogresstracker.dto.request;
import lombok.Data;
/**
* 用量查询条件(契约 2.2 / 2.3 / 2.4):summary、series、breakdown 共用同一组筛选参数。
*/
@Data
public class AiUsageQuery {
/** 起始时刻(epoch millis);为空表示最近 30 天 */
private Long from;
/** 结束时刻(epoch millis);为空表示「到此刻为止」 */
private Long to;
/** 任务类型,精确匹配;为空表示不限 */
private String taskType;
/** 模型名,精确匹配;为空表示不限 */
private String model;
/** series 的分桶粒度:day / hour */
private String bucket = "day";
/** breakdown 的分组维度:taskType / model */
private String groupBy = "taskType";
}
@@ -0,0 +1,76 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;
import java.math.BigDecimal;
/**
* 一条 AI 用量记录(契约 1)。
*
* <p>token 类字段一律包装类型:{@code null} 表示上游未上报,{@code 0} 表示上游明确上报为 0,
* 两者语义不同,不得用 0 顶替 null。</p>
*/
@Data
public class AiUsageRecordRequest {
/** 幂等键,lpt-ai 生成 */
@NotBlank(message = "recordId 不能为空")
private String recordId;
/** 调用发生时间,ISO 8601 UTC,如 {@code 2026-10-10T09:38:23.543Z} */
@NotBlank(message = "occurredAt 不能为空")
private String occurredAt;
@NotBlank(message = "taskType 不能为空")
private String taskType;
private String taskId;
/**
* 模型名。
*
* <p>用 {@code @NotNull} 而不是 {@code @NotBlank}:{@code isLlmCall=false} 的记录
* (如 {@code /fetch-title})本来就没调用模型,契约里它的 model 就是空串。
* 用 {@code @NotBlank} 会让这一条把整批上报打成 400,而上报方会把 400 当成可重试错误,
* outbox 被永久堵死。</p>
*/
@NotNull(message = "model 不能为空")
private String model;
@NotNull(message = "attempts 不能为空")
private Integer attempts;
@NotNull(message = "isLlmCall 不能为空")
private Boolean isLlmCall;
@NotBlank(message = "usageSource 不能为空")
private String usageSource;
private Integer promptTokens;
private Integer completionTokens;
private Integer totalTokens;
private Integer cacheHitTokens;
private Integer cacheMissTokens;
private Integer reasoningTokens;
private BigDecimal costUsd;
private String pricingVersion;
private Boolean peak;
@NotNull(message = "durationMs 不能为空")
private Integer durationMs;
@NotNull(message = "status 不能为空")
private Integer status;
private String errorCode;
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import lombok.Data;
import java.util.List;
/**
* lpt-ai 用量上报请求体(契约 1,{@code POST /internal/ai-usage/records})。
*/
@Data
public class AiUsageReportRequest {
/** 单次最多 200 条(见 {@code AiUsageInternalController.MAX_RECORDS_PER_REPORT}) */
@NotNull(message = "records 不能为空")
@Valid
private List<AiUsageRecordRequest> records;
}
@@ -0,0 +1,111 @@
package com.guo.learningprogresstracker.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.io.Serializable;
import java.math.BigDecimal;
import java.time.LocalDateTime;
/**
* AI 用量记录:lpt-ai 每完成一次 AI 任务后上报一条,供「AI 用量统计」面板聚合。
*
* <p><b>系统级表</b>:已加入 {@code MybatisPlusConfig.EXCLUDE_TABLES},不做按 {@code created_by}
* 的租户过滤——用量是运维口径,面板展示的是全部调用,而不是当前用户自己触发的那几次。</p>
*
* <p>token 类字段一律用包装类型:{@code null} 表示上游没上报,{@code 0} 表示上游明确上报为 0,
* 两者语义不同,不得用 0 顶替 null(面板要能显示「未上报」的调用数)。</p>
*/
@TableName(value = "ai_usage_records")
@Data
public class AiUsageRecordEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 幂等键:lpt-ai 生成的 UUID,重复上报直接跳过 */
@TableField(value = "record_id")
private String recordId;
/** 调用发生时间(UTC) */
@TableField(value = "occurred_at")
private LocalDateTime occurredAt;
/** 任务类型:aggregate-report/generate-mind-map/compare-recall/guidance/fetch-title */
@TableField(value = "task_type")
private String taskType;
/** lpt-ai 任务 id */
@TableField(value = "task_id")
private String taskId;
/** 模型名,如 deepseek-flash */
@TableField(value = "model")
private String model;
/** 本次任务实际发起的 LLM 调用次数(含失败重试) */
@TableField(value = "attempts")
private Integer attempts;
/** 是否消耗 LLM;false 表示没调用(如 /fetch-title) */
@TableField(value = "is_llm_call")
private Boolean isLlmCall;
/** 用量来源:upstream=上游返回 / estimated=估算 / missing=上游未给 */
@TableField(value = "usage_source")
private String usageSource;
/** 输入 token;null=未上报 */
@TableField(value = "prompt_tokens")
private Integer promptTokens;
/** 输出 token;null=未上报 */
@TableField(value = "completion_tokens")
private Integer completionTokens;
/** 总 token;null=未上报 */
@TableField(value = "total_tokens")
private Integer totalTokens;
/** 命中缓存的输入 token;null=未上报 */
@TableField(value = "cache_hit_tokens")
private Integer cacheHitTokens;
/** 未命中缓存的输入 token;null=未上报 */
@TableField(value = "cache_miss_tokens")
private Integer cacheMissTokens;
/** 推理 token;null=未上报 */
@TableField(value = "reasoning_tokens")
private Integer reasoningTokens;
/** 本次费用(USD),上报时算好并冻结 */
@TableField(value = "cost_usd")
private BigDecimal costUsd;
/** 计价表版本 */
@TableField(value = "pricing_version")
private String pricingVersion;
/** 是否按峰时价计费 */
@TableField(value = "peak")
private Boolean peak;
/** 本次调用耗时(毫秒) */
@TableField(value = "duration_ms")
private Integer durationMs;
/** 调用结果:200 成功,其余失败 */
@TableField(value = "status")
private Integer status;
/** 失败分类,如 timeout/rate_limited/upstream_error */
@TableField(value = "error_code")
private String errorCode;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
}
@@ -0,0 +1,75 @@
package com.guo.learningprogresstracker.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.guo.learningprogresstracker.dto.AiUsageBreakdownRow;
import com.guo.learningprogresstracker.dto.AiUsageSeriesRow;
import com.guo.learningprogresstracker.dto.AiUsageSummaryRow;
import com.guo.learningprogresstracker.entity.AiUsageRecordEntity;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import java.time.LocalDateTime;
import java.util.List;
/**
* AI 用量记录 Mapper。
*
* <p>SUM / GROUP BY 这类 {@code Wrapper} 表达不了的查询下沉到这里,用自定义 SQL + 显式结果类,
* 语句见 {@code resources/mapper/AiUsageRecordMapper.xml}。</p>
*
* <p>两个前提条件写在 SQL 里而不是靠框架:自定义 SQL 不会被 {@code @TableLogic} 追加条件,
* 因此每处都显式写 {@code deleted = 0};而 {@code created_by} 租户条件<strong>不能</strong>出现——
* 本表已在 {@code MybatisPlusConfig.EXCLUDE_TABLES} 中,用量是运维口径,面板展示的是全部调用。</p>
*/
@Mapper
public interface AiUsageRecordMapper extends BaseMapper<AiUsageRecordEntity> {
/**
* 汇总用量(契约 2.2)。
*
* @param from 起始时刻(含);null 表示不限
* @param to 结束时刻(含);null 表示不限
* @param taskType 任务类型精确匹配;null 表示不限
* @param model 模型名精确匹配;null 表示不限
* @return 无匹配记录时返回全 0 的一行(AVG 为 null)
*/
AiUsageSummaryRow selectSummary(@Param("from") LocalDateTime from,
@Param("to") LocalDateTime to,
@Param("taskType") String taskType,
@Param("model") String model);
/**
* P95 调用耗时(毫秒,最近秩法:取第 {@code ceil(0.95 × 调用数)} 小的耗时)。
*
* <p>MySQL 与 H2 都没有通用的百分位聚合函数,这里用窗口函数先给耗时排名,
* 再取第一个越过 95% 位次的行;两库都支持该写法(有落库集成测试守住)。</p>
*
* @return 无匹配记录时返回 null
*/
Integer selectP95DurationMs(@Param("from") LocalDateTime from,
@Param("to") LocalDateTime to,
@Param("taskType") String taskType,
@Param("model") String model);
/**
* 按天或按小时分桶的用量趋势(契约 2.3)。
*
* @param bucket {@code day}(默认)或 {@code hour}
*/
List<AiUsageSeriesRow> selectSeries(@Param("from") LocalDateTime from,
@Param("to") LocalDateTime to,
@Param("taskType") String taskType,
@Param("model") String model,
@Param("bucket") String bucket);
/**
* 按任务类型或模型分组的用量(契约 2.4)。
*
* @param groupBy {@code taskType}(默认)或 {@code model}
*/
List<AiUsageBreakdownRow> selectBreakdown(@Param("from") LocalDateTime from,
@Param("to") LocalDateTime to,
@Param("taskType") String taskType,
@Param("model") String model,
@Param("groupBy") String groupBy);
}
@@ -0,0 +1,43 @@
package com.guo.learningprogresstracker.service;
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.request.AiUsageQuery;
import com.guo.learningprogresstracker.dto.request.AiUsageRecordRequest;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import java.util.List;
/**
* AI 用量统计(落库 + 聚合 + 余额代理)。
*
* <p>用量记录是系统级数据(不按用户隔离),但查询接口只对白名单用户开放,
* 白名单口径见 {@code lpt.ai-usage.admin-usernames}。</p>
*/
public interface AiUsageService {
/**
* 落库 lpt-ai 上报的用量记录,按 {@code recordId} 幂等(已存在的直接跳过)。
*
* @return 本次新落库与跳过的条数
*/
AiUsageIngestResult ingest(List<AiUsageRecordRequest> records) throws ErrorParameterException;
/** 当前登录用户是否在用量面板白名单里 */
boolean isAdmin();
/** 用量汇总(契约 2.2) */
AiUsageSummary summary(AiUsageQuery query);
/** 按天/按小时的用量趋势(契约 2.3) */
List<AiUsageSeriesPoint> series(AiUsageQuery query) throws ErrorParameterException;
/** 按任务类型/模型的用量分组(契约 2.4) */
List<AiUsageBreakdownItem> breakdown(AiUsageQuery query) throws ErrorParameterException;
/** 代理查询上游余额(契约 2.5);上游不可用时返回 {@code configured=false} */
AiUsageBalance balance();
}
@@ -18,4 +18,14 @@ public interface UserService extends IService<UserEntity> {
* @return
*/
String authenticate(String username, String password) throws AppException;
/**
* 按用户 id 取登录名。
*
* <p>登录态里只有用户 id,而「AI 用量统计」白名单按用户名配置(见
* {@code lpt.ai-usage.admin-usernames}),需要这一次转换。</p>
*
* @return 用户不存在时返回 null
*/
String getUserNameById(String userId);
}
@@ -0,0 +1,96 @@
package com.guo.learningprogresstracker.service.impl;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageBalance;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
/**
* lpt-ai 用量相关接口的客户端。
*
* <p>只做一件事:代理 lpt-ai 的 {@code GET /admin/usage/balance}(契约 2.5 / 3)。
* 单独一个客户端而不是塞进 {@link AiServiceClient},是因为后者的职责是「提交 AI 任务并等结果」,
* 与运维面板取数是两件事;地址与令牌仍复用 {@code lpt.ai-service} 的配置项,不新增一份配置来源。</p>
*
* <p>上游未配置或调用失败一律返回 {@code configured=false}:余额是面板上的附加信息,
* 拿不到就显示「未配置」,不该让整个页面报错。</p>
*/
@Slf4j
@Component
@RequiredArgsConstructor
@ConfigurationProperties(prefix = "lpt.ai-service")
@Setter
public class AiUsageClient {
/** lpt-ai 服务地址,如 http://localhost:5199 */
private String url;
/** 与 {@link AiServiceClient} 共用的入站令牌;为空表示不携带 */
private String token;
private final AiUsageProperties usageProperties;
private final HttpClient httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
private final ObjectMapper objectMapper = new ObjectMapper();
/**
* 查询 DeepSeek 账户余额。
*
* @return 上游未配置、超时、非 200 或响应无法解析时返回 {@code configured=false}
*/
public AiUsageBalance fetchBalance() {
if (url == null || url.isBlank()) {
return AiUsageBalance.notConfigured();
}
try {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url + "/admin/usage/balance"))
.timeout(Duration.ofSeconds(usageProperties.getBalanceTimeoutSeconds()))
.header("x-api-token", token == null ? "" : token.trim())
.GET()
.build();
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
log.warn("lpt-ai 查询余额失败: status={}", response.statusCode());
return AiUsageBalance.notConfigured();
}
JsonNode json = objectMapper.readTree(response.body());
if (!json.path("configured").asBoolean(false)) {
return AiUsageBalance.notConfigured();
}
AiUsageBalance balance = new AiUsageBalance();
balance.setConfigured(true);
balance.setCurrency(textOrNull(json, "currency"));
balance.setTotalBalance(textOrNull(json, "totalBalance"));
balance.setGrantedBalance(textOrNull(json, "grantedBalance"));
balance.setToppedUpBalance(textOrNull(json, "toppedUpBalance"));
balance.setFetchedAt(textOrNull(json, "fetchedAt"));
return balance;
} catch (Exception e) {
log.warn("lpt-ai 查询余额异常: {}", e.getMessage());
return AiUsageBalance.notConfigured();
}
}
/** 金额一律按上游给的字符串透传,避免在 lpt-be 侧对金额做浮点转换 */
private static String textOrNull(JsonNode node, String field) {
return node.path(field).asText(null);
}
}
@@ -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) {
}
}
@@ -33,4 +33,13 @@ public class UserServiceImpl extends ServiceImpl<UserMapper, UserEntity>
return userEntity.getId();
}
@Override
public String getUserNameById(String userId) {
if (userId == null || userId.isBlank()) {
return null;
}
UserEntity userEntity = getById(userId);
return userEntity == null ? null : userEntity.getUserName();
}
}
+12 -1
View File
@@ -92,4 +92,15 @@ lpt:
# 立即投递线程池
executor-core-size: 2
executor-max-size: 4
executor-queue-capacity: 50
executor-queue-capacity: 50
# AI 用量统计:lpt-ai 上报调用记录,本服务落库并聚合给白名单用户看
ai-usage:
# 可见「AI 用量统计」入口的用户名白名单(按 user.user_name 精确匹配)
admin-usernames:
- admin
# lpt-ai 上报用量时携带的令牌;为空表示不校验
report-token: ""
# 代理查询上游余额的超时(秒)
balance-timeout-seconds: 10
# 费用展示用的美元兑人民币汇率(costCny = costUsd × 该值)
usd-to-cny: 7
@@ -0,0 +1,49 @@
-- AI 用量统计:lpt-ai 每次调用 LLM 后上报一条记录,本表落库,供「AI 用量统计」面板聚合展示。
--
-- 这是**系统级表**,必须加入 MybatisPlusConfig.EXCLUDE_TABLES,不能按 created_by 做租户过滤:
-- 1. 记录由 lpt-ai 通过内部接口 POST /internal/ai-usage/records 上报,请求里没有登录用户,
-- created_by 只是审计列(可能为空),拿它当租户键等于「每行一个不存在的租户」;
-- 2. 用量是运维口径——每个用户能看到的是**全部**调用,而不是自己触发的那几次。
-- 若按 created_by 过滤,管理员登录后只能看到自己点出来的调用,面板永远是空的。
--
-- token 列一律可空,null 表示「上游没上报」,与 0(上游明确上报为 0)语义不同,不得用 0 顶替。
CREATE TABLE ai_usage_records
(
id INT AUTO_INCREMENT COMMENT 'id无业务含义'
PRIMARY KEY,
record_id VARCHAR(64) NOT NULL COMMENT '幂等键:lpt-ai 生成的 UUID,重复上报直接跳过',
occurred_at DATETIME(3) NOT NULL COMMENT '调用发生时间(UTC)',
task_type VARCHAR(50) NOT NULL COMMENT '任务类型:aggregate-report/generate-mind-map/compare-recall/guidance/fetch-title',
task_id VARCHAR(64) NULL COMMENT 'lpt-ai 任务 id',
model VARCHAR(100) NOT NULL COMMENT '模型名,如 deepseek-flash',
attempts INT NOT NULL COMMENT '本次任务实际发起的 LLM 调用次数(含失败重试)',
is_llm_call TINYINT(1) NOT NULL COMMENT '是否消耗 LLM:0 表示没调用(如 /fetch-title)',
usage_source VARCHAR(20) NOT NULL COMMENT '用量来源:upstream=上游返回 / estimated=估算 / missing=上游未给',
prompt_tokens INT NULL COMMENT '输入 token;NULL=未上报,0=上游明确上报为 0',
completion_tokens INT NULL COMMENT '输出 token;NULL=未上报',
total_tokens INT NULL COMMENT '总 token;NULL=未上报',
cache_hit_tokens INT NULL COMMENT '命中缓存的输入 token;NULL=未上报',
cache_miss_tokens INT NULL COMMENT '未命中缓存的输入 token;NULL=未上报',
reasoning_tokens INT NULL COMMENT '推理 token;NULL=未上报',
cost_usd DECIMAL(18, 8) NULL COMMENT '本次费用(USD),上报时按当期价目算好并冻结,后续改价不改历史',
pricing_version VARCHAR(50) NULL COMMENT '计价表版本',
peak TINYINT(1) NULL COMMENT '是否按峰时价计费',
duration_ms INT NOT NULL COMMENT '本次调用耗时(毫秒)',
status INT NOT NULL COMMENT '调用结果:200 成功,其余失败',
error_code VARCHAR(50) NULL COMMENT '失败分类,如 timeout/rate_limited/upstream_error',
created_time DATETIME NOT NULL COMMENT '落库时间',
created_by VARCHAR(255) NULL COMMENT '审计列;上报请求没有登录用户,可能为空,不参与任何过滤',
last_modified_time DATETIME NULL,
last_modified_by VARCHAR(255) NULL,
device_info VARCHAR(50) NULL COMMENT '操作者设备类型',
deleted INT DEFAULT 0 NOT NULL COMMENT '逻辑删除符',
-- 幂等:同一 record_id 重复上报不报错、不产生第二行
UNIQUE KEY uk_ai_usage_records_record_id (record_id),
-- 面板默认按时间范围取数(最近 30 天)
KEY idx_ai_usage_records_occurred (occurred_at),
-- 按任务类型筛选 + 时间范围
KEY idx_ai_usage_records_type_occurred (task_type, occurred_at),
-- 按模型筛选 + 时间范围
KEY idx_ai_usage_records_model_occurred (model, occurred_at)
)
COMMENT 'AI 用量记录(系统级表:不按租户过滤,面板展示的是全部调用)';
@@ -0,0 +1,147 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.guo.learningprogresstracker.mapper.AiUsageRecordMapper">
<!--
聚合结果一律用显式 <resultMap>:这里的列名是别名与计算列(total_calls、bucket、group_key),
不依赖 map-underscore-to-camel-case,也不依赖各数据库对标识符大小写的处理规则。
-->
<resultMap id="AiUsageSummaryRowMap" type="com.guo.learningprogresstracker.dto.AiUsageSummaryRow">
<result property="totalCalls" column="total_calls" jdbcType="BIGINT"/>
<result property="successCalls" column="success_calls" jdbcType="BIGINT"/>
<result property="failedCalls" column="failed_calls" jdbcType="BIGINT"/>
<result property="promptTokens" column="prompt_tokens" jdbcType="BIGINT"/>
<result property="completionTokens" column="completion_tokens" jdbcType="BIGINT"/>
<result property="totalTokens" column="total_tokens" jdbcType="BIGINT"/>
<result property="cacheHitTokens" column="cache_hit_tokens" jdbcType="BIGINT"/>
<result property="cacheMissTokens" column="cache_miss_tokens" jdbcType="BIGINT"/>
<result property="unreportedUsageCalls" column="unreported_usage_calls" jdbcType="BIGINT"/>
<result property="costUsd" column="cost_usd" jdbcType="DECIMAL"/>
<result property="avgDurationMs" column="avg_duration_ms" jdbcType="DOUBLE"/>
</resultMap>
<resultMap id="AiUsageSeriesRowMap" type="com.guo.learningprogresstracker.dto.AiUsageSeriesRow">
<result property="bucket" column="bucket" jdbcType="VARCHAR"/>
<result property="calls" column="calls" jdbcType="BIGINT"/>
<result property="successCalls" column="success_calls" jdbcType="BIGINT"/>
<result property="failedCalls" column="failed_calls" jdbcType="BIGINT"/>
<result property="promptTokens" column="prompt_tokens" jdbcType="BIGINT"/>
<result property="completionTokens" column="completion_tokens" jdbcType="BIGINT"/>
<result property="costUsd" column="cost_usd" jdbcType="DECIMAL"/>
</resultMap>
<resultMap id="AiUsageBreakdownRowMap" type="com.guo.learningprogresstracker.dto.AiUsageBreakdownRow">
<result property="groupKey" column="group_key" jdbcType="VARCHAR"/>
<result property="calls" column="calls" jdbcType="BIGINT"/>
<result property="successCalls" column="success_calls" jdbcType="BIGINT"/>
<result property="failedCalls" column="failed_calls" jdbcType="BIGINT"/>
<result property="promptTokens" column="prompt_tokens" jdbcType="BIGINT"/>
<result property="completionTokens" column="completion_tokens" jdbcType="BIGINT"/>
<result property="cacheHitTokens" column="cache_hit_tokens" jdbcType="BIGINT"/>
<result property="costUsd" column="cost_usd" jdbcType="DECIMAL"/>
<result property="avgDurationMs" column="avg_duration_ms" jdbcType="DOUBLE"/>
</resultMap>
<!--
面板口径:只看真正消耗 LLM 的调用(is_llm_call = 1),fetch-title 这类不消耗 LLM 的任务不进统计。
自定义 SQL 不会被 @TableLogic 自动追加逻辑删除条件,deleted = 0 必须显式写出;
而 created_by 条件刻意不写——本表是系统级表,用量要统计全部调用(见 MybatisPlusConfig)。
-->
<sql id="usageFilter">
WHERE deleted = 0
AND is_llm_call = 1
<if test="from != null">AND occurred_at &gt;= #{from}</if>
<if test="to != null">AND occurred_at &lt;= #{to}</if>
<if test="taskType != null and taskType != ''">AND task_type = #{taskType}</if>
<if test="model != null and model != ''">AND model = #{model}</if>
</sql>
<!--
分桶表达式:MySQL 的 DATE_FORMAT 在测试用的 H2 上不存在,因此改用两库都认的写法——
CAST(occurred_at AS DATE) 取日期,HOUR() 取小时再补零,拼出契约要求的桶字符串。
(H2 的 CAST(x AS CHAR) 会截成 1 个字符,所以日期部分用 CONCAT 补成字符串。)
-->
<sql id="bucketExpression">
<choose>
<when test="bucket == 'hour'">
CONCAT(CAST(occurred_at AS DATE), ' ', LPAD(HOUR(occurred_at), 2, '0'), ':00')
</when>
<otherwise>
CONCAT(CAST(occurred_at AS DATE), '')
</otherwise>
</choose>
</sql>
<select id="selectSummary" resultMap="AiUsageSummaryRowMap">
SELECT COUNT(*) AS total_calls,
COALESCE(SUM(CASE WHEN status = 200 THEN 1 ELSE 0 END), 0) AS success_calls,
COALESCE(SUM(CASE WHEN status = 200 THEN 0 ELSE 1 END), 0) AS failed_calls,
COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
COALESCE(SUM(total_tokens), 0) AS total_tokens,
COALESCE(SUM(cache_hit_tokens), 0) AS cache_hit_tokens,
COALESCE(SUM(cache_miss_tokens), 0) AS cache_miss_tokens,
COALESCE(SUM(CASE WHEN prompt_tokens IS NULL THEN 1 ELSE 0 END), 0) AS unreported_usage_calls,
COALESCE(SUM(cost_usd), 0) AS cost_usd,
AVG(duration_ms) AS avg_duration_ms
FROM ai_usage_records
<include refid="usageFilter"/>
</select>
<!--
P95 耗时:先按耗时排名并取总行数,再取第一个越过 95% 位次的行(最近秩法)。
MySQL 与 H2 都支持窗口函数与 CEIL,写在这里比在 Java 里拉全量耗时更省内存。
-->
<select id="selectP95DurationMs" resultType="java.lang.Integer">
SELECT duration_ms
FROM (SELECT duration_ms,
ROW_NUMBER() OVER (ORDER BY duration_ms) AS rn,
COUNT(*) OVER () AS cnt
FROM ai_usage_records
<include refid="usageFilter"/>) ranked
WHERE rn &gt;= CEIL(cnt * 0.95)
ORDER BY duration_ms
LIMIT 1
</select>
<select id="selectSeries" resultMap="AiUsageSeriesRowMap">
SELECT <include refid="bucketExpression"/> AS bucket,
COUNT(*) AS calls,
COALESCE(SUM(CASE WHEN status = 200 THEN 1 ELSE 0 END), 0) AS success_calls,
COALESCE(SUM(CASE WHEN status = 200 THEN 0 ELSE 1 END), 0) AS failed_calls,
COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
COALESCE(SUM(cost_usd), 0) AS cost_usd
FROM ai_usage_records
<include refid="usageFilter"/>
GROUP BY <include refid="bucketExpression"/>
ORDER BY bucket
</select>
<select id="selectBreakdown" resultMap="AiUsageBreakdownRowMap">
SELECT
<choose>
<when test="groupBy == 'model'">model</when>
<otherwise>task_type</otherwise>
</choose>
AS group_key,
COUNT(*) AS calls,
COALESCE(SUM(CASE WHEN status = 200 THEN 1 ELSE 0 END), 0) AS success_calls,
COALESCE(SUM(CASE WHEN status = 200 THEN 0 ELSE 1 END), 0) AS failed_calls,
COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
COALESCE(SUM(cache_hit_tokens), 0) AS cache_hit_tokens,
COALESCE(SUM(cost_usd), 0) AS cost_usd,
AVG(duration_ms) AS avg_duration_ms
FROM ai_usage_records
<include refid="usageFilter"/>
GROUP BY
<choose>
<when test="groupBy == 'model'">model</when>
<otherwise>task_type</otherwise>
</choose>
ORDER BY calls DESC, group_key
</select>
</mapper>
@@ -0,0 +1,57 @@
package com.guo.learningprogresstracker.config;
import org.junit.jupiter.api.Test;
import org.springframework.boot.context.properties.bind.Bindable;
import org.springframework.boot.context.properties.bind.Binder;
import org.springframework.boot.env.YamlPropertySourceLoader;
import org.springframework.core.env.PropertySource;
import org.springframework.core.env.StandardEnvironment;
import org.springframework.core.io.FileSystemResource;
import java.io.IOException;
import java.math.BigDecimal;
import java.nio.file.Path;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
/**
* {@code lpt.ai-usage} 配置块的绑定守卫。
*
* <p>测试环境的 {@code src/test/resources/application.yml} 会遮蔽主配置文件,所以主配置里的键名写错了
* 测试也照样全绿——只有部署起来才发现白名单是空的、汇率没生效。这里直接读主配置文件绑定一次,
* 把「键名与配置类对不上」挡在提交之前(同 {@code MigrationIndexKeyLengthTest} 直接读迁移文件的思路)。</p>
*/
class AiUsagePropertiesTest {
private static final Path MAIN_APPLICATION_YML = Path.of("src/main/resources/application.yml");
@Test
void mainApplicationYml_bindsAiUsageBlock() throws IOException {
AiUsageProperties properties = bindMainYml();
assertEquals(List.of("admin"), properties.getAdminUsernames(), "默认只有 admin 能看用量面板");
assertEquals("", properties.getReportToken(), "默认不校验上报令牌");
assertEquals(10, properties.getBalanceTimeoutSeconds());
assertEquals(0, new BigDecimal("7").compareTo(properties.getUsdToCny()), "costCny = costUsd × 7");
}
/** 测试环境没有这个配置块,绑定失败时必须回落到契约给的默认值,而不是 null */
@Test
void defaults_matchContract() {
AiUsageProperties properties = new AiUsageProperties();
assertEquals(List.of("admin"), properties.getAdminUsernames());
assertEquals("", properties.getReportToken());
assertEquals(10, properties.getBalanceTimeoutSeconds());
assertEquals(0, new BigDecimal("7").compareTo(properties.getUsdToCny()));
}
private static AiUsageProperties bindMainYml() throws IOException {
List<PropertySource<?>> sources = new YamlPropertySourceLoader()
.load("main-application-yml", new FileSystemResource(MAIN_APPLICATION_YML));
StandardEnvironment environment = new StandardEnvironment();
sources.forEach(environment.getPropertySources()::addLast);
return Binder.get(environment).bind("lpt.ai-usage", Bindable.of(AiUsageProperties.class)).get();
}
}
@@ -77,6 +77,17 @@ class MybatisPlusConfigTest {
assertTrue(handler.ignoreTable("databasechangeloglock"));
}
/**
* 用量是运维口径的系统级表:按 created_by 过滤会让每个用户只看到自己触发的调用,面板等于永远空的。
*/
@Test
void ignoreTable_excludesSystemLevelAiUsageRecords() throws Exception {
TenantLineHandler handler = tenantLineHandler(tenantInterceptorOf(new MybatisPlusConfig()));
assertTrue(handler.ignoreTable("ai_usage_records"));
assertTrue(handler.ignoreTable("AI_USAGE_RECORDS"));
}
@Test
void ignoreTable_businessTablesAreFiltered() throws Exception {
TenantLineHandler handler = tenantLineHandler(tenantInterceptorOf(new MybatisPlusConfig()));
@@ -112,6 +112,23 @@ class WebMvcConfigTest {
assertTrue(interceptor instanceof MappedInterceptor || interceptor instanceof SaInterceptor);
}
/**
* 服务间接口(lpt-ai 用量上报)没有登录态,必须排除登录校验,改用 x-api-token 自校验;
* 漏掉这条会让 lpt-ai 的上报全部 401。
*/
@Test
void addInterceptors_excludesInternalServicePaths() {
WebMvcConfig config = new WebMvcConfig(new CorsProperties());
InspectableInterceptorRegistry registry = new InspectableInterceptorRegistry();
config.addInterceptors(registry);
MappedInterceptor mapped = assertInstanceOf(MappedInterceptor.class,
registry.getInterceptorsPublic().get(0));
assertTrue(List.of(mapped.getExcludePathPatterns()).contains("/login"));
assertTrue(List.of(mapped.getExcludePathPatterns()).contains("/internal/**"));
}
@Test
void preHandle_optionsRequest_passesWithoutLoginCheck() throws Exception {
SaInterceptor interceptor = registeredSaInterceptor();
@@ -0,0 +1,138 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageIngestResult;
import com.guo.learningprogresstracker.dto.request.AiUsageRecordRequest;
import com.guo.learningprogresstracker.dto.request.AiUsageReportRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.service.AiUsageService;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import java.util.ArrayList;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
/**
* AiUsageInternalController 纯单元测试:令牌校验、单次条数上限、幂等结果透传。
*/
@ExtendWith(MockitoExtension.class)
class AiUsageInternalControllerUnitTest {
@Mock
private AiUsageService aiUsageService;
private AiUsageProperties properties;
private AiUsageInternalController controller;
@BeforeEach
void setUp() {
properties = new AiUsageProperties();
controller = new AiUsageInternalController(aiUsageService, properties);
}
@Test
void report_withoutConfiguredToken_acceptsAnyCaller() throws Exception {
properties.setReportToken("");
when(aiUsageService.ingest(any())).thenReturn(new AiUsageIngestResult(1, 0));
CommonResult<AiUsageIngestResult> result = controller.report("", request(1));
assertEquals(200, result.getCode());
assertEquals(1, result.getData().getAccepted());
assertEquals(0, result.getData().getDuplicated());
}
@Test
void report_withMatchingToken_accepts() throws Exception {
properties.setReportToken("report-secret");
when(aiUsageService.ingest(any())).thenReturn(new AiUsageIngestResult(1, 0));
CommonResult<AiUsageIngestResult> result = controller.report("report-secret", request(1));
assertEquals(200, result.getCode());
assertEquals(1, result.getData().getAccepted());
}
@Test
void report_withWrongToken_isRejected() throws Exception {
properties.setReportToken("report-secret");
CommonResult<AiUsageIngestResult> result = controller.report("wrong-token", request(1));
assertEquals(400, result.getCode());
assertEquals("上报令牌不正确", result.getMessage());
verifyNoInteractions(aiUsageService);
}
@Test
void report_missingToken_isRejectedWhenTokenConfigured() throws Exception {
properties.setReportToken("report-secret");
CommonResult<AiUsageIngestResult> result = controller.report(null, request(1));
assertEquals(400, result.getCode());
verifyNoInteractions(aiUsageService);
}
@Test
void report_moreThanTwoHundredRecords_isRejected() throws Exception {
int tooMany = AiUsageInternalController.MAX_RECORDS_PER_REPORT + 1;
CommonResult<AiUsageIngestResult> result = controller.report("", request(tooMany));
assertEquals(400, result.getCode());
assertEquals("单次最多上报 200 条记录", result.getMessage());
verifyNoInteractions(aiUsageService);
}
@Test
void report_exactlyTwoHundredRecords_isAccepted() throws Exception {
when(aiUsageService.ingest(any())).thenReturn(new AiUsageIngestResult(200, 0));
CommonResult<AiUsageIngestResult> result =
controller.report("", request(AiUsageInternalController.MAX_RECORDS_PER_REPORT));
assertEquals(200, result.getCode());
assertEquals(200, result.getData().getAccepted());
}
/** 幂等:重复上报不报错,重复的条数体现在 duplicated 上,调用方据此判断不必重试 */
@Test
void report_duplicatedRecords_areCountedNotRejected() throws Exception {
when(aiUsageService.ingest(any())).thenReturn(new AiUsageIngestResult(0, 2));
CommonResult<AiUsageIngestResult> result = controller.report("", request(2));
assertEquals(200, result.getCode());
assertEquals(0, result.getData().getAccepted());
assertEquals(2, result.getData().getDuplicated());
}
private static AiUsageReportRequest request(int recordCount) {
List<AiUsageRecordRequest> records = new ArrayList<>(recordCount);
for (int i = 0; i < recordCount; i++) {
AiUsageRecordRequest record = new AiUsageRecordRequest();
record.setRecordId("record-" + i);
record.setOccurredAt("2026-10-10T09:38:23.543Z");
record.setTaskType("aggregate-report");
record.setModel("deepseek-flash");
record.setAttempts(1);
record.setIsLlmCall(true);
record.setUsageSource("upstream");
record.setDurationMs(1000);
record.setStatus(200);
records.add(record);
}
AiUsageReportRequest request = new AiUsageReportRequest();
request.setRecords(records);
return request;
}
}
@@ -1,5 +1,6 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.LoginResult;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.dto.request.LoginBody;
import com.guo.learningprogresstracker.exception.AppException;
@@ -8,6 +9,7 @@ import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
@SpringBootTest
class LoginControllerTest {
@@ -20,12 +22,14 @@ class LoginControllerTest {
LoginBody loginBody = new LoginBody();
loginBody.setUsername("admin");
loginBody.setPassword("admin");
CommonResult<String> login = loginController.login(loginBody);
CommonResult<LoginResult> login = loginController.login(loginBody);
assertEquals("登录成功!", login.getMessage());
// 测试种子用户 admin 命中默认白名单 lpt.ai-usage.admin-usernames
assertTrue(login.getData().isAiAdmin(), "admin 应被识别为用量面板管理员");
}
@Test
void loingOut() {
}
}
}
@@ -1,7 +1,9 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.LoginResult;
import com.guo.learningprogresstracker.dto.request.LoginBody;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.service.AiUsageService;
import com.guo.learningprogresstracker.service.LoginService;
import com.guo.learningprogresstracker.service.UserService;
import org.junit.jupiter.api.Test;
@@ -11,11 +13,13 @@ import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/**
* LoginController 纯单元测试:mock LoginService / UserService。
* LoginController 纯单元测试:mock LoginService / UserService / AiUsageService。
*/
@ExtendWith(MockitoExtension.class)
class LoginControllerUnitTest {
@@ -26,6 +30,9 @@ class LoginControllerUnitTest {
@Mock
private UserService userServiceImpl;
@Mock
private AiUsageService aiUsageService;
@InjectMocks
private LoginController controller;
@@ -36,15 +43,32 @@ class LoginControllerUnitTest {
body.setPassword("secret");
when(userServiceImpl.authenticate("alice", "secret")).thenReturn("U-1");
when(loginService.login("U-1")).thenReturn("token-abc");
when(aiUsageService.isAdmin()).thenReturn(true);
CommonResult<String> result = controller.login(body);
CommonResult<LoginResult> result = controller.login(body);
assertEquals(200, result.getCode());
assertEquals("登录成功!", result.getMessage());
assertEquals("token-abc", result.getData());
assertEquals("token-abc", result.getData().getToken());
assertTrue(result.getData().isAiAdmin(), "白名单用户登录后应下发 aiAdmin=true");
verify(loginService).login("U-1");
}
@Test
void login_nonAdminUser_getsAiAdminFalse() throws Exception {
LoginBody body = new LoginBody();
body.setUsername("alice");
body.setPassword("secret");
when(userServiceImpl.authenticate("alice", "secret")).thenReturn("U-1");
when(loginService.login("U-1")).thenReturn("token-abc");
when(aiUsageService.isAdmin()).thenReturn(false);
CommonResult<LoginResult> result = controller.login(body);
assertEquals(200, result.getCode());
assertFalse(result.getData().isAiAdmin(), "非白名单用户不该拿到用量面板入口");
}
@Test
void logout_delegatesToLoginService() {
CommonResult<Void> result = controller.logout();
@@ -0,0 +1,350 @@
package com.guo.learningprogresstracker.service.impl;
import cn.dev33.satoken.stp.StpUtil;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
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.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 org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import java.math.BigDecimal;
import java.time.Instant;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
/**
* AI 用量的落库与聚合集成测试:在真实 SQL 下验证上报落库、幂等、以及 summary / series / breakdown 的聚合结果。
*
* <p>聚合走自定义 Mapper SQL(SUM / GROUP BY / 窗口函数),{@code Wrapper} 表达不了,因此不能只靠 mock 单测。
* 这里同时守住三件容易漏的事:逻辑删除条件显式写出、系统级表不做租户过滤、
* 以及分桶表达式在 H2(MODE=MySQL)与 MySQL 上都能跑。</p>
*
* <p>每条用例用自己独有的时间窗口与任务类型取数,避免同库其他用例的数据串进来。</p>
*/
@SpringBootTest
class AiUsageAggregationIntegrationTest {
@Autowired
private AiUsageService aiUsageService;
@Autowired
private AiUsageRecordMapper aiUsageRecordMapper;
// ============ summary ============
@Test
void summary_aggregatesPersistedRows() throws Exception {
String taskType = unique("IT-SUMMARY");
String from = "2026-03-01T00:00:00Z";
String to = "2026-03-02T00:00:00Z";
AiUsageRecordRequest r1 = record(taskType + "-1", taskType, "2026-03-01T09:00:00Z", true);
r1.setPromptTokens(100);
r1.setCompletionTokens(200);
r1.setTotalTokens(300);
r1.setCacheHitTokens(40);
r1.setCacheMissTokens(60);
r1.setCostUsd(new BigDecimal("0.01"));
r1.setDurationMs(1000);
AiUsageRecordRequest r2 = record(taskType + "-2", taskType, "2026-03-01T09:10:00Z", true);
r2.setPromptTokens(50);
r2.setCompletionTokens(0);
r2.setTotalTokens(50);
r2.setCacheHitTokens(0);
r2.setCacheMissTokens(0);
r2.setCostUsd(new BigDecimal("0.005"));
r2.setDurationMs(2000);
r2.setStatus(500);
r2.setErrorCode("upstream_error");
// 上游整组没给 token:保持 null,不能折成 0
AiUsageRecordRequest r3 = record(taskType + "-3", taskType, "2026-03-01T09:20:00Z", true);
r3.setUsageSource("missing");
r3.setDurationMs(3000);
// 上游明确上报为 0:与 r3 的「未上报」是两回事
AiUsageRecordRequest r4 = record(taskType + "-4", taskType, "2026-03-01T09:30:00Z", true);
r4.setPromptTokens(0);
r4.setCompletionTokens(0);
r4.setTotalTokens(0);
r4.setCacheHitTokens(0);
r4.setCacheMissTokens(0);
r4.setDurationMs(500);
// 不消耗 LLM 的调用(fetch-title)不进统计
AiUsageRecordRequest r5 = record(taskType + "-5", taskType, "2026-03-01T09:40:00Z", false);
r5.setDurationMs(4000);
aiUsageService.ingest(List.of(r1, r2, r3, r4, r5));
AiUsageSummary summary = aiUsageService.summary(query(from, to, taskType));
assertEquals(4L, summary.getTotalCalls(), "只统计 is_llm_call = 1 的 4 条");
assertEquals(3L, summary.getSuccessCalls());
assertEquals(1L, summary.getFailedCalls());
assertEquals(150L, summary.getPromptTokens(), "未上报的那条不参与求和");
assertEquals(200L, summary.getCompletionTokens());
assertEquals(350L, summary.getTotalTokens());
assertEquals(40L, summary.getCacheHitTokens());
assertEquals(60L, summary.getCacheMissTokens());
assertEquals(0.4, summary.getCacheHitRate(), 1e-9);
assertEquals(0, new BigDecimal("0.015").compareTo(summary.getCostUsd()));
assertEquals(0, new BigDecimal("0.105").compareTo(summary.getCostCny()), "costCny = costUsd × 7");
assertEquals(1625L, summary.getAvgDurationMs(), "(1000+2000+3000+500)/4");
assertEquals(3000L, summary.getP95DurationMs(), "最近秩法:第 ceil(4×0.95)=4 小的耗时");
assertEquals(1L, summary.getUnreportedUsageCalls(), "只有 prompt_tokens IS NULL 的那条算未上报");
}
@Test
void summary_withoutMatchingRows_returnsZerosAndNullRates() throws Exception {
AiUsageSummary summary = aiUsageService.summary(query("2026-03-03T00:00:00Z", "2026-03-04T00:00:00Z",
unique("IT-EMPTY")));
assertEquals(0L, summary.getTotalCalls());
assertEquals(0L, summary.getPromptTokens());
assertEquals(0, BigDecimal.ZERO.compareTo(summary.getCostUsd()));
assertNull(summary.getCacheHitRate(), "没有缓存 token 时命中率是 null");
assertNull(summary.getAvgDurationMs());
assertNull(summary.getP95DurationMs());
}
/** 系统级表:不按 created_by 过滤,换个用户看还是同一份用量(否则面板只会看到自己触发的那几次) */
@Test
void summary_isNotFilteredByTenant() throws Exception {
String taskType = unique("IT-NOTENANT");
String from = "2026-03-05T00:00:00Z";
String to = "2026-03-06T00:00:00Z";
StpUtil.login("用量集成测试用户A", "test_device");
AiUsageRecordRequest r1 = record(taskType + "-1", taskType, "2026-03-05T10:00:00Z", true);
r1.setPromptTokens(10);
aiUsageService.ingest(List.of(r1));
StpUtil.login("用量集成测试用户B", "test_device");
AiUsageSummary summary = aiUsageService.summary(query(from, to, taskType));
assertEquals(1L, summary.getTotalCalls(), "用量是运维口径:任何白名单用户看到的都是全部调用");
}
/** 自定义 SQL 不会被 @TableLogic 自动追加条件,deleted = 0 必须显式写出 */
@Test
void summary_excludesLogicallyDeletedRecords() throws Exception {
String taskType = unique("IT-DELETED");
String from = "2026-03-07T00:00:00Z";
String to = "2026-03-08T00:00:00Z";
AiUsageRecordRequest kept = record(taskType + "-1", taskType, "2026-03-07T10:00:00Z", true);
kept.setPromptTokens(10);
AiUsageRecordRequest removed = record(taskType + "-2", taskType, "2026-03-07T11:00:00Z", true);
removed.setPromptTokens(999);
aiUsageService.ingest(List.of(kept, removed));
aiUsageRecordMapper.deleteById(aiUsageRecordMapper.selectOne(Wrappers.<AiUsageRecordEntity>lambdaQuery()
.eq(AiUsageRecordEntity::getRecordId, taskType + "-2")).getId());
AiUsageSummary summary = aiUsageService.summary(query(from, to, taskType));
assertEquals(1L, summary.getTotalCalls());
assertEquals(10L, summary.getPromptTokens(), "已逻辑删除的记录不进聚合");
}
// ============ series ============
@Test
void series_bucketsByDayAndHour() throws Exception {
String taskType = unique("IT-SERIES");
String from = "2026-04-01T00:00:00Z";
String to = "2026-04-03T00:00:00Z";
AiUsageRecordRequest t1 = record(taskType + "-1", taskType, "2026-04-01T09:05:00Z", true);
t1.setPromptTokens(10);
t1.setCostUsd(new BigDecimal("0.001"));
AiUsageRecordRequest t2 = record(taskType + "-2", taskType, "2026-04-01T09:55:00Z", true);
t2.setPromptTokens(20);
t2.setCostUsd(new BigDecimal("0.002"));
t2.setStatus(500);
AiUsageRecordRequest t3 = record(taskType + "-3", taskType, "2026-04-02T11:30:00Z", true);
t3.setPromptTokens(30);
t3.setCostUsd(new BigDecimal("0.003"));
aiUsageService.ingest(List.of(t1, t2, t3));
List<AiUsageSeriesPoint> byDay = aiUsageService.series(query(from, to, taskType));
assertEquals(2, byDay.size(), "两天两个桶");
assertEquals("2026-04-01", byDay.get(0).getBucket());
assertEquals(2L, byDay.get(0).getCalls());
assertEquals(1L, byDay.get(0).getSuccessCalls());
assertEquals(1L, byDay.get(0).getFailedCalls());
assertEquals(30L, byDay.get(0).getPromptTokens());
assertEquals(0, new BigDecimal("0.003").compareTo(byDay.get(0).getCostUsd()));
assertEquals("2026-04-02", byDay.get(1).getBucket());
assertEquals(1L, byDay.get(1).getCalls());
AiUsageQuery hourQuery = query(from, to, taskType);
hourQuery.setBucket("hour");
List<AiUsageSeriesPoint> byHour = aiUsageService.series(hourQuery);
assertEquals(2, byHour.size(), "两小时两个桶");
assertEquals("2026-04-01 09:00", byHour.get(0).getBucket(), "同一小时内的两条合并成一桶");
assertEquals(2L, byHour.get(0).getCalls());
assertEquals("2026-04-02 11:00", byHour.get(1).getBucket());
assertEquals(1L, byHour.get(1).getCalls());
}
@Test
void series_rejectsUnknownBucket() {
AiUsageQuery query = query("2026-04-01T00:00:00Z", "2026-04-03T00:00:00Z", null);
query.setBucket("week");
assertThrows(ErrorParameterException.class, () -> aiUsageService.series(query));
}
// ============ breakdown ============
@Test
void breakdown_groupsByTaskTypeAndModel() throws Exception {
String taskTypeA = unique("IT-BREAKDOWN-A");
String taskTypeB = unique("IT-BREAKDOWN-B");
String modelA = "it-model-a";
String modelB = "it-model-b";
String from = "2026-05-01T00:00:00Z";
String to = "2026-05-02T00:00:00Z";
aiUsageService.ingest(List.of(
breakdownRecord(taskTypeA + "-1", taskTypeA, modelA, "2026-05-01T09:00:00Z", 10, 5, "0.001", 1000, 200),
breakdownRecord(taskTypeA + "-2", taskTypeA, modelA, "2026-05-01T09:10:00Z", 20, 5, "0.002", 3000, 500),
breakdownRecord(taskTypeA + "-3", taskTypeA, modelB, "2026-05-01T09:20:00Z", 30, 0, "0.003", 2000, 200),
breakdownRecord(taskTypeB + "-1", taskTypeB, modelA, "2026-05-01T09:30:00Z", 40, 10, "0.004", 4000, 200)
));
AiUsageQuery byTaskType = query(from, to, null);
List<AiUsageBreakdownItem> taskTypeRows = aiUsageService.breakdown(byTaskType);
assertEquals(2, taskTypeRows.size());
AiUsageBreakdownItem rowA = find(taskTypeRows, taskTypeA);
assertEquals(3L, rowA.getCalls());
assertEquals(2L, rowA.getSuccessCalls());
assertEquals(1L, rowA.getFailedCalls());
assertEquals(60L, rowA.getPromptTokens());
assertEquals(10L, rowA.getCacheHitTokens());
assertEquals(0, new BigDecimal("0.006").compareTo(rowA.getCostUsd()));
assertEquals(2000L, rowA.getAvgDurationMs(), "(1000+3000+2000)/3");
AiUsageBreakdownItem rowB = find(taskTypeRows, taskTypeB);
assertEquals(1L, rowB.getCalls());
assertEquals(0L, rowB.getFailedCalls());
assertEquals(40L, rowB.getPromptTokens());
assertEquals(4000L, rowB.getAvgDurationMs());
AiUsageQuery byModel = query(from, to, null);
byModel.setGroupBy("model");
List<AiUsageBreakdownItem> modelRows = aiUsageService.breakdown(byModel);
assertEquals(2, modelRows.size());
AiUsageBreakdownItem modelRowA = find(modelRows, modelA);
assertEquals(3L, modelRowA.getCalls(), "同一模型跨任务类型合并");
assertEquals(70L, modelRowA.getPromptTokens());
assertEquals(20L, modelRowA.getCacheHitTokens());
assertEquals(0, new BigDecimal("0.007").compareTo(modelRowA.getCostUsd()));
assertEquals(2667L, modelRowA.getAvgDurationMs(), "(1000+3000+4000)/3 四舍五入");
assertEquals(1L, find(modelRows, modelB).getCalls());
}
@Test
void breakdown_rejectsUnknownGroupBy() {
AiUsageQuery query = query("2026-05-01T00:00:00Z", "2026-05-02T00:00:00Z", null);
query.setGroupBy("status");
assertThrows(ErrorParameterException.class, () -> aiUsageService.breakdown(query));
}
// ============ 幂等 ============
@Test
void ingest_isIdempotentByRecordId() throws Exception {
String taskType = unique("IT-IDEMPOTENT");
List<AiUsageRecordRequest> records = List.of(
record(taskType + "-1", taskType, "2026-06-01T09:00:00Z", true),
record(taskType + "-2", taskType, "2026-06-01T09:01:00Z", true));
AiUsageIngestResult first = aiUsageService.ingest(records);
AiUsageIngestResult second = aiUsageService.ingest(records);
assertEquals(2, first.getAccepted());
assertEquals(0, first.getDuplicated());
assertEquals(0, second.getAccepted(), "重复上报不再落库");
assertEquals(2, second.getDuplicated());
assertEquals(2L, aiUsageRecordMapper.selectCount(Wrappers.<AiUsageRecordEntity>lambdaQuery()
.in(AiUsageRecordEntity::getRecordId, List.of(taskType + "-1", taskType + "-2"))),
"唯一索引与幂等判断共同保证重复上报不产生第二行");
}
@Test
void ingest_rejectsUnparsableOccurredAt() {
AiUsageRecordRequest broken = record(unique("IT-BADTIME") + "-1", "aggregate-report",
"2026-06-01 09:00:00", true);
assertThrows(ErrorParameterException.class, () -> aiUsageService.ingest(List.of(broken)));
}
// ============ 造数 ============
private static String unique(String prefix) {
return prefix + "-" + System.nanoTime();
}
private static AiUsageQuery query(String from, String to, String taskType) {
AiUsageQuery query = new AiUsageQuery();
query.setFrom(Instant.parse(from).toEpochMilli());
query.setTo(Instant.parse(to).toEpochMilli());
query.setTaskType(taskType);
return query;
}
private static AiUsageRecordRequest record(String recordId, String taskType, String occurredAt, boolean isLlmCall) {
AiUsageRecordRequest record = new AiUsageRecordRequest();
record.setRecordId(recordId);
record.setOccurredAt(occurredAt);
record.setTaskType(taskType);
record.setTaskId("task-" + recordId);
record.setModel("it-model-a");
record.setAttempts(1);
record.setIsLlmCall(isLlmCall);
record.setUsageSource("upstream");
record.setDurationMs(1000);
record.setStatus(200);
return record;
}
private static AiUsageRecordRequest breakdownRecord(String recordId, String taskType, String model, String occurredAt,
int promptTokens, int cacheHitTokens, String costUsd,
int durationMs, int status) {
AiUsageRecordRequest record = record(recordId, taskType, occurredAt, true);
record.setModel(model);
record.setPromptTokens(promptTokens);
record.setCacheHitTokens(cacheHitTokens);
record.setCostUsd(new BigDecimal(costUsd));
record.setDurationMs(durationMs);
record.setStatus(status);
return record;
}
private static AiUsageBreakdownItem find(List<AiUsageBreakdownItem> rows, String key) {
return rows.stream()
.filter(row -> key.equals(row.getKey()))
.findFirst()
.orElseThrow(() -> new AssertionError("分组里没有 " + key + ",实际:" + rows));
}
}
@@ -0,0 +1,77 @@
package com.guo.learningprogresstracker.service.impl;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageBalance;
import com.guo.learningprogresstracker.support.TestHttpServer;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* AiUsageClient 单元测试:基于本地 TestHttpServer 覆盖余额代理的透传与降级分支。
*
* <p>余额是面板上的附加信息,上游没配置或查不到时必须返回 {@code configured=false} 而不是报错,
* 所以这里把「未配置 / 非 200 / 上游自己说没配置 / 响应解析不了」四条路都走一遍。</p>
*/
class AiUsageClientTest extends TestHttpServer {
private AiUsageClient client(String url) {
AiUsageClient client = new AiUsageClient(new AiUsageProperties());
client.setUrl(url);
client.setToken("ai-service-token");
return client;
}
@Test
void fetchBalance_notConfigured_returnsConfiguredFalse() {
AiUsageBalance balance = client(null).fetchBalance();
assertFalse(balance.isConfigured());
assertNull(balance.getCurrency());
}
@Test
void fetchBalance_passesThroughUpstreamFieldsAndToken() {
route("GET", "/admin/usage/balance", 200, """
{"configured":true,"currency":"CNY","totalBalance":"12.34","grantedBalance":"0.00",
"toppedUpBalance":"12.34","fetchedAt":"2026-10-10T09:38:23.543Z"}
""");
AiUsageBalance balance = client(baseUrl()).fetchBalance();
assertTrue(balance.isConfigured());
assertEquals("CNY", balance.getCurrency());
assertEquals("12.34", balance.getTotalBalance());
assertEquals("0.00", balance.getGrantedBalance());
assertEquals("12.34", balance.getToppedUpBalance());
assertEquals("2026-10-10T09:38:23.543Z", balance.getFetchedAt());
assertEquals("ai-service-token", requestHeader("GET", "/admin/usage/balance", "x-api-token"));
}
@Test
void fetchBalance_upstreamSaysNotConfigured_returnsConfiguredFalse() {
route("GET", "/admin/usage/balance", 200, "{\"configured\":false}");
AiUsageBalance balance = client(baseUrl()).fetchBalance();
assertFalse(balance.isConfigured());
assertNull(balance.getCurrency(), "上游没配置时不该编造余额");
}
@Test
void fetchBalance_upstreamError_returnsConfiguredFalse() {
route("GET", "/admin/usage/balance", 500, "boom");
assertFalse(client(baseUrl()).fetchBalance().isConfigured());
}
@Test
void fetchBalance_unparsableBody_returnsConfiguredFalse() {
route("GET", "/admin/usage/balance", 200, "not-json");
assertFalse(client(baseUrl()).fetchBalance().isConfigured());
}
}
@@ -0,0 +1,183 @@
package com.guo.learningprogresstracker.service.impl;
import cn.dev33.satoken.SaManager;
import cn.dev33.satoken.context.SaTokenContext;
import cn.dev33.satoken.context.SaTokenContextForThreadLocal;
import cn.dev33.satoken.context.SaTokenContextForThreadLocalStorage;
import cn.dev33.satoken.servlet.model.SaRequestForServlet;
import cn.dev33.satoken.servlet.model.SaResponseForServlet;
import cn.dev33.satoken.servlet.model.SaStorageForServlet;
import cn.dev33.satoken.stp.StpUtil;
import com.guo.learningprogresstracker.config.AiUsageProperties;
import com.guo.learningprogresstracker.dto.AiUsageSummary;
import com.guo.learningprogresstracker.dto.AiUsageSummaryRow;
import com.guo.learningprogresstracker.mapper.AiUsageRecordMapper;
import com.guo.learningprogresstracker.service.UserService;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import java.math.BigDecimal;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.when;
/**
* AiUsageServiceImpl 纯单元测试:白名单口径与汇总口径(mock Mapper / UserService)。
*
* <p>租户条件、逻辑删除与 SQL 聚合本身无法用 mock 表达,由
* {@code AiUsageAggregationIntegrationTest} 落库守住。</p>
*/
@ExtendWith(MockitoExtension.class)
class AiUsageServiceUnitTest {
private static final String USER_ID = "U-1";
@Mock
private AiUsageRecordMapper aiUsageRecordMapper;
@Mock
private UserService userService;
@Mock
private AiUsageClient aiUsageClient;
private AiUsageProperties properties;
private AiUsageServiceImpl aiUsageService;
private SaTokenContext previousContext;
@BeforeEach
void setUp() {
previousContext = SaManager.getSaTokenContext();
SaManager.setSaTokenContext(new SaTokenContextForThreadLocal());
MockHttpServletRequest request = new MockHttpServletRequest();
SaTokenContextForThreadLocalStorage.setBox(
new SaRequestForServlet(request),
new SaResponseForServlet(new MockHttpServletResponse()),
new SaStorageForServlet(request));
properties = new AiUsageProperties();
aiUsageService = new AiUsageServiceImpl(aiUsageRecordMapper, userService, properties, aiUsageClient);
}
@AfterEach
void tearDown() {
SaTokenContextForThreadLocalStorage.clearBox();
SaManager.setSaTokenContext(previousContext);
}
// ============ 白名单 ============
@Test
void isAdmin_userNameInWhitelist_isTrue() {
StpUtil.login(USER_ID);
properties.setAdminUsernames(List.of("admin", "ops"));
when(userService.getUserNameById(USER_ID)).thenReturn("admin");
assertTrue(aiUsageService.isAdmin(), "登录名命中白名单即可见用量面板");
}
@Test
void isAdmin_userNameNotInWhitelist_isFalse() {
StpUtil.login(USER_ID);
properties.setAdminUsernames(List.of("admin"));
when(userService.getUserNameById(USER_ID)).thenReturn("alice");
assertFalse(aiUsageService.isAdmin(), "非白名单用户不应看到用量面板");
}
@Test
void isAdmin_userNotFound_isFalse() {
StpUtil.login(USER_ID);
properties.setAdminUsernames(List.of("admin"));
when(userService.getUserNameById(USER_ID)).thenReturn(null);
assertFalse(aiUsageService.isAdmin(), "查不到登录名时按无权处理,不能默认放行");
}
@Test
void isAdmin_emptyWhitelist_isFalse() {
StpUtil.login(USER_ID);
properties.setAdminUsernames(List.of());
assertFalse(aiUsageService.isAdmin(), "白名单为空时谁都不放行");
}
// ============ 汇总口径 ============
@Test
void summary_cacheHitRateIsNullWhenDenominatorIsZero() {
when(aiUsageRecordMapper.selectSummary(any(), any(), any(), any())).thenReturn(row(3L, 0L, 0L));
when(aiUsageRecordMapper.selectP95DurationMs(any(), any(), any(), any())).thenReturn(null);
AiUsageSummary summary = aiUsageService.summary(null);
assertNull(summary.getCacheHitRate(), "没有缓存 token 时命中率是 null,而不是 0(面板要区分「没数据」和「零命中」)");
assertNull(summary.getAvgDurationMs(), "没有调用时平均耗时是 null");
assertNull(summary.getP95DurationMs(), "没有调用时 P95 是 null");
assertEquals(0L, summary.getCacheHitTokens());
assertEquals(0L, summary.getCacheMissTokens());
}
@Test
void summary_cacheHitRateIsRatioOfHitTokens() {
AiUsageSummaryRow row = row(4L, 40L, 60L);
row.setCostUsd(new BigDecimal("0.01230000"));
row.setAvgDurationMs(7466.4);
when(aiUsageRecordMapper.selectSummary(any(), any(), any(), any())).thenReturn(row);
when(aiUsageRecordMapper.selectP95DurationMs(any(), any(), any(), any())).thenReturn(12000);
AiUsageSummary summary = aiUsageService.summary(null);
assertEquals(0.4, summary.getCacheHitRate(), 1e-9);
assertEquals(7466L, summary.getAvgDurationMs(), "平均耗时取整返回");
assertEquals(12000L, summary.getP95DurationMs());
assertEquals(0, new BigDecimal("0.0861").compareTo(summary.getCostCny()),
"costCny = costUsd × lpt.ai-usage.usd-to-cny(默认 7)");
}
/**
* null token 与 0 token 是两件事:0 表示上游明确上报为 0(不算「未上报」),
* null 才是未上报。服务层必须原样透传,不能把 null 折成 0。
*/
@Test
void summary_keepsNullTokenApartFromZeroToken() {
AiUsageSummaryRow row = row(2L, 0L, 0L);
row.setPromptTokens(0L);
row.setUnreportedUsageCalls(1L);
when(aiUsageRecordMapper.selectSummary(any(), any(), any(), any())).thenReturn(row);
when(aiUsageRecordMapper.selectP95DurationMs(any(), any(), any(), any())).thenReturn(0);
AiUsageSummary summary = aiUsageService.summary(null);
assertEquals(0L, summary.getPromptTokens(), "明确上报的 0 就是 0");
assertEquals(1L, summary.getUnreportedUsageCalls(), "prompt_tokens 为 null 的那条才是「未上报」");
assertEquals(0L, summary.getP95DurationMs());
}
private static AiUsageSummaryRow row(long totalCalls, long cacheHitTokens, long cacheMissTokens) {
AiUsageSummaryRow row = new AiUsageSummaryRow();
row.setTotalCalls(totalCalls);
row.setSuccessCalls(totalCalls);
row.setFailedCalls(0L);
row.setPromptTokens(0L);
row.setCompletionTokens(0L);
row.setTotalTokens(0L);
row.setCacheHitTokens(cacheHitTokens);
row.setCacheMissTokens(cacheMissTokens);
row.setUnreportedUsageCalls(0L);
row.setCostUsd(BigDecimal.ZERO);
return row;
}
}