spring data core annotations

@Repository  // Exception translation + component scan
public interface ProductRepository extends JpaRepository<Product, UUID> {}
 
// Spring Data auto-generates implementation cho interface
// @Repository thật ra KHÔNG cần vì Spring Data đã tự detect, nhưng convention tốt

@NoRepositoryBean  // Spring KHÔNG tạo bean cho interface này
public interface BaseRepository<T, ID> extends JpaRepository<T, ID> {
 
   @Query("SELECT e FROM #{#entityName} e WHERE e.deletedAt IS NULL")
   List<T> findAllActive();
 
   @Transactional
   @Modifying
   @Query("UPDATE #{#entityName} e SET e.deletedAt = CURRENT_TIMESTAMP WHERE e.id = :id")
   int softDelete(@Param("id") ID id);
}
 
// Concrete repositories extend base → Spring tạo implementation
@Repository
public interface ProductRepository extends BaseRepository<Product, UUID> {
   List<Product> findByStatus(ProductStatus status);
}
 
@Repository
public interface OrderRepository extends BaseRepository<Order, UUID> {
   List<Order> findByCustomerId(UUID customerId);
}

// Thay vì extend JpaRepository (có 20+ methods), chỉ expose methods cần thiết
@RepositoryDefinition(domainClass = Product.class, idClass = UUID.class)
public interface ReadOnlyProductRepository {
   Optional<Product> findById(UUID id);
   List<Product> findByStatus(ProductStatus status);
   long count();
   boolean existsById(UUID id);
   // Không có save, delete → read-only
}

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
@Getter @Setter
public abstract class BaseEntity {
 
   @Id
   @GeneratedValue(strategy = GenerationType.UUID)
   private UUID id;
 
   @CreatedDate  // Auto set khi INSERT
   @Column(name = "created_at", nullable = false, updatable = false)
   private LocalDateTime createdAt;
 
   @LastModifiedDate  // Auto set khi INSERT + UPDATE
   @Column(name = "updated_at")
   private LocalDateTime updatedAt;
 
   @CreatedBy  // Auto set username/ID khi INSERT
   @Column(name = "created_by", updatable = false)
   private String createdBy;
 
   @LastModifiedBy  // Auto set khi INSERT + UPDATE
   @Column(name = "updated_by")
   private String updatedBy;
}
 
// Enable auditing
@Configuration
@EnableJpaAuditing(auditorAwareRef = "auditorProvider")
public class AuditConfig {
 
   @Bean
   public AuditorAware<String> auditorProvider() {
       return () -> Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
           .filter(Authentication::isAuthenticated)
           .map(auth -> {
               if (auth.getPrincipal() instanceof Jwt jwt) {
                   return jwt.getClaimAsString("preferred_username");
               }
               return auth.getName();
           });
   }
}

@Document(collection = "process_definitions")
@Getter @Setter
public class ProcessDefinition {
 
   @Id
   private String id;
 
   private String name;
   private String version;
 
   @CreatedDate
   private Instant createdAt;
 
   @LastModifiedDate
   private Instant updatedAt;
 
   @CreatedBy
   private String createdBy;
 
   @LastModifiedBy
   private String updatedBy;
}
 
// Enable
@Configuration
@EnableMongoAuditing
public class MongoAuditConfig {
   @Bean
   public AuditorAware<String> auditorProvider() { ... }
}

// JPA (JPQL)
@Repository
public interface ProductJpaRepository extends JpaRepository<Product, UUID> {
   @Query("SELECT p FROM Product p WHERE p.status = :status AND p.deletedAt IS NULL")
   List<Product> findActiveByStatus(@Param("status") ProductStatus status);
}
 
// MongoDB
@Repository
public interface ProcessDefinitionRepository extends MongoRepository<ProcessDefinition, String> {
   @Query("{'workspaceId': ?0, 'status': ?1, 'deletedAt': null}")
   List<ProcessDefinition> findByWorkspaceAndStatus(String workspaceId, String status);
 
   @Query(value = "{'name': {$regex: ?0, $options: 'i'}}", sort = "{'createdAt': -1}")
   Page<ProcessDefinition> searchByName(String nameRegex, Pageable pageable);
 
   @Query(value = "{'tags': {$in: ?0}}", fields = "{'name': 1, 'version': 1, 'status': 1}")
   List<ProcessDefinition> findSummaryByTags(List<String> tags);
}

@Query("SELECT p FROM Product p WHERE p.name LIKE %:keyword% AND p.category.id = :catId")
Page<Product> search(@Param("keyword") String keyword, @Param("catId") UUID categoryId, Pageable pageable);

