혼공댕 — 상세 기획서 (PRD)

01 프로덕트 개요 Product Overview

혼공댕의 제품 정의, 핵심 가치, 주요 지표를 정리합니다.

🐕 혼공댕이란?

혼공댕(HonGongDaeng)은 초등~중학생 자녀의 자기주도학습을 부모-자녀가 함께 관리하는 PWA 기반 학습 플래너입니다. "혼자 공부하는 댕댕이"라는 의미로, 코기 왈왈이 🐶와 턱시도 냥냥이 🐱 마스코트가 학습 동반자 역할을 합니다.

제품 유형

PWA SaaS

웹 + 모바일 홈 화면 설치

타깃 유저

초중등 가정

부모 + 자녀 (7~15세)

핵심 가치

자기주도학습

Plan → Do → Review 순환

수익 모델

구독 SaaS

Free / Plus / Family

📐 이론적 기반

교육학 이론에 기반한 제품 설계

이론	핵심 개념	제품 반영
Self-Regulated Learning Zimmerman (1989)	Plan-Do-Review 자기조절 학습 순환	일일 계획 → 타이머 실행 → 완료 리뷰 → 통계 피드백
Self-Determination Theory Deci & Ryan (1985)	자율성 · 유능감 · 관계성	아이가 과목/시간 직접 선택, Trophy Shelf, 부모 응원
Operant Conditioning Skinner (1938)	긍정적 강화 (보상)	학습 완료 → 게임 시간 적립 (Bone 포인트)
Metacognition Flavell (1976)	자신의 학습 과정 인식	일일 회고, 과목별 통계, 연속 학습 스트릭

02 유저 페르소나 User Personas

혼공댕의 두 핵심 유저 유형을 정의합니다.

👩‍💼

부모 (Parent)

Google OAuth 계정 · 관리자 권한

자녀의 학습 진도를 모니터링하고 싶다
게임 시간을 학습 보상과 연결하여 동기부여를 하고 싶다
교재 완료 시 알림을 받고, 적절한 보상을 주고 싶다
시험 기간에는 게임을 동결하고 싶다
여러 자녀를 하나의 계정으로 관리하고 싶다

🧒

자녀 (Child)

4자리 PIN 로그인 · 학습 실행자

오늘 뭘 공부해야 하는지 한눈에 보고 싶다
공부하면 게임 시간이 쌓이는 게 재미있다
교재를 다 끝내면 성취감을 느끼고 싶다
타이머로 집중 시간을 관리하고 싶다
마스코트(왈왈이/냥냥이)와 함께 공부하는 느낌이 좋다

03 정보 구조 Information Architecture

앱의 화면 구조와 탭 네비게이션을 정리합니다.

🗂️ 앱 구조 (SPA)

🏠 혼공댕 App (app.html)
- 🔐 인증 레이어
  - 온보딩 (5단계)
  - Google OAuth 로그인 (부모)
  - PIN 로그인 (자녀)
  - 자녀 선택 화면
- 📱 탭 바 (하단 6개 탭)
  - 📅 계획 (Plan)
    - 요일별 학습 계획 그리드 (월~일)
    - 과목 카테고리 시스템 (9개)
    - 활성 과목 목록
    - 과목 상세 설정
  - 📆 캘린더 (Calendar)
    - 주간 카드 뷰 (이번 주 + 다음 주)
    - 주간 통계 (달성률, Bones, 연속일수)
    - 학습 통계 섹션 (차트, 일별 진행률, 스트릭, 월 개요)
  - 📖 오늘 (Today / Day View)
    - Today's Plan 칩 인터랙션
    - 학습 슬롯 (과목, 타이머, 교재 진도)
    - 일일 리뷰 / 부모 승인·메모
  - 📚 교재 (Books)
    - 진행 중인 교재 (프로그레스 바)
    - 🏆 트로피 선반 (완료 교재)
    - 교재 검색 (알라딘 API)
    - 표지 스캔 (카메라)
  - 🎮 게임 (Game Time)
    - 잔고 / 타이머 / 히스토리
    - 부모: 보너스 / 패널티 / 동결
    - 게임 시간 계약서
  - ⚙️ 설정 (Settings)
    - 자녀 관리 (CRUD + PIN)
    - 과목 / 교재 관리
    - 공휴일·방학 관리
    - 결제·구독
    - 고객 문의
    - 클라우드 저장 / 초기화
- 🔝 헤더 바
  - BI 로고 (혼공댕)
  - 🔔 알림 벨 + 뱃지 (부모 전용)
  - 계정 아바타 → 전환 드롭다운
  - 🇰🇷/🇬🇧 언어 토글
  - 🌙/☀️ 테마 토글

04 인증 시스템 Authentication System

Google OAuth (부모) + 4자리 PIN (자녀) 이중 인증 구조

🔐 인증 구조

유저 유형	인증 방식	세션 만료	권한
부모 (Parent)	Google OAuth 2.0 accounts.google.com	30일	관리자 (자녀 CRUD, 게임타임 관리, 설정)
자녀 (Child)	4자리 PIN SHA-256 해시 저장	7일	학습 실행 (슬롯, 교재, 리뷰)

부모 로그인 플로우 (Google OAuth)

🔑 로그인 클릭

→

Google 인증

→

OAuth Callback

→

DB 조회/생성

→

세션 토큰 발급

→

앱 리디렉트

      토큰 전달: OAuth callback 후 app.html?auth_token={token}으로 리디렉트.
      프론트엔드가 URL에서 토큰 추출 → localStorage에 저장 → 이후 Authorization: Bearer {token} 헤더로 API 호출.
    

자녀 PIN 로그인 플로우

가정 코드 입력

→

자녀 목록 로드

→

자녀 선택

→

PIN 4자리 입력

→

SHA-256 검증

→

세션 생성

      Rate Limit: PIN 로그인은 IP당 60초에 5회 제한으로 brute-force 방지
    

👥 계정 전환 (Account Switching)

헤더의 사용자 아바타 클릭 시 드롭다운 메뉴가 표시되며, 자녀/부모 간 실시간 전환이 가능합니다.

