HBIM000_임포터 (데이터 이관)
(Hereby) 임포터 (데이터 이관: CLI + in-app 시트) > 앱 개요
| 메타 | 프로토타입 바로가기 (TBU) |
개요
임포터는 병원 기존 Excel 급여 workbook(실측 47 sheets — TC 확정: 09.0 wb.SheetNames.length===47, BESTRH 워크북)을 Hereby로 이관하는 온보딩 데이터 이관 체계다. 🔴 정정 — "CLI가 유일한 이관 수단"이라는 단정은 폐기한다: TC 09 전체가 in-app 시트 기반 이관 정본 경로가 라이브임을 증명한다 — sheetView.create / sheetTemplate.apply / sheetView.commitToRecords / sheetView.commitMasterOverrides(시트 override → 원본 엔티티 역커밋) / sheetView.carryForward(차기월 구성 복제) 전량 SDK 동작 (TC 확정: 09.1~9.8). 즉 이관 경로는 ①전용 CLI 도구(docs 기준, command/flags TBU) ②in-app 시트 마이그레이션(HR 시트 UX + sheetView.* SDK) 의 2원 체계다.웹 전용 라우트 없음: /importer · /admin/importer · /import · /data-import · /migration 웹 경로 5종이 전부 403 응답(2026-07-06 404에서 변화 — 라우트 등록 후 접근 차단 추정). 단 이는 "전용 importer 화면"의 부재이지, in-app 시트 경로(HR 워크스페이스)를 통한 이관 가능성을 부정하지 않는다.핵심 경계: Excel workbook(입력 원천) → parse/validate/dry-run → operator commit → DB 정본 / PayrollLedger. AI는 mapping·validation·dry-run·error explanation까지만 관여하고, commit·rollback mutation은 항상 operator가 실행한다 (POL_데이터이관).
문서 히스토리
- 2026-07-06 최초 작성 - 카나/콸
- 2026-07-10 접속 재확인 (기능 검토 라운드) - 카나/콸
- 2026-07-21 🔴 정정: "CLI 전용" 단정 폐기 — in-app 시트 마이그레이션 정본 경로 실재(sheetView.*), 47시트 실측 확정 (TC 정본, 콸 승인) - 카나/콸
Data I/O
| 메타 | Source → Importer:${payroll_workbook} : 병원 기존 급여/인사 Excel workbook. docs 기준 47 sheets → ImportSourceFile${target_organization} : 대상 병원 org name/id. 없으면 자동 생성 → Organization${import_scope} : all / category / records 단위 이관 (선택 단위 TBU) → ImportRun.scope${run_mode} : parse / profile / validate / dry-run / commit 단계 분리 (실제 flags TBU) → ImportRun.mode${operator_credential} : CLI auth/session 또는 service credential. 없으면 stop / auth requiredImporter → Server/DB:organization / employee master / employee numbers / team structure → Admin 도메인 (사번·급여대장 선행 settle)payroll ledger / salary grade / allowance·deduction / fixed incentive / overtime / education subsidy / year-end·resignation settlement → HR·HBTM 도메인이관 대상 테이블(employment_contracts / overtime_records / fixed_incentives 등) = HBMM calculator 입력 테이블과 1:1 → 이관이 calculator 입력을 시드하는 관계외부 통합 (cross-app):[[HBAD000_관리자 패널 (앱 개요)]] : organization / admin / role bootstrap 연계 (auto-create 범위 TBU)[[HBHR200_급여대장 시트]] : payroll ledger 정본 적재 대상System Admin provisioning : ProvisioningRun ↔ ImportRun 연결 (연결 여부 TBU) |
Import Pipeline 플로우 (parse → settle → category import)
flowchart TD START["CLI Importer 실행"] --> AUTH{"operator auth?"} AUTH -->|없음| DENY["stop / auth required"] AUTH -->|있음| FILE["Excel workbook47 sheets"] FILE --> PARSE["parse sheets"] PARSE --> PROFILE["sheet profilecounts/columns"] PROFILE --> ORG{"target org exists?"} ORG -->|없음| CREATEORG["organization auto-create"] ORG -->|있음| MAP["column/entity mapping"] CREATEORG --> MAP MAP --> VALIDATE["validate rowsrequired/format/ref integrity"] VALIDATE --> DRY["dry-run reportcreate/update/skip/error"] DRY --> CONFIRM{"operator confirm?"} CONFIRM -->|아니오| FIX["fix workbook / mapping"] CONFIRM -->|예| SETTLE["employee numbers + payroll ledger settle"] SETTLE --> CAT["category-by-category import"] CAT --> VERIFY["post-import verification"] VERIFY --> REPORT["report + audit log"] style START fill:#27ae60,color:#fff style DRY fill:#3498db,color:#fff style CONFIRM fill:#e67e22,color:#fff style SETTLE fill:#e74c3c,color:#fff style REPORT fill:#3498db,color:#fff
commit은 대량 mutation = destructive. dry-run 없이 commit하지 않는 것을 원칙으로 하고, 실행은 사람(operator)이 한다.
앱 개요 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 구현 형태 | - | • 이관 경로 2원 체계 (🔴 정정 — 구 "CLI 전용" 단정 폐기): - CASE01 [전용 CLI 도구]: docs 기준, command/flags TBU. 전용 웹 경로 5종(/importer 등) 전부 403(2026-07-06 404→변화) - CASE02 [in-app 시트 마이그레이션]: HR 시트 UX + sheetView.create/sheetTemplate.apply/commitToRecords/commitMasterOverrides/carryForward — 라이브 정본 경로 실재 (TC 확정: 09 전체) | 라우트 census · sheetView.* SDK | TC 09 근거 |
| 10 | 진입/실행 조건 | - | 플랫폼 운영자/온보딩 담당자가 CLI에서 operator auth/session 또는 service credential로 실행. 실제 command/flags TBU | operator | command TBU |
| 20 | source workbook | Input | 병원 기존 Excel payroll workbook을 입력. every sheet parse → sheet profile(name / row count / columns / empty / suspicious) → workbook fingerprint(file hash / sheet count / modified) → category detection | ImportSourceFile · ImportSheetProfile | docs 기준 47 sheets |
| 30 | target organization | Input | 대상 병원 organization. 없으면 자동 생성. org auto-create 시 admin/role/permission bootstrap 범위 TBU | Organization | docs 확인 |
| 40 | mapping / validation | Process | column mapping(Excel column → entity.field) + required(필수누락/형식/날짜·금액 파싱) + reference(사번/팀/월/category 무결성) + duplicate(사번·월·row identity) 검증. issue severity = error/warning/info | ImportMapping · ImportValidationIssue | AI assist 후보 |
| 50 | dry-run / commit | Gate | dry-run summary(create/update/skip/error, category별) + diff preview 후 operator confirmation(사람 확정). commit order = employee numbers/payroll ledger 먼저 settle 후 category별 import → post-import verification(source vs DB totals) → report/audit | ImportDryRunResult · ImportCommitLog | dry-run 필수 원칙 |
| 60 | 이관 대상 카테고리 | - | Organization → Employee master(사번) → Team structure → Payroll ledger(settle) → Salary grade → Allowance/Deduction → Fixed incentive → Overtime → Education subsidy → Year-end settlement → Resignation settlement (아래 보조표 참조) | Category Import Order | 의존성 순서 |
| 70 | 사번·이메일 규칙 | - | 사번 자동생성 = {기관코드}{직군prefix}{seq} (bestrhrn87 간호 / bestrhdr24 의사 / bestrhph06 약사 · hms/hsd/hga 직군코드). 이메일 미입력 시 @{기관코드}.import placeholder(예: bestrhrn14@bestrh.import) | Employee.employeeNo | 4월 출력물 fingerprint 역추적(유일 live 증거) |
| 80 | internal record (설계 제안) | - | ※ 일부 신규 설계 제안: ImportRun(실행 단위/run id) · ImportSourceFile(workbook artifact/hash) · ImportSheetProfile · ImportMapping · ImportValidationIssue · ImportDryRunResult · ImportCommitLog(rollback/reconcile) · ImportRowResult(row별 결과/traceability). 하단 보조표 참조 | Donue 권장 설계 | 라이브 존재 미확인 |
| 90 | Donue 확장 (설계 예정) | - | CLI 맹목 실행 → AI 가이드형 이관 GUI 전환. workbook 업로드/매핑/검증/dry-run/commit을 화면화. 검증·dry-run·GUI = 설계 예정(라이브 미구현). PoC 전환율 핵심 레버 | HBIM800~ (설계 예정) | "이관 3개월 → AI 1주" 포지셔닝 |
이관 대상 카테고리 (Category Import Order)
| 번호 | category | target(추정) | 의존성 | 비고 |
|---|---|---|---|---|
| 00 | Organization | Organization | none | 없으면 자동 생성 |
| 10 | Employee master | Employee/User | Organization | employee numbers 선행 |
| 20 | Team structure | Team/TeamMembership | Employee | |
| 30 | Payroll ledger | PayrollLedger/PayrollSheet | EmployeeNo | docs상 선행 settle |
| 40 | Salary grade | SalaryGrade | Employee/Payroll | 호봉/등급 |
| 50 | Allowance/Deduction | AllowanceRecord/DeductionRecord | Payroll/ModuleRegistry | calculator output key 정합 |
| 60 | Fixed incentive | FixedIncentive/IncentiveRecord | Employee/Team | taxonomy OQ |
| 70 | Overtime | OvertimeRecord | Employee/Attendance | 근태 원천 정합 |
| 80 | Education subsidy | EducationSubsidy | Employee | 산식 TBU |
| 90 | Year-end settlement | YearEndSettlement | Employee/Payroll | adjustment/refund/tax |
| 100 | Resignation settlement | ResignationRecord | Employee/Leave | severance 산식 정합 |
internal record (설계 제안)
| record | 역할 | 비고 |
|---|---|---|
| ImportRun | import 실행 단위 / run id | operator, timestamp, status. 이관 audit 기준 |
| ImportSourceFile | source workbook artifact | file hash/fingerprint, idempotency 후보 |
| ImportSheetProfile | sheet별 row/column profile | 47 sheets profile |
| ImportMapping | sheet/column → entity/field mapping | AI mapping 후보 |
| ImportValidationIssue | validation error/warning (row-level) | severity: error/warning/info |
| ImportDryRunResult | create/update/skip/error preview | commit 전 검증/승인 기준 |
| ImportCommitLog | 실제 생성/수정 records log | rollback/reconcile |
| ImportRowResult | source row별 결과 | traceability |
AI 접점 요약
임포터 AI는 데이터를 대신 넣는 agent가 아니라, 이관 전 매핑·검증·오류 설명·dry-run을 돕는 온보딩 보조자다. 핵심 룰: AI는 mapping suggestion / validation / dry-run / error explanation까지만 수행, 실제 commit·rollback mutation은 operator confirm + audit + rollback plan 이후 사람이 실행한다 (POL_AI안전경계).
| AI Skill | 트리거 위치 | 동작 | 안전 경계 | 우선도 |
|---|---|---|---|---|
| importMappingSuggest | 매핑 단계 | 47시트 sheet/column → target entity.field 자동 매핑 제안(사번/이름/부서/호봉/수당) | 자동 삽입 X, 사람 확정 | ★★★★★ |
| validatePreflight | 검증 단계 | 필수누락/타입오류/중복사번/팀 미존재/참조무결성을 commit 전에 플래그 | 읽기 전용 | ★★★★★ |
| dryRunDiff | dry-run 단계 | "직원 N명·팀 M개 생성, 충돌 K건" 형태로 create/update/skip/error preview 요약 | 읽기 전용 | ★★★★☆ |
| errorExplain | 검증/dry-run 결과 | 실패 row에 "왜 실패했는지·어떻게 고칠지" 자연어 설명(호봉 미매칭/사번 중복) | 읽기 전용, DB write 금지 | ★★★★☆ |
권한 / 상태 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
| [operator auth 없음] | credential 미제공 | stop / auth required | CLI command TBU |
| [dry-run] | validate 통과/warning 허용 | create/update/skip/error preview (no mutation) | dry-run 없이 commit 금지 |
| [commit] | operator confirm | 사번·급여대장 settle 후 category별 정본 생성 + audit | 실행 주체 = operator (destructive) |
OQ
- 실제 CLI command / flags (parse/profile/validate/dry-run/commit 분리 실행) = TBU
- rollback/revert 지원 여부, transactional 보장 수준, idempotency/re-run 기준 = TBU
- 47 sheets의 sheet name 전체 목록, selected records import의 선택 단위(sheet/category/row) = TBU
- validation report format, row-level error 저장 여부, import run audit log entity 존재 여부 = TBU
- org auto-create 시 admin/role/permission bootstrap 범위, ProvisioningRun↔ImportRun 연결 = TBU
- route 404가 의도인지 배포 누락인지, CLI→GUI 가이드형 이관을 Donue P1에 포함할지 = TBU