@Transactional
@Modifying(clearAutomatically = true)
@Query("UPDATE Product p SET p.status = :status WHERE p.id IN :ids")
int bulkUpdateStatus(@Param("ids") Collection<UUID> ids, @Param("status") ProductStatus status);

@Document(collection = "build_records")  // Collection name
@TypeAlias("BuildRecord")               // Short class name trong _class field
@CompoundIndex(def = "{'workspaceId': 1, 'status': 1}", name = "idx_workspace_status")
@Getter @Setter @Builder
@NoArgsConstructor @AllArgsConstructor
public class BuildRecord {
 
   @Id  // Mapped to _id
   private String id;
 
   @Field("workspace_id")  // Custom field name in MongoDB
   @Indexed                // Single field index
   private String workspaceId;
 
   @Field("app_name")
   private String appName;
 
   @Field("app_version")
   private String appVersion;
 
   @Indexed(unique = true)
   @Field("build_number")
   private String buildNumber;
 
   @Field("status")
   private BuildStatus status;
 
   @Field("artifacts")
   private List<Artifact> artifacts;
 
   @Field("metadata")
   private Map<String, Object> metadata;
 
   @DBRef  // Reference to another document (mặc định eager)
   private ProcessDefinition processDefinition;
 
   @DBRef(lazy = true)
   private User triggeredBy;
 
   // Embedded subdocument (không cần @DBRef)
   private BuildConfig config;
 
   @CreatedDate
   private Instant createdAt;
 
   @LastModifiedDate
   private Instant updatedAt;
 
   @Version  // Optimistic locking
   private Long version;
 
   @Transient  // NOT persisted to MongoDB
   private transient String computedField;
}
 
@Getter @Setter
public class Artifact {
   private String name;
   private String path;
   private long size;
   private String checksum;
}
 
@Getter @Setter
public class BuildConfig {
   private String baseImage;
   private Map<String, String> envVars;
   private List<String> buildArgs;
}

@Repository
public interface BuildRecordRepository extends MongoRepository<BuildRecord, String> {
 
   // Derived queries (same syntax as JPA)
   List<BuildRecord> findByWorkspaceIdAndStatus(String workspaceId, BuildStatus status);
   Optional<BuildRecord> findByBuildNumber(String buildNumber);
   Page<BuildRecord> findByWorkspaceIdOrderByCreatedAtDesc(String workspaceId, Pageable pageable);
   long countByWorkspaceIdAndStatus(String workspaceId, BuildStatus status);
   boolean existsByBuildNumber(String buildNumber);
 
   // @Query with MongoDB JSON syntax
   @Query("{'workspaceId': ?0, 'status': {$in: ?1}, 'createdAt': {$gte: ?2}}")
   List<BuildRecord> findRecentByStatuses(String workspaceId, List<BuildStatus> statuses, Instant since);
 
   // Projection — chỉ lấy fields cần thiết
   @Query(value = "{'workspaceId': ?0}", fields = "{'appName': 1, 'buildNumber': 1, 'status': 1}")
   List<BuildRecord> findSummaryByWorkspace(String workspaceId);
 
   // Delete
   void deleteByWorkspaceIdAndStatusAndCreatedAtBefore(
       String workspaceId, BuildStatus status, Instant before);
 
   // Aggregation
   @Aggregation(pipeline = {
       "{'$match': {'workspaceId': ?0}}",
       "{'$group': {'_id': '$status', 'count': {'$sum': 1}}}",
       "{'$sort': {'count': -1}}"
   })
   List<StatusCount> countByStatusGrouped(String workspaceId);
}
 
@Data
public class StatusCount {
   @Id  // _id của $group (giá trị status) map vào đây
   private String status;
   private long count;
}

@Service
@RequiredArgsConstructor
public class BuildRecordService {
 
   private final MongoTemplate mongoTemplate;
 
   // Complex query
   public List<BuildRecord> search(BuildSearchCriteria criteria) {
       Query query = new Query();
 
       if (criteria.getWorkspaceId() != null) {
           query.addCriteria(Criteria.where("workspaceId").is(criteria.getWorkspaceId()));
       }
       if (criteria.getKeyword() != null) {
           query.addCriteria(Criteria.where("appName")
               .regex(criteria.getKeyword(), "i"));
       }
       if (criteria.getStatuses() != null) {
           query.addCriteria(Criteria.where("status").in(criteria.getStatuses()));
       }
       if (criteria.getFromDate() != null) {
           query.addCriteria(Criteria.where("createdAt").gte(criteria.getFromDate()));
       }
 
       query.with(Sort.by(Sort.Direction.DESC, "createdAt"));
       query.with(PageRequest.of(criteria.getPage(), criteria.getSize()));
 
       return mongoTemplate.find(query, BuildRecord.class);
   }
 
