Files
lpt-be/AGENTS.md
T
cat-shark cf7518c320 feat: 回忆去掉结束状态,新增按标签查相关导图
- 删除 status/endedAt 与结束接口,回忆只能继续编辑,用时继续累计
- 新增 review_recall_scope_tags 索引表与回填迁移,按标签交集查询保存导图
- 新增 GET /review/recalls/related,分页在 SQL 完成;列表支持 excludeRecallNum
- 范围匹配不到知识碎片时拒绝开始回忆(SCOPE_EMPTY)
2026-11-22 21:41:31 +08:00

15 KiB
Raw Blame History

LPT 后端服务(lpt-be)

Java Spring Boot 后端,提供 REST API、数据库访问、认证鉴权。

规则与技能位置

  • 通用规则(跨仓库):meta 仓库 .agents/roles/(本仓库的 Git 提交规范也统一在其中的 commit-convention.md,本文件不再重复)
  • 命名:业务概念的英文名以 lpt-docs/docs/concepts/README.md 术语表为准,库表、实体、DTO 字段由它派生,不另起别名(规则见 meta .agents/roles/business-terminology.md)。
  • 本仓库专属规则:.agents/roles/
    • .agents/roles/database-migration.md:数据库迁移(Flyway Migration)
    • .agents/roles/code-standards.md:后端代码规范的取值与出处(Checkstyle 门禁、棘轮、不采纳的上游规则)
    • .agents/roles/code-review-checklist.md:Checkstyle 查不了、必须人看的评审项(实体出 controller、Map 请求体、patch 更新等)
    • .agents/roles/data-access.md:编码规范 · 数据访问层与写入形态
    • .agents/roles/api-response.md:响应规范、DTO 转换
    • .agents/roles/ownership-and-markers.md:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01)
    • .agents/roles/ai-integration.md:学习引导(复习-06)、AI 异步链路(AI-02)
    • 跨服务校验归属:不写在本仓库,统一按 meta 仓库 .agents/roles/service-boundaries-and-validation.md (结构由产出方保证、LLM 输出在调用模型的那侧校验、接收方只做映射)
  • 本仓库专属技能:.agents/skills/(如 comment-cleanup);决策笔记:.agents/notes/(见下节「重要改动必须留笔记」)

本仓库的 .agents/ 只放 lpt-be 独有的东西(上述专属规则、comment-cleanup、本仓笔记)。 共有技能(write-notes-like-deepseek、mermaid-diagram)只在 meta 的 .agents/skills/,本仓库不放副本。 agent 在 meta 根目录运行,改动本仓库用 subagent(cwd=lpt-be);详见 meta AGENTS.md。

重要改动必须留笔记

规则来源:meta 仓库 .agents/skills/write-notes-like-deepseek/SKILL.md(动手前先读它,本文件只列接入约定)。

  1. 非平凡改动先立笔记:改了行为、架构、跨文件契约、流程与工具链、测试策略、落盘/网络/配置格式, 或写了会被以后重新审视的取舍,就在 .agents/notes/ 下写或更新一篇;纯机械改(样式、格式化、打标、 不改行为的依赖补丁、常规 CRUD)直接提交,不要为了留痕而留痕。
  2. 先检索再动手:rg --hidden --glob '!.agents/notes/archived/**' "<机制名或关键词>" .agents/notes/, 有归属就就地更新那篇(路径、类名、默认值等事实直接改);决定翻转则新开一篇并互链,禁止把 ## Decision 改成反面。
  3. 生命周期:动手前写 proposed/;落地后移到 implemented/ 并改成现在时;方案被否决且能防重犯写 rejected/;彻底被取代才归档。路径格式 {proposed|implemented|rejected}/{feature|bug-fix|simplification|architecture|process|testing}/yyyy-mm-dd-主题.md。
  4. 备选方案先写对方最强理由再否决;真实没考虑过备选就写「无」,不要编造凑数。
  5. 提交前跑校验(在 meta 根目录,无 git hook,靠自觉):
    node .agents/scripts/verify-notes.ts lpt-be
    
    未接 CI 强制门,红了先修再交。

技术栈

  • 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 端点总览(87 个)

模块 端点数 端点
登录认证 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
复习与导图 20 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}, GET /review/recalls/related
标签导图 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 比对。

自由回忆的 /review/recalls 系列(创建、列表、详情、恢复、保存、来源、删除)未在本表逐条列出。 其中 GET /review/recalls 支持可选 excludeRecallNum,由 SQL 排除指定的那条回忆(最近回忆首屏用它排除顶部「上次编辑的导图」)。 GET /review/recalls/related 按所选标签(重复 tags 参数,1–10 个)查保存过的导图,命中标签多的在前,分页在 SQL 里完成。

数据库(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 决定。

启动命令

mvn clean compile -DskipTests   # 编译(需要 JDK 17)
mvn spring-boot:run              # 启动(默认 profile: local)
./mvnw validate                  # 先跑 Checkstyle,违规即失败
  • Checkstyle 门禁:./mvnw validate 会先跑 Checkstyle(绑 validate 阶段,failOnViolation=true,只查 src/main/java), test / package / CI / Docker 构建都会先撞上它。配置在 config/checkstyle/:checkstyle.xml 是规则与阈值, suppressions.xml 是存量豁免基线(改到被豁免的文件时顺手删掉对应豁免行)。
  • 应急跳闸:-Dcheckstyle.skip=true 只用于本地临时绕过(failOnViolation 写死在 pom,user property 覆盖不了), 推之前必须再跑一次 ./mvnw validate。规则取值、理由与出处见 .agents/roles/code-standards.md。

关联项目

项目 路径 端口 说明
lpt-fe ../lpt-fe/ 5158 Vue 3 前端,通过 /api 代理调用本服务
lpt-ai ../lpt-ai/ 5199 AI 服务,本服务通过 HTTP 调用其异步任务接口