diff --git a/AGENTS.md b/AGENTS.md index 705e48f..d894c00 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,7 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ - entity 使用 `@TableName`、`@TableField` 映射数据库字段。 - mapStruct 承载 DTO 转换。 -## API 端点总览(69 个) +## API 端点总览(75 个) | 模块 | 端点数 | 端点 | |------|--------|------| @@ -63,11 +63,21 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ | 学习引导 | 5 | `POST /review/guidance`, `POST /review/guidance/{guidanceNum}/turns`, `GET /review/guidance/{guidanceNum}`, `POST /review/guidance/{guidanceNum}/fragments`, `DELETE /review/guidance/{guidanceNum}` | | 统一标记 | 7 | `GET /markers`, `POST /markers`, `POST /markers/batch`, `DELETE /markers/{id}`, `PUT /markers/rename`, `GET /markers/filter`, `GET /markers/tags` | | AI 异步任务 | 3 | `POST /ai/tasks`, `GET /ai/tasks/{taskNum}`, `GET /ai/tasks/latest` | +| AI 用量统计 | 5 | `GET /ai/usage/permission`, `GET /ai/usage/summary`, `GET /ai/usage/series`, `GET /ai/usage/breakdown`, `GET /ai/usage/balance` | +| 内部(服务间) | 1 | `POST /internal/ai-usage/records` | | 工具 | 1 | `GET /utils/fetch-title?url=...` | -## 数据库(10 个核心表) +> 「AI 用量统计」只对 `lpt.ai-usage.admin-usernames` 白名单用户开放:`permission` 用 `allowed=false` +> 让前端静默隐藏入口,其余 4 个接口直接拒绝。`POST /internal/ai-usage/records` 是 lpt-ai 的上报入口, +> 没有登录态,在 `WebMvcConfig` 里排除了 Sa-Token,改用 `x-api-token` 与 `lpt.ai-usage.report-token` 比对。 -`users`, `tasks`, `study_sessions`, `study_reports`, `study_report_fragments`, `study_expectations`, `task_applications`, `review_standard_mind_maps`, `review_recall_records`, `user_priority_weights` +## 数据库(11 个核心表) + +`users`, `tasks`, `study_sessions`, `study_reports`, `study_report_fragments`, `study_expectations`, `task_applications`, `review_standard_mind_maps`, `review_recall_records`, `user_priority_weights`, `ai_usage_records` + +> `ai_usage_records` 是**系统级表**,已加入 `MybatisPlusConfig.EXCLUDE_TABLES`: +> 记录由 lpt-ai 上报、没有登录用户,而且用量是运维口径(面板要看全部调用)。 +> 若按 `created_by` 过滤,管理员只能看到自己触发的那几次,面板等于永远是空的。 ## 关键机制 @@ -84,7 +94,8 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ - **租户值来源:** `StpUtil.getLoginIdAsString()`(当前登录用户) - **自动注入:** 所有 SELECT/UPDATE/DELETE 语句自动追加 `WHERE created_by = #{当前用户}` - **归属校验:** 查询单条记录时拦截器自动校验 `created_by`,非本人数据直接返回空 -- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock` +- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock`、`ai_usage_records` + (`ai_usage_records` 是系统级表,用量要统计全部调用,不能按 `created_by` 切分) ### 自动填充(MetaObjectHandler) @@ -131,6 +142,20 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ 注意变量名带连字符才能映射到 `lpt.ai-service.token`,与既有的 `LPT_AI-SERVICE_URL` 保持一致。 - AI 服务不可用时自动降级到内置规则引擎(`BuiltinMindMapGenerator`) +## AI 用量统计 + +- **数据来源**:lpt-ai 每次任务结算后上报一条记录(`POST /internal/ai-usage/records`,按 `record_id` 幂等)。 + 上报失败由 lpt-ai 侧本地 outbox 重试;4xx 属于确定性拒绝,lpt-ai 会丢弃这批并计数,不会无限重试。 +- **token 的 null 语义**:`prompt_tokens` 等列为 `NULL` 表示上游没上报,`0` 表示上游明确上报为 0。 + 两者必须区分(`unreported_usage_calls` 就是靠它算的),**不得用 0 顶替 null**。 +- **计价在 lpt-ai 侧冻结**:`cost_usd` 是上报时按当期价目算好的,本服务只做聚合与汇率换算, + 改价不会重写历史账。汇率走 `lpt.ai-usage.usd-to-cny`。 +- **口径**:只统计 `is_llm_call = 1` 的记录(`/fetch-title` 这类不消耗 LLM)。 +- 配置:`lpt.ai-usage.admin-usernames`(白名单,部署用 `LPT_AI-USAGE_ADMIN-USERNAMES`)、 + `lpt.ai-usage.report-token`(上报令牌,部署用 `LPT_AI-USAGE_REPORT-TOKEN`,与 lpt-ai 的 + `LPT_AI_REPORT_TOKEN` 共用 `lpt-secrets/lpt-ai-report-token`)。 +- 前端入口:`lpt-fe` 的 `/ai-usage`,入口按钮在「退出登录」左侧,显隐由登录响应里的 `aiAdmin` 决定。 + ## 启动命令 ```bash diff --git a/src/main/java/com/guo/learningprogresstracker/config/AiUsageProperties.java b/src/main/java/com/guo/learningprogresstracker/config/AiUsageProperties.java new file mode 100644 index 0000000..dca0533 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/config/AiUsageProperties.java @@ -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 adminUsernames = List.of("admin"); + + /** lpt-ai 上报用量时携带的令牌;为空表示不校验 */ + private String reportToken = ""; + + /** 代理查询上游余额的超时(秒) */ + private int balanceTimeoutSeconds = 10; + + /** 费用展示用的美元兑人民币汇率:{@code costCny = costUsd × 该值} */ + private BigDecimal usdToCny = BigDecimal.valueOf(7); +} diff --git a/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java b/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java index e871e95..f8d8301 100644 --- a/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java +++ b/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java @@ -23,13 +23,18 @@ import java.util.List; public class MybatisPlusConfig { /** - * 不需要租户过滤的表(仅排除不含 created_by 的系统表) + * 不需要租户过滤的表(仅排除不含 created_by 或不该按 created_by 过滤的表) + * + *