   // Update specific fields
   public void updateStatus(String id, BuildStatus status) {
       Query query = Query.query(Criteria.where("id").is(id));
       Update update = new Update()
           .set("status", status)
           .set("updatedAt", Instant.now())
           .push("metadata.statusHistory", Map.of("status", status, "at", Instant.now()));
 
       mongoTemplate.updateFirst(query, update, BuildRecord.class);
   }
 
   // Upsert
   public void upsertDiscovery(String serviceId, ServiceInfo info) {
       Query query = Query.query(Criteria.where("serviceId").is(serviceId));
       Update update = new Update()
           .set("host", info.getHost())
           .set("port", info.getPort())
           .set("lastHeartbeat", Instant.now())
           .setOnInsert("registeredAt", Instant.now());
 
       mongoTemplate.upsert(query, update, "service_discovery");
   }
 
   // Aggregation
   public List<BuildStats> getBuildStats(String workspaceId, Instant from) {
       Aggregation agg = Aggregation.newAggregation(
           Aggregation.match(Criteria.where("workspaceId").is(workspaceId)
               .and("createdAt").gte(from)),
           Aggregation.group("status")
               .count().as("count")
               .avg("metadata.durationMs").as("avgDuration"),
           Aggregation.sort(Sort.Direction.DESC, "count")
       );
 
       return mongoTemplate.aggregate(agg, "build_records", BuildStats.class)
           .getMappedResults();
   }
}

@RedisHash(value = "sessions", timeToLive = 3600)  // TTL = 1 hour
@Getter @Setter @Builder
public class UserSession {
 
   @Id
   private String id;
 
   @Indexed  // Searchable by this field
   private String userId;
 
   @Indexed
   private String workspaceId;
 
   private String username;
   private Set<String> roles;
   private Map<String, String> metadata;
   private Instant createdAt;
   private Instant lastAccessedAt;
 
   @TimeToLive  // Dynamic TTL per instance
   private Long ttl;
}
 
@Repository
public interface UserSessionRepository extends CrudRepository<UserSession, String> {
   List<UserSession> findByUserId(String userId);
   List<UserSession> findByWorkspaceId(String workspaceId);
   void deleteByUserId(String userId);
}

@Configuration
@EnableCaching
public class CacheConfig {
 
   @Bean
   public RedisCacheManager cacheManager(RedisConnectionFactory factory) {
       RedisCacheConfiguration defaultConfig = RedisCacheConfiguration.defaultCacheConfig()
           .entryTtl(Duration.ofMinutes(30))
           .serializeKeysWith(RedisSerializationContext.SerializationPair
               .fromSerializer(new StringRedisSerializer()))
           .serializeValuesWith(RedisSerializationContext.SerializationPair
               .fromSerializer(new GenericJackson2JsonRedisSerializer()))
           .disableCachingNullValues();
 
       Map<String, RedisCacheConfiguration> cacheConfigs = Map.of(
           "products", defaultConfig.entryTtl(Duration.ofHours(1)),
           "users", defaultConfig.entryTtl(Duration.ofMinutes(15)),
           "configs", defaultConfig.entryTtl(Duration.ofHours(24))
       );
 
       return RedisCacheManager.builder(factory)
           .cacheDefaults(defaultConfig)
           .withInitialCacheConfigurations(cacheConfigs)
           .build();
   }
}
 
@Service
@RequiredArgsConstructor
public class ProductService {
 
   private final ProductRepository productRepository;
 
   @Cacheable(value = "products", key = "#id", unless = "#result == null")
   public ProductDTO getById(UUID id) {
       return productRepository.findById(id)
           .map(this::toDTO)
           .orElseThrow(() -> new EntityNotFoundException("Product not found: " + id));
   }
 
   @Cacheable(value = "productLists", key = "#status + ':' + #pageable.pageNumber + ':' + #pageable.pageSize")
   public Page<ProductDTO> findByStatus(ProductStatus status, Pageable pageable) {
       return productRepository.findByStatus(status, pageable).map(this::toDTO);
   }
 
   @CachePut(value = "products", key = "#result.id")
   public ProductDTO update(UUID id, UpdateProductRequest request) {
       Product product = productRepository.findById(id).orElseThrow();
       product.setName(request.getName());
       return toDTO(productRepository.save(product));
   }
 
   @CacheEvict(value = "products", key = "#id")
   public void delete(UUID id) {
       productRepository.deleteById(id);
   }
 
