ylsw-bw/.cursor/rules/java/java-tf-ylsw-backend.mdc

---
description: tf-ylsw 后端 MUST/SHOULD（ResultRespone、Swagger、ToFlyAppLog、Wrappers/XML、字段与 SQL 性能、雪花 ID、包结构）
globs: "**/*.java,**/mapper/**/*.xml"
alwaysApply: false
---

# tf-ylsw 代码生成与开发规则

本规则用于统一 `controller`、`service`、`mapper/xml`、数据库字段及代码生成行为。  
规则级别：

- **MUST**：强制要求，不满足视为不合规。
- **SHOULD**：推荐要求，特殊情况可说明原因后例外。

## 1. Controller 返回值规范

- **MUST**：所有接口返回类型使用 `ResultRespone<T>`，必须显式声明泛型，不允许裸类型 `ResultRespone`。
- **MUST**：接口方法必须有明确 `return` 值，不允许返回 `null`。
- **SHOULD**：按实际业务选择泛型，如：
  - 分页：`ResultRespone<Page<XXXVo>>`
  - 详情：`ResultRespone<XXXVo>` / `ResultRespone<XXX>`
  - 写操作：`ResultRespone<Boolean>` 或 `ResultRespone<Object>`

## 2. Swagger 注解规范

- **MUST**：所有 Controller 类添加 `@Api(tags = "...")`。
- **MUST**：所有接口方法添加 `@ApiOperation(value = "...")`。
- **MUST**：路径参数、关键查询参数添加 `@ApiImplicitParam(s)` 或等价参数说明注解。
- **SHOULD**：`value`/`tags` 使用中文业务语义，避免“新增1”“方法2”这类无意义描述。

## 3. POST 接口入参规范

- **MUST**：所有 `@PostMapping` 接口使用 `@RequestBody` 接收业务对象参数。
- **MUST**：如需校验，配合 `@Valid` + `BindingResult`（或全局异常方式）进行参数校验。
- **SHOULD**：一个 POST 仅接收一个主体 DTO；多对象场景优先封装聚合 DTO，避免多个离散参数。

## 4. 操作日志规范（ToFlyAppLog）

- **MUST**：所有写操作接口（至少 `POST`，建议包含 `PUT/DELETE`）增加 `@ToFlyAppLog(title = "...")`。
- **MUST**：`title` 必须是可读的业务动作描述，如：`新增漏损工单管理`、`修改车辆人员绑定`。
- **SHOULD**：`@ToFlyAppLog` 的 `title` 与 `@ApiOperation` 业务语义保持一致。

示例：

```java
@PostMapping("/save")
@ApiOperation(value = "新增漏损工单管理")
@ToFlyAppLog(title = "新增漏损工单管理")
public ResultRespone<Boolean> save(@RequestBody @Valid LeakOrderDto dto) {
    return ResultRespone.success(leakOrderService.saveLeakOrder(dto));
}
```

## 5. Service 代码注释与外部接口日志

- **MUST**：Service 中关键业务逻辑（复杂分支、补偿逻辑、状态流转、金额/计费计算）添加简要注释，说明“为什么这样做”。
- **MUST**：调用外部接口（HTTP/Feign/第三方 SDK）时打印日志，至少包含：
  - 请求地址（URL/服务名+路径）
  - 请求参数（脱敏后）
  - 响应结果（脱敏后）
  - 耗时与调用结果状态（成功/失败）
- **MUST**：异常分支记录错误日志并保留关键上下文，禁止吞异常。
- **SHOULD**：日志中不得输出明文密码、token、身份证、手机号全量等敏感信息。

## 6. 查询实现选择（Wrappers vs XML）

- **MUST**：简单单表 CRUD/条件查询优先使用 MyBatis-Plus `Wrappers` / LambdaQueryWrapper。
- **MUST**：复杂查询（多表 JOIN、子查询、聚合统计、窗口函数、跨库兼容）在 `mapper.xml` 中编写 SQL。
- **SHOULD**：复杂 SQL 在 XML 中按“条件块、关联块、排序块”分段，便于维护和优化。

## 7. 数据库字段命名规范

- **MUST**：定义数据库字段时避免数据库关键字（如 `order`, `group`, `index`, `level`, `user` 等）。
- **MUST**：字段命名采用有业务语义的英文/拼音缩写，避免 `a1/b2/tmp` 等无意义命名。
- **SHOULD**：统一下划线命名风格（`snake_case`），与现有表规范保持一致。

## 8. SQL 性能与 OR 使用规范

- **MUST**：编写 SQL 时避免无约束的大范围 `OR` 条件。
- **MUST**：必须考虑大数据量性能：索引命中、回表次数、排序/分页成本。
- **SHOULD**：可通过 `UNION ALL`、条件拆分、覆盖索引、先分页后关联等方式替代低效写法。
- **SHOULD**：上线前对核心 SQL 做执行计划评估（如 `EXPLAIN`）。

## 9. 是否字段类型规范

- **MUST**：语义为“是否/开关/启用状态”的 Java Bean 字段优先使用 `boolean`（或在需空值语义时使用 `Boolean`）。
- **MUST**：命名使用可读前缀：`enabled`、`deleted`、`valid`、`isActive` 等。
- **SHOULD**：数据库层与应用层取值映射保持一致（如 `0/1`、`Y/N`），并在注释中写明。

## 10. 主键生成策略

- **MUST**：新代码主键统一使用 MyBatis 雪花 ID 策略，不使用数据库序列生成主键。
- **MUST**：实体主键注解与全局 ID 生成策略保持一致，避免多策略混用导致冲突。
- **SHOULD**：分布式场景验证雪花 ID 的时钟回拨与唯一性风险处理策略。

## 11. 代码生成目录与包结构

- **MUST**：按“一个业务模块一个根包”生成代码，不跨模块混放。
- **MUST**：模块包内至少包含：
  - `controller`
  - `service`
  - `service/impl`
  - `mapper`
  - `entity`（或按模块现有规范）
- **MUST**：`mapper.xml` 统一放在 `src/main/resources/mapper`（可按子目录分组）。
- **SHOULD**：定制扩展代码放在 `custom` 子包（如 `custom.controller`、`custom.service`），与基础生成代码分离。

## 12. 建议新增的通用质量门禁

- **SHOULD**：新增接口必须补充参数校验与异常处理，不直接将底层异常栈返回前端。
- **SHOULD**：新增/修改 SQL 必须考虑索引策略和分页稳定性（明确 `ORDER BY`）。
- **SHOULD**：重要写操作增加单元测试或集成测试覆盖（最少覆盖成功/失败两条路径）。
- **SHOULD**：提交前检查编译、静态检查、日志脱敏与接口文档完整性。

---

## 快速检查清单（提交前）

- [ ] Controller 返回值是否全部为 `ResultRespone<T>`（带泛型）
- [ ] 接口是否全部有 Swagger 注解
- [ ] POST 是否全部使用 `@RequestBody`
- [ ] 写操作是否添加 `@ToFlyAppLog`
- [ ] 外部接口调用日志是否完整且已脱敏
- [ ] 简单查询是否优先 Wrappers，复杂查询是否在 XML
- [ ] 字段名是否避开数据库关键字
- [ ] SQL 是否避免低效 OR 并评估大数据量性能
- [ ] “是否”字段 Java 类型是否为 `boolean/Boolean`
- [ ] 主键是否使用雪花 ID，未使用序列
- [ ] 包结构与 mapper.xml 位置是否符合模块规范