- 新增 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 过滤
182 lines
11 KiB
Markdown
182 lines
11 KiB
Markdown
# 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 调用其异步任务接口 |
|