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>