# 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 端点总览(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` ## 关键机制 - 多租户隔离:`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 允许所有来源。 ### 行级数据隔离(多租户拦截器) - **配置类:** `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 ## 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 调用其异步任务接口 |