기능	설명
부모 → 자녀 전환	드롭다운에 자녀 목록 표시 → 클릭 시 `currentChild` 변경, 데이터 리로드
자녀 → 부모 전환	"부모 모드" 메뉴 표시 → 클릭 시 부모 모드 활성화
데이터 스코핑	모든 KV 키에 `f:{familyId}:c:{childId}:` 프리픽스 적용
로그아웃	세션 DB 삭제 + 쿠키 제거 + localStorage 클리어

05 온보딩 Onboarding Flow

첫 진입 시 5단계 온보딩으로 사용자를 유도합니다.

🚀 온보딩 단계

단계	화면명	내용	인터랙션
Step 0	웰컴	마스코트 소개, "혼공댕에 오신 걸 환영해요!"	시작하기 → 버튼
Step 1	로그인	Google OAuth / PIN 로그인 / 건너뛰기 옵션	Google 버튼 · PIN 버튼 · Skip 버튼
Step 2	프로필	이름, 나이, 마스코트 선택 (🐕 왈왈이 / 🐱 냥냥이 / 🦝 쿤이)	input + 마스코트 카드 토글
Step 3	과목 선택	기본 과목 8개 (수학, 영어, 국어, 과학, 독서, 피아노, 숙제, 기타)	선택 가능한 칩 그리드
Step 4	완료	"준비 완료!" 축하 화면 + 마스코트 애니메이션	🐾 공부 시작! 버튼

      프로그레스 인디케이터: 상단에 5개의 점(dot)으로 현재 위치 표시. 진행 시 점이 활성화됩니다.
    

06 계획 탭 Plan Tab

요일별 학습 계획과 과목 카테고리 시스템을 관리합니다.

📅 요일별 학습 계획 (Weekly Schedule)

월~일 7일 그리드에 요일별 기본 과목을 배정합니다. 배정된 과목은 해당 요일의 Day View에 자동으로 Plan Chip으로 표시됩니다.

기능	동작
요일 헤더	월~일 7칸 그리드, 각 칸에 요일명 표시
과목 배정	요일 칸 클릭 → 과목 선택 모달 → 체크박스로 다중 선택
과목 표시	배정된 과목이 칩 형태로 해당 요일 칸에 표시
수정	요일 칸 재클릭으로 과목 추가/제거
연동	`dayPlans` 객체에 `{dayIndex: [subjectName, ...]}` 저장

📂 과목 카테고리 시스템 (Subject Categories)

9개 기본 카테고리, 각 카테고리 안에 세부 과목 포함

카테고리	이모지	포함 과목 (기본)
계획 Planning	📅	자기 주도 계획
국어 Korean	📖	독서, 글쓰기, 문법, 한자, 국어 숙제
수학 Math	🔢	개념, 연산, 심화/경시, 수학 숙제
영어 English	🌎	Reading, Writing, Vocabulary, Listening, Speaking, Grammar, 영어 숙제
과학 Science	🔬	일반과학, 물리, 화학, 생물, 지구과학, 과학 숙제
사회 Social Studies	🌏	역사, 지리, 일반사회, 사회 숙제
예체능 Arts & PE	🎨	음악/피아노, 미술, 체육
시험대비 Test Prep	📝	TOEFL, 수학 경시, 내신
기타 Other	📌	코딩, 독서(교양), 특별

⚡ 카테고리 인터랙션

액션	동작
카테고리 토글	카테고리 카드 헤더 클릭 → 접기/펼치기. 비활성화 시 해당 과목 전체 비활성
과목 토글	카테고리 내 개별 과목 on/off. 활성화된 과목만 Plan/Day View에 표시
과목 추가	카테고리 내 "➕" 버튼 → 과목명 입력 → 해당 카테고리에 추가
새 카테고리 추가	카테고리 리스트 하단 "➕ 카테고리 추가" 버튼 → 이름+이모지 입력

🔧 과목 상세 설정

