우리매장 앱 — 기능 가이드

최종 업데이트: 2026-08-10 (v5.41) Android / Kotlin + Jetpack Compose

앱 개요

우리매장은 소상공인을 위한 매장 관리 앱입니다.
직원 등록부터 출퇴근 기록, 스케줄 관리, 급여 계산까지 한 앱에서 처리합니다.

앱은 사장 앱과 직원 앱 두 모듈로 구성됩니다.

빌드 플레이버

사장 앱 (app 모듈)

직원 앱 (staff-app 모듈)

사장 앱 화면 구성 (5개 탭 + 시트 레이어)

🚀 온보딩 (최초 1회)

prod 플레이버(IS_DEV=false) 신규 유저 첫 로그인 시 OnboardingScreen 표시

• 매장 아이콘 선택 (이모지 그리드 — 고기/BBQ·한식·해산물·카페·디저트·주점·양식 등 50종+)
• 매장명 입력
• "시작하기" 버튼 → 메인 화면 진입
• 이후 앱 종료/재시작 시 자동 로그인 (Firebase Auth 토큰 유지)

🏠 홈 탭

상단 헤더

• 매장 아이콘(동적) + 매장명 표시 — 온보딩/설정에서 지정한 아이콘 사용
• 우상단 프로필 버튼 (이니셜 원형) → 프로필 시트 열기

오늘 현황 카드

• 전체 / 출근중 / 출근전 / 퇴근 4개 통계를 색상 구분하여 표시

빠른 실행 타일 (4개)

급여일 D-day 배너

• 다음 급여일까지 남은 일수 표시
• 급여일 당일: "오늘은 급여일입니다 🎉"

오늘의 직원 목록

• 각 직원의 현재 출퇴근 상태와 시간 표시
• 직원 이름: 그라디언트 색상 표시
• 직원 탭 → HomeStaffDetailSheet 열기
  • 오늘 출퇴근 현황 (출근/퇴근 처리 버튼)
  • 이번 주 스케줄 목록 (오늘~+6일)
  • 스케줄 추가하기 버튼 → 스케줄 탭으로 이동

주간 리포트

• 홈 하단 "주간 리포트 보기" 버튼 → WeeklyReportSheet 열기
  • 기간: 지난주 월요일 ~ 일요일
  • 요약 카드: 총 근무일수 / 총 근무시간 / 평균 근무시간
  • 요일별 바 차트: 월~일 총 근무시간 비율
  • 직원별 근무 테이블: 아바타 + 이름 + 근무일수 + 총 근무시간

🪪 직원 탭

직원 목록

• 재직 중인 직원 카드 목록
• 필터 칩: 전체 / 정규직 / 파트타임 / 퇴직자
• 빈 상태 아이콘: 🪪

직원 추가 버튼 (헤더 우상단)

• 📋 버튼 → ContactImportSheet (주소록에서 여러 명 일괄 추가, PRO 전용)
• ＋ 직원 추가 → AddStaffSheet (1명 직접 입력)
• 무료 플랜: 최대 5명 제한 (초과 시 안내 다이얼로그)

직원 추가/수정 시트 (AddStaffSheet)

아바타 설정

• 이니셜 / 이모지(30종) / 사진(갤러리·카메라) 3가지 타입
• 색상 피커: "자동" + 9가지 그라디언트 선택

기본 정보

• 이름 / 직책 / 고용형태(정규직·파트타임·아르바이트·단기)
• 시급 / 연락처 / 입사일

급여 정보

• 지급방식: 계좌이체 / 현금
• 계좌이체 선택 시: 은행명 / 계좌번호 / 예금주 입력
  • 계좌번호 입력: 숫자만 입력 (최대 20자리), 화면 표시 시 은행별 하이픈 패턴 자동 적용
  • 예) 국민 14자리 → 123456-78-123456, 신한 12자리 → 123-456-123456

고정 근무 패턴 설정 (자동채우기 기능 연동)

• 고정 근무일 선택 (월·화·수·목·금·토·일 체크)
• 고정 시작시간 / 종료시간 입력
• 설정 후 스케줄 탭 주간 보드에서 "🔄 자동채우기" 사용 가능

직원 상세 시트 (StaffDetailSheet)

• 3개 스탯 카드: 근무시간 / 예상급여 / 출근율
• 기본 정보 / 계좌 정보 / 최근 출퇴근 기록 / 메모
• 계좌번호: 은행명 기준 하이픈 포맷 표시 + 복사 버튼
• 초대코드 카드 (직원 앱 연동):
  • staffUid 연결됨: ✅ 연결됨 + 이메일 표시
  • 미연결: "초대코드 발급" 버튼 → 6자리 코드 + 복사 버튼 → 직원이 직원 앱에 입력하면 연결
• 하단: "정보 수정" / "퇴사 처리" 버튼

