lpt-be/.pi/SYSTEM.md

LPT 后端服务（lpt-be）

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

---

技术栈

• 框架: Spring Boot 3.2.5
• ORM: MyBatis-Plus 3.5.5
• 数据库: MySQL 8.0（端口 8109，服务器 39.105.149.197）
• 认证: Sa-Token 1.38.0（Cookie 名 satoken）
• 数据库迁移: Flyway
• 对象映射: MapStruct 1.5.5
• 连接池: Druid 1.2.8
• 密码加密: jBCrypt 0.4
• API 文档: Knife4j (OpenAPI 3)

---

项目结构

lpt-be/src/main/java/com/guo/learningprogresstracker/
├── controller/   → REST 接口层（6个控制器）
├── service/      → 业务逻辑层（12个服务接口 + impl）
├── mapper/       → MyBatis-Plus BaseMapper（10个）
├── entity/       → 数据库实体（10个）
├── dto/          → 请求/响应 DTO
│   ├── request/  → 请求体
│   └── response/ → 响应体
├── config/       → Spring 配置
├── common/       → 全局异常处理、Ops
├── mapStruct/    → MapStruct Converter
├── enums/        → 枚举类
├── exception/    → 自定义异常
└── utils/        → 工具类

---

API 端点总览（32 个）

模块	端点数	端点
学习会话	9	POST /study-sessions/{taskNum}/start, PUT .../pause, PUT .../resume, PUT .../end, POST .../fragments, GET .../history, PUT .../expectation, GET .../expectation, GET .../report-draft
标准思维导图	6	GET /review/standard-mind-map/{taskNum}, POST .../regenerate, PUT ..., POST .../recall, POST .../find-node, GET .../recall-records
复习模块	6	GET /review/feed, GET /review/task/{taskNum}, GET /review/report/{id}, GET /review/fragment/{id}, GET /review/standard-mind-map/recall-records/{recordId}, GET /review/tasks
任务管理	6	GET /tasks, POST /tasks, PUT /tasks/{taskNum}, DELETE /tasks/{taskNum}, GET /tasks/priority-weights, PUT /tasks/priority-weights
应用场景	4	GET/POST/PUT/DELETE /tasks/{taskNum}/applications[/{id}]
工具	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<T> 统一包装 { code, message, data }
• CORS: 可配置，local profile 允许所有来源

---

配置文件

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
• 不可用时自动降级到内置规则引擎（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 调用其异步任务接口

调用关系

浏览器 → lpt-fe (5158) ──/api──→ lpt-be (5157) ──HTTP──→ lpt-ai (5199)
                                      │
                                      └── MySQL (8109)