Leyve Docs

다크모드

일괄 업로드 다이얼로그 — BE 참고 ​

펀치리스트 Critical C-6 (최소 정직 배선). 정본 plan: docs/superpowers/plans/2026-07-10-upload-dialog-honest-wire.md.

1. 개요 ​

전 앱 ~75개 SheetCreateUpload*Art.vue 다이얼로그는 파일 입력 + "서식 다운로드" UI는 있었으나 footer(취소/업로드하기)가 통째 주석 처리되어 제출 불가능한 dead-end였다. 이번 슬라이스는 관리비 판매 흐름 5개 다이얼로그에 한해 "파일 선택 검증 + 제출 이벤트 발행 + 닫기"까지 정직하게 배선했다.

실제 CSV/xlsx 파싱과 엔티티 행 생성(bulk import)은 이번 스코프에 없다. 백엔드/파서가 아직 없으므로, 이 문서는 향후 구현할 계약을 스케치한다.

2. 현재 계약 (as-built) ​

SheetCreateUploadArt.vue(src/components/_shared/SheetCreateUploadArt.vue)가 emit하는 이벤트:

emit('upload', selectedFile)   // selectedFile: 브라우저 File 객체 (원본 그대로, 파싱 없음)
  • 파일이 선택되지 않으면 업로드하기 버튼이 disabled라 이 이벤트 자체가 발생하지 않는다.
  • 이벤트 수신 측(각 도메인 wrapper)은 현재 아무도 이 이벤트를 구독하지 않는다 — wrapper는 <SheetCreateUploadArt :id=".." title=".." />만 렌더하며 @upload 리스너를 달지 않았다. 즉 지금은 "파일을 골라 제출하면 창만 닫히고 아무 데이터도 만들어지지 않는" 상태다(사용자 매뉴얼에도 ❌ 예정으로 명시).

3. 의도된 후속 계약 (스케치 — follow-up) ​

실제 일괄 업로드를 구현할 때 각 도메인 wrapper가 @upload="handleUpload"로 구독하고, 아래 파이프라인을 실행하는 것을 권장한다.

① upload 이벤트 (File)
  ↓
② 파싱 — File → 텍스트(FileReader.readAsText, UTF-8 BOM 고려) → CSV/XLSX 파싱 → 행 배열
  ↓
③ 행별 검증 — 필수 컬럼 존재·타입·참조 무결성(예: unitCode가 units 마스터에 존재하는지)
     검증 실패 행은 성공 카운트에서 제외, { line, reason } 형태로 수집 (부분 성공 계약)
  ↓
④ 엔티티 행 생성 — 검증 통과 행만 해당 도메인 컴포저블(create 함수)에 upsert/insert
  ↓
⑤ 결과 리포트 — { added: N, errors: [{line, reason}] } 형태로 사용자에게 표시

이 패턴은 이미 검침 입력(useMeterReadings().importCsv, docs/handoff/backend/service-charge-metering.md §6)에서 동일한 형태(부분 성공 + 행별 에러 리포트)로 구현되어 있다 — 신규 도메인 import를 만들 때 그 계약을 참고 템플릿으로 재사용할 것을 권장한다(파일 형식, 헤더 자동 감지, {added, errors} 반환 shape 포함).

주의: 검침의 importCsv는 텍스트(string) 입력을 받는다. 이번 공유 컴포넌트는 File 객체를 그대로 emit하므로, 후속 구현 시 FileReader로 텍스트화하는 단계가 각 wrapper(혹은 공용 유틸)에 필요하다.

4. 적용 범위 (이번 슬라이스, 5곳) ​

Wrapperid도메인 엔티티
src/components/tax-invoice/tax-invoice/unit/general/overlays/SheetCreateUploadUnitArt.vuesheet-create-upload-unit-art유닛(세금계산서 발행)
src/components/administration/billing/workspace/property/console/general/overlays/SheetCreateUploadPropertyArt.vuesheet-create-upload-property-art프로퍼티(관리비 콘솔)
src/components/administration/billing/workspace/property/console/account/overlays/SheetCreateUploadSiteArt.vuesheet-create-upload-site-art현장
src/components/administration/billing/workspace/property/console/plan/overlays/SheetCreateUploadBuildingArt.vuesheet-create-upload-building-art동
src/components/administration/billing/workspace/property/overlays/SheetCreateUploadPropertyArt.vuesheet-create-upload-property-art프로퍼티(루트)

각 wrapper의 실 데이터 생성 API는 아직 없다 — 이 표는 "어떤 엔티티에 붙일지"의 배치도이며, 실제 create 컴포저블 연결은 스코프 밖.

5. 관련 백로그 — 건축물대장/세움터 오픈API 자동수집 ​

프로퍼티(단지)·동·호(유닛) 온보딩을 CSV 수기 업로드가 아니라 정부 오픈API 자동수집으로 대체/보완하는 기능 백로그가 별도로 존재한다: docs/decisions/FEATURE-PROPERTY-ONBOARDING-BUILDING-REGISTRY-API-2026-07-09.md(건축HUB 건축물대장정보 서비스 — 총괄표제부/표제부/전유부를 프로퍼티/동/호 마스터에 매핑). 미착수 기획 단계이며, 이번 CSV 업로드 배선과는 별개 경로(자동수집 vs 수기 업로드)로 병행 검토 대상이다.

6. 스코프 경계 ​

포함: 공유 컴포넌트 파일 선택 검증·upload 이벤트 발행(raw File)·닫기, 5개 wrapper 적용.

제외 (YAGNI — follow-up):

  • 실제 CSV/xlsx 파싱.
  • 파싱 결과의 엔티티 행 생성(각 도메인 create API 연결).
  • 행별 검증·부분 성공 리포트({added, errors}) — 위 §3 스케치 참고.
  • 실제 서식(템플릿) 파일 다운로드.
  • 나머지 ~70개 다이얼로그(HR·facility·crm·contract·master-data 등) — docs/handoff/frontend/billing-upload-dialog.md §5 참고.
  • 3개 orphan 다이얼로그(트리거 미연결) — 아래 FE 문서 §4 참고.