Excel 기능

Q-Framework는 엔티티 선언만으로 Excel 다운로드/업로드 기능을 자동으로 제공합니다. 별도의 Excel 처리 코드가 필요하지 않습니다.

자동 생성되는 Excel API

@QfEntity를 선언한 엔티티에는 다음 API가 자동으로 생성됩니다.

GET  /api/app/products/excel/download         # 전체 데이터 Excel 다운로드
GET  /api/app/products/excel/sample           # 업로드용 샘플 파일 다운로드
POST /api/app/products/excel/upload           # Excel 업로드 (대량 등록)
GET  /api/app/products/excel/upload/{jobId}   # 업로드 작업 상태 확인
DEL  /api/app/products/excel/upload/{jobId}   # 업로드 작업 취소

---

Excel 다운로드

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

    @QfListAttribute(sortable = true)   // 목록에 표시되는 필드가 Excel 컬럼이 됩니다
    @QfDisplayLabel(text = "Product Name")
    private String name;

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

    @QfListAttribute(sortable = true)
    @QfCodeGroup(code = "PRODUCT_CATEGORY")
    @QfDisplayLabel(text = "Category")
    private String category;
}

@QfListAttribute가 선언된 필드가 Excel 컬럼으로 자동 매핑됩니다. @QfDisplayLabel의 표시명이 헤더로 사용됩니다.

다운로드 요청

GET /api/app/products/excel/download?search=노트북&category=ELECTRONICS

현재 검색 조건이 반영된 데이터를 Excel로 다운로드합니다.

---

Excel 샘플 다운로드

업로드할 때 사용할 샘플 파일을 다운로드합니다.

GET /api/app/products/excel/sample

샘플 파일에는:

• 필드별 헤더 (다국어 표시명)
• 예시 데이터 한 행
• 코드성 필드의 허용 값 목록 (별도 시트)
• 필수 필드 표시 (헤더 빨간색)

---

Excel 업로드

비동기 처리

대량 데이터 업로드는 비동기로 처리됩니다.

# 1. 업로드 요청
POST /api/app/products/excel/upload
Content-Type: multipart/form-data
Body: file=products.xlsx

# 응답
{
  "success": true,
  "data": {
    "jobId": "job-abc-123",
    "status": "PENDING",
    "totalRows": 1000
  }
}

# 2. 상태 폴링
GET /api/app/products/excel/upload/job-abc-123

# 응답
{
  "success": true,
  "data": {
    "jobId": "job-abc-123",
    "status": "IN_PROGRESS",
    "totalRows": 1000,
    "processedRows": 350,
    "failedRows": 2,
    "errors": [
      {
        "row": 45,
        "field": "price",
        "message": "가격은 0 이상이어야 합니다.",
        "value": "-1000"
      }
    ]
  }
}

업로드 작업 취소

DELETE /api/app/products/excel/upload/job-abc-123

---

프론트엔드 Excel UI

<template>
  <!-- Excel 다운로드/업로드 버튼 자동 렌더링 -->
  <QfEntityView
    client-app="app"
    entity="product"
  />
</template>

QfEntityView 컴포넌트는 Excel 다운로드/업로드 버튼을 자동으로 포함합니다. 업로드 진행 상태 표시도 자동으로 처리됩니다.

---

Excel 설정

qf:
  excel:
    max-upload-rows: 10000      # 최대 업로드 행 수
    max-file-size: 10MB         # 최대 파일 크기
    batch-size: 100             # 배치 처리 단위
    async-threshold: 500        # 비동기 전환 기준 행 수

---

다음 단계

• SPI 확장 — Excel 처리 커스터마이징
• 어노테이션 레퍼런스 — 전체 어노테이션 목록