{@code ai_usage_records} 是系统级表:记录由 lpt-ai 通过内部接口上报,请求里没有登录用户, + * created_by 只是审计列;用量又是运维口径——管理员要看的是**全部**调用。 + * 若按 created_by 过滤,每个人只能看到自己触发的那几次调用,面板等于永远空的。

*/ private static final List EXCLUDE_TABLES = Arrays.asList( "user", "flyway_schema_history", "databasechangelog", - "databasechangeloglock" + "databasechangeloglock", + "ai_usage_records" ); @Bean diff --git a/src/main/java/com/guo/learningprogresstracker/config/WebMvcConfig.java b/src/main/java/com/guo/learningprogresstracker/config/WebMvcConfig.java index 38007dd..f90cff8 100644 --- a/src/main/java/com/guo/learningprogresstracker/config/WebMvcConfig.java +++ b/src/main/java/com/guo/learningprogresstracker/config/WebMvcConfig.java @@ -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 diff --git a/src/main/java/com/guo/learningprogresstracker/controller/AiUsageController.java b/src/main/java/com/guo/learningprogresstracker/controller/AiUsageController.java new file mode 100644 index 0000000..322b5bb --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/controller/AiUsageController.java @@ -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)。 + * + *

用量记录是系统级数据,只有白名单用户能看:{@code permission} 用 {@code allowed=false} + * 让前端静默隐藏入口,其余接口直接拒绝,避免入口藏起来了、接口却谁都能拉。

+ */ +@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 permission() { + return CommonResult.success(new AiUsagePermission(aiUsageService.isAdmin())); + } + + @GetMapping("/summary") + public CommonResult summary(AiUsageQuery query) { + if (!aiUsageService.isAdmin()) { + return CommonResult.error(NO_PERMISSION_MESSAGE); + } + return CommonResult.success(aiUsageService.summary(query)); + } + + @GetMapping("/series") + public CommonResult> series(AiUsageQuery query) throws ErrorParameterException { + if (!aiUsageService.isAdmin()) { + return CommonResult.error(NO_PERMISSION_MESSAGE); + } + return CommonResult.success(aiUsageService.series(query)); + } + + @GetMapping("/breakdown") + public CommonResult> 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 balance() { + if (!aiUsageService.isAdmin()) { + return CommonResult.error(NO_PERMISSION_MESSAGE); + } + return CommonResult.success(aiUsageService.balance()); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/controller/AiUsageInternalController.java b/src/main/java/com/guo/learningprogresstracker/controller/AiUsageInternalController.java new file mode 100644 index 0000000..5840268 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/controller/AiUsageInternalController.java @@ -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)。 + * + *

