초기 설정 가이드 구조 개편 스펙 (6→8단계)

Simple HR 프로젝트의 초기 설정 가이드(Setup Guide Checklist)는 신규 테넌트 온보딩을 안내하는 체크리스트다. 기존 6단계 구조에서 아래 문제가 확인되어 8단계로 전면 개편한다. [초기 설정 가이드 구조 개편 설계]

개편 배경

• 신규 테넌트 생성 시 tenant_bootstrap_service.py가 부서·직원·관리자·회사정보를 자동 생성하므로 6개 항목 중 4개가 즉시 "완료"로 표시되는 문제 발생
• 가이드 순서 변경 및 신규 단계 추가 필요 (accounting_policy, positions, workplace)
• 모든 단계 완료 후에도 가이드를 계속 열람할 수 있어야 함
• 신규 테넌트 등록 시 가이드 항목이 이미 완료로 표시되는 버그 확인 → 원인: tenant_bootstrap_service.py의 자동 생성 데이터로 인한 오탐 → 수정 완료 [fix-taskNew-0702 (26년 07월 02일 우선수정사항)] [fix-task-0703 (26년 07월 03일 수정사항)]
• 완료된 항목도 클릭 시 해당 페이지로 이동하도록 개선 필요 → 수정 완료 [fix-taskNew-0702 (26년 07월 02일 우선수정사항)] [fix-task-0703 (26년 07월 03일 수정사항)]
• 모든 사항 완료 후에도 가이드를 열람할 수 있도록 개선 → 수정 완료 [fix-task-0703 (26년 07월 03일 수정사항)]
• 단계 순서 확정: 회사 기본 정보 → 회계·급여 정책 → 근로 정책 → 직위/직책/직무 → 근무지 → 부서 → 직원 → 관리자 [fix-task-0703 (26년 07월 03일 수정사항)]
• 07/09: EWP 없는 기존 직원 289명에 EWP 일괄 생성(backfill 마이그레이션), overrides_dept=false 통일 완료. 부서 정책 미배정 시 직원 등록/수정 차단 적용. 초기 설정 가이드에서 부서 등록과 부서별 근로정책 배정 단계를 분리하는 방향으로 추가 설계. [fix-task-0709]

변경 요약: company_branding 단계를 company_info에 통합하고, accounting_policy · positions · workplace 3개 단계를 신규 추가. 단계 총수 6 → 8.

07/02 순서 조정 확정: 모든 항목은 한 번이라도 수정(저장)하지 않으면 각 페이지의 안내 배너가 사라지지 않고 완료 처리도 되지 않는다. [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]

07/02 추가 요건: 모든 사항이 완료된 이후에도 가이드를 언제든지 열람할 수 있도록 유지. 완료 항목 클릭 시에도 해당 페이지로 이동. [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]

[초기 설정 가이드 구조 개편 설계]

1. DB 모델 (backend/app/db/models.py)

CompanySettings 클래스에 컬럼 추가. _sync_missing_columns에 의해 ALTER TABLE이 자동 반영되므로 별도 마이그레이션 스크립트 불필요. [초기 설정 가이드 구조 개편 설계]

setup_guide_completed_steps = Column(ARRAY(String), default=list, nullable=True)

2. 스키마 (backend/app/schemas/setup_guide.py)

CompleteStepRequest 모델 추가:

step_key: str

3. 서비스 로직 (backend/app/services/setup_guide_service.py)

• STEPS 상수를 8단계로 교체
• 완료 판정:

  completed = step["key"] in (cs.setup_guide_completed_steps or [])

• 신규 함수 2개:
• mark_step_completed(db, tenant_id, step_key) — 타 서비스에서 내부 호출용 헬퍼
• complete_step(db, tenant_id, step_key, updated_by) — 프론트엔드 API용

4. API 엔드포인트 (backend/app/api/v2/setup_guide.py)

POST /admin/setup-guide/complete-step
Body: { "step_key": "company_info" }

5. 기존 서비스 훅 추가

각 함수의 commit 이후 mark_step_completed 호출을 1줄 추가. 실패 시 메인 로직에 영향 없도록 try-except 처리. [초기 설정 가이드 구조 개편 설계]

미구현 범위: accounting_policy, positions, workplace 3단계의 서비스 훅은 이번 범위에서 제외. 해당 페이지 저장 로직에 추후 추가. [초기 설정 가이드 구조 개편 설계]

관련 스펙: 근무 정책 스펙, 직무 관리 스펙, 관리자 등급 및 권한 관리 스펙, 직원 등록 플로우

API 레이어 (frontend/src/lib/api.ts)

setupGuideApi에 completeStep 메서드 추가:

completeStep: (stepKey: string) => apiClient<{ success: boolean }>(
  '/v2/admin/setup-guide/complete-step',
  { method: 'POST', body: JSON.stringify({ step_key: stepKey }) }
),

SetupGuideChecklist.tsx

• completed_count === total_count 일 때 null 반환하지 않음 → 축하 메시지 표시 + "가이드 숨기기" 옵션 유지
• 완료 항목 포함 모든 항목에 Link 추가 (해당 페이지로 이동)
• 미완료 항목도 모두 클릭 가능 (기존: 첫 미완료 항목만 "설정하기" 링크)

페이지별 배너 변경

근무지(workplace) 추가 설계 (07/02): 근무지 이름과 좌표가 등록되지 않으면 안내 배너 유지. 체크 반경 기본값 100m로 세팅. 출퇴근 방법은 GPS만 활성화하고 나머지 방법은 비활성(막기) 처리. [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]

[초기 설정 가이드 구조 개편 설계]

1. 1.백엔드 서버 재시작 → setup_guide_completed_steps 컬럼 자동 생성 확인
2. 2.신규 테넌트 생성 → GET /admin/setup-guide/status 호출 → 8단계 모두 미완료 (completed: false) 확인
3. 3.회사 설정 저장 → company_info 단계가 완료로 전환됨 확인
4. 4.모든 단계 완료 후에도 체크리스트 표시되는지 확인
5. 5.완료된 항목 클릭 시 해당 페이지로 이동하는지 확인
6. 6.기존 테넌트(guide dismissed 상태)는 영향 없음 확인

E2E 테스트 시나리오 (초기 설정 가이드)

E2E 테스트 시나리오 Part 1에 정의된 초기 설정 가이드 관련 시나리오는 다음과 같다. [E2E 테스트 시나리오 - Part 1 관리자 (대시보드, 근태, 직원관리)]

[초기 설정 가이드 구조 개편 설계]

[초기 설정 가이드 구조 개편 설계]