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

- 新增 ai_usage_records 表(系统级表,不按租户过滤)与幂等上报接口
- 新增按时间/任务类型/模型的汇总、趋势、明细查询,仅白名单用户可见
- 登录响应返回 aiAdmin,供前端决定是否展示入口
This commit is contained in:
2026-10-10 18:46:01 +08:00
parent 02d5c24946
commit 650b0956de
39 changed files with 2355 additions and 15 deletions
+29 -4
View File
@@ -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