这是服务间接口,不是用户接口:调用方是 lpt-ai 进程,没有登录态, + * 因此 {@code /internal/**} 已在 {@code WebMvcConfig} 中排除 Sa-Token 登录校验, + * 改用 {@code x-api-token} 与 {@code lpt.ai-usage.report-token} 比对(配置为空表示不校验)。

+ */ +@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; + + /** + * 上报用量记录。 + * + *

按 {@code recordId} 幂等:重复上报不报错,只在结果里体现为 {@code duplicated}。

+ */ + @PostMapping("/records") + public CommonResult report( + @RequestHeader(name = "x-api-token", required = false) String apiToken, + @Valid @RequestBody AiUsageReportRequest request) throws ErrorParameterException { + if (!isTokenAccepted(apiToken)) { + return CommonResult.error("上报令牌不正确"); + } + List 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); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/controller/LoginController.java b/src/main/java/com/guo/learningprogresstracker/controller/LoginController.java index 94abdba..7ac72c1 100644 --- a/src/main/java/com/guo/learningprogresstracker/controller/LoginController.java +++ b/src/main/java/com/guo/learningprogresstracker/controller/LoginController.java @@ -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 login(@RequestBody LoginBody loginBody) throws AppException { + public CommonResult 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") diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBalance.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBalance.java new file mode 100644 index 0000000..7ff199a --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBalance.java @@ -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})。 + * + *

由 lpt-be 代理 lpt-ai 的 {@code GET /admin/usage/balance};上游未配置或调用失败时只有 + * {@code configured=false} 一个字段,因此这里用 {@code NON_NULL} 让其余字段直接不出现, + * 与契约给的响应体形状一致。

+ */ +@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(); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBreakdownItem.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBreakdownItem.java new file mode 100644 index 0000000..1fc2764 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBreakdownItem.java @@ -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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBreakdownRow.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBreakdownRow.java new file mode 100644 index 0000000..a13bb35 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageBreakdownRow.java @@ -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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageIngestResult.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageIngestResult.java new file mode 100644 index 0000000..1eb143b --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageIngestResult.java @@ -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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsagePermission.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsagePermission.java new file mode 100644 index 0000000..c66edb6 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsagePermission.java @@ -0,0 +1,18 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.AllArgsConstructor; +import lombok.Data; + +/** + * 当前用户能否查看「AI 用量统计」(契约 2.1,{@code GET /ai/usage/permission})。 + * + *

非白名单也返回 HTTP 200 + {@code allowed=false},前端据此静默隐藏入口, + * 不需要为一个「看不见的按钮」处理报错。

+ */ +@Data +@AllArgsConstructor +public class AiUsagePermission { + + /** 用户名是否命中 {@code lpt.ai-usage.admin-usernames} */ + private boolean allowed; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSeriesPoint.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSeriesPoint.java new file mode 100644 index 0000000..abddf58 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSeriesPoint.java @@ -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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSeriesRow.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSeriesRow.java new file mode 100644 index 0000000..3a87033 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSeriesRow.java @@ -0,0 +1,30 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.Data; + +import java.math.BigDecimal; + +/** + * 用量趋势的分桶聚合结果(Mapper 层直接映射,契约 2.3)。 + * + *

{@code bucket} 是计算列(按天/按小时格式化后的字符串),必须由显式 + * {@code } 映射。

+ */ +@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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSummary.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSummary.java new file mode 100644 index 0000000..aba0243 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSummary.java @@ -0,0 +1,47 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.Data; + +import java.math.BigDecimal; + +/** + * AI 用量汇总(契约 2.2,{@code GET /ai/usage/summary})。 + * + *

只统计真正消耗 LLM 的调用({@code is_llm_call = 1})。

+ */ +@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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSummaryRow.java b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSummaryRow.java new file mode 100644 index 0000000..9eff3d9 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiUsageSummaryRow.java @@ -0,0 +1,39 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.Data; + +import java.math.BigDecimal; + +/** + * 用量汇总的聚合结果(Mapper 层直接映射,契约 2.2)。 + * + *

列名与属性不一致(别名、计算列),因此由 {@code AiUsageRecordMapper.xml} 的显式 + * {@code } 承载映射,不依赖下划线转驼峰。

+ */ +@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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/LoginResult.java b/src/main/java/com/guo/learningprogresstracker/dto/LoginResult.java new file mode 100644 index 0000000..51f6e24 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/LoginResult.java @@ -0,0 +1,20 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.AllArgsConstructor; +import lombok.Data; + +/** + * 登录结果。 + * + *

除 token 外额外下发 {@code aiAdmin}:前端据此决定是否显示「AI 用量统计」入口 + * (契约 5,白名单口径在服务端,前端不自己判断)。

+ */ +@Data +@AllArgsConstructor +public class LoginResult { + + private String token; + + /** 该用户是否在 {@code lpt.ai-usage.admin-usernames} 白名单里 */ + private boolean aiAdmin; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageQuery.java b/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageQuery.java new file mode 100644 index 0000000..4c13475 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageQuery.java @@ -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"; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageRecordRequest.java b/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageRecordRequest.java new file mode 100644 index 0000000..5c018f4 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageRecordRequest.java @@ -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)。 + * + *

token 类字段一律包装类型:{@code null} 表示上游未上报,{@code 0} 表示上游明确上报为 0, + * 两者语义不同,不得用 0 顶替 null。

+ */ +@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; + + /** + * 模型名。 + * + *

用 {@code @NotNull} 而不是 {@code @NotBlank}:{@code isLlmCall=false} 的记录 + * (如 {@code /fetch-title})本来就没调用模型,契约里它的 model 就是空串。 + * 用 {@code @NotBlank} 会让这一条把整批上报打成 400,而上报方会把 400 当成可重试错误, + * outbox 被永久堵死。

+ */ + @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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageReportRequest.java b/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageReportRequest.java new file mode 100644 index 0000000..5a9ac27 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/request/AiUsageReportRequest.java @@ -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 records; +} diff --git a/src/main/java/com/guo/learningprogresstracker/entity/AiUsageRecordEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/AiUsageRecordEntity.java new file mode 100644 index 0000000..d5543c4 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/entity/AiUsageRecordEntity.java @@ -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 用量统计」面板聚合。 + * + *

系统级表:已加入 {@code MybatisPlusConfig.EXCLUDE_TABLES},不做按 {@code created_by} + * 的租户过滤——用量是运维口径,面板展示的是全部调用,而不是当前用户自己触发的那几次。

+ * + *

token 类字段一律用包装类型:{@code null} 表示上游没上报,{@code 0} 表示上游明确上报为 0, + * 两者语义不同,不得用 0 顶替 null(面板要能显示「未上报」的调用数)。

+ */ +@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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/mapper/AiUsageRecordMapper.java b/src/main/java/com/guo/learningprogresstracker/mapper/AiUsageRecordMapper.java new file mode 100644 index 0000000..aa85b18 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/mapper/AiUsageRecordMapper.java @@ -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。 + * + *

SUM / GROUP BY 这类 {@code Wrapper} 表达不了的查询下沉到这里,用自定义 SQL + 显式结果类, + * 语句见 {@code resources/mapper/AiUsageRecordMapper.xml}。

+ * + *

两个前提条件写在 SQL 里而不是靠框架:自定义 SQL 不会被 {@code @TableLogic} 追加条件, + * 因此每处都显式写 {@code deleted = 0};而 {@code created_by} 租户条件不能出现—— + * 本表已在 {@code MybatisPlusConfig.EXCLUDE_TABLES} 中,用量是运维口径,面板展示的是全部调用。

+ */ +@Mapper +public interface AiUsageRecordMapper extends BaseMapper { + + /** + * 汇总用量(契约 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 × 调用数)} 小的耗时)。 + * + *

MySQL 与 H2 都没有通用的百分位聚合函数,这里用窗口函数先给耗时排名, + * 再取第一个越过 95% 位次的行;两库都支持该写法(有落库集成测试守住)。

+ * + * @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 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 selectBreakdown(@Param("from") LocalDateTime from, + @Param("to") LocalDateTime to, + @Param("taskType") String taskType, + @Param("model") String model, + @Param("groupBy") String groupBy); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/AiUsageService.java b/src/main/java/com/guo/learningprogresstracker/service/AiUsageService.java new file mode 100644 index 0000000..7b61b24 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/AiUsageService.java @@ -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 用量统计(落库 + 聚合 + 余额代理)。 + * + *

用量记录是系统级数据(不按用户隔离),但查询接口只对白名单用户开放, + * 白名单口径见 {@code lpt.ai-usage.admin-usernames}。

+ */ +public interface AiUsageService { + + /** + * 落库 lpt-ai 上报的用量记录,按 {@code recordId} 幂等(已存在的直接跳过)。 + * + * @return 本次新落库与跳过的条数 + */ + AiUsageIngestResult ingest(List records) throws ErrorParameterException; + + /** 当前登录用户是否在用量面板白名单里 */ + boolean isAdmin(); + + /** 用量汇总(契约 2.2) */ + AiUsageSummary summary(AiUsageQuery query); + + /** 按天/按小时的用量趋势(契约 2.3) */ + List series(AiUsageQuery query) throws ErrorParameterException; + + /** 按任务类型/模型的用量分组(契约 2.4) */ + List breakdown(AiUsageQuery query) throws ErrorParameterException; + + /** 代理查询上游余额(契约 2.5);上游不可用时返回 {@code configured=false} */ + AiUsageBalance balance(); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/UserService.java b/src/main/java/com/guo/learningprogresstracker/service/UserService.java index 7f01787..1740ab4 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/UserService.java +++ b/src/main/java/com/guo/learningprogresstracker/service/UserService.java @@ -18,4 +18,14 @@ public interface UserService extends IService { * @return */ String authenticate(String username, String password) throws AppException; + + /** + * 按用户 id 取登录名。 + * + *

登录态里只有用户 id,而「AI 用量统计」白名单按用户名配置(见 + * {@code lpt.ai-usage.admin-usernames}),需要这一次转换。

+ * + * @return 用户不存在时返回 null + */ + String getUserNameById(String userId); } diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiUsageClient.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiUsageClient.java new file mode 100644 index 0000000..12c0e78 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiUsageClient.java @@ -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 用量相关接口的客户端。 + * + *

只做一件事:代理 lpt-ai 的 {@code GET /admin/usage/balance}(契约 2.5 / 3)。 + * 单独一个客户端而不是塞进 {@link AiServiceClient},是因为后者的职责是「提交 AI 任务并等结果」, + * 与运维面板取数是两件事;地址与令牌仍复用 {@code lpt.ai-service} 的配置项,不新增一份配置来源。

+ * + *

上游未配置或调用失败一律返回 {@code configured=false}:余额是面板上的附加信息, + * 拿不到就显示「未配置」,不该让整个页面报错。

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

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

+ */ + private AiUsageIngestResult insertSkippingDuplicates(List entities, + Set knownRecordIds) { + Set seen = new HashSet<>(knownRecordIds); + int accepted = 0; + int duplicated = 0; + for (AiUsageRecordEntity entity : entities) { + if (!seen.add(entity.getRecordId())) { + duplicated++; + continue; + } + try { + aiUsageRecordMapper.insert(entity); + accepted++; + } catch (DuplicateKeyException e) { + duplicated++; + } + } + if (duplicated > 0) { + log.info("AI 用量上报:落库 {} 条,跳过重复 {} 条", accepted, duplicated); + } + return new AiUsageIngestResult(accepted, duplicated); + } + + private AiUsageRecordEntity toEntity(AiUsageRecordRequest record) throws ErrorParameterException { + AiUsageRecordEntity entity = new AiUsageRecordEntity(); + entity.setRecordId(record.getRecordId()); + entity.setOccurredAt(parseUtc(record.getOccurredAt())); + entity.setTaskType(record.getTaskType()); + entity.setTaskId(record.getTaskId()); + entity.setModel(record.getModel()); + entity.setAttempts(record.getAttempts()); + entity.setIsLlmCall(record.getIsLlmCall()); + entity.setUsageSource(record.getUsageSource()); + entity.setPromptTokens(record.getPromptTokens()); + entity.setCompletionTokens(record.getCompletionTokens()); + entity.setTotalTokens(record.getTotalTokens()); + entity.setCacheHitTokens(record.getCacheHitTokens()); + entity.setCacheMissTokens(record.getCacheMissTokens()); + entity.setReasoningTokens(record.getReasoningTokens()); + entity.setCostUsd(record.getCostUsd()); + entity.setPricingVersion(record.getPricingVersion()); + entity.setPeak(record.getPeak()); + entity.setDurationMs(record.getDurationMs()); + entity.setStatus(record.getStatus()); + entity.setErrorCode(record.getErrorCode()); + return entity; + } + + /** 契约 1:occurredAt 是 ISO 8601 UTC 字符串,落库统一换算成 UTC 的本地时间 */ + private static LocalDateTime parseUtc(String occurredAt) throws ErrorParameterException { + try { + return OffsetDateTime.parse(occurredAt.trim()) + .withOffsetSameInstant(ZoneOffset.UTC) + .toLocalDateTime(); + } catch (DateTimeParseException e) { + throw new ErrorParameterException("上报数据里的时间格式不对,需要 ISO 8601 UTC 时间"); + } + } + + // ============ 权限 ============ + + @Override + public boolean isAdmin() { + List adminUsernames = properties.getAdminUsernames(); + if (adminUsernames == null || adminUsernames.isEmpty()) { + return false; + } + // 登录态里是用户 id,白名单配的是用户名,需要这一次转换 + String userName = userService.getUserNameById(StpUtil.getLoginIdAsString()); + return userName != null && adminUsernames.contains(userName); + } + + // ============ 聚合查询 ============ + + @Override + public AiUsageSummary summary(AiUsageQuery query) { + ResolvedFilter filter = resolve(query); + AiUsageSummaryRow row = aiUsageRecordMapper.selectSummary( + filter.from(), filter.to(), filter.taskType(), filter.model()); + 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 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 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) { + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/UserServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/UserServiceImpl.java index 0f2516b..9b9bd9b 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/UserServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/UserServiceImpl.java @@ -33,4 +33,13 @@ public class UserServiceImpl extends ServiceImpl 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(); + } } diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index 61e454c..9e097c0 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -92,4 +92,15 @@ lpt: # 立即投递线程池 executor-core-size: 2 executor-max-size: 4 - executor-queue-capacity: 50 \ No newline at end of file + 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 diff --git a/src/main/resources/db/migration/V20261010_4__add_ai_usage_records.sql b/src/main/resources/db/migration/V20261010_4__add_ai_usage_records.sql new file mode 100644 index 0000000..cf0f4c1 --- /dev/null +++ b/src/main/resources/db/migration/V20261010_4__add_ai_usage_records.sql @@ -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 用量记录(系统级表:不按租户过滤,面板展示的是全部调用)'; diff --git a/src/main/resources/mapper/AiUsageRecordMapper.xml b/src/main/resources/mapper/AiUsageRecordMapper.xml new file mode 100644 index 0000000..818c488 --- /dev/null +++ b/src/main/resources/mapper/AiUsageRecordMapper.xml @@ -0,0 +1,147 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WHERE deleted = 0 + AND is_llm_call = 1 + AND occurred_at >= #{from} + AND occurred_at <= #{to} + AND task_type = #{taskType} + AND model = #{model} + + + + + + + CONCAT(CAST(occurred_at AS DATE), ' ', LPAD(HOUR(occurred_at), 2, '0'), ':00') + + + CONCAT(CAST(occurred_at AS DATE), '') + + + + + + + + + + + + + diff --git a/src/test/java/com/guo/learningprogresstracker/config/AiUsagePropertiesTest.java b/src/test/java/com/guo/learningprogresstracker/config/AiUsagePropertiesTest.java new file mode 100644 index 0000000..2e1aa17 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/config/AiUsagePropertiesTest.java @@ -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} 配置块的绑定守卫。 + * + *

测试环境的 {@code src/test/resources/application.yml} 会遮蔽主配置文件,所以主配置里的键名写错了 + * 测试也照样全绿——只有部署起来才发现白名单是空的、汇率没生效。这里直接读主配置文件绑定一次, + * 把「键名与配置类对不上」挡在提交之前(同 {@code MigrationIndexKeyLengthTest} 直接读迁移文件的思路)。

+ */ +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> 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(); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/config/MybatisPlusConfigTest.java b/src/test/java/com/guo/learningprogresstracker/config/MybatisPlusConfigTest.java index b8b9cd5..81d591c 100644 --- a/src/test/java/com/guo/learningprogresstracker/config/MybatisPlusConfigTest.java +++ b/src/test/java/com/guo/learningprogresstracker/config/MybatisPlusConfigTest.java @@ -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())); diff --git a/src/test/java/com/guo/learningprogresstracker/config/WebMvcConfigTest.java b/src/test/java/com/guo/learningprogresstracker/config/WebMvcConfigTest.java index ba19c54..833506e 100644 --- a/src/test/java/com/guo/learningprogresstracker/config/WebMvcConfigTest.java +++ b/src/test/java/com/guo/learningprogresstracker/config/WebMvcConfigTest.java @@ -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(); diff --git a/src/test/java/com/guo/learningprogresstracker/controller/AiUsageInternalControllerUnitTest.java b/src/test/java/com/guo/learningprogresstracker/controller/AiUsageInternalControllerUnitTest.java new file mode 100644 index 0000000..8b57447 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/controller/AiUsageInternalControllerUnitTest.java @@ -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 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 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 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 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 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 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 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 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; + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerTest.java b/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerTest.java index de5893a..7fcc114 100644 --- a/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerTest.java +++ b/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerTest.java @@ -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 login = loginController.login(loginBody); + CommonResult login = loginController.login(loginBody); assertEquals("登录成功!", login.getMessage()); + // 测试种子用户 admin 命中默认白名单 lpt.ai-usage.admin-usernames + assertTrue(login.getData().isAiAdmin(), "admin 应被识别为用量面板管理员"); } @Test void loingOut() { } -} \ No newline at end of file +} diff --git a/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerUnitTest.java b/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerUnitTest.java index 1abc423..b015e34 100644 --- a/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerUnitTest.java +++ b/src/test/java/com/guo/learningprogresstracker/controller/LoginControllerUnitTest.java @@ -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 result = controller.login(body); + CommonResult 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 result = controller.login(body); + + assertEquals(200, result.getCode()); + assertFalse(result.getData().isAiAdmin(), "非白名单用户不该拿到用量面板入口"); + } + @Test void logout_delegatesToLoginService() { CommonResult result = controller.logout(); diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageAggregationIntegrationTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageAggregationIntegrationTest.java new file mode 100644 index 0000000..570448e --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageAggregationIntegrationTest.java @@ -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 的聚合结果。 + * + *

聚合走自定义 Mapper SQL(SUM / GROUP BY / 窗口函数),{@code Wrapper} 表达不了,因此不能只靠 mock 单测。 + * 这里同时守住三件容易漏的事:逻辑删除条件显式写出、系统级表不做租户过滤、 + * 以及分桶表达式在 H2(MODE=MySQL)与 MySQL 上都能跑。

+ * + *

每条用例用自己独有的时间窗口与任务类型取数,避免同库其他用例的数据串进来。

+ */ +@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.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 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 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 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 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 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.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 rows, String key) { + return rows.stream() + .filter(row -> key.equals(row.getKey())) + .findFirst() + .orElseThrow(() -> new AssertionError("分组里没有 " + key + ",实际:" + rows)); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageClientTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageClientTest.java new file mode 100644 index 0000000..d3e9468 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageClientTest.java @@ -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 覆盖余额代理的透传与降级分支。 + * + *

余额是面板上的附加信息,上游没配置或查不到时必须返回 {@code configured=false} 而不是报错, + * 所以这里把「未配置 / 非 200 / 上游自己说没配置 / 响应解析不了」四条路都走一遍。

+ */ +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()); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageServiceUnitTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageServiceUnitTest.java new file mode 100644 index 0000000..05adbd8 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/AiUsageServiceUnitTest.java @@ -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)。 + * + *

租户条件、逻辑删除与 SQL 聚合本身无法用 mock 表达,由 + * {@code AiUsageAggregationIntegrationTest} 落库守住。

+ */ +@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; + } +}