backend-claude-code 1.0.0

package/skills/springboot-patterns/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: springboot-patterns
+description: Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.
+origin: ECC
+---
+
+# Spring Boot Development Patterns
+
+Spring Boot 아키텍처 및 API 패턴 — 확장 가능한 프로덕션 등급 서비스.
+
+## When to Activate
+
+- Spring MVC 또는 WebFlux로 REST API 구축
+- controller → service → repository 레이어 구조화
+- Spring Data JPA, 캐싱, 비동기 처리 설정
+- 검증, 예외 처리, 페이지네이션 추가
+- dev/staging/production 프로파일 설정
+- Spring Events 또는 Kafka를 사용한 이벤트 기반 패턴 구현
+
+## REST API Structure
+
+```java
+@RestController
+@RequestMapping("/api/orders")
+@Validated
+class OrderController {
+  private final OrderService orderService;
+
+  OrderController(OrderService orderService) {
+    this.orderService = orderService;
+  }
+
+  @GetMapping
+  ResponseEntity<Page<OrderResponse>> list(
+      @RequestParam(defaultValue = "0") int page,
+      @RequestParam(defaultValue = "20") int size) {
+    return ResponseEntity.ok(
+        orderService.list(PageRequest.of(page, size)));
+  }
+
+  @PostMapping
+  ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest request) {
+    return ResponseEntity.status(HttpStatus.CREATED)
+        .body(orderService.create(request));
+  }
+
+  @GetMapping("/{id}")
+  ResponseEntity<OrderResponse> findById(@PathVariable Long id) {
+    return ResponseEntity.ok(orderService.findById(id));
+  }
+
+  @DeleteMapping("/{id}")
+  ResponseEntity<Void> delete(@PathVariable Long id) {
+    orderService.delete(id);
+    return ResponseEntity.noContent().build();
+  }
+}
+```
+
+## Repository Pattern (Spring Data JPA)
+
+```java
+public interface OrderRepository extends JpaRepository<OrderEntity, Long> {
+  @Query("select o from OrderEntity o where o.status = :status order by o.createdAt desc")
+  Page<OrderEntity> findByStatus(@Param("status") OrderStatus status, Pageable pageable);
+
+  Optional<OrderEntity> findByOrderNumber(String orderNumber);
+}
+```
+
+## Service Layer with Transactions
+
+```java
+@Service
+public class OrderService {
+  private final OrderRepository repo;
+
+  public OrderService(OrderRepository repo) {
+    this.repo = repo;
+  }
+
+  @Transactional
+  public OrderResponse create(CreateOrderRequest request) {
+    OrderEntity entity = OrderEntity.from(request);
+    OrderEntity saved = repo.save(entity);
+    return OrderResponse.from(saved);
+  }
+
+  @Transactional(readOnly = true)
+  public OrderResponse findById(Long id) {
+    return repo.findById(id)
+        .map(OrderResponse::from)
+        .orElseThrow(() -> new OrderNotFoundException(id));
+  }
+
+  @Transactional(readOnly = true)
+  public Page<OrderResponse> list(Pageable pageable) {
+    return repo.findAll(pageable).map(OrderResponse::from);
+  }
+
+  @Transactional
+  public void delete(Long id) {
+    if (!repo.existsById(id)) {
+      throw new OrderNotFoundException(id);
+    }
+    repo.deleteById(id);
+  }
+}
+```
+
+## DTOs and Validation
+
+```java
+public record CreateOrderRequest(
+    @NotBlank @Size(max = 100) String customerName,
+    @NotNull @Positive BigDecimal amount,
+    @NotNull @FutureOrPresent LocalDate deliveryDate) {}
+
+public record OrderResponse(Long id, String customerName, BigDecimal amount, OrderStatus status) {
+  static OrderResponse from(OrderEntity entity) {
+    return new OrderResponse(
+        entity.getId(), entity.getCustomerName(),
+        entity.getAmount(), entity.getStatus());
+  }
+}
+```
+
+## Exception Handling
+
+```java
+@RestControllerAdvice
+class GlobalExceptionHandler {
+  private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+
+  @ExceptionHandler(EntityNotFoundException.class)
+  ResponseEntity<ApiResponse<Void>> handleNotFound(EntityNotFoundException ex) {
+    return ResponseEntity.status(HttpStatus.NOT_FOUND)
+        .body(ApiResponse.error(ex.getMessage()));
+  }
+
+  @ExceptionHandler(MethodArgumentNotValidException.class)
+  ResponseEntity<ApiResponse<Void>> handleValidation(MethodArgumentNotValidException ex) {
+    String message = ex.getBindingResult().getFieldErrors().stream()
+        .map(e -> e.getField() + ": " + e.getDefaultMessage())
+        .collect(Collectors.joining(", "));
+    return ResponseEntity.badRequest().body(ApiResponse.error(message));
+  }
+
+  @ExceptionHandler(Exception.class)
+  ResponseEntity<ApiResponse<Void>> handleGeneric(Exception ex) {
+    log.error("Unexpected error", ex);
+    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .body(ApiResponse.error("Internal server error"));
+  }
+}
+```
+
+## Caching
+
+`@EnableCaching` 설정 클래스에 추가 필요.
+
+```java
+@Service
+public class OrderCacheService {
+  private final OrderRepository repo;
+
+  public OrderCacheService(OrderRepository repo) { this.repo = repo; }
+
+  @Cacheable(value = "order", key = "#id")
+  public OrderResponse getById(Long id) {
+    return repo.findById(id)
+        .map(OrderResponse::from)
+        .orElseThrow(() -> new OrderNotFoundException(id));
+  }
+
+  @CacheEvict(value = "order", key = "#id")
+  public void evict(Long id) {}
+}
+```
+
+## Async Processing
+
+`@EnableAsync` 설정 클래스에 추가 필요.
+
+```java
+@Service
+public class NotificationService {
+  @Async
+  public CompletableFuture<Void> sendAsync(Notification notification) {
+    // 이메일/SMS 발송
+    return CompletableFuture.completedFuture(null);
+  }
+}
+```
+
+## Logging (SLF4J)
+
+```java
+@Service
+public class OrderService {
+  private static final Logger log = LoggerFactory.getLogger(OrderService.class);
+
+  public OrderResponse create(CreateOrderRequest request) {
+    log.info("create_order customerName={}", request.customerName());
+    try {
+      // 로직
+      log.info("order_created id={}", saved.getId());
+      return OrderResponse.from(saved);
+    } catch (Exception ex) {
+      log.error("create_order_failed customerName={}", request.customerName(), ex);
+      throw ex;
+    }
+  }
+}
+```
+
+## Request Logging Filter
+
+```java
+@Component
+public class RequestLoggingFilter extends OncePerRequestFilter {
+  private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain filterChain) throws ServletException, IOException {
+    long start = System.currentTimeMillis();
+    try {
+      filterChain.doFilter(request, response);
+    } finally {
+      long duration = System.currentTimeMillis() - start;
+      log.info("req method={} uri={} status={} durationMs={}",
+          request.getMethod(), request.getRequestURI(),
+          response.getStatus(), duration);
+    }
+  }
+}
+```
+
+## Pagination and Sorting
+
+```java
+PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
+Page<OrderEntity> results = orderRepository.findAll(page);
+```
+
+## Production Defaults
+
+- 생성자 주입 선호, 필드 주입 지양
+- Spring Boot 3+: `spring.mvc.problemdetails.enabled=true` (RFC 7807)
+- HikariCP 풀 크기 설정, 타임아웃 구성
+- 조회에 `@Transactional(readOnly = true)` 사용
+- `@NonNull`과 `Optional`로 null 안전성 강제
+
+**Remember**: 컨트롤러는 얇게, 서비스는 집중되게, 레포지토리는 단순하게, 오류는 중앙에서 처리.