퇴직 처리

• ResignConfirmSheet: 퇴사일 + 퇴사 사유 입력 → "퇴직자 보관함으로 이동"
• ResignedStaffDetailSheet: 재입사 처리 / 영구 삭제

📅 스케줄 탭

뷰 구성

상단 토글로 두 가지 뷰 전환:

• 📅 월간 달력 (기본) — 날짜 탭으로 일정 조회 및 편집
• 📊 주간 보드 (보조) — 직원×7일 흐름 파악용, 읽기 전용

📅 월간 달력 뷰

달력 그리드

• 직원 배정 일정: 컬러 도트(최대 3개) + "N명" 배지
• 직원 미배정 일정: 반투명 점 + "N개" 배지
• 공휴일: 셀 내 이름 표시 (빨간 텍스트)
• 월 네비게이터 (‹ ›)

DayPanel (날짜 탭 시 하단 표시)

• 선택된 날짜의 근무 목록
• 날짜 헤더: 날짜명 + "오늘" 배지 + 공휴일 배지 + "N건 · N명" 요약
• 빈 날: 📭 + "등록된 근무가 없어요"
• 각 근무 항목: 컬러바(4dp) + 제목 + 시간 + 직원 칩
  • 반복 일정: 제목 옆 ↺ 반복 파란 배지
  • ✏️ 버튼: 수정 시트 열기
  • 🗑 버튼 (일반 일정): 인라인 삭제/취소 확인
  • 🗑 버튼 (반복 일정): 3-option 다이얼로그 표시
    • 이 날만 삭제 — 이 날짜 레코드만 삭제
    • 이 날 이후 전체 삭제 — 이 날 포함 이후 N개 삭제
    • 반복 전체 삭제 — 그룹 전체 삭제 (N개)

근무 추가/수정 시트 (ScheduleSheet) 헤더 우상단 "＋ 근무 추가" 버튼 또는 ✏️ 버튼으로 열기

반복 등록

• 주기 선택: 없음 / 매일 / 매주 / 격주
• 매주·격주 선택 시 요일 칩 표시 (평일/주말 빠른 선택 + 일·월·화·수·목·금·토 개별 선택)
• 기간 선택: 이번달 / 다음달 / 2개월 / 직접지정 (DatePicker)
• 반복 선택 시 "날짜범위 → N개 생성 예정" 초록 미리보기 박스
• 저장 버튼: "저장" → "N개 저장" 동적 변경
• 반복으로 만든 일정은 동일한 repeatGroupId 공유

근무 유형별 자동 설정

• 추가 모드: 유형 칩 선택 시 기본 시간 자동 채움
• 수정 모드: 기존 시간 유지, 하단에 "삭제" 버튼 추가
  • 반복 일정 수정 시 주황 배너: "↺ 반복 일정입니다. 이 날만 수정됩니다."
• 저장 완료: "✅ 근무가 저장됐어요" / "✅ N개 근무가 저장됐어요" SnackBar

📊 주간 보드 뷰 (읽기 전용)

직원 × 7일 그리드 — 한 주 흐름 파악용

헤더 영역

• 주간 라벨: "M월 D일(요일) — M월 D일(요일)" + ‹ › 주 이동
• 요약 칩: 배치 인원 / 시프트 수 / 이번 주 포함 여부
• [🔄 자동채우기] 버튼: 고정 근무 패턴 설정된 직원의 이번 주 일정 자동 생성
• [📋 지난주 복사] 버튼: 지난주 전체 일정을 이번 주로 복사

그리드

• 헤더 행: 직원 열 + 일~토 날짜/요일
• 직원 행: 아바타+이름 + 7개 시프트 블록
• 오늘 컬럼: 연주황 하이라이트
• 미배정 행: 직원 없는 일정 표시
• 하단 총인원 행

시프트 블록 색상 규칙 | 키워드 | 배경 | 텍스트 | |--------|------|--------| | "오픈" 포함 | 연주황 | 주황 | | "오후" 포함 | 연파랑 | 파랑 | | "마감" 포함 | 연보라 | 보라 | | 그 외 | 연초록 | 초록 | | 없음 (휴무) | 연회색 | 회색 |

⏱ 출퇴근 탭

오늘 근무 현황

• 직원 카드 정렬: 출근중 → 출근전 → 퇴근 → 휴무
• 출근 버튼(초록) / 퇴근 버튼(파랑 외곽선)

근무 현황 상세 시트 (AttendDetailSheet)

• 출근/퇴근 시간 직접 수정 (HH:mm)
• 상태 칩: 출근중 / 출근전 / 퇴근 / 휴무

💰 급여 탭

직원 급여 카드

• 근무시간 / 기본급 / 조정액 / 총지급액
• 지급 상태 배지 (완료/미지급)
• 카드 탭 → AdjustSheet (추가수당/공제 입력)
• 카드 롱클릭 → SettleSheet (지급 완료 처리)

