@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/java-architect/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: java-architect
+description: Use when building, configuring, or debugging enterprise Java applications with Spring Boot 3.x, microservices, or reactive programming. Invoke to implement WebFlux endpoints, optimize JPA queries and database performance, configure Spring Security with OAuth2/JWT, or resolve authentication issues and async processing challenges in cloud-native Spring applications.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: language
+  triggers: Spring Boot, Java, microservices, Spring Cloud, JPA, Hibernate, WebFlux, reactive, Java Enterprise
+  role: architect
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, api-designer, devops-engineer, database-optimizer
+---
+
+# Java Architect
+
+Enterprise Java specialist focused on Spring Boot 3.x, microservices architecture, and cloud-native development using Java 21 LTS.
+
+## Core Workflow
+
+1. **Architecture analysis** - Review project structure, dependencies, Spring config
+2. **Domain design** - Create models following DDD and Clean Architecture; verify domain boundaries before proceeding. If boundaries are unclear, resolve ambiguities before moving to implementation.
+3. **Implementation** - Build services with Spring Boot best practices
+4. **Data layer** - Optimize JPA queries, implement repositories; run `./mvnw verify -pl <module>` to confirm query correctness. If integration tests fail: review Hibernate SQL logs, fix queries or mappings, re-run before proceeding.
+5. **Security & config** - Apply Spring Security, externalize configuration, add observability; run `./mvnw verify` after security changes to confirm filter chain and JWT wiring. If tests fail: check `SecurityFilterChain` bean order and token validation config, then re-run.
+6. **Quality assurance** - Run `./mvnw verify` (Maven) or `./gradlew check` (Gradle) to confirm all tests pass and coverage reaches 85%+ before closing. If coverage is below threshold: identify untested branches via JaCoCo report (`target/site/jacoco/index.html`), add missing test cases, re-run.
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Spring Boot | `references/spring-boot-setup.md` | Project setup, configuration, starters |
+| Reactive | `references/reactive-webflux.md` | WebFlux, Project Reactor, R2DBC |
+| Data Access | `references/jpa-optimization.md` | JPA, Hibernate, query tuning |
+| Security | `references/spring-security.md` | OAuth2, JWT, method security |
+| Testing | `references/testing-patterns.md` | JUnit 5, TestContainers, Mockito |
+
+## Constraints
+
+### MUST DO
+- Use Java 21 LTS features (records, sealed classes, pattern matching)
+- Apply database migrations (Flyway/Liquibase)
+- Document APIs with OpenAPI/Swagger
+- Use proper exception handling hierarchy
+- Externalize all configuration (never hardcode values)
+
+### MUST NOT DO
+- Use deprecated Spring APIs
+- Skip input validation
+- Store sensitive data unencrypted
+- Use blocking code in reactive applications
+- Ignore transaction boundaries
+
+## Output Templates
+
+When implementing Java features, provide:
+1. Domain models (entities, DTOs, records)
+2. Service layer (business logic, transactions)
+3. Repository interfaces (Spring Data)
+4. Controller/REST endpoints
+5. Test classes with comprehensive coverage
+6. Brief explanation of architectural decisions
+
+## Code Examples
+
+### Minimal WebFlux REST Endpoint
+
+```java
+@RestController
+@RequestMapping("/api/v1/orders")
+@RequiredArgsConstructor
+public class OrderController {
+
+    private final OrderService orderService;
+
+    @GetMapping("/{id}")
+    public Mono<ResponseEntity<OrderDto>> getOrder(@PathVariable UUID id) {
+        return orderService.findById(id)
+                .map(ResponseEntity::ok)
+                .defaultIfEmpty(ResponseEntity.notFound().build());
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public Mono<OrderDto> createOrder(@Valid @RequestBody CreateOrderRequest request) {
+        return orderService.create(request);
+    }
+}
+```
+
+### JPA Repository with Optimized Query
+
+```java
+public interface OrderRepository extends JpaRepository<Order, UUID> {
+
+    // Avoid N+1: fetch association in one query
+    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.customerId = :customerId")
+    List<Order> findByCustomerIdWithItems(@Param("customerId") UUID customerId);
+
+    // Projection to limit fetched columns
+    @Query("SELECT new com.example.dto.OrderSummary(o.id, o.status, o.total) FROM Order o WHERE o.status = :status")
+    Page<OrderSummary> findSummariesByStatus(@Param("status") OrderStatus status, Pageable pageable);
+}
+```
+
+### Spring Security OAuth2 JWT Configuration
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+                .csrf(AbstractHttpConfigurer::disable)
+                .sessionManagement(s -> s.sessionCreationPolicy(STATELESS))
+                .authorizeHttpRequests(auth -> auth
+                        .requestMatchers("/actuator/health").permitAll()
+                        .anyRequest().authenticated())
+                .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+                .build();
+    }
+}
+```
+
+## Knowledge Reference
+
+Spring Boot 3.x, Java 21, Spring WebFlux, Project Reactor, Spring Data JPA, Spring Security, OAuth2/JWT, Hibernate, R2DBC, Spring Cloud, Resilience4j, Micrometer, JUnit 5, TestContainers, Mockito, Maven/Gradle

package/skills/java-architect/references/jpa-optimization.md

@@ -0,0 +1,393 @@
+# JPA Optimization
+
+## Optimized Entity Design
+
+```java
+package com.example.domain.model;
+
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.BatchSize;
+import org.hibernate.annotations.Cache;
+import org.hibernate.annotations.CacheConcurrencyStrategy;
+import org.springframework.data.annotation.CreatedDate;
+import org.springframework.data.annotation.LastModifiedDate;
+import org.springframework.data.jpa.domain.support.AuditingEntityListener;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+
+@Entity
+@Table(
+    name = "users",
+    indexes = {
+        @Index(name = "idx_email", columnList = "email"),
+        @Index(name = "idx_created_at", columnList = "created_at")
+    }
+)
+@EntityListeners(AuditingEntityListener.class)
+@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class User {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false, unique = true, length = 100)
+    private String email;
+
+    @Column(nullable = false, length = 50)
+    private String username;
+
+    @Column(nullable = false)
+    private Boolean active = true;
+
+    @OneToMany(
+        mappedBy = "user",
+        cascade = CascadeType.ALL,
+        orphanRemoval = true,
+        fetch = FetchType.LAZY
+    )
+    @BatchSize(size = 25)
+    @Builder.Default
+    private List<Order> orders = new ArrayList<>();
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "department_id")
+    private Department department;
+
+    @CreatedDate
+    @Column(nullable = false, updatable = false)
+    private Instant createdAt;
+
+    @LastModifiedDate
+    private Instant updatedAt;
+
+    @Version
+    private Long version;
+
+    // Helper methods
+    public void addOrder(Order order) {
+        orders.add(order);
+        order.setUser(this);
+    }
+
+    public void removeOrder(Order order) {
+        orders.remove(order);
+        order.setUser(null);
+    }
+}
+```
+
+## Repository with Custom Queries
+
+```java
+package com.example.domain.repository;
+
+import com.example.domain.model.User;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.jpa.repository.EntityGraph;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.repository.query.Param;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+
+public interface UserRepository extends JpaRepository<User, Long> {
+
+    // N+1 prevention with EntityGraph
+    @EntityGraph(attributePaths = {"orders", "department"})
+    @Query("SELECT u FROM User u WHERE u.id = :id")
+    Optional<User> findByIdWithOrders(@Param("id") Long id);
+
+    // Projection for read-only queries
+    @Query("""
+        SELECT new com.example.application.dto.UserSummary(
+            u.id, u.email, u.username, COUNT(o)
+        )
+        FROM User u
+        LEFT JOIN u.orders o
+        WHERE u.active = true
+        GROUP BY u.id, u.email, u.username
+        """)
+    List<UserSummary> findActiveUsersSummary();
+
+    // Fetch join to avoid N+1
+    @Query("""
+        SELECT DISTINCT u FROM User u
+        LEFT JOIN FETCH u.orders
+        WHERE u.department.id = :deptId
+        """)
+    List<User> findByDepartmentWithOrders(@Param("deptId") Long deptId);
+
+    // Pagination with count query optimization
+    @Query(
+        value = "SELECT u FROM User u WHERE u.active = true",
+        countQuery = "SELECT COUNT(u) FROM User u WHERE u.active = true"
+    )
+    Page<User> findActiveUsers(Pageable pageable);
+
+    // Batch update
+    @Modifying
+    @Query("UPDATE User u SET u.active = false WHERE u.createdAt < :date")
+    int deactivateOldUsers(@Param("date") Instant date);
+
+    // Native query for complex operations
+    @Query(
+        value = """
+            SELECT u.* FROM users u
+            WHERE u.id IN (
+                SELECT DISTINCT o.user_id
+                FROM orders o
+                WHERE o.total > :amount
+            )
+            """,
+        nativeQuery = true
+    )
+    List<User> findUsersWithLargeOrders(@Param("amount") Double amount);
+}
+```
+
+## DTO Projections
+
+```java
+package com.example.application.dto;
+
+// Interface-based projection
+public interface UserProjection {
+    Long getId();
+    String getEmail();
+    String getUsername();
+    DepartmentProjection getDepartment();
+
+    interface DepartmentProjection {
+        String getName();
+    }
+}
+
+// Class-based projection (constructor expression)
+public record UserSummary(
+    Long id,
+    String email,
+    String username,
+    Long orderCount
+) {}
+
+// Dynamic projection
+public interface UserRepository extends JpaRepository<User, Long> {
+    <T> List<T> findByActive(boolean active, Class<T> type);
+}
+
+// Usage
+List<UserProjection> users = userRepository.findByActive(true, UserProjection.class);
+```
+
+## Query Optimization Patterns
+
+```java
+package com.example.application.service;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class UserQueryService {
+
+    private final UserRepository userRepository;
+    private final EntityManager entityManager;
+
+    // Batch fetching
+    public List<User> findUsersWithOrders(List<Long> userIds) {
+        return entityManager.createQuery("""
+            SELECT DISTINCT u FROM User u
+            LEFT JOIN FETCH u.orders
+            WHERE u.id IN :ids
+            """, User.class)
+            .setParameter("ids", userIds)
+            .setHint("hibernate.default_batch_fetch_size", 25)
+            .getResultList();
+    }
+
+    // Pagination with total count
+    public Page<UserSummary> findUsersPaged(Pageable pageable) {
+        List<UserSummary> users = entityManager.createQuery("""
+            SELECT new com.example.application.dto.UserSummary(
+                u.id, u.email, u.username, COUNT(o)
+            )
+            FROM User u
+            LEFT JOIN u.orders o
+            GROUP BY u.id, u.email, u.username
+            """, UserSummary.class)
+            .setFirstResult((int) pageable.getOffset())
+            .setMaxResults(pageable.getPageSize())
+            .getResultList();
+
+        Long total = entityManager.createQuery(
+            "SELECT COUNT(DISTINCT u) FROM User u",
+            Long.class
+        ).getSingleResult();
+
+        return new PageImpl<>(users, pageable, total);
+    }
+
+    // Stream large datasets
+    @Transactional(readOnly = true)
+    public void processLargeDataset() {
+        try (Stream<User> stream = userRepository.streamByActiveTrue()) {
+            stream
+                .filter(user -> user.getOrders().size() > 10)
+                .forEach(this::processUser);
+        }
+    }
+
+    // Criteria API for dynamic queries
+    public List<User> findUsersByCriteria(UserSearchCriteria criteria) {
+        CriteriaBuilder cb = entityManager.getCriteriaBuilder();
+        CriteriaQuery<User> query = cb.createQuery(User.class);
+        Root<User> user = query.from(User.class);
+
+        List<Predicate> predicates = new ArrayList<>();
+
+        if (criteria.email() != null) {
+            predicates.add(cb.like(user.get("email"), "%" + criteria.email() + "%"));
+        }
+        if (criteria.active() != null) {
+            predicates.add(cb.equal(user.get("active"), criteria.active()));
+        }
+        if (criteria.createdAfter() != null) {
+            predicates.add(cb.greaterThan(user.get("createdAt"), criteria.createdAfter()));
+        }
+
+        query.where(predicates.toArray(new Predicate[0]));
+        return entityManager.createQuery(query).getResultList();
+    }
+}
+```
+
+## Batch Operations
+
+```java
+@Service
+@RequiredArgsConstructor
+public class UserBatchService {
+
+    private final UserRepository userRepository;
+    private final EntityManager entityManager;
+
+    @Transactional
+    public void batchInsert(List<User> users) {
+        int batchSize = 50;
+        for (int i = 0; i < users.size(); i++) {
+            entityManager.persist(users.get(i));
+            if (i % batchSize == 0 && i > 0) {
+                entityManager.flush();
+                entityManager.clear();
+            }
+        }
+        entityManager.flush();
+        entityManager.clear();
+    }
+
+    @Transactional
+    public void batchUpdate(List<User> users) {
+        int batchSize = 50;
+        for (int i = 0; i < users.size(); i++) {
+            entityManager.merge(users.get(i));
+            if (i % batchSize == 0 && i > 0) {
+                entityManager.flush();
+                entityManager.clear();
+            }
+        }
+        entityManager.flush();
+        entityManager.clear();
+    }
+}
+```
+
+## Second-Level Cache Configuration
+
+```yaml
+spring:
+  jpa:
+    properties:
+      hibernate:
+        cache:
+          use_second_level_cache: true
+          use_query_cache: true
+          region:
+            factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
+        javax:
+          cache:
+            provider: org.ehcache.jsr107.EhcacheCachingProvider
+            uri: classpath:ehcache.xml
+```
+
+```xml
+<!-- ehcache.xml -->
+<config xmlns="http://www.ehcache.org/v3">
+    <cache alias="users">
+        <key-type>java.lang.Long</key-type>
+        <value-type>com.example.domain.model.User</value-type>
+        <expiry>
+            <ttl unit="minutes">10</ttl>
+        </expiry>
+        <resources>
+            <heap unit="entries">1000</heap>
+        </resources>
+    </cache>
+</config>
+```
+
+## Performance Monitoring
+
+```java
+@Component
+@Aspect
+@Slf4j
+public class QueryPerformanceAspect {
+
+    @Around("@annotation(org.springframework.data.jpa.repository.Query)")
+    public Object logQueryPerformance(ProceedingJoinPoint joinPoint) throws Throwable {
+        long start = System.currentTimeMillis();
+        try {
+            return joinPoint.proceed();
+        } finally {
+            long duration = System.currentTimeMillis() - start;
+            if (duration > 1000) {
+                log.warn("Slow query detected: {} took {}ms",
+                    joinPoint.getSignature(), duration);
+            }
+        }
+    }
+}
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `@EntityGraph` | Prevent N+1 queries |
+| `JOIN FETCH` | Eager fetch associations |
+| DTO Projection | Read-only queries |
+| `@BatchSize` | Batch fetch collections |
+| `@Query` with pagination | Large datasets |
+| `@Modifying` | Bulk updates/deletes |
+| Criteria API | Dynamic queries |
+| Second-level cache | Frequently accessed data |
+| Stream API | Process large results |
+| `readOnly = true` | Optimization hint |