package/skills/springboot-security/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: springboot-security
+description: Spring Security best practices for authn/authz, validation, CSRF, secrets, headers, rate limiting, and dependency security in Java Spring Boot services.
+origin: ECC
+---
+
+# Spring Boot Security Review
+
+인증, 입력 처리, 엔드포인트 생성, 시크릿 처리 시 사용.
+
+## When to Activate
+
+- 인증 추가 (JWT, OAuth2, 세션 기반)
+- 인가 구현 (@PreAuthorize, 역할 기반 접근)
+- 사용자 입력 검증 (Bean Validation, 커스텀 검증기)
+- CORS, CSRF, 보안 헤더 설정
+- 시크릿 관리 (Vault, 환경 변수)
+- 속도 제한 또는 무차별 대입 보호 추가
+- 의존성 CVE 스캔
+
+## Authentication
+
+- 상태 없는 JWT 또는 취소 목록이 있는 불투명 토큰 선호
+- 세션에는 `httpOnly`, `Secure`, `SameSite=Strict` 쿠키 사용
+- `OncePerRequestFilter` 또는 리소스 서버로 토큰 검증
+
+```java
+@Component
+public class JwtAuthFilter extends OncePerRequestFilter {
+  private final JwtService jwtService;
+
+  public JwtAuthFilter(JwtService jwtService) {
+    this.jwtService = jwtService;
+  }
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain chain) throws ServletException, IOException {
+    String header = request.getHeader(HttpHeaders.AUTHORIZATION);
+    if (header != null && header.startsWith("Bearer ")) {
+      String token = header.substring(7);
+      Authentication auth = jwtService.authenticate(token);
+      SecurityContextHolder.getContext().setAuthentication(auth);
+    }
+    chain.doFilter(request, response);
+  }
+}
+```
+
+## Authorization
+
+- 메서드 보안 활성화: `@EnableMethodSecurity`
+- `@PreAuthorize("hasRole('ADMIN')")` 또는 `@PreAuthorize("@authz.canEdit(#id)")` 사용
+- 기본 거부; 필요한 범위만 노출
+
+```java
+@RestController
+@RequestMapping("/api/admin")
+public class AdminController {
+
+  @PreAuthorize("hasRole('ADMIN')")
+  @GetMapping("/users")
+  public Page<UserDto> listUsers(Pageable pageable) {
+    return userService.findAll(pageable);
+  }
+
+  @PreAuthorize("@authz.isOwner(#id, authentication)")
+  @DeleteMapping("/users/{id}")
+  public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
+    userService.delete(id);
+    return ResponseEntity.noContent().build();
+  }
+}
+```
+
+## Input Validation
+
+```java
+// BAD: 검증 없음
+@PostMapping("/users")
+public User createUser(@RequestBody UserDto dto) {
+  return userService.create(dto);
+}
+
+// GOOD: 검증된 DTO
+public record CreateUserDto(
+    @NotBlank @Size(max = 100) String name,
+    @NotBlank @Email String email,
+    @NotNull @Min(0) @Max(150) Integer age
+) {}
+
+@PostMapping("/users")
+public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserDto dto) {
+  return ResponseEntity.status(HttpStatus.CREATED)
+      .body(userService.create(dto));
+}
+```
+
+## SQL Injection Prevention
+
+```java
+// BAD: 문자열 연결
+@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true)
+
+// GOOD: 파라미터화된 네이티브 쿼리
+@Query(value = "SELECT * FROM users WHERE name = :name", nativeQuery = true)
+List<User> findByName(@Param("name") String name);
+
+// GOOD: Spring Data 파생 쿼리 (자동 파라미터화)
+List<User> findByEmailAndActiveTrue(String email);
+```
+
+## Password Encoding
+
+```java
+@Bean
+public PasswordEncoder passwordEncoder() {
+  return new BCryptPasswordEncoder(12); // cost factor 12
+}
+
+public User register(CreateUserDto dto) {
+  String hashedPassword = passwordEncoder.encode(dto.password());
+  return userRepository.save(new User(dto.email(), hashedPassword));
+}
+```
+
+## CSRF Protection
+
+```java
+// 순수 JWT API — stateless 인증
+http
+  .csrf(csrf -> csrf.disable())
+  .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
+
+// 세션 기반 브라우저 앱 — CSRF 활성화 유지
+http.csrf(Customizer.withDefaults());
+```
+
+## Secrets Management
+
+```yaml
+# BAD: application.yml에 하드코딩
+spring:
+  datasource:
+    password: mySecretPassword123
+
+# GOOD: 환경 변수 플레이스홀더
+spring:
+  datasource:
+    password: ${DB_PASSWORD}
+
+# GOOD: Spring Cloud Vault
+spring:
+  cloud:
+    vault:
+      uri: https://vault.example.com
+      token: ${VAULT_TOKEN}
+```
+
+## Security Headers
+
+```java
+http
+  .headers(headers -> headers
+    .contentSecurityPolicy(csp -> csp
+      .policyDirectives("default-src 'self'; script-src 'self'"))
+    .frameOptions(HeadersConfigurer.FrameOptionsConfig::deny)
+    .xssProtection(Customizer.withDefaults())
+    .referrerPolicy(rp -> rp
+        .policy(ReferrerPolicyHeaderWriter.ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN)));
+```
+
+## CORS Configuration
+
+```java
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+  CorsConfiguration config = new CorsConfiguration();
+  config.setAllowedOrigins(List.of("https://app.example.com")); // 프로덕션에서 * 금지
+  config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
+  config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+  config.setAllowCredentials(true);
+  config.setMaxAge(3600L);
+
+  UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+  source.registerCorsConfiguration("/api/**", config);
+  return source;
+}
+
+http.cors(cors -> cors.configurationSource(corsConfigurationSource()));
+```
+
+## Rate Limiting (Bucket4j)
+
+```java
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+  private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
+
+  private Bucket createBucket() {
+    return Bucket.builder()
+        .addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
+        .build();
+  }
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain chain) throws ServletException, IOException {
+    String clientIp = request.getRemoteAddr(); // ForwardedHeaderFilter 설정 시 정확한 IP 반환
+    Bucket bucket = buckets.computeIfAbsent(clientIp, k -> createBucket());
+
+    if (bucket.tryConsume(1)) {
+      chain.doFilter(request, response);
+    } else {
+      response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
+      response.getWriter().write("{\"error\": \"Rate limit exceeded\"}");
+    }
+  }
+}
+```
+
+## Dependency Security
+
+- CI에서 OWASP Dependency Check / Snyk 실행
+- Spring Boot 및 Spring Security 지원 버전 유지
+- 알려진 CVE 발견 시 빌드 실패
+
+## Release Checklist
+
+- [ ] 인증 토큰 검증 및 만료 확인
+- [ ] 모든 민감한 경로에 인가 가드
+- [ ] 모든 입력 검증 및 새니타이즈
+- [ ] SQL 문자열 연결 없음
+- [ ] 앱 타입에 맞는 CSRF 설정
+- [ ] 시크릿 외부화, 커밋 없음
+- [ ] 보안 헤더 설정
+- [ ] API에 속도 제한
+- [ ] 의존성 스캔 완료
+- [ ] 로그에 민감 데이터 없음
+
+**Remember**: 기본 거부, 입력 검증, 최소 권한, 설정으로 보안 우선.