Files
lpt-be/AGENTS.md
T
cat-shark 1ba3ae5a04 feat: 用量统计支持用户维度报表
- 新增 ai_usage_records.user_id 与 (user_id, occurred_at) 索引,NULL 表示未归属
- 归属标记跟着请求走:AiServiceClient 提交任务时带上顶层 callerRef(当前用户 id),
  lpt-ai 原样透传,上报后落到 user_id。取不到身份就不带,绝不让 AI 调用因此失败
- breakdown 支持 groupBy=user,新增 label(登录名,未归属为「未归属」);
  summary/series/breakdown 支持 userId 过滤
2026-10-10 20:28:04 +08:00

182 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LPT 后端服务(lpt-be)
> Java Spring Boot 后端,提供 REST API、数据库访问、认证鉴权。
## 规则与技能位置
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`(本仓库的 Git 提交规范也统一在其中的 `commit-convention.md`,本文件不再重复)
- 本仓库专属规则:`roles/`
- `roles/database-migration.md`:数据库迁移(Flyway Migration)
- `roles/data-access.md`:编码规范 · 数据访问层
- `roles/api-response.md`:响应规范、DTO 转换
- `roles/ownership-and-markers.md`:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01)
- `roles/ai-integration.md`:学习引导(复习-06)、AI 异步链路(AI-02)
- 本仓库专属技能:`skills/`(如 `comment-cleanup`)
## 技术栈
- Java 17
- 框架:Spring Boot 3.2.5
- ORM:MyBatis-Plus 3.5.5
- 数据库:MySQL 8.0
- 认证:Sa-Token 1.38.0,Cookie 名 `satoken`
- 数据库迁移:Flyway
- 对象映射:MapStruct 1.5.5
- 连接池:Druid 1.2.8
- 密码加密:jBCrypt 0.4
- API 文档:Knife4j (OpenAPI 3)
- Lombok(@Data, @Slf4j)
## 项目结构
```text
lpt-be/src/main/java/com/guo/learningprogresstracker/
├── controller/ → REST 接口层
├── service/ → 业务逻辑层(接口 + impl)
├── mapper/ → MyBatis-Plus BaseMapper
├── entity/ → 数据库实体
├── dto/ → 请求/响应 DTO
├── config/ → Spring 配置
├── common/ → 全局异常处理、Ops
├── mapStruct/ → MapStruct Converter
├── enums/ → 枚举类
├── exception/ → 自定义异常
└── utils/ → 工具类
```
- controller 只做参数校验和路由。
- service/impl 承载业务逻辑。
- mapper 使用 MyBatis-Plus BaseMapper。
- entity 使用 `@TableName`、`@TableField` 映射数据库字段。
- mapStruct 承载 DTO 转换。
## API 端点总览(75 个)
| 模块 | 端点数 | 端点 |
|------|--------|------|
| 登录认证 | 2 | `POST /login`, `POST /logout` |
| 学习会话 | 11 | `PUT /study-sessions/{sessionNum}/expectation`, `GET /study-sessions/{sessionNum}/expectation`, `GET /study-sessions/{sessionNum}`, `POST /study-sessions/{sessionNum}/study-sessions/continue`, `POST /study-sessions/{sessionNum}/study-sessions/pause`, `POST /study-sessions/{sessionNum}/study-sessions/ended`, `POST /study-sessions/{sessionNum}/study-sessions/abort`, `GET /study-sessions/{sessionNum}/all-fragments`, `GET /study-sessions/tasks/{taskNum}/fragments`, `GET /study-sessions/tasks/{taskNum}/reports`, `GET /study-sessions/active` |
| 任务管理 | 14 | `GET/POST /tasks`, `GET/PUT/DELETE /tasks/{taskId}`, `GET/PUT /tasks/priority-weights`, `GET/POST /tasks/{taskNum}/applications`, `PUT/DELETE /tasks/applications/{id}`, `GET /tasks/{taskNum}/study-sessions/start-or-continue`, `GET /tasks/{taskNum}/not-ended-study-session`, `GET /tasks/{taskId}/deletion-preview` |
| 复习与导图 | 18 | `GET /review/feed`, `PUT /review/feed/{fragmentId}/feedback`, `POST /review/feed/{fragmentId}/touched`, `GET /review/sort-preference`, `PUT /review/sort-preference`, `GET /review/tasks`, `GET /review/tasks/{taskNum}`, `GET /review/task/{taskNum}`, `GET /review/report/{id}`, `GET /review/report/{id}/structured`, `PUT /review/report/{id}`, `DELETE /review/report/{id}`, `GET /review/fragment/{id}`, `GET /review/standard-mind-map/{taskNum}`, `PUT /review/standard-mind-map/{taskNum}`, `POST /review/standard-mind-map/{taskNum}/find-node`, `GET /review/standard-mind-map/{taskNum}/recall-records`, `GET /review/standard-mind-map/recall-records/{recordId}` |
| 知识碎片 | 6 | `POST /report-fragments`, `PUT /report-fragments/{id}`, `PUT /report-fragments/{id}/ownership`, `DELETE /report-fragments/{id}`, `GET /report-fragments/session/{sessionNum}`, `GET /report-fragments/pending-ownership` |
| 数据导出 | 2 | `GET /export/task/{taskNum}`, `GET /export/range` |
| 学习引导 | 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=...` |
> 「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` 比对。
## 数据库(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` 过滤,管理员只能看到自己触发的那几次,面板等于永远是空的。
## 关键机制
- 多租户隔离:`TenantLineInnerInterceptor` 自动注入 `WHERE created_by = #{当前用户}`,排除 `user`/`flyway_schema_history` 表。
- 自动填充:`MetaObjectHandler` 自动填充 `created_by`/`updated_by`/`created_time`/`updated_time`。
- 认证鉴权:Sa-Token 拦截 `/**` 排除 `/login`,Cookie `satoken`,支持 `@SaCheckPermission` 注解式权限。
- 响应格式:`CommonResult<T>` 统一包装 `{ code, message, data }`。
- CORS:可配置,local profile 允许所有来源。
### 行级数据隔离(多租户拦截器)
- **配置类:** `MybatisPlusConfig` 注册 `TenantLineInnerInterceptor`
- **租户字段:** `created_by`(每个业务表的创建人字段)
- **租户值来源:** `StpUtil.getLoginIdAsString()`(当前登录用户)
- **自动注入:** 所有 SELECT/UPDATE/DELETE 语句自动追加 `WHERE created_by = #{当前用户}`
- **归属校验:** 查询单条记录时拦截器自动校验 `created_by`,非本人数据直接返回空
- **排除表:** `user`、`flyway_schema_history`、`databasechangelog`、`databasechangeloglock`、`ai_usage_records`
(`ai_usage_records` 是系统级表,用量要统计全部调用,不能按 `created_by` 切分)
### 自动填充(MetaObjectHandler)
- **created_by / updated_by:** 插入/更新时自动填充为当前登录用户
- **created_time / updated_time:** 插入/更新时自动填充当前时间
### 认证鉴权(Sa-Token)
- **会话管理:** 基于 `StpUtil` 的登录/登出/会话查询
- **权限校验:** `@SaCheckPermission` 注解式权限控制
- **未登录处理:** 全局异常处理器捕获 `NotLoginException` 返回 401
## CORS
- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins`。
- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`,兼容 `allowCredentials`。
## 标题抓取
- `TitleFetcher`:静态工具类,支持 HTTP→HTTPS 重定向和宽松 SSL。
- `UtilsController`:`GET /utils/fetch-title?url=...` 代理端点。
## 运行环境
- 默认 profile:local(`application.yml` 中 `spring.profiles.active: local`)。
- 编译命令:`mvn clean compile -DskipTests`,需要 JDK 17。
## 配置文件
| Profile | 文件 |
|---------|------|
| local | `application-local.yml` |
| dev | `application-dev.yml` |
| uat | `application-uat.yml` |
| prod | `application-prod.yml` |
| 公共 | `application.yml` |
## AI 服务依赖
- 配置:`lpt.ai-service.url=http://localhost:5199`
- 超时:600s
- 入站令牌(安全-03):`lpt.ai-service.token`,空表示 lpt-ai 未启用令牌校验。
部署侧用 `LPT_AI-SERVICE_TOKEN`(`lpt-secrets/lpt-ai-token`,`optional: true`)注入;
注意变量名带连字符才能映射到 `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)。
- **分组维度**:`breakdown?groupBy=taskType|model|user`。用户维度下 `key` 是用户 id
(未归属为 `null`)、`label` 是登录名(未归属为「未归属」,查不到登录名时回退为 `key`);
其它维度下 `label` 等于 `key`,前端统一渲染 `label` 即可。用户筛选用 `userId` 参数。
- **归属链路(callerRef)**:lpt-ai 不知道调用方是谁,所以归属标记跟着请求走——
`AiServiceClient` 提交任务时把当前用户 id 作为**顶层** `callerRef` 带上(取不到身份就不带,
记为未归属,绝不让 AI 调用因此失败),lpt-ai 原样透传,上报后落到 `user_id`。
标记在 LLM 调用之前就已确定,因此没有「上报先到、归属还没写回」的竞态。
**`callerRef` 不能放进 `params`**:params 会喂给 prompt 模板、也参与 lpt-ai 的幂等键。
- **`user_id` 不是租户列**:本表在 `EXCLUDE_TABLES` 中,`user_id` 只用于分组与筛选。
改成租户过滤会让管理员只能看到自己触发的调用,面板等于永远是空的。
- 配置:`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
mvn clean compile -DskipTests # 编译(需要 JDK 17)
mvn spring-boot:run # 启动(默认 profile: local)
```
## 关联项目
| 项目 | 路径 | 端口 | 说明 |
|------|------|------|------|
| lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端,通过 `/api` 代理调用本服务 |
| lpt-ai | `../lpt-ai/` | 5199 | AI 服务,本服务通过 HTTP 调用其异步任务接口 |