---
name: crud-by-controller
description: 基于本项目既有 Controller 风格生成或补全 CRUD（Controller/Service/Mapper/Mapper.xml），并约束分层职责与 SQL 放置规则。用户提到“参考现有控制器生成接口”“补全增删改查”“统一接口风格”“规范 MyBatis XML”时使用。
---

# CRUD By Controller (PMS)

## 适用场景

当用户要求按现有模块风格新增或补全 CRUD 时使用。优先复用同模块现有风格，而不是强行统一成新风格。

项目里常见两类接口返回风格：
- `ResponseResult<T>`（常见于 `pms-base`）
- 直接返回实体/布尔值或分页对象（常见于 `pms-service` 部分控制器）

优先原则：
1. 同一模块内与既有 Controller 保持一致。
2. 若用户要求统一返回结构，优先采用该模块已使用最多的返回类型。

## 公共 Skill 引用

- POM 工作流：`language/java/pom-factory-skill.md`；**Maven 治理条文**：[`rules/java-pom-governance.mdc`](../../../../../rules/java/java-pom-governance.mdc)。
- **Java CRUD 通用规范**：[`rules/java-crud-common.mdc`](../../../../../rules/java/java-crud-common.mdc)。
- 当任务涉及 `pom.xml`、多模块依赖版本治理、`dependencyManagement/pluginManagement`、`systemPath` 清理时，必须同时应用 `pom-factory-skill` 与 **`java-pom-governance`**。
- 当 CRUD 生成与 POM 治理同时出现时，Controller/Service/Mapper 代码规范遵循本文件，Maven 构建与依赖规范遵循 `pom-factory-skill` + **`java-pom-governance`**。
- 当本文件与 **java-crud-common** 有冲突时：本文件的项目差异规则优先。

## PMS 专项约束

### 分层与 SQL（与通用规则一致时不再展开）

- 分层、SQL 仅 `Mapper.xml`、禁止注解 SQL、禁止 Controller/Service 拼 SQL：见 **`rules/java-crud-common.mdc`**。

### 接口与参数

- 延续同模块路由命名与 HTTP 动词习惯（如 `/save`、`/updateById`、`/deleteById`、`/page` 或 RESTful 风格）。
- 查询参数用 `@RequestParam` 或查询对象时，与同模块既有接口一致。
- 写接口使用 `@RequestBody`（除非同模块已有明确例外）。
- Swagger 注解与现有风格保持一致（`@Api`、`@ApiOperation` 等）。

### 安全与校验

- 若目标模块已有 `@PreAuthorize` 约束，新增接口必须补齐同级权限策略。
- DTO 校验沿用现有 `@Validated` + 分组（如 `AddGroup`、`UpdateGroup`、`DeleteGroup`）。
- 不向前端暴露 SQL 或堆栈细节，异常遵循全局异常处理链路。

## 默认执行步骤

1. 识别目标模块与参考 Controller
- 在同包或同业务域找到风格最接近的 Controller。
- 确认返回体、路由风格、权限注解、参数绑定方式。

2. 生成/补全 Controller
- 增加分页、详情、新增、修改、删除（含批量删除按需）接口。
- 保持命名与路由风格一致，不跨模块混用风格。

3. 生成/补全 Service
- `Service` 接口声明业务方法。
- `ServiceImpl` 承担业务逻辑与事务边界。

4. 生成/补全 Mapper + Mapper.xml
- `Mapper.java` 仅方法签名。
- 自定义查询在 `Mapper.xml` 编写，`namespace` 对齐接口全限定名。
- 禁止 `select *`，显式列字段。

5. 自检
- 按 **`rules/java-crud-common.mdc`** 自检。
- 检查是否出现注解 SQL。
- 检查 Controller 是否写入业务逻辑。
- 检查新增接口是否与模块安全注解和返回风格一致。

## 输出格式

```markdown
## CRUD 结果
- 模块：`...`
- 实体/对象：`...`
- 新增文件：`...`
- 修改文件：`...`

## 接口清单
- `...`

## 规范检查
- [x] Controller 无业务编排
- [x] SQL 位于 Mapper.xml
- [x] Mapper 无注解 SQL
- [x] 返回风格与模块一致
- [x] 权限/校验注解已对齐
```

## 参考

- 详细示例见 [examples-pms.md](examples-pms.md)