11 KiB
11 KiB
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)
项目结构
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 端点总览(86 个)
| 模块 | 端点数 | 端点 |
|---|---|---|
| 登录认证 | 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 |
| 任务管理 | 15 | GET/POST /tasks, GET/PUT/DELETE /tasks/{taskId}, GET/PUT /tasks/priority-weights, GET /tasks/options, 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 |
| 复习与导图 | 19 | GET /review/feed, PUT /review/feed/{fragmentId}/feedback, POST /review/feed/{fragmentId}/touched, GET /review/sort-preference, PUT /review/sort-preference, GET /review/summary, 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} |
| 标签导图 | 4 | POST /review/tag-mind-map/query, PUT /review/tag-mind-map, GET /review/tag-mind-map/list, POST /review/tag-mind-map/recall-records |
| 知识碎片 | 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} |
| 统一标记 | 12 | GET /markers, POST /markers, POST /markers/batch, DELETE /markers/{id}, PUT /markers/rename, GET /markers/filter, GET /markers/tags, GET/POST /markers/tags/dictionary, PUT/DELETE /markers/tags/dictionary/{id}, GET /markers/tags/candidates |
| 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,Cookiesatoken,支持@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决定。
启动命令
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 调用其异步任务接口 |