속성	타입	설명
`name`	string	과목명 (한국어 또는 영문)
`category`	string	상위 카테고리 (Math, English, Korean 등)
`color`	string	hex 컬러 (#6366f1 등)
`trackingType`	'time' \| 'quantity'	시간 기반 or 횟수 기반 추적
`trackTime`	boolean	quantity 타입에서 추가 시간 추적 여부
`points`	number	완료 시 획득 포인트 (기본값: 1)
`active`	boolean	활성화 여부

07 캘린더 (주간 뷰) Calendar / Week View

이번 주와 다음 주 2주를 카드 형식으로 표시합니다.

📆 주간 캘린더

구성 요소	설명
네비게이션	◀▶ 버튼으로 주 이동 + "오늘" 버튼으로 현재 주로 복귀
이번 주 라벨	"← 이번 주" 라벨 표시 (i18n 지원)
요일 카드	7일 × 2주 = 최대 14개 카드. 각 카드에 아이콘, 과목 수, 진행 바, 달성 점수 표시
오늘 강조	현재 날짜의 카드에 인디고 border glow 효과
공휴일 표시	공휴일인 날짜에 🏖️ 아이콘 + 0 target 표시
클릭 이동	카드 클릭 → 해당 날짜의 Day View로 이동

📊 주간 통계 카드

Weekly Rate

85%

이번 주 달성률 (done/target)

Bones Earned

🦴 42

이번 주 적립 포인트

Streak

🔥 7

연속 학습 일수

📈 학습 통계 섹션

차트/위젯	내용
과목별 학습량	수평 바 차트. 과목별 완료 횟수 시각화. 과목 색상 적용
일별 진행률	7일 바 차트. 각 요일의 done/target 비율. 100% 이상은 초록색
연속 학습 (Streak)	현재 스트릭 + 최장 기록. 🔥 아이콘과 함께 마스코트 메시지
이번 달 개요	월간 달성률, 총 학습 횟수, 달성 일수, 최장 연속 기록

08 일별 뷰 Day View

하루의 학습 실행 화면. Plan → Do → Review 사이클의 핵심입니다.

📝 Today's Plan (계획 칩)

요일별 기본 과목이 인터랙티브 칩으로 표시됩니다.

기능	동작
칩 표시	요일 기본 과목이 둥근 칩으로 배열. 과목 이모지 + 이름
칩 클릭	클릭 시 해당 과목의 새 학습 슬롯이 자동 생성
완료 표시	이미 해당 과목 슬롯이 있으면 칩에 체크 표시
수정 모드	"✏️ 수정" 버튼으로 과목 추가/제거 가능
추가 버튼	"➕ 추가" 버튼으로 커스텀 과목 슬롯 생성

⏱️ 학습 슬롯 (Study Slot)

각 과목 학습의 단위. 시간 추적과 교재 진도를 관리합니다.

구성 요소	설명
과목 선택	드롭다운으로 활성 과목 중 선택
타이머	Start → Pause → Resume → End 상태 머신
시작/종료 시간	타이머 start 시 자동 기록. 수동 수정 가능 (5분 단위)
경과 시간	실시간 표시 (hh:mm:ss). pause 구간 자동 제외
교재 연동	과목에 연결된 교재가 있으면 자동 표시. 진도 입력 가능
완료 처리	체크 아이콘 → done=true. 포인트 적립
삭제	🗑️ 아이콘. 완료된 항목은 확인 팝업
메모	슬롯별 메모 입력란

🍅 타이머 사양

기본 시간

45분

포모도로 방식 (TIMER_MINUTES=45)

추적 방식

시간 / 횟수

trackingType에 따라 결정

타이머 상태 머신:

idle

▶ Start →

running

⏸ Pause →

paused

▶ Resume →

running

⏹ End →

ended

        Quantity 기반 슬롯: trackingType이 'quantity'인 과목은 타이머 대신 ✅ 완료 / ↩️ 취소 버튼만 표시.
        trackTime: true이면 횟수 완료 후에도 추가 시간 추적 가능.
      

📝 리뷰 & 부모 승인

기능	설명
일일 회고	텍스트 입력: "오늘 공부는 어땠나요?" 자유 작성
부모 메모	부모 모드에서만 표시. 댓글 형태로 격려 메시지 작성
부모 승인	슬롯별 체크박스로 부모가 완료 항목 승인 (parentApproved 배열)

09 교재 관리 Books Management

알라딘 API 연동 검색, 진도 트래킹, Trophy Shelf 기능

📚 교재 검색 (알라딘 API)

🔍 검색어 입력

→

debounce 300ms

→

Worker 프록시

→

알라딘 API

→

결과 10건

→

원클릭 등록

반환 필드	설명
`title`	교재 제목
`author`	저자
`isbn`	ISBN-13 (또는 ISBN-10)
`cover`	표지 이미지 URL (Big 사이즈)
`publisher`	출판사
`page`	총 페이지 수 (subInfo.itemPage)
`categoryName`	분류명 → 과목 자동 추천에 활용

      과목 자동 추천: 교재 제목과 카테고리의 키워드를 매칭하여 과목 자동 선택.
      예: "수학" 포함 → 수학 카테고리, "TOEFL" → 영어 카테고리 등
    

📷 표지 스캔 (Book Cover Scan)

카메라로 교재 표지를 촬영하면 Claude Vision API가 제목/저자/과목을 추출합니다.

📷 카메라 촬영

→

JPEG base64 변환

→

POST /api/scan-book

→

Claude claude-sonnet-4-20250514

→

{title, author, subject}

📊 교재 진도 관리

기능	설명
프로그레스 바	현재 페이지 / 총 페이지 → 퍼센트 표시
슬롯 연동	Day View 슬롯에서 교재 진도 직접 업데이트
수동 수정	교재 카드에서 현재 페이지 직접 입력
완료 처리	교재 진도 100% 또는 수동 완료 → 축하 이벤트 트리거
교재 수정 모달	교재 클릭 → 교재명, 과목 변경, 페이지 수정 가능
과목별 그룹핑	교재를 과목별로 그룹핑하여 표시
즉시 반영	교재 추가/수정 후 화면에 즉시 반영

🏆 Trophy Shelf (완료 교재 선반)

완료한 교재가 표지 이미지와 함께 진열됩니다.

기능	설명
표지 그리드	완료 교재 표지 이미지를 그리드로 표시
완료 수 뱃지	"📚 N권 완독!" 뱃지 표시
필터	전체 / 과목별 필터링
완료 축하	교재 완료 시 🎉 confetti 애니메이션 + 마스코트 축하 메시지
부모 알림	교재 완료 시 부모에게 알림 발송 + 게임시간 보상 액션

10 게임타임 Game Time System

학습 보상 기반 게임 시간 관리 시스템 — 핵심 동기부여 엔진

🦴 Bone 포인트 시스템

학습 완료 → 게임 시간(분) 적립. 단위: 분(minutes)

트랜잭션 유형	이모지	효과	제한
earn (학습 적립)	📚	+ 잔고	하루 1회. 공휴일 불가. 동결 시 불가.
bonus (부모 보너스)	🎁	+ 잔고	부모 모드에서만. 사유 메모 필수.
penalty (부모 벌칙)	⚠️	- 잔고	최대 500분. 부모 모드에서만.
use (게임 사용)	🎮	- 잔고	60분 예비금 유지. 동결 시 불가.

      60분 예비금 규칙: 잔고에서 항상 60분은 보유합니다. 사용 가능 시간 = max(0, balance - 60).
      잔고가 60분 이하로 떨어지면 텔레그램으로 부모 알림 발송.
    

🎮 게임 타이머

게임 시간을 Start/Pause/End로 실시간 추적

상태	동작
대기 (idle)	잔고 표시 + "🎮 플레이 시작!" 버튼
플레이 중 (playing)	실시간 타이머 카운트업 + Pause/End 버튼
일시정지 (paused)	"💤 낮잠 중..." + Resume/End 버튼
종료 (ended)	사용 시간 계산 → 잔고 차감

      30분 경고: 게임 타이머가 30분에 도달하면 경고 팝업 + 비프음 재생. 이후 10분 간격으로 반복 경고.
    

🔒 시험 동결 (Exam Freeze)

기능	설명
동결 활성화	시험명 + 시험일 입력 → 시험 7일 전부터 자동 동결
동결 효과	earn, use 불가. 기록에 🔒 로그.
치트 데이	동결 중 1일 예외 허용. 기록에 🎉 로그.
동결 해제	부모가 수동 해제. 기록에 🔓 로그.

📜 게임 시간 계약서 (Game Time Agreement v2.0)

부모와 자녀 간의 게임 시간 규칙을 명문화한 계약서

게임타임 탭 내에 계약서 형태로 표시. 적립 규칙, 사용 규칙, 보너스/벌칙 조건, 예비금 규칙 등을 정리.

📋 사용 히스토리

필드	설명
`date`	날짜 (YYYY-MM-DD)
`time`	정확한 시각 (ISO 8601)
`type`	earn / bonus / penalty / use / freeze / unfreeze / cheatday
`emoji`	타입별 이모지 (📚/🎁/⚠️/🎮/🔒/🔓/🎉)
`amount`	변동량 (양수: 적립, 음수: 차감)
`memo`	사유 메모
`balanceAfter`	트랜잭션 후 잔고

      히스토리 보존: 최근 365건 유지. 가장 최근 90건을 API 응답으로 반환.
    

11 알림 시스템 Notification System

7종 알림 이벤트 + 3채널 (인앱/이메일/카카오톡) 부모 알림 시스템

🔔 알림 이벤트 (7종)

이벤트	코드	설명
🎮 게임 시작	`game_start`	자녀가 게임 타이머를 시작할 때
🎮 게임 종료	`game_end`	자녀가 게임 타이머를 종료할 때
📚 학습 시작	`study_start`	자녀가 학습 타이머를 시작할 때
📚 학습 종료	`study_end`	자녀가 학습 타이머를 종료할 때
📖 교재 완료	`book_complete`	교재 진도 100% 달성 시
✅ 일일 달성	`daily_complete`	당일 학습 목표 전체 달성 시
🔥 스트릭 마일스톤	`streak_milestone`	연속 학습 7일, 30일 등 달성 시

📡 알림 채널 (3종)

채널	상태	설명
인앱 알림	동작	헤더 벨 🔔 + 드롭다운 패널. 뱃지 카운트, 읽음/안읽음, 액션 버튼. 최대 50건.
이메일	Coming Soon	부모 이메일로 알림 발송 (향후 구현)
카카오톡	Coming Soon	카카오톡 알림톡 연동 (향후 구현)

⚙️ 알림 설정 (Notification Preferences)

설정 탭에서 알림 종류별 ON/OFF 토글 관리

기능	설명
종류별 토글	7종 알림 이벤트 각각에 대해 인앱/이메일/카카오톡 채널별 ON/OFF
기본값	모든 인앱 알림 ON, 이메일/카카오톡은 OFF
API 저장	`GET/POST /api/notification-prefs`로 설정 조회/저장
KV 키	`f:{fid}:notification-prefs`

📲 텔레그램 알림 (레거시)

트리거	알림 내용
게임 잔고 부족	⚠️ 잔고 60분 이하 알림 (잔고 + 사용 가능 시간)
교재 완료	축하 메시지 + 교재명

      구현: Cloudflare Worker에서 Telegram Bot API로 직접 sendMessage 호출.
      TELEGRAM_BOT_TOKEN 환경변수 + 하드코딩된 chat_id 사용.
    

12 AI 학습 코치 AI Study Coach PLUS

Claude AI가 학습 패턴을 분석하고 개인 맞춤 피드백을 제공합니다. Plus 이상 요금제 전용.

✨ AI 분석 기능

기능	설명
캘린더 탭 분석	"✨ 분석 요청" 버튼 → Claude가 최근 학습 데이터를 분석하여 패턴 인사이트 제공
부모 모드 분석	자녀별 "🤖 AI 분석" 버튼 → 해당 자녀의 학습 패턴 분석
분석 내용	학습 패턴 요약 + 칭찬 포인트 + 개선 추천
페이월	`isPaidPlan()` 체크. 무료 사용자 → 업그레이드 프롬프트 모달

🔧 기술 구현

항목	상세
AI 모델	Anthropic Claude (브라우저에서 직접 API 호출, CF Worker 403 우회)
인증	Worker 인증 토큰 검증 후 API 키 전달
Rate Limit	하루 10회 제한 (가정 단위)
캐싱	분석 결과 1시간 캐시 (동일 요청 시 캐시 반환)
PLUS 뱃지	AI 기능 옆에 PLUS 뱃지 표시

📡 API

POST /api/ai-insight AI 학습 분석 요청 (Plus 전용)

13 주간 리포트 Weekly Report PLUS

7일 학습 데이터를 자동 집계하여 통계 + AI 코멘트를 제공합니다. Plus 이상 요금제 전용.

📊 리포트 구성

항목	설명
접근 경로	부모 모드 캘린더 → "📊 주간 리포트" 버튼
학습일 수	지난 7일 중 학습한 날 수
총 학습 시간	7일 합산 학습 시간
달성률	완료 슬롯 / 목표 슬롯 비율
XP 획득	7일간 획득한 총 XP
과목별 분포	과목별 학습 시간 분포 차트
AI 코멘트	Claude가 자동 생성한 학습 분석 코멘트

📡 API

GET /api/weekly-report 주간 리포트 데이터 조회 (Plus 전용)

14 결제 시스템 Billing (Toss Payments)

Toss Payments 빌링키 방식으로 카드 등록 → 매월 자동결제를 구현합니다.

💳 요금제

Free

₩0

자녀 2명 / 기본 기능

✨ Plus

₩4,900/월

자녀 3명 / AI 코치 + 주간 리포트

👨‍👩‍👧‍👦 Family

₩7,900/월

자녀 5명 / 전체 기능

🔄 결제 플로우

설정 탭 → 요금제 선택

→

Toss 카드 등록

→

빌링키 발급

→

첫 결제

→

매월 자동결제

기능	설명
요금제 카드 UI	설정 탭에 현재 요금제 + 결제 정보 + 업그레이드/취소 카드
자녀 수 제한	Free: 2명 / Plus: 3명 / Family: 5명
페이월	`isPaidPlan()`으로 유료 기능 체크 → 무료 사용자에게 업그레이드 프롬프트 모달
KV 관리	`f:{fid}:plan`에 요금제 저장 (free / plus / family)

📡 결제 API

POST /api/billing/checkout 결제 세션 생성 (빌링키 발급 요청)

POST /api/billing/confirm 결제 확인 (빌링키 저장 + 첫 결제)

POST /api/billing/cancel 구독 취소 (빌링키 삭제, 기간 만료까지 유지)

GET /api/billing/status 결제 상태 조회 (요금제, 다음 결제일, 카드 정보)

POST /api/billing/charge 수동 과금 (자동결제 실패 시 재시도)

15 부모 통합 뷰 Parent Integrated Views

부모 모드에서 드롭다운 없이 모든 자녀의 데이터를 한 화면에서 관리합니다.

👨‍👩‍👧‍👦 통합 뷰 구성

탭	렌더 함수	설명
계획 탭	`renderParentPlanView()`	자녀별 요일 학습 계획을 카드로 스크롤 표시
캘린더 탭	`renderParentWeekView()`	자녀별 주간 달성률, AI 분석 버튼, 주간 리포트 포함
교재 탭	`renderParentBooksViewAllChildren()`	자녀별 진행 중인 교재 + Trophy Shelf 통합 표시

      UX 개선: 기존에는 자녀 드롭다운으로 한 명씩 전환했으나, 이제 모든 자녀 카드를 한 화면에서 스크롤로 확인 가능.
    

🎮 부모 게임시간 관리

부모 모드에서 자녀별 게임시간을 통합 관리합니다.

기능	설명
게임시간 카드	자녀별 카드에 잔액, 사용 가능 시간, 상태(활성/동결) 표시
시간 추가/제거	사유 입력 + 시간 조정. 히스토리 로그에 기록
🔄 반복 버튼	이전과 동일한 사유로 시간 재추가 (원클릭)
게임 동결/해제	confirm 다이얼로그 후 즉시 동결/해제 처리

16 설정 Settings

가정 관리, 과목/교재, 공휴일, 구독, 고객 지원 등의 설정 기능

👨‍👩‍👧 자녀 관리

기능	설명	권한
자녀 추가	이름, 나이, 아바타 (🐶/🐱), PIN (4자리) 설정	부모 전용
자녀 수정	이름, 나이, 아바타, PIN 변경	부모 전용
자녀 삭제	확인 팝업 후 삭제. 관련 세션도 함께 삭제	부모 전용
가정 코드	family_id를 "가정 코드"로 표시. 자녀가 PIN 로그인 시 필요	부모 뷰
PIN 상태	설정됨 🔒 / 미설정 표시	부모 뷰

🏖️ 공휴일 / 방학 관리

기능	설명
공휴일 추가	이름 + 시작일 + 종료일 입력
공휴일 목록	설정된 공휴일 리스트 표시
공휴일 삭제	개별 삭제 (확인 팝업)
학습 목표 영향	공휴일인 날은 target이 9로 설정 (평일 5 vs 주말/공휴일 9)
게임타임 영향	공휴일에는 게임시간 earn 불가

💳 구독 플랜 (Toss Payments 연동)

Free

₩0

자녀 2명 / 기본 기능

✨ Plus

₩4,900/월

자녀 3명 / AI 코치 + 주간 리포트

👨‍👩‍👧‍👦 Family

₩7,900/월

자녀 5명 / 전체 기능

결제 구현 완료: Toss Payments 빌링키 방식. 설정 탭에서 요금제 선택 → 카드 등록 → 매월 자동결제. 자세한 내용은 결제 시스템 섹션 참조.

📧 고객 문의

이메일 폼으로 고객 문의 발송. 로그인한 이메일로 답변 수신. mailto: 링크 기반.

☁️ 클라우드 저장 / 초기화

기능	설명
클라우드 저장	Settings(과목, 교재, 요일계획)를 Worker KV에 저장
클라우드 로드	KV에서 설정 로드 → localStorage에 병합
초기화	모든 과목, 교재, 요일 계획을 기본값으로 리셋

17 데이터 모델 Data Model

Cloudflare D1 (관계형) + KV (키-값) 하이브리드 구조

🗄️ D1 테이블 (SQLite)

-- families (가정)
CREATE TABLE families (
  id       TEXT PRIMARY KEY,
  name     TEXT NOT NULL,
  created_at TEXT DEFAULT (datetime('now')),
  plan     TEXT DEFAULT 'free',
  locale   TEXT DEFAULT 'ko'
);

-- parents (부모)
CREATE TABLE parents (
  id        TEXT PRIMARY KEY,
  family_id TEXT NOT NULL REFERENCES families(id),
  email     TEXT UNIQUE NOT NULL,
  name      TEXT NOT NULL,
  google_id TEXT UNIQUE,
  avatar_url TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

-- children (자녀)
CREATE TABLE children (
  id        TEXT PRIMARY KEY,
  family_id TEXT NOT NULL REFERENCES families(id),
  name      TEXT NOT NULL,
  age       INTEGER,
  pin       TEXT,  -- SHA-256 해시
  avatar    TEXT DEFAULT 'puppy',
  created_at TEXT DEFAULT (datetime('now'))
);

-- sessions (로그인 세션)
CREATE TABLE sessions (
  token      TEXT PRIMARY KEY,  -- 64-char hex (32 bytes)
  user_type  TEXT NOT NULL,     -- 'parent' | 'child'
  user_id    TEXT NOT NULL,
  family_id  TEXT NOT NULL,
  expires_at TEXT NOT NULL,
  created_at TEXT DEFAULT (datetime('now'))
);
    

📦 KV 키 구조 (Cloudflare Workers KV)

모든 키는 f:{familyId}:c:{childId}: 프리픽스로 스코핑

키 패턴	값 타입	설명
`day:{YYYY-MM-DD}`	JSON	일일 데이터 (slots, review, parentNote, parentApproved, checkedPlan)
`settings:subjects`	JSON	과목 목록, 교재 목록, 요일 계획, 완료 교재
`settings:holidays`	JSON[]	공휴일 배열 [{name, startDate, endDate}]
`gametime:balance`	number	게임 시간 잔고 (분)
`gametime:log`	JSON[]	게임 시간 히스토리 (최대 365건)
`gametime:freeze`	JSON	{frozen, examName, examDate, freezeStart, cheatDay}
`gametime:earned:{YYYY-MM-DD}`	boolean	오늘 이미 적립했는지 여부
`notifications`	JSON[]	인앱 알림 (최대 50건)
`notification-prefs`	JSON	알림 설정 (이벤트별 채널 ON/OFF)
`rl:{IP}`	JSON	Rate limit 카운터 ({window, count})

📦 KV 키 구조 — 가정 레벨 (f:{familyId}: 프리픽스)

자녀 독립 데이터는 아래 키에 저장

키 패턴	값 타입	설명
`f:{fid}:plan`	string	요금제 (free / plus / family)
`f:{fid}:billing`	JSON	결제 정보 (billingKey, cardInfo, nextPaymentDate 등)
`f:{fid}:notification-prefs`	JSON	부모 알림 설정 (이벤트별 채널 토글)

📅 일일 데이터 구조 (Day)

{
  "date": "2026-02-16",
  "slots": [
    {
      "subject": "AoPS",
      "done": true,
      "start": "2026-02-16T09:00:00.000Z",
      "end": "2026-02-16T09:45:00.000Z",
      "pauses": [],   // [{pause: ISO, resume: ISO}]
      "note": "Chapter 3 완료",
      "textbook": { "id": "t1", "currentPage": 42, "totalPage": 180 }
    }
  ],
  "review": "오늘 수학이 좀 어려웠다",
  "parentNote": "잘했어! 계속 화이팅 🐶",
  "parentApproved": [0, 1],  // 승인된 슬롯 인덱스
  "checkedPlan": ["AoPS", "AMC"]  // 플랜 칩 상태
}
    

18 API 스펙 API Specification

Cloudflare Worker 기반 REST API. Base URL: https://hongongdang-api.hwang-d5c.workers.dev

🔐 인증 엔드포인트

GET /auth/google Google OAuth 시작 (리디렉트)

GET /auth/callback Google OAuth 콜백 → 세션 생성

POST /auth/pin 자녀 PIN 로그인

GET /auth/me 현재 사용자 정보

POST /auth/logout 로그아웃 (세션 삭제)

👨‍👩‍👧 가정/자녀 엔드포인트

GET /family 가정 정보 + 자녀 목록

GET /family/children?family_id= PIN 로그인용 자녀 목록

POST /family/children 자녀 추가 (부모 전용)

PUT /family/children/:id 자녀 수정 (부모 전용)

DELETE /family/children/:id 자녀 삭제 (부모 전용)

📖 학습 데이터 엔드포인트

GET /api/day?date=YYYY-MM-DD 일일 데이터 조회

POST /api/day 일일 데이터 저장 (병합)

GET /api/week?start=YYYY-MM-DD 7일 데이터 일괄 조회

GET /api/month?year=YYYY&month=M 월간 데이터 + 요약 통계

GET /api/stats?month=YYYY-MM 월간 통계 (과목별, 달성률, 스트릭)

⚙️ 설정 엔드포인트

GET /api/settings 과목/교재/요일계획 설정 조회

POST /api/settings 설정 저장

GET /api/settings/holidays 공휴일 목록

POST /api/settings/holidays 공휴일 저장 (전체 교체)

🎮 게임타임 엔드포인트

GET /api/gametime 잔고, 히스토리, 동결 상태, 오늘 적립 여부

POST /api/gametime 트랜잭션 (earn/bonus/penalty/use)

GET /api/gametime/freeze 동결 상태 조회

POST /api/gametime/freeze 동결/해제/치트데이

📚 교재 엔드포인트

GET /books/search?q= 알라딘 교재 검색 (프록시)

POST /api/scan-book 표지 스캔 (Claude Vision)

🔔 알림 엔드포인트

GET /api/notifications 알림 목록 조회

POST /api/notifications 알림 추가 (7종 이벤트)

GET /api/notification-prefs 알림 설정 조회

POST /api/notification-prefs 알림 설정 저장

🤖 AI / 리포트 엔드포인트 PLUS

POST /api/ai-insight AI 학습 분석 (하루 10회, 1시간 캐시)

GET /api/weekly-report 주간 리포트 (7일 통계 + AI 코멘트)

💳 결제 엔드포인트

POST /api/billing/checkout 결제 세션 생성

POST /api/billing/confirm 결제 확인 (빌링키 저장)

POST /api/billing/cancel 구독 취소

GET /api/billing/status 결제 상태 조회

POST /api/billing/charge 수동 과금 (재시도)

📡 공통 사양

항목	값
인증	`Authorization: Bearer {token}` 또는 `session` 쿠키
Content-Type	`application/json`
CORS	hongongdang.com, *.pages.dev, localhost 허용
Rate Limit	IP당 120req/min (일반), 5req/min (PIN)
캐싱	week/month 조회: `Cache-Control: public, max-age=30`
에러 형식	`{"error": "message", "code": 4xx}`
child_id 스코핑	`?child_id=` 쿼리 파라미터로 자녀별 데이터 분리

19 보안 Security

인증, 데이터 보호, 입력 검증, 요율 제한 등 보안 조치

🛡️ 보안 계층

계층	조치	구현
인증	세션 토큰 (32바이트 랜덤 hex)	`crypto.getRandomValues()` + D1 세션 테이블
PIN 해싱	SHA-256 단방향 해시	`crypto.subtle.digest('SHA-256', pin)`
Rate Limiting	IP 기반 요율 제한	KV 카운터 방식 (120/min 일반, 5/min PIN)
입력 검증	XSS 방지 문자열 정제	`sanitizeString()`: <>"'& 이스케이프, 1000자 제한
날짜 검증	정규식 패턴 검증	`/^\d{4}-\d{2}-\d{2}$/`, `/^\d{4}-\d{2}$/`
CORS	화이트리스트 + 패턴 매칭	프로덕션 도메인 + localhost/pages.dev 패턴
보안 헤더	8개 보안 HTTP 헤더	X-Content-Type-Options, X-Frame-Options, CSP, X-XSS-Protection, Referrer-Policy
쿠키	HttpOnly + Secure + SameSite	`SameSite=Lax; HttpOnly; Secure; Path=/`
데이터 격리	family_id + child_id 스코핑	KV 키 프리픽스 `f:{fid}:c:{cid}:`

20 기술 스택 Tech Stack

레이어	기술	비고
Frontend	Vanilla HTML/CSS/JS	단일 SPA 파일 (app.html, ~8,500줄). 프레임워크 없음.
Backend	Cloudflare Worker	index.js (~1,150줄). REST API 서버.
DB (관계형)	Cloudflare D1 (SQLite)	families, parents, children, sessions 4개 테이블
DB (키-값)	Cloudflare Workers KV	일일 데이터, 설정, 게임타임, 알림 등
Auth	Google OAuth 2.0 + PIN	부모: OAuth → 세션 토큰, 자녀: PIN → 세션 토큰
교재 API	알라딘 Open API	도서 검색, 표지 이미지, 페이지 정보
AI	Anthropic Claude claude-sonnet-4-20250514	표지 스캔 (Vision), AI 학습 코치, 주간 리포트 코멘트
결제	Toss Payments	빌링키 자동결제 (카드 등록 → 매월 과금)
알림	Telegram Bot API	부모 실시간 알림
Hosting	Cloudflare Pages	정적 파일 호스팅 + CDN
Domain	hongongdang.com	Cloudflare DNS 관리
PWA	manifest.json + sw.js	오프라인 지원, 홈 화면 설치
Font	Inter + Noto Sans KR	Google Fonts CDN

21 글로벌 기능 Global Features

📱 PWA (Progressive Web App)

기능	설명
manifest.json	name: "혼공댕", display: standalone, theme_color: #6366f1
서비스 워커	sw.js — 오프라인 캐싱 (Cache First 전략)
홈 화면 설치	iOS Safari / Android Chrome "홈 화면에 추가"
오프라인	캐시된 정적 파일로 오프라인 앱 동작
아이콘	SVG 기반 🐕 이모지 아이콘 (maskable 포함)

🌐 i18n (국제화)

기능	설명
지원 언어	🇰🇷 한국어 (ko) · 🇬🇧 영어 (en)
번역 키	160+ 키 (온보딩, 탭, 모달, 알림, 에러 메시지 등)
전환 방식	헤더의 🇰🇷/🇬🇧 플래그 버튼 토글
적용 범위	`data-i18n` 속성 기반 DOM 업데이트 + 동적 `t(key)` 함수
저장	localStorage에 lang 저장

🎨 테마 시스템

기능	설명
다크 모드 (기본)	배경 #0a0a0b, ambient glow, glassmorphism
라이트 모드	배경 #f8fafc, 부드러운 그림자
전환	헤더 🌙/☀️ 토글 버튼
구현	`[data-theme]` CSS 커스텀 속성 전환 (40+ 변수)
저장	localStorage에 theme 저장

🐾 마스코트 시스템

🐶

코기 왈왈이

Welsh Corgi — 기본 마스코트

🐱

턱시도 냥냥이

Tuxedo Cat — 대체 마스코트

온보딩에서 선택. 헤더 BI, 통계 메시지, 빈 상태 메시지 등에서 마스코트별 맞춤 텍스트 표시. 이미지는 /mascots/ 폴더에 PNG로 저장 + 헤더 BI에 /images/puppy.png, /images/kitty.png 사용.

22-A 🎓 학년 시스템 Grade System

출생연도 기반 자동 학년 계산 + 4개국 학제 지원 (v0.9.0)

학년 계산 로직

국가	체계	계산 기준
🇰🇷 한국 (KR)	초1~고3 (1~12)	올해 - 출생연도 - 5 (3월 기준)
🇬🇧 영국 (UK)	Year 1~13	올해 - 출생연도 - 4 (9월 기준)
🇺🇸 미국 (US)	K~12	올해 - 출생연도 - 5 (9월 기준)
🇯🇵 일본 (JP)	小1~高3	올해 - 출생연도 - 5 (4월 기준)

      auto 모드: 브라우저 locale 또는 앱 언어 설정에 따라 자동 선택. 수동 오버라이드 가능.
    

학년별 일일 목표 추천

학년	평일	토요일
1~2학년	2교시	1교시
3학년	3교시	2교시
4학년	4교시	3교시
5~6학년	5교시	3~4교시
중학생 (7~9)	6~8교시	4~5교시
고등학생 (10~12)	8~10교시	6~7교시

22-B 📖 교재 DB + AI 학년 추정 Textbook Database

교재 정보를 D1에 저장하고, AI로 학년 수준을 분석합니다. (v0.9.0)

D1 textbooks 테이블

컬럼	타입	설명
`id`	TEXT PK	UUID
`family_id`	TEXT	가정 ID
`child_id`	TEXT	자녀 ID
`name`	TEXT	교재명
`estimated_grade`	INTEGER	규칙 기반 학년 추정
`ai_grade`	INTEGER	AI 분석 학년
`ai_confidence`	REAL	AI 신뢰도 (0~1)
`ai_reasoning`	TEXT	AI 판단 근거

API 엔드포인트

POST /api/textbooks/sync 앱 → D1 교재 동기화

GET /api/textbooks/pending-ai AI 분석 대기 교재 (admin)

POST /api/textbooks/ai-update AI 분석 결과 저장 (admin)

GET /api/textbooks/grades 자녀별 교재 학년 정보

학년 추정 흐름

📚 교재 추가 → 📏 규칙 기반 추정 → ☁️ D1 sync → 🤖 주간 AI 크론잡 → ✅ ai_grade 업데이트

22-C 💡 코치 한 마디 Coach Tips

앱 10곳에 자기주도학습 이론 기반 팁을 배치하여 부모 교육 효과를 높입니다. (v0.9.0)

배치 위치 (10곳)

#	위치	이론	핵심 메시지
1	캘린더 상단	자기주도학습 4단계	계획→실행→평가→보상 순환
2	일일 뷰 슬롯	포모도로 + 의도적 연습	45분 집중의 과학
3	게임시간 상단	행동주의 강화 스케줄	변동비율 강화의 원리
4	교재 탭	인지부하 이론	적절한 난이도가 몰입을 만든다
5	부모 뷰	자기결정이론 (SDT)	자율성 지지가 핵심
6	주간 리포트	성장 마인드셋	과정 칭찬 vs 결과 칭찬
7	계획 탭	메타인지	계획 세우기 자체가 학습
8	계약서	자율성 (Autonomy)	규칙 설정 참여 = 소유감
9	알림 설정	비계 설정 (Scaffolding)	적절한 관심은 자율성을 해치지 않음
10	과목 설정	유능감 (Competence)	과목 선택이 자기주도학습의 시작

      각 팁은 접기/펼치기 가능하며, ✕ 버튼으로 개별 숨김 처리 가능. 설정에서 전체 ON/OFF + 숨긴 팁 복원 가능.
    

22-D 🎯 일일 목표 시스템 Daily Targets

학년별 기본 목표 + 계약서 연동 + 캘린더 달성률 표시 (v0.9.0)

목표 결정 우선순위

1️⃣ 계약서 dailyTargets → 2️⃣ 학년별 기본값 → 3️⃣ 4학년 기본값 (fallback)

      계약서 연동: 부모가 계약서의 dailyTargets (평일/토/일/요일별 오버라이드) 설정 시, 해당 값이 최우선 적용됩니다.
    

캘린더 달성률 표시

월간 캘린더와 주간 뷰에서 각 날짜별 목표 대비 달성률을 시각적으로 표시합니다.

달성률	표시	CSS class
100%+	🟢 초록 배경	`.cal-cell.full`
50~99%	🟡 노란 배경	`.cal-cell.half`
1~49%	🔴 빨간 배경	`.cal-cell.low`
0%	기본 배경	-

23 제품 로드맵 Product Roadmap

구현 완료 기능과 향후 계획을 정리합니다.

✅ 구현 완료 현재 배포된 기능

✅ Google OAuth 로그인

✅ PIN 자녀 로그인

✅ 멀티테넌트 (가정/자녀)

✅ 주간 캘린더 뷰

✅ 일별 학습 슬롯

✅ 45분 포모도로 타이머

✅ 과목 카테고리 시스템

✅ 교재 검색 (알라딘 API)

✅ 교재 진도 트래킹

✅ Trophy Shelf

✅ 표지 스캔 (Claude Vision)

✅ 게임타임 (Bone 포인트)

✅ 게임 타이머

✅ 시험 동결/치트데이

✅ 인앱 알림 시스템

✅ 텔레그램 부모 알림

✅ 한/영 i18n (160+ 키)

✅ 다크/라이트 테마

✅ PWA + 오프라인

✅ 5단계 온보딩

✅ 부모 승인/메모

✅ 학습 통계 (4종 차트)

✅ 공휴일/방학 관리

✅ 계정 전환 드롭다운

✅ 부모 게임시간 관리 (추가/제거/반복/동결)

✅ 부모 알림 시스템 (7종 이벤트)

✅ AI 학습 코치 (Claude 분석)

✅ 주간 리포트 (통계 + AI 코멘트)

✅ 교재 수정 모달 + 과목별 그룹핑

✅ Toss Payments 결제 연동

✅ 유료 기능 페이월 (isPaidPlan)

✅ 부모 통합 뷰 (모든 자녀 카드)

✅ 알림 설정 (종류별 ON/OFF 토글)

✅ 학년 시스템 (출생연도 기반, 4개국)

✅ 교재 DB (D1 + AI 학년 추정)

✅ 코치 한 마디 (10곳 학습이론 팁)

✅ 일일 목표 시스템 (학년별 추천)

✅ 캘린더 목표 달성률 표시

🔮 향후 계획 로드맵

우선순위	기능	설명
P1	XP/레벨 시스템	학습 XP 획득 → 레벨업 애니메이션
P1	뱃지/업적	"7일 연속!", "100시간 돌파!" 등 20+ 업적
P1	이용약관 + 개인정보처리방침	아동 개인정보 관련 법적 문서
P2	캐릭터 커스터마이징	마스코트 옷/악세사리 아이템
P2	가족 리더보드	형제 간 선의의 경쟁
P2	카카오톡 알림	알림톡 연동 (한국 학부모 도달률)
P2	이메일 알림	부모 이메일로 알림 발송
P3	월간 리포트 자동 발송	부모 이메일로 월간 학습 요약 리포트
P3	챕터별 진도 추적	교재 내 챕터 구성 + 챕터 단위 추적
P3	Stripe 해외 결제	글로벌 유저 대상 결제 연동

기능	설명
자동 등록	월~금 비휴일에 학교 슬롯 자동 생성 (맨 위)
특별 스타일	에메랄드 그린(#059669), 왼쪽 보더, 배경 그라데이션
최상단 정렬	슬롯 + 요일별 칩 모두 학교가 항상 맨 위
마이그레이션	기존 유저: 과목 자동 추가 + 평일 dayPlans 삽입
점수	completion 타입, 2점

기능	설명
이름 마스킹	가족 코드 자녀 목록에서 중간 글자 마스킹 (황재하→황하, John→J*n)
마스킹 규칙	1자: X, 2자: X, 3자+: 첫/끝 보존, 중간 *

혼공댕 상세 기획서

22-E 학교 과목 시스템 (v0.9.1)

개요

구현

22-F 자녀 계정 관리 (v0.9.1)

자녀 내 계정 카드

개인정보 보호

아바타 변경 API

항목	설명
마스코트 선택	🐶 왈왈이 / 🐱 냥냥이 / 🦝 쿤이 — 즉시 반영 + DB 저장
가족 코드	읽기 전용 표시 (API: GET /auth/family-code/status)
PIN 변경	4자리 숫자 변경 (API: POST /auth/pin/change)