급여 상세 시트 (PayrollDetailSheet)

• 월별 출퇴근 기록 / 근무시간 / 예상 급여 / 조정 이력
• 월 네비게이션 (◀ 년월 ▶): 이전 달 기록 조회 가능

급여 히스토리 (PayHistorySheet)

• 연도 내비게이터
• 연간 요약 카드: 총 인건비 / 완료월 / 월평균 / YoY%
• 월별 막대 차트: 완료(오렌지) / 진행중(노랑) / 미진행(회색), 금액/시간 토글
• 분기별 현황 카드 (Q1~Q4)
• 직원별 인건비 랭킹 (상위 8명)

⚙️ 프로필 시트

프로필 버튼(홈 우상단) 탭으로 진입

내 정보

• 아바타 + 이름 + 이메일
• ✏️ 수정 버튼 → 이름/이메일/아바타 변경

내 매장

• 매장 아이콘 + 매장명 목록
• 현재 매장: 주황 강조 표시
• 매장 탭 → 해당 매장으로 전환
• PRO + 매장 2개 이상: 비현재 매장에 🗑️ 삭제 버튼 표시
  • 삭제 확인 AlertDialog: 매장 + 관련 직원·출퇴근·급여·스케줄 전체 삭제
• "새 매장 추가" 버튼 (PRO, 1개 매장 무료 제한)

매장 설정

• 💰 급여일 설정: 매월 5/10/15/20/25/말일
• 📋 근로계약서 기본 조항: 4개 조항 인라인 편집

앱 설정

• 🎨 테마: 기본(오렌지 그라디언트) / 웜(크림 미니멀) 선택
• 🔔 알림 설정 (4종 토글): 출퇴근 / 급여일 / 미체크 / 주간리포트
• ☁️ 데이터 백업/복원: JSON 내보내기/가져오기 (SAF)
• Firestore 동기화 (PRO + 로그인): 로그인 시 자동 클라우드 동기화

로그아웃

• "로그아웃" 버튼 → 로그인 화면으로 이동

📱 직원 앱 (staff-app)

직원 전용 별도 앱. 초대코드로 매장에 연결 후 사용.

앱 정보

• 패키지: com.hmhworks.ourshop.staff (dev: .staff.dev)
• 테마: 인디고 #4F46E5 / 바이올렛 #7C3AED

인증 흐름

1. 스플래시 → 로그인 상태 확인
2. 미로그인: 로그인 화면 (이메일/비밀번호 또는 Google 로그인)
3. 로그인 후 매장 미연결: 초대코드 입력 화면
4. 연결 완료: 메인 4탭 화면 진입

초대코드 연결 (InviteCodeScreen)

• 6자리 개별 박스 입력 UI
• 유효 코드 입력 → 사장 앱의 해당 직원 계정에 staffUid/staffEmail 자동 연결
• 코드 유효시간: 24시간

4탭 구성

☁️ Firestore 동기화

• 조건: PRO 플랜 + 로그인 상태
• 구조: /users/{uid}/stores · staff · attendance · payroll · schedules
• 동작: 앱 시작/로그인 시 Firestore → 로컬(Room) 자동 동기화
• 쓰기: 모든 데이터 변경 시 Room DB + Firestore 동시 저장 (fire-and-forget)
• 오프라인: Room DB가 로컬 소스, 오프라인 완전 동작

아바타 & 색상 시스템

그라디언트 팔레트 (9가지)

색상 결정 규칙

• avatarColorIndex = -1: 리스트 순서(index) % 9 자동 배정
• avatarColorIndex = 0~8: 직원이 선택한 고정 색상
• 퇴직자: 회색(#9CA3AF) 고정

아바타 타입

• INITIAL: 이름 첫 글자, 그라디언트 원형 배경
• EMOJI: 이모지 30종, 그라디언트 배경
• PHOTO: 갤러리/카메라 URI, 원형 크롭

계좌번호 하이픈 패턴

패턴 없는 은행은 숫자 그대로 표시 (fallback)

빌드 & 설치

# 사장 앱 — 빌드만 (devDebug 기본)
.\scripts\build.ps1

# 사장 앱 — prodPro 빌드만
.\scripts\build.ps1 -Flavor prodPro -BuildType release

# 사장 앱 — 빌드 + ADB 설치
.\scripts\build-install.ps1 -Target <ip:port>
.\scripts\build-install.ps1 -Target <ip:port> -Flavor prodPro -BuildType release

# 직원 앱 — 빌드 + ADB 설치
.\scripts\build-install-staff.ps1 -Target <ip:port>

주의: ADB 포트는 세션마다 변경됩니다. 매번 사용자에게 직접 받아서 사용하세요.

주요 기술 스택