---
sync_policy: engine_only
---
package {{basePackage}}.controller;

import {{basePackage}}.dto.{{ModuleName}}DTO;
import {{basePackage}}.service.{{ModuleName}}Service;
import jakarta.validation.Valid;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * {{ModuleName}} 控制器 — 提供 {{moduleName}} 的增删改查 REST 接口。
 */
@RestController
@RequestMapping("/api/{{module_name}}s")
public class {{ModuleName}}Controller {

    private static final Logger log = LoggerFactory.getLogger({{ModuleName}}Controller.class);

    private final {{ModuleName}}Service {{moduleName}}Service;

    /**
     * 创建 {{moduleName}} 控制器实例。
     * @param {{moduleName}}Service {{moduleName}} 业务服务
     */
    public {{ModuleName}}Controller({{ModuleName}}Service {{moduleName}}Service) {
        this.{{moduleName}}Service = {{moduleName}}Service;
    }

    /**
     * 查询 {{moduleName}} 列表。
     * @return {{moduleName}} 列表
     */
    @GetMapping
    public List<{{ModuleName}}DTO> list() {
        log.info("查询 {} 列表", "{{ModuleName}}");
        return {{moduleName}}Service.list();
    }

    /**
     * 根据 ID 查询 {{moduleName}} 详情。
     * @param id 主键标识
     * @return {{moduleName}} 数据传输对象
     */
    @GetMapping("/{id}")
    public {{ModuleName}}DTO getById(@PathVariable Long id) {
        log.info("查询 {} 详情: id={}", "{{ModuleName}}", id);
        return {{moduleName}}Service.getById(id);
    }

    /**
     * 创建 {{moduleName}}。
     * @param dto 创建请求数据（经参数校验）
     * @return 创建后的 {{moduleName}} 数据
     */
    @PostMapping
    public {{ModuleName}}DTO create(@Valid @RequestBody {{ModuleName}}DTO dto) {
        log.info("创建{}请求开始 requestId={}", "{{ModuleName}}", dto.getId());
        return {{moduleName}}Service.create(dto);
    }

    /**
     * 更新 {{moduleName}}。
     * @param id  主键标识
     * @param dto 更新请求数据（经参数校验）
     * @return 更新后的 {{moduleName}} 数据
     */
    @PutMapping("/{id}")
    public {{ModuleName}}DTO update(@PathVariable Long id, @Valid @RequestBody {{ModuleName}}DTO dto) {
        log.info("更新 {}: id={}", "{{ModuleName}}", id);
        return {{moduleName}}Service.update(id, dto);
    }

    /**
     * 删除 {{moduleName}}。
     * @param id 主键标识
     */
    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) {
        log.info("删除 {}: id={}", "{{ModuleName}}", id);
        {{moduleName}}Service.delete(id);
    }
}