SimpleHR project
이용요금 및 과금 정책
conceptedited by Cairni · 방금 · AIv3
개요
Simple HR 의 이용요금 정책은 기업 내 등록 직원 수를 기준으로 구간별 요금이 자동 적용되는 구조를 가진다. 과금 정책의 자동 계산 적용 및 구현은 설계 문서에 따라 진행 중이다. fix-task-0612-md 참조.
인원 구간별 기본 요금
| 구간 | 기본 요금 | 비고 |
|---|---|---|
| 5명 이하 | 무료 | — |
| 5명 초과 ~ 10명 이하 | 20,000원 (월 고정) | 기본비용 청구 |
| 10명 초과 | 20,000원 + 1인당 플랜 단가 | 초과 인원에 단가 적용 |
예시: 스탠다드 플랜에서 11명 → 20,000원 + 1명 × 3,000원 = 23,000원 설계-요금제시스템-md
플랜별 1인당 요금 및 기능 범위
AI · 출처 클릭
무료0
베이직2000
스탠다드3000
스페셜10000
| 플랜 | 1인당 월 요금 | 메뉴 제한 |
|---|---|---|
| 무료 (PLAN_FREE) | 0원 | 이러닝·전자근로계약서 제외 |
| 베이직 (PLAN_BASIC) | 2,000원 | 이러닝·전자근로계약서 제외 |
| 스탠다드 (PLAN_STD) | 3,000원 | 전체 메뉴 접근 가능 |
| 스페셜 (PLAN_SPC) | 10,000원 | 전체 메뉴 + 페이롤 연동 |
자동 계산 로직 흐름
재직인원 기준
과금 계산에 포함되는 직원 수 = Employee.employment_status != "EMP_RETIRED" AND Employee.tenant_id == tenant_id 인 직원 수
플랜별 메뉴 접근 제한
권위 소스: Menu.visible_tiers
메뉴별 접근 가능한 플랜 목록은 Menu 모델의 visible_tiers JSONB 필드를 권위 소스로 사용한다.
- 별도 License 매핑 테이블 제거 → 동기화 이슈 방지
- 메뉴 데이터와 플랜 정보를 한 곳에서 관리
- 프론트엔드 사이드바 자동 필터링
메뉴별 플랜 접근 규칙
| 메뉴 그룹 | PLAN_FREE | PLAN_BASIC | PLAN_STD | PLAN_SPC |
|---|---|---|---|---|
| 급여관리 (4개) | O | O | O | O |
| 이러닝센터 (5개) | X | X | O | O |
| 전자근로계약서 | X | X | O | O |
| 나머지 전체 메뉴 | O | O | O | O |
캐시 전략
Menu.visible_tiers 데이터를 앱 시작 시 메모리에 로드하여 매 요청마다 DB 조회 없이 dictionary lookup으로 플랜 권한 검사:
{menu_url: set(plan_codes)} — 각 메뉴에 접근 가능한 플랜 코드 목록DB 스키마
BillingPlan (신규)
시스템관리자가 플랜별 단가를 설정·수정하는 마스터 테이블.
| 필드 | 설명 |
|---|---|
| plan_code | PLAN_FREE, PLAN_BASIC, PLAN_STD, PLAN_SPC |
| name_ko | 플랜 한글명 |
| price_per_user | 1인당 월 요금 |
| flat_fee_amount | 5명 초과 시 기본 고정료 (기본값 20,000원) |
| is_active | 활성화 여부 |
BillingSnapshot (신규)
월별 과금 스냅샷을 기록하여 이력 추적.
| 필드 | 설명 |
|---|---|
| tenant_id | 업체 ID |
| billing_month | "2026-06" 형식 |
| plan_code | 당월 적용 플랜 |
| active_employee_count | 재직 직원 수 |
| total_amount | 월 청구액 |
TenantBillingOverride (구조 수준)
업체별 할인/추가요금 적용 (후순위 구현).
API 설계
시스템관리자 API
GET /v2/system/billing-plans
→ 플랜 목록 및 단가 조회
PUT /v2/system/billing-plans/{plan_code}
← 플랜 단가 수정
GET /v2/system/usage
→ 전체 테넌트 사용량 및 과금액 조회
POST /v2/system/billing-snapshots/generate
← 월별 스냅샷 생성
GET /v2/system/billing-snapshots?month=2026-06
→ 스냅샷 이력 조회
PATCH /v2/system/tenants/{id}/trial
← 체험판 연장/단축/정식 전환회사 최고관리자 API (읽기 전용)
GET /v2/admin/billing/current
→ 현재 플랜, 인원, 기본료, 추가분, 합계
GET /v2/admin/billing/history
→ 월별 청구 이력 조회권한: require_company_admin + employee.admin_role.is_system == True 체크
구현 범위
포함 사항
- 시스템관리자가 플랜 단가 설정/수정
- 테넌트별 사용량·과금 실시간 조회
- 체험판 연장/단축/정식 전환
- 월별 과금 스냅샷 생성 및 이력 관리
- 플랜별 메뉴 접근 제한 실동작
- 회사 최고관리자 정산 페이지 (읽기 전용)
범위 제외 (후순위)
- PG(결제게이트웨이) 연동
- 자동 청구 및 결제
- 업체별 커스텀 단가 UI (DB 구조만 준비)
프론트엔드 페이지 계획
| 대상 | 페이지 | 기능 |
|---|---|---|
| 시스템관리자 | plans/page.tsx | 플랜 4종 카드, 단가 수정 가능 |
| 시스템관리자 | companies/page.tsx | 플랜 선택 드롭다운, 필터 추가 |
| 시스템관리자 | usage 페이지 | 테넌트별 과금, 스냅샷 생성 |
| 시스템관리자 | license-menus/page.tsx | 4개 플랜 열 표시 |
| 회사 최고관리자 | admin/billing/page.tsx (신규) | 현재월 및 청구 이력 |
마이그레이션 전략
서버 시작 시 자동 실행:
- 1.BillingPlan 테이블 생성 (SQLAlchemy create_all)
- 2.tenants.plan_code 데이터 마이그레이션 (PLAN_PRM → PLAN_SPC)
- 3.BillingPlan 시드 삽입 (무료, 베이직, 스탠다드, 스페셜)
- 4.Menu.visible_tiers 업데이트 (이러닝/계약서 메뉴만 STD/SPC로, 나머지는 전체 플랜)
- 5.PlanCode enum에서 PLAN_PRM 제거
진행 상태
요금제 시스템 구현AI · 출처 클릭
설계 완료4
DB 스키마 (BillingPlan, BillingSnapshot)
API 설계 (시스템관리자, 회사관리자)
플랜별 메뉴 접근 제한 전략
마이그레이션 전략
구현 예정4
BillingService 구현
API 엔드포인트 구현
프론트엔드 페이지 연동
단위 및 통합 테스트
관련 문서
- 설계-요금제시스템.md — 상세 구현 설계
- 이용요금(과금) 정책 스펙 — 이전 기본 스펙
- Simple HR 프로젝트 개요
- fix-task-0612.md — 작업 태스크
- 액션 아이템
- 의사결정 로그