前后端命名与接口规范

// [✓] 统一格式：<模块>用小写英文括号，后接中文描述
@Tag(name = "(system)用户管理")
@Tag(name = "(iot)驱动实例")
@Tag(name = "(energy)能耗报表")

// [✗] 不规范（缺模块前缀 / 中英混排 / 大小写不一）
@Tag(name = "收支对账管理")           // 缺 (bill) 前缀
@Tag(name = "B 端支付订单查询")        // 中英混排
@Tag(name = "(bill) 用户资金密码管理") // 前缀后多空格

@Operation(summary = "新增驱动实例", description = "可选的详细说明")
@PostMapping
public Result<Void> save(@Validated @RequestBody SaveDriverDTO dto) { ... }

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 统一鉴权：让文档支持带 Authorization 请求调试
                .components(new Components().addSecuritySchemes("Authorization",
                        new SecurityScheme()
                                .type(SecurityScheme.Type.APIKEY)
                                .in(SecurityScheme.In.HEADER)
                                .name("Authorization")))
                .addSecurityItem(new SecurityRequirement().addList("Authorization"))
                .info(new Info()
                        .title("源创云平台")
                        .version("2.0.0")
                        .description("源创云平台在线 API"));
    }
}