16 KiB
16 KiB
LPT 后端服务(lpt-be)
Java Spring Boot 后端,提供 REST API、数据库访问、认证鉴权。
Git 提交规范
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:
类型: 简述,例如feat: 新增用户登录接口、fix: 修复多租户拦截器空指针、docs: 补充API文档。
技术栈
- 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 端点总览(69 个)
| 模块 | 端点数 | 端点 |
|---|---|---|
| 登录认证 | 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 |
| 工具 | 1 | GET /utils/fetch-title?url=... |
数据库(10 个核心表)
users, tasks, study_sessions, study_reports, study_report_fragments, study_expectations, task_applications, review_standard_mind_maps, review_recall_records, user_priority_weights
内容归属与结构化报告(归属-01 / 报告-01)
知识碎片有两个互相独立的维度,改动任何一处都要先分清是哪一维:
- 记录上下文(
context_type+context_num):产生于哪次学习会话或复习行为。由系统确定、不可变、不可为空;用于时间统计与「这份报告里有哪些碎片」。 - 内容归属(
owner_task_num):内容在知识结构上属于哪个任务。由用户确定、可变、可为空(为空即待归类);用于导图取材、按任务检索与统计。
由此得出的几条硬约束:
- 导图、按任务检索、碎片计数一律按内容归属(
owner_task_num),不再用「该任务的会话所产生的报告/碎片」。 - 报告按会话生成,报告的任务来自它所属会话——这与上一条是两个视角,是有意为之,不是重复。
- 新建碎片时内容归属默认取该会话所属任务;用户可以改到别的任务或清空为待归类。
- 归属变化(或碎片删除)会把原任务与新任务的标准导图标记为
needs_update=1;重建由用户手动触发,不自动跑 AI。 - 报告只落库三段文本(
session_summary/expectation_verdict/free_summary);「按归属分组的碎片」不落库,查看时按当前归属实时聚合,以免与导图取材出现两套口径。文档里的展示顺序是:会话摘要 → 预期达成判断 → 按归属分组的碎片 → 自由总结。 - 删除报告不连带删除碎片;删除任务时碎片保留并把归属置空(进入待归类),其余(会话、报告、导图、回忆记录、应用场景)随任务软删除。
标记(标记-01)
标记是附加在对象上的轻量元信息,统一存放,新增一种标记不改各功能表结构。
- 可挂对象只有知识碎片与学习任务:报告是会话的派生结果且已有「按归属分组」这一维度;会话是时间轴对象,其流程性信息留在主体上。
- 两类彻底分开:系统标记走
SystemMarkerEnum固定词表、由系统写入、用户只读;用户标签自由增删改。分开的理由是「找出所有来自 X 的内容」这类检索必须可靠。 - 系统标记成对(名 = 值),用户标签只有名(标签名本身就是全部信息)。
- 检索只提供单一标记筛选;标记对用户全部可见,标签可改名可删除(改名安全:标记不参与聚合口径)。
- 标记不是状态:会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上。碎片上的复习反馈(已掌握/稍后再看)也因此落在碎片自身字段,不进标记表。
- 对象被删除时清理其标记(
MarkerService.removeAllMarkers)。
学习引导(复习-06)
一次引导是一次复习行为,有自己的记录实体 review_guidance_conversations:
- 产出的知识碎片以它作为记录上下文(
context_type=REVIEW),默认内容归属为被引导概念所属任务,并带FROM_GUIDANCE系统标记。 - 复习耗时记在会话行上(与回忆对比同一口径)。
- 多轮对话复用 AI 异步任务:每轮提交一个
GUIDANCE任务,前端轮询取回复;AI 回复会写回会话轮次,供下一轮作为上下文。 - 没有降级形态:AI 不可用时该链路直接失败,前端把入口置为不可用。
AI 异步链路(AI-02)
生成类能力(回忆对比、标准导图、报告草稿)不在请求线程里等 AI:
- 前端
POST /ai/tasks提交,秒级拿到taskNum;随后轮询GET /ai/tasks/{taskNum}直到SUCCEEDED/FAILED。 - 结果写在
ai_tasks.result_payload,按taskNum可重复获取,刷新或离开页面都不丢。 - 同一用户 + 同一类型 + 同一目标已有进行中任务时复用该任务(AI-04),不重复生成。
- 执行器在
ai-task-*线程池里跑;提交后立即投递,@Scheduled兜底扫描接手投递失败或进程重启的任务。 - 后台线程必须显式声明身份:执行线程没有 Web 上下文,租户拦截器与
MetaObjectHandler字段自动填充都取不到当前用户。执行器用TenantContext.callAs(task.createdBy, ...)绑定任务所属用户;请求线程不受影响(没有绑定时仍走StpUtil)。新增后台任务时必须照此处理,否则会抛NotWebContextException。 - 禁止在
@Transactional方法内调用 AI:等待 AI 期间不得占用数据库连接。
关键机制
- 多租户隔离:
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 允许所有来源。
响应规范
- 成功:
CommonResult.success(data),code=200。 - 业务错误:
CommonResult.error(msg),code=400,HTTP 200。 - 未登录:
GlobalExceptionHandler.handleNotLogin(),HTTP 401 + code=401。 - 参数校验失败:
MethodArgumentNotValidException,code=400。 - 用户可见错误文案必须口语化、可理解,避免“无法生成”“不存在”等技术化表述;技术细节写入日志。例如无学习报告时应提示“这个任务还没开始学习哦,学习后产生学习报告后再来吧”,而不是“没有学习报告,无法生成思维导图”。
DTO 转换
- MapStruct 编译期生成
*ConvertImpl.java,同名属性自动映射。 - 默认
unmappedTargetPolicy = IGNORE。 - 自定义映射使用
@Mapping(source, target)。 - 增删 DTO 字段后必须重新编译,否则生成代码不含新字段。
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)
启动命令
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 调用其异步任务接口 |
项目规范
数据库迁移(Flyway Migration)
测试用 H2、部署用 MySQL:这几件事 H2 测不出来
迁移脚本在测试里跑的是 H2(MODE=MySQL),它与真实 MySQL 的差异会造成「测试全绿、部署起不来」:
- 索引键长度上限:InnoDB 对索引键有 3072 字节硬上限(DYNAMIC 行格式),超了直接报 error 1071;
utf8mb4 下
VARCHAR(n)要按4n字节算,多列唯一键很容易越界。H2 不校验。 → 改动任何索引后跑MigrationIndexKeyLengthTest(它直接读迁移文件复算键长)。 - 整型显示宽度:
TINYINT(1)在 MySQL 8.0.17 起被标记弃用(MySQL 9.7 文档确认尚未移除,只是弃用)。 这里刻意保留TINYINT(1):它正是 JDBC 把列映射成Boolean的惯用声明,换成裸TINYINT会让布尔字段的映射行为依赖连接参数。 - 遇脏数据要响亮失败:
V20261009_3(业务编号唯一约束)与V20261009_5(计时列类型修正) 在历史数据不干净时会直接让启动失败。这是有意的——宁可失败也不静默跳过约束。部署前先按迁移注释里的核对 SQL 检查。
命名规则
- 脚本格式:
V{YYYYMMDD}_{序号}__{描述}.sql - 日期必须使用实际编写日期,不得使用过去的日期
- 序号从 1 开始,同一天多个脚本递增
- 描述使用下划线分隔的英文短语
核心原则
- 不可变性:已执行的迁移脚本永远不得修改
- 只增不减:数据库变更只能通过新增迁移脚本实现
- 向后兼容:新脚本应兼容已有数据
操作规范
- 删除表:创建新迁移脚本,使用
DROP TABLE IF EXISTS - 修改表结构:使用
ALTER TABLE语句 - 新增表:创建新迁移脚本,使用
CREATE TABLE
框架机制
行级数据隔离(多租户拦截器)
- 配置类:
MybatisPlusConfig注册TenantLineInnerInterceptor - 租户字段:
created_by(每个业务表的创建人字段) - 租户值来源:
StpUtil.getLoginIdAsString()(当前登录用户) - 自动注入: 所有 SELECT/UPDATE/DELETE 语句自动追加
WHERE created_by = #{当前用户} - 归属校验: 查询单条记录时拦截器自动校验
created_by,非本人数据直接返回空 - 排除表:
user、flyway_schema_history、databasechangelog、databasechangeloglock
自动填充(MetaObjectHandler)
- created_by / updated_by: 插入/更新时自动填充为当前登录用户
- created_time / updated_time: 插入/更新时自动填充当前时间
认证鉴权(Sa-Token)
- 会话管理: 基于
StpUtil的登录/登出/会话查询 - 权限校验:
@SaCheckPermission注解式权限控制 - 未登录处理: 全局异常处理器捕获
NotLoginException返回 401
编码规范
数据访问层
- 优先使用纯 MyBatis-Plus Java API(
Wrappers.<T>lambdaQuery()、selectList、selectById等),避免手写 XML SQL - 复杂查询通过
Wrappers链式构建条件,必要时使用.apply()拼接原生 SQL 片段 - 查询结果一律用类承载,禁止
selectMaps+ 字符串 key 取值- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:
map-underscore-to-camel-case与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),row.get("taskNum")会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错 - 单列聚合用
selectObjs,多列聚合用下面的自定义 Mapper 方法
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:
Wrapper表达不了的查询(SUM/GROUP BY/多表JOIN)收敛到 Mapper 层,用自定义方法 + 显式结果类(dto/下的类或实体),参考ReviewRecallRecordMapper.sumReviewDurationByTask→dto/TaskReviewDuration+resources/mapper/ReviewRecallRecordMapper.xml- 结果映射:列名与属性能对应时可用自动映射,但
map-underscore-to-camel-case必须在application.yml里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式<resultMap> - 自定义 SQL 不会被
@TableLogic自动追加逻辑删除条件,必须显式写deleted = 0;租户条件created_by = ?仍由TenantLineInnerInterceptor自动追加 - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考
ReviewDurationIntegrationTest) - 反向约束:
Wrapper能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
- 结果映射:列名与属性能对应时可用自动映射,但