SimpleHR project
초기 설정 가이드 구조 개편 설계
sourceedited by Cairni · 방금 · AIv1
개요
tenant_bootstrap_service.py가 신규 테넌트 생성 시 부서·직원·관리자·회사정보를 자동 생성하여, 기존 6단계 가이드 중 4개가 즉시 "완료"로 표시되는 문제를 해결하기 위한 구조 개편 설계. 초기 설정 가이드 구조 개편 설계
핵심 변경 요약
AI · 출처 클릭
가이드 단계
6 → 8단계
Backend 수정 파일
9개
Frontend 수정 파일
8개
| 구분 | 기존 | 변경 |
|---|---|---|
| 단계 수 | 6단계 | 8단계 |
| 완료 판정 | 데이터 존재 여부 (count > 0 등) | setup_guide_completed_steps 배열에 key 포함 여부 |
| 완료 후 UI | 가이드 숨김(null 반환) | 축하 메시지 + "가이드 숨기기" 유지 |
| 항목 클릭 | 첫 미완료 항목만 링크 | 모든 항목(완료 포함) 클릭 가능 |
8단계 가이드 구성
| # | key | 라벨 | 링크 |
|---|---|---|---|
| 1 | company_info | 회사 기본 정보 등록 | /admin/settings/company |
| 2 | accounting_policy | 회계·급여 정책 설정 | /admin/settings/fiscal-policy |
| 3 | work_policy | 근로 정책 등록 | /admin/policy/work |
| 4 | positions | 직위/직책/직무 설정 | /admin/positions |
| 5 | workplace | 근무지 설정 | /admin/locations |
| 6 | departments | 부서 등록 및 근로정책 배정 | /admin/organization |
| 7 | employees | 직원 등록 | /admin/employees |
| 8 | managers | 관리자 등록 | /admin/managers |
company_branding단계는company_info에 통합됨.
아키텍처 변경 흐름
Backend 변경 상세
DB 모델 (models.py)
CompanySettings에 setup_guide_completed_steps = Column(ARRAY(String), ...) 컬럼 추가. _sync_missing_columns를 통해 ALTER TABLE 자동 반영.
서비스 훅 (mark_step_completed)
각 서비스 함수 commit 이후 호출. try-except로 감싸 메인 로직에 영향 없음.
| 서비스 파일 | 함수 | step_key |
|---|---|---|
settings_service.py | update_company_settings | company_info |
api/v2/settings.py | upload_company_logo | company_info |
policy_service.py | create/update_work_policy | work_policy |
organization_service.py | create/update_department | departments |
employee_service.py | create_employee | employees |
employee_service.py | grant_admin | managers |
accounting_policy,positions,workplace3단계의 서비스 훅은 이번 범위 제외. 해당 페이지 저장 로직에 추후 추가.
신규 API
POST /admin/setup-guide/complete-step — body: { "step_key": "company_info" } — 프론트엔드에서 직접 완료 처리 시 사용.
Frontend 변경 상세
SetupGuideChecklist.tsx: 완료 시 null 반환 제거 → 축하 메시지 + 숨기기 버튼 유지api.ts:setupGuideApi.completeStep(stepKey)함수 추가- 페이지 배너 변경:
company/page.tsx: 배너 2개 → 1개로 통합work/page.tsx: stepKeybasic_policy→work_policyfiscal-policy/page.tsx,positions/page.tsx,locations/page.tsx: 배너 신규 추가
배포 리스크
배포 리스크 평가AI · 출처 클릭
리스크 없음2
setup_guide_completed_steps 컬럼 추가: nullable + 자동동기화
초기 설정 가이드 구조 개편 설계
기존 테넌트 (guide dismissed): 영향 없음
초기 설정 가이드 구조 개편 설계
주의2
기존 테넌트 (미dismiss): 모든 단계가 미완료로 리셋됨 — 가이드 재진행 또는 숨기기 필요
초기 설정 가이드 구조 개편 설계
step key/개수 변경 — API 응답 구조는 유지되나 클라이언트 step key 참조 코드 확인 필요
초기 설정 가이드 구조 개편 설계