   @CacheEvict(value = "products", allEntries = true)
   public void clearCache() {
       // Xóa tất cả entries trong cache "products"
   }
 
   // Multiple cache operations
   @Caching(evict = {
       @CacheEvict(value = "products", key = "#id"),
       @CacheEvict(value = "productLists", allEntries = true)  // cache key không hỗ trợ wildcard
   })
   public void deleteAndInvalidateList(UUID id) {
       productRepository.deleteById(id);
   }
}

// Pageable — request object
Pageable pageable = PageRequest.of(0, 20);                          // page 0, size 20
Pageable pageable = PageRequest.of(0, 20, Sort.by("name"));         // + sort
Pageable pageable = PageRequest.of(0, 20, Sort.by(Direction.DESC, "createdAt"));
 
// Sort
Sort sort = Sort.by("name");                                         // ASC
Sort sort = Sort.by(Direction.DESC, "createdAt");                    // DESC
Sort sort = Sort.by("status").ascending().and(Sort.by("name").descending());  // Multi
 
// Page — kết quả phân trang (biết total)
Page<Product> page = repository.findByStatus(status, pageable);
page.getContent();        // List<Product> — data
page.getTotalElements();  // long — total records
page.getTotalPages();     // int — total pages
page.getNumber();         // int — current page (0-based)
page.getSize();           // int — page size
page.hasNext();           // boolean
page.hasPrevious();       // boolean
page.isFirst();           // boolean
page.isLast();            // boolean
 
// Slice — kết quả phân trang (KHÔNG biết total — faster)
Slice<Product> slice = repository.findByCategory(cat, pageable);
slice.getContent();       // List<Product>
slice.hasNext();          // boolean (fetches N+1 records to check)
// KHÔNG có getTotalElements(), getTotalPages()
 
// Page transformation
Page<ProductDTO> dtoPage = page.map(product -> toDTO(product));

// AbstractAggregateRoot — tích hợp Domain Events
@Entity
public class Order extends AbstractAggregateRoot<Order> {
 
   @Id
   private UUID id;
   private OrderStatus status;
 
   public Order confirm() {
       this.status = OrderStatus.CONFIRMED;
       registerEvent(new OrderConfirmedEvent(this.id));  // Queue event
       return this;
   }
 
   public Order cancel(String reason) {
       this.status = OrderStatus.CANCELLED;
       registerEvent(new OrderCancelledEvent(this.id, reason));
       return this;
   }
}
 
// Events published khi gọi repository.save()
@Service
@RequiredArgsConstructor
public class OrderService {
   private final OrderRepository repo;
 
   @Transactional
   public OrderDTO confirm(UUID id) {
       Order order = repo.findById(id).orElseThrow();
       order.confirm();
       repo.save(order);  // → publish OrderConfirmedEvent ngay tại đây (trong TX)
       return toDTO(order);
   }
}
 
// Listener
@Component
public class OrderEventHandler {
   @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
   public void onOrderConfirmed(OrderConfirmedEvent event) {
       notificationService.notifyCustomer(event.getOrderId());
   }
}

@Entity
public class Product extends BaseEntity {
 
   private String name;
   private BigDecimal price;
 
   @Transient  // KHÔNG lưu vào database
   private BigDecimal discountedPrice;
 
   @ReadOnlyProperty  // Chỉ đọc từ DB, không ghi (computed column, DB trigger)
   @Column(name = "search_vector", insertable = false, updatable = false)
   private String searchVector;
 
   @PostLoad
   public void computeFields() {
       this.discountedPrice = this.price.multiply(BigDecimal.valueOf(0.9));
   }
}

// Tự động tạo REST endpoints từ repository
@RepositoryRestResource(path = "products", collectionResourceRel = "products")
public interface ProductRepository extends JpaRepository<Product, UUID> {
 
   @RestResource(path = "by-status", rel = "by-status")
   List<Product> findByStatus(@Param("status") ProductStatus status);
 
   @RestResource(exported = false)  // KHÔNG expose endpoint này
   void deleteById(UUID id);
}
 
// Auto-generated endpoints:
// GET    /products              → findAll (paginated)
// GET    /products/{id}         → findById
// POST   /products              → save
// PUT    /products/{id}         → save (update)
// PATCH  /products/{id}         → partial update
// DELETE /products/{id}         → delete
// GET    /products/search/by-status?status=ACTIVE → custom finder
 
// Configuration
@Configuration
public class RestConfig implements RepositoryRestConfigurer {
   @Override
   public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config,
           CorsRegistry cors) {
       config.exposeIdsFor(Product.class, Order.class);  // Include ID in response
       config.setBasePath("/api");  // Base path
   }
}