feat: 新增 AI 用量落库与统计接口
- 新增 ai_usage_records 表(系统级表,不按租户过滤)与幂等上报接口 - 新增按时间/任务类型/模型的汇总、趋势、明细查询,仅白名单用户可见 - 登录响应返回 aiAdmin,供前端决定是否展示入口
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user