# 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) ## 项目结构 ```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 端点总览(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`,Cookie `satoken`,支持 `@SaCheckPermission` 注解式权限。 - 响应格式:`CommonResult` 统一包装 `{ 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`) ## 启动命令 ```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 调用其异步任务接口 | ## 项目规范 ## 数据库迁移(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.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 方法 - **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml` - 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `` - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串