이력 관리

Q-Framework는 엔티티 선언만으로 변경 이력 자동 추적을 활성화할 수 있습니다. 별도의 Audit 로직 구현이 필요 없습니다.

이력 관리 활성화

@QfEntity(
    appKey = "app",
    name = @QfI18n(defaultMessage = "Product", texts = { @QfI18nText(locale = "ko", message = "상품") }),
    autoHistoryEnabled = true     // 이 선언 하나로 이력 관리 활성화
)
public class ProductEntity {

    @QfListAttribute(sortable = true)
    @QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfUpdateAttribute
    @QfDisplayLabel(text = "Product Name")
    private String name;

    @QfListAttribute(sortable = true)
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfDisplayLabel(text = "Price")
    private Integer price;
}

---

자동 생성되는 이력 API

GET /api/app/products/{id}/history

응답 예시

{
  "success": true,
  "data": [
    {
      "historyId": "h-001",
      "action": "UPDATE",
      "changedAt": "2026-03-15T10:30:00",
      "changedBy": "user-123",
      "changedByName": "홍길동",
      "changes": [
        {
          "field": "price",
          "fieldLabel": "가격",
          "before": "10000",
          "after": "12000"
        }
      ]
    },
    {
      "historyId": "h-000",
      "action": "CREATE",
      "changedAt": "2026-03-01T09:00:00",
      "changedBy": "user-100",
      "changedByName": "김철수"
    }
  ]
}

---

CRUD 자동 기록 어노테이션 (Modifier)

등록자, 수정자, 등록일시, 수정일시를 자동으로 기록합니다.

@QfEntity(
    appKey = "app",
    name = @QfI18n(defaultMessage = "Product", texts = { @QfI18nText(locale = "ko", message = "상품") }),
    autoHistoryEnabled = true
)
public class ProductEntity {

    // ... 비즈니스 필드 ...

    @QfCreatedBy              // 등록자 자동 기록
    private String createdBy;

    @QfCreatedAt              // 등록일시 자동 기록
    private LocalDateTime createdAt;

    @QfUpdatedBy              // 수정자 자동 기록
    private String updatedBy;

    @QfUpdatedAt              // 수정일시 자동 기록
    private LocalDateTime updatedAt;
}

@QfCreatedBy, @QfCreatedAt, @QfUpdatedBy, @QfUpdatedAt 선언 필드는 QfUserProvider에서 반환하는 현재 사용자 정보로 자동 채워집니다. 개발자가 직접 설정할 필요가 없습니다.

---

프론트엔드 이력 화면

<template>
  <!-- 이력 조회 UI 자동 렌더링 -->
  <QfEntityHistory
    client-app="app"
    entity="product"
    :entity-id="productId"
  />
</template>

---

이력 보존 정책

qf:
  history:
    retention-days: 365    # 이력 보존 기간 (일)
    max-records: 1000      # 엔티티당 최대 이력 건수

TIP

이력 데이터는 별도의 이력 테이블에 저장됩니다. 메인 테이블의 성능에 영향을 주지 않습니다.

---

다음 단계

• Excel 기능 — 대량 데이터 처리
• SPI 확장 — 이력 저장소 커스터마이징