# LPT 后端规范

## 技术栈
- Java 17, Spring Boot 3.2.5
- MyBatis-Plus 3.5.5 + MySQL
- MapStruct 1.5.5（编译期生成代码，DTO 增删字段后需重新编译）
- Sa-Token 1.38.0（认证/鉴权）
- Flyway（数据库迁移）
- Lombok（@Data, @Slf4j）

## 项目结构
```
controller/   → REST 接口，只做参数校验和路由
service/      → 业务逻辑
  impl/
mapper/       → MyBatis-Plus BaseMapper
entity/       → 数据库实体（@TableName, @TableField）
dto/          → 请求/响应 DTO
  request/
  response/
config/       → Spring 配置（WebMvcConfig, JacksonConfig 等）
utils/        → 工具类
common/       → GlobalExceptionHandler, Ops 等
mapStruct/    → MapStruct Converter 接口
```

## 响应规范
- 统一使用 `CommonResult<T>` 包装：`{ code, message, data }`
- 成功：`CommonResult.success(data)` → code=200
- 业务错误：`CommonResult.error(msg)` → code=400, HTTP 200
- 未登录：`GlobalExceptionHandler.handleNotLogin()` → HTTP 401 + code=401
- 参数校验失败走 `MethodArgumentNotValidException` → code=400

## 认证
- SaInterceptor 注册在 `WebMvcConfig`（无 @Profile 限制，所有环境生效）
- 拦截 `/**`，排除 `/login`
- `StpUtil.checkLogin()` 失败 → NotLoginException → GlobalExceptionHandler → 401
- Cookie 名 `satoken`，前端 axios 需 `withCredentials: true`

## 数据库变更
- Flyway 迁移文件：`src/main/resources/db/migration/V{日期}_{序号}__{描述}.sql`
- 文件名日期格式：`yyyyMMdd`

## DTO 转换
- MapStruct 编译期生成 `*ConvertImpl.java`（target/generated-sources/）
- 同名属性自动映射，`unmappedTargetPolicy = IGNORE`
- 如需自定义映射用 `@Mapping(source, target)`
- **增删 DTO 字段后必须重新编译**，否则 MapStruct 生成代码不含新字段

## CORS
- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins` 配置
- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`（兼容 allowCredentials）
- local profile：`allow-credentials: true`, `allowed-origins: '*'`

## 标题抓取
- `TitleFetcher`：静态工具类，支持手动跟随 HTTP→HTTPS 重定向、宽松 SSL
- `UtilsController`：`GET /utils/fetch-title?url=...` 代理端点

## 运行
- 默认 profile：local（application.yml 中 `spring.profiles.active: local`）
- IDEA JDK：`C:/Users/cat-win/.jdks/ms-17.0.19`
- Maven：IDEA 内置 `C:/Program Files/JetBrains/IntelliJ IDEA 2026.1.3/plugins/maven/lib/maven3/bin/mvn`
- 编译：`mvn clean compile -DskipTests`（须用 JDK 17）