KOK
준비는 AI가, 외우기는 내가.
공부 자료(PDF·사진·직접 쓴 글)를 넣으면 AI가 정리 노트·마인드맵·핵심 문제·복습 일정을 만들고, 학생은 하루 5분씩 풀기만 하는 공부 웹앱이에요. 이 저장소는 v0.1 (혼자 공부 완성) 이에요.
이름은 KOK이에요(화면 글과 문장 속 이름 모두). 앱 아이콘은 인디고 그라데이션 위의 흰 K와 라임 점이고, 화면 속 로고는 src/components/Brand.tsx, 아이콘 파일은 node tools/icons/build.mjs 로 만들어요(색을 바꾸면 둘 다 고쳐요).
들어 있는 기능 (v0.1)
- 구글 로그인(카카오·Apple 로그인은 설정 후 켜기), 약관 동의, 닉네임, 과목·단원
- 자료 넣기: 어느 화면에서나 오른쪽 아래 + 버튼 → 입력창에 적고 엔터(Shift+엔터는 줄바꿈)면 바로 AI 정리. PDF·사진·글 파일은 화면 아무 데나 끌어다 놓거나 붙여 넣으면 검사하고 알아서 정리(PDF는 하나씩, 사진은 묶어서 한 자료, 한글·워드는 PDF로 저장하라고 안내). PDF는 15쪽씩(무거운 PDF는 AI에 보낼 수 있는 크기로 더 잘게) 나눠 처리, 파일 한 개 무료 10MB·Pro 200MB(관리자 화면에서 바꿈), 사진은 올리기 전 긴 변 2000px로 줄임
- 자료함: 노트 앱처럼 과목(폴더) 칩 + 노트 카드 격자, 큰 제목이 스크롤하면 위 띠로 작아짐, 정리 중인 카드는 진행 고리, 멈춘 카드는 바로 다시 하기
- 과목 서랍: 과목이 많아도 칩 줄에는 고정한 과목과 최근 쓴 과목만(다섯 개까지, 자리는 바뀌지 않게) 보이고, 나머지는 '모든 과목'에서 찾아요(이름이나 첫 자음 'ㄱㅎ'). 과목의 ⋯ 를 누르면 서랍 안에서 '과목 관리'가 열려요: 위에 고정, 다 끝난 과목은 보관(목록에서만 빠지고 복습은 그대로, 자료를 넣으면 다시 꺼내져요), 이름·색·시험 날 바꾸기, 다른 과목과 합치기, 지우기 — 할 일마다 한 줄 설명이 붙어요. 과목을 꾹 누르면 여러 과목을 골라 한꺼번에 고정·보관·지우기를 해요. 지울 때는 늘 확인 화면이 지울 과목과 자료 수를 보여 주고, '대신 보관하기'도 권해요. 고정한 과목의 차례는 '순서 바꾸기' 스위치를 켠 뒤 꾹 눌러 끌어서(마우스는 끌기, 키보드는 스페이스와 화살표) 바꾸거나, 과목 관리의 앞으로·뒤로로 정해요. 복습 고르기·자료 넣기 입력창도 같은 차례
- 자료함 정리: 카드 오른쪽 위 별 버튼을 누르면 별이 튀어 오르고, 별표 빛이 번진 뒤 맨 위로 미끄러져 올라가요(메뉴로도 별표·복습에서 빼기). 카드를 꾹 누르면(또는 메뉴의 '여러 개 고르기') 노트 앱처럼 여러 개를 골라 아래 띠에서 한꺼번에 별표·복습 켜고 끄기·다른 과목으로 옮기기·합치기·지우기(모두 고르기, Esc, 키보드 스페이스). 과목 안에서는 '순서 바꾸기'로 꾹 눌러 끌어 순서를 정해요(단원마다, 별표한 자료는 늘 위)
- 자료 그림: PDF·사진 속 중요한 그림(지도·그래프·표·연표·도식·유물 사진·작품·사료·삽화)을 정리할 때 같이 찾아, 원본에서 잘라 관련 개념 카드에 붙이고(개념이 없으면 '자료 그림'), 그림을 보고 푸는 그림 문제를 만들어요(문제에서는 제목·설명을 숨겨 답을 알려 주지 않고, 풀고 나면 보여 줌). 비스듬히 찍은 사진은 반듯하게 펴서 잘라요. Pro는 지도·그래프·표·연표·도식을 KOK 스타일로 다시 그려 주고(지도는 실제 해안선 밑그림 위에: Natural Earth, 퍼블릭 도메인), 그림마다 '다시 그린 그림 / 원본'을 바꿔 볼 수 있어요. 설정에서 '원본으로 먼저 보기', '자료의 그림으로 문제 만들기'를 고를 수 있어요. 사진·작품은 다시 그리면 모양이 틀어질 수 있어 늘 원본이에요
- 노트 옮기기·합치기: 노트를 다른 과목으로 옮기면(카드 메뉴·노트 메뉴·여러 개 고르기, 새 과목을 만들며 옮길 수도) 문제·복습 기록도 같이 가요. 노트 여러 개를 고르고 '합치기'를 누르면 AI 없이(번개 0) 남길 노트 하나에 이어 붙여요(개념·용어·공식·문제·푼 기록이 모이고 원본은 원본 탭에 남아요). 합친 노트에서 Pro는 'AI로 다시 정리'로 겹치는 개념을 하나로 다듬어요(정리 전 노트는 버전 기록에 남고, 그 버전으로 돌아가면 문제도 그때의 개념을 다시 가리켜요). 버전이 있는 노트에 합치면 '노트 합치기' 버전이 새로 생겨서, 다른 버전을 바꾸거나 지워도 합친 자료가 엉키지 않아요. 지금 쓰는 버전에 없는 자료가 있는 노트·더하지 못한 자료가 있는 노트는 자료를 잃지 않게 합쳐지는 쪽으로 고를 수 없어요(합치기 화면이 미리 알려 주고, 그 노트를 남길 노트로 고르면 돼요). 과목끼리도 합칠 수 있어요
- 완료 알림: '지웠어요'·'옮겼어요' 같은 끝났다는 알림은 설정 > 알림에서 끌 수 있어요(오류·꼭 알아야 할 안내는 그대로 떠요)
- 노트마다 복습에 나올지: 자료를 넣을 때 입력창 위쪽 과목 옆의 '복습 켬·끔'으로 끄거나, 나중에 자료함·노트 메뉴에서 바꿔요. 끈 노트의 문제는 오늘 복습·기간 복습·오답 복습·홈 숫자에서 빠지고(오답노트는 몇 개 뺐는지 알려 줌), 노트의 '이 노트 문제 풀기'와 약점 개념 풀기는 그대로 돼요. 복습 기록은 지우지 않아서 다시 켜면 이어서 나와요
- AI 정리 노트: 한 줄 요약, 핵심 개념(중요도·시험 포인트·출처 쪽), 용어, 공식(KaTeX), 함정, 예시, 내가 쓴 글이면 "확인해 보세요"와 바뀐 점
- 노트 고치기: 요약·개념(이름·중요도·설명·시험 포인트·함정·예시)·공식·용어를 모두 고치고 더하고 지우기. 글 칸마다 쉬운 꾸미기 버튼(굵게, ==형광펜==, !!빨간 글씨!!, 목록, 번호, 수식
$x^2$)과 미리보기·꾸미는 법, 기호를 직접 적어도 똑같이 보여요. 공식은 기호 버튼(분수·거듭제곱·루트·화살표 …)과 미리보기
- 별표: 누르면 별이 튀어 오르며 빛나고, 별표한 개념은 맨 위로 미끄러져 올라가요(별표끼리·나머지끼리는 내가 정한 순서). 별표한 개념·자료 카드는 별표 빛(별 쪽에서 번지는 두 색 그라데이션 + 테두리 빛 + 카드 밖 빛)으로 물들어요. 기본은 골드이고, Pro는 테마에서 색 6가지(골드·선셋·오로라·오션·베리·테마 색)와 세기(0~100)를 골라요. 카드 안 빛은 글자가 잘 읽히는 만큼만 진해져요(명암비를 지키게 스스로 줄임) 개념·공식·용어는 '순서 바꾸기'에서 꾹 눌러 끌어 순서를 바꿔요(키보드·화면 읽기 프로그램도)
- 빈 노트: + 버튼 입력창의 '빈 노트'로 AI 없이(에너지 0) 직접 채우는 노트를 만들어요. 이름은 노트 메뉴의 '이름 바꾸기'
- 그림: 마인드맵은 두 가지 보기 — 카드(폰 기본: 가운데 주제 둘레에 가지를 놓은 한눈 지도 + 가지마다 카드, 가지마다 외우기 한 줄(전구 아이콘)과 기억 상태 '헷갈려요·복습할 때·잘 기억해요')와 지도(넓은 화면 기본: 리본처럼 굵어지는 가지, 퍼지기·오른쪽으로·아래로, 고치기, 끌어서 옮기기, 가리기 모드, PNG 저장). 가지를 누르면 '가지 자세히'(노트 설명·시험 포인트·예·헷갈리는 점·이 개념 문제 풀기·정리에서 보기, 이전·다음 가지). 고른 보기는 기기에 기억. 표는 폰에서 카드로, 연표는 번호 레일로 — 다시 그리기는 미리보기 후 적용, 내가 고친 가지는 잠김
- 핵심 문제: 객관식·OX·빈칸·단답·서술형, AI 자기 검사, 직접 만들기·고치기·잠그기·쉬게 하기. 문제는 실제 시험지처럼 보여요: 자료(지문·실험·조건)는 상자에, 묻는 문장은 굵게, <보기>는 이름 붙은 상자, 객관식 보기는 ①②. 과목마다 모양이 달라요(국어·영어 지문, 수학 조건·풀이, 과학 실험 과정·결과, 사회 사료, 코딩 코드). 예전 문제도 글자는 그대로 두고 나눠서 그려요. '문제 신고'(깃발)로 무엇이 이상한지 운영자에게 보내요(링크·개인정보·욕설·알아볼 수 없는 글은 보내기 전에 막고, 보내면 고맙다는 알림). 꾹 눌러 여러 개 고른 뒤에는 아래 띠 맨 앞의 '선택 해제'로 바로 끝내요
- 그림 풀이 (Pro): 노트를 만들 때 그림이 도움이 되는 문제(도형·그래프·과정·구조, 모든 과목)에 문제 그림과 그림으로 보는 단계별 풀이를 붙여요. AI는 그림 대신 '설계도'(점·선·원·각·그래프·상자·화살표를 좌표로 적은 JSON)를 주고 화면이 정확하게 그려요. 문제 그림에는 답을 알려 주는 선이 없고, 풀이에서 한 단계씩 넘기면 선이 더해지고 지금 단계 부분이 형광펜으로 칠해져요(다음·이전, 좌우 화살표 키, 옆으로 밀기, 모든 단계). 틀리면 풀이가 펼쳐진 채로 나와요. 예전 문제·직접 만든 문제는 문제 탭에서 '그림 풀이 만들기'. 정답·보기를 고치면 예전 풀이는 지워요. 설정 > 문제에서 끌 수 있어요. 무료는 그림 없이 글 단계만(채팅)
- 노트 채팅: 노트 화면의 주황 버튼을 누르면 그 노트에 대해 묻는 창이 열려요. 노트를 바탕으로 답하고(노트 밖 설명은 표시), 답마다 에너지, 모델 고르기(마지막 선택 기억), 노트마다 대화 저장. "문제로/노트에/용어로 넣어 줘" 하면 미리보기를 보여 주고 [넣기]를 눌러야 들어가요(설정 > AI 채팅에서 켜고 끄기. 용어는 새 것은 뒤에 붙고 이미 있는 것은 뜻만 바뀌어요). 사진·PDF·글 파일 붙이기와 사진 찍기(📎·📷, 창에 끌어다 놓기·붙여 넣기, 한 번에 4개): 문제 사진을 보내면 읽은 문제와 단계별 풀이(Pro는 그림으로)를 보여 주고 '이 노트 문제로 넣기'로 노트 문제가 돼요. 사진에 문제가 여럿이면 문제마다, 꼬리 문제((1)(2)(3))도 하나씩 풀이를 따로 만들어(한 번에 5개까지) 번호 탭으로 하나씩 보고, 하나씩 또는 'N문제 모두 이 노트에 넣기'로 넣어요. Pro는 보낸 파일을 대화와 함께 보관하고(대화를 지우면 같이 지움), 무료는 이름만 남아요
- AI에게 물어보기: 홈 위쪽 줄을 누르면 자료 넣기처럼 채팅 창이 떠요. 모든 과목을 묻고, 사진·파일·사진 찍기로 문제를 보내면 단계별로 풀어 줘요(Pro는 그림으로 보는 단계, 무료는 글 단계). 단계는 과목마다 차례가 달라요(수학: 주어진 것 → 식 세우기 → 계산 → 검산, 과학: 개념 → 자료 해석 → 결론, 국어: 지문 근거 → 선지 판단, 영어: 해석 → 근거·문법, 사회·역사: 사료 단서 → 시대·개념, 코딩: 코드 따라가기). 사진에 문제가 여럿이면 문제마다·꼬리 문제마다 풀이가 하나씩 오고 'N문제 모두 노트에 넣기'로 한 번에 넣어요. 모델 고르기, 대화는 저장하지 않아서 홈을 떠나면 사라져요. 푼 문제는 '노트에 넣기'로 과목(없으면 새 과목)·단원(새 단원)·노트(새 노트)를 골라 노트 문제로 넣어요(AI가 과목·단원을 짐작해 미리 골라 둠, 복습 카드도 같이). 답 글·마지막 풀이 단계·넣을 문제의 정답이 서로 다른 답을 말하면 끝까지 푼 단계를 믿고 맞추고(객관식), 정할 수 없으면 넣을 문제를 빼고 한 번 더 확인해 보라고 알려요
- 레슨 (Pro): 노트의 '레슨' 탭에서 수준(초등·중등·고등·대학·전문)을 고르면 AI가 노트와 원본 자료로 단계 → 레슨(카드 몇 장 + 확인 문제) → 단계 복습 → 총정리의 길을 만들어요. 레슨은 차례대로 하나씩 열리지만, 뒤 칸을 눌러 '건너뛰고 시작'할 수도 있어요(한 번 물어봐요). 끝낸 레슨은 별 1~3개, 언제든 다시. 수준을 바꿔 다시 만들면 진도는 처음부터
- PDF 요약 정리: 그림 탭 아래에서 AI 없이(에너지 0) 노트를 어두운 모눈종이 / 밝은 종이 PDF로 만들어요(제목·구역·개념·정의·공식·마인드맵 줄기·자료 그림·확인 네모). 노트마다 30개까지 두고 이름 바꾸기·지우기, 앱 안에서 보기, 내려받기
- 노트에 자료 더하기와 버전 (Pro): 원본 탭에서 글·파일을 더하거나 노트 화면에 끌어다 놓기·붙여 넣기(먼저 물어봄). AI가 지금 노트와 합쳐 새 버전을 만들고, 기존 문제·복습 기록은 그대로 두고 새 내용으로만 문제를 더해요. 버전 기록(1. 처음 자료, 2. 더한 자료 …)에서 열기·고치기, 이 버전 쓰기, 지우기(지운 번호는 다시 쓰지 않음). 복습은 지금 버전의 문제만(쉬게 한 문제는 버전을 오가도 쉬는 그대로). 더하는 동안에는 정리·그림을 고칠 수 없고, 실패한 자료를 나중에 다시 하면 그때의 노트에 다시 합쳐요. 다른 탭·기기에서 먼저 바뀐 노트는 덮어쓰지 않아요. 예전 노트는 그대로 버전 1
- 복습: FSRS(ts-fsrs) 간격 반복, 자동 채점(맞음·틀림과 걸린 시간으로 다음 복습 날짜를 정해요: 쉬움·어려움을 고르지 않아요), 단답형 AI 채점. 푸는 화면은 답을 고르고 '확인' → 화면 아래에 붙은 채점 띠(정답·해설, '계속')로 짧게, 해설이 길면 띠 안에서만 넘기고 '계속'은 늘 보여요. 섞어 풀기, 오답노트(3번 연속 맞히면 졸업, 카드나 약점 개념 카드를 꾹 눌러 여러 개를 한꺼번에 '다 외웠어요'로 빼기)와 약점 개념. 홈의 '5분 KOK 시작'은 고르는 화면 없이 복습할 차례 문제에서 5분 분량(지난번에 고른 시간)만 골라 바로 시작해요. 홈의 '오늘의 KOK' 숫자와 고리도 그 5분 분량 기준(X문제 중 n문제)이고, 진행은 저장돼서 나갔다 와도 '이어서 하기'로 남은 문제부터 — '처음부터'를 누르면(한 번 물어봐요) 저장한 진행을 지우고 새로 골라요. 복습 탭에서 시작한 세션(5·15·30분)도 저장돼서 다음에 열면 '하던 복습이 있어요' 카드로 이어서 하거나 처음부터 할 수 있어요. 그사이 새 노트가 생기면 새 문제가 남은 시간에 맞춰 나눠 들어가요. 복습 화면에서 기간(복습할 차례·오늘·3일·1주·1달·전체 — 문제를 넣은 날 기준)과 과목, 시간(5·15·30분)을 고르면 기간의 문제 수와 내 빠르기로 시간마다 문제 수를 계산해 보여 주고, 짧을수록 핵심 문제(틀렸던 문제·중요/별표 개념·복습할 차례, 같은 개념은 몰리지 않게)만 골라요. 시간은 문제 수만 정하고 지나도 멈추지 않아요(집중 모드, 남은 시간은 안내만). 고른 기간·시간은 다음에 그대로. 노트의 '이 노트 문제 풀기'는 노트 안에서 그 노트 문제로 바로 시작해요(시간 제한 없이 다 풀면 끝, 끝나면 보던 탭으로)
- AI 에너지: 무료 하루 20 / Pro 한 달 2,000(하루 300), 무료 전체 월 예산, 분당 제한, 비상 스위치, 실패하면 돌려주기
- 테스트 플랜: 관리자가 에너지(번개) 총량·하루 최대·쪽수·사진·글자·파일 크기·꼼꼼 모델을 정해 만들고, 그 플랜의 코드를 나눠 준다. 코드를 쓴 계정은 정한 날수 동안 그 플랜(관리자 > 테스트 플랜 > Pro > 무료)을 쓰고, 끝나면 원래 요금제로 돌아간다
- 관리자 화면: 키 상태·시험, 숫자, 모델·effort, 한도, 사용자(테스트 플랜 끝내기), 테스트 플랜, 쿠폰(Pro·테스트 플랜 코드), 신고함, 공지, 운영자 정보
- 설정: 테마(계정 바로 아래), 모델(빠름/꼼꼼), AI 채팅, 시각화, 복습, 문제, 내 데이터 내려받기, 탈퇴
- 색: 요즘 앱처럼 맑은 회색 바탕 + 흰 카드(어두울 때는 검정 + 짙은 회색 카드), 포인트는 인디고 하나. 기본 색은
src/app/globals.css 맨 위, 기본 테마 9가지는 src/lib/themes/presets.ts(둘이 같은지 시험이 확인해요)
- 화면 꾸미기: 별표 빛처럼 화면 위·아래에 은은한 빛, 핵심 카드(오늘의 KOK·복습 시작)의 빛 테두리, 두 색 버튼·고른 칩·+ 버튼이 기본이에요. 빛은 그 아래 글자가 잘 읽히는 만큼만 진해지고, 테마마다 어울리는 빛 색을 맞춰 두었어요. Pro는 내 테마마다 '꾸미기'에서 하나씩 켜고 끄고, 작은 카드 빛 포인트·떠 있는 아래 메뉴·아래 메뉴가 비치는 정도(안 비침~유리처럼)·빛 색을 바꿔요(바로 보이는 폰 미리보기)
- 테마 (Pro): 화면 밝기(기기 설정·밝게·어둡게), 테마는 작은 화면 미리보기(바탕·카드·글자·버튼 색, 같게 쓸 때는 대각선으로 밝을 때·어두울 때)로 골라요. 테마 칸의 '+'로 새 테마(AI로 만들기, 또는 기본 테마 하나에서 시작해 직접 만들기), 고른 내 테마의 연필로 고치기·지우기(기본 테마는 고칠 수 없어요). 밝을 때·어두울 때 테마를 따로 고르기(기본 9가지: KOK·블루·라벤더·핑크·코럴·라임·민트·모카·미드나잇 + 내 테마), 별표 빛(색·세기, 밝을 때·어두울 때 미리보기), 내 테마 20개까지 — AI로 만들기(느낌을 적으면 두 모드의 색·글꼴·종이·배경 그림을 골라 줌)와 직접 만들기(모드마다 바탕·카드·포인트 색, 배경은 사진 올리기·AI 그림·무늬, 그림 위를 덮는 정도). 글꼴 4가지(고운돋움·개구·고운바탕, 고른 사람만 글꼴 파일을 받음), 노트 종이 무늬(줄·모눈·점). 색은 글자가 잘 보이게(명암비 4.5 이상) 맞추고, 배경 그림이 있으면 그림 위에서도 글자가 잘 보이게 덮는 정도와 글자 색을 알아서 올려요. Pro가 끝나면 기본 모양으로 돌아가고 고른 테마는 남아요(Pro가 끝나도 내 테마를 지울 수는 있어요)
- 테스트 플랜마다 꼼꼼 모델·노트에 자료 더하기·테마·그림 풀이를 켜고 끌 수 있어요
- PWA(홈 화면에 설치), 밝은/어두운 화면, 노트 앱(One UI) 느낌의 디자인과 움직임(움직임 줄이기 설정을 따름). 고르기 칸도 브라우저 기본 대신 앱 디자인의 펼침 목록
구조
| 부분 | 쓰는 것 |
|---|
| 화면 + 서버 | Next.js 16 (App Router, src/), React 19, Tailwind CSS 4 |
| 로그인·데이터·파일 | Supabase (Auth + Postgres RLS + Storage sources 버킷) |
| AI | Claude API (@anthropic-ai/sdk), 서버에서만 호출, JSON 스키마로 답 받기 |
| 테마 배경 그림 | Cloudflare Workers AI (FLUX.1 schnell, 무료 몫 안에서), 서버에서만 호출. 그림은 비공개 theme-images 버킷 |
| 복습 알고리즘 | ts-fsrs (브라우저에서 계산, RLS로 내 카드만 저장) |
| 호스팅 | Vercel (함수 지역 서울 icn1, 매일 청소 Cron) |
src/
app/ 화면과 API (route.ts)
(app)/ 로그인한 뒤 화면: home, library, notes, review, wrong, questions, settings, plan, admin, welcome (add 는 자료함으로 보내기만)
api/ 서버 API: sources(자료 처리·노트에 더하기), notes(그림·문제 다시 만들기, chat, versions), questions(그림 풀이 만들기), chat(홈 AI에게 물어보기), themes(내 테마·AI 테마·배경 그림), grade, coupon, account, admin, cron, internal
auth/callback/ 구글·카카오·Apple 로그인에서 돌아오는 곳
components/ 화면 조각 (QuickAdd: + 버튼·끌어다 놓기, LibraryView: 자료함, mindmap/: 한눈 지도·가지 카드·가지 자세히, figure/: 문제 그림·단계별 풀이, chat/: 채팅 창 조각·홈 물어보기·노트에 넣기, NoteView, QuestionCard …)
lib/
ai/ 요금표·에너지, 프롬프트, JSON 스키마
server/ 서버 전용 (계정·에너지, Claude·Cloudflare 호출, 처리 파이프라인, 테마)
figure/ 그림 설계도(검사·좌표·어느 단계에 무엇이 보이는지), 상자 그림 배치, 풀이 읽기
themes/ 테마 색 계산(명암비), 기본 테마 색, 테마 모양 검사, CSS 만들기, 무늬 SVG 거르기
supabase/ Supabase 클라이언트 (브라우저·서버·proxy·관리자)
proxy.ts 로그인 세션 새로 고침, 로그인 안 하면 첫 화면으로
supabase/
schema.sql 표·권한·RLS·함수·저장소 정책 (SQL Editor에서 한 번 실행)
test/ 로컬 Postgres로 RLS를 시험하는 SQL
파일은 서버가 개수·크기·하루 한도를 검사하고 준 한 번짜리 올리기 주소(POST /api/uploads)로만 올려요. 학생이 저장소에 직접 올리거나 지울 수는 없어요. 1시간 넘게 정리를 시작하지 않은 파일은 서버가 지워요.
자료 처리는 단계별(정리 → 합치기 → 그림 → 문제 → 검사 → (Pro) 그림 풀이 두 번 → 저장)로 진행되고, 상태는 sources 표에 저장돼요. 노트에 더한 자료는 부모 자료(parent_id)를 가리키는 자료 행으로 같은 단계를 거치고(합치기는 지금 노트와), 끝나면 kok_finalize_append 가 지금 버전을 note_versions 에 남기고 합친 노트를 새 버전으로 써요. 지금 버전의 내용은 늘 notes·visuals·questions 에 있고, 지금 버전에 없는 문제는 status = 'hidden' 이라 복습에 나오지 않아요. 자료 만들기와 다시 하기는 DB 함수(kok_create_source, kok_retry_source)가 한 사람씩 줄을 세워서, 동시에 정리하는 수와 에너지(정리 중인 자료가 더 쓸 몫까지)를 한 번에 검사해요. 한 번 부를 때 90초까지 새 단계를 시작하고, 남으면 서버가 서명된 요청으로 자기 자신을 다시 불러 이어 가요(Vercel 300초 제한). 화면이 열려 있으면 멈춘 처리를 화면이 다시 깨워요.
환경변수
Vercel → Settings → Environment Variables 에만 넣어요. 이 저장소는 공개라서 값을 코드나 파일에 적지 않아요. (.env.example 참고)
| 이름 | 설명 |
|---|
NEXT_PUBLIC_SUPABASE_URL | Supabase 프로젝트 주소 |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | Supabase publishable key (sb_publishable_…) |
SUPABASE_SECRET_KEY | Supabase secret key (sb_secret_…) — 비밀 |
ANTHROPIC_API_KEY | Claude API 키 — 비밀 |
ADMIN_EMAILS | 관리자 구글 이메일 (쉼표로 여러 개). 구글로 로그인한 계정만 관리자가 돼요 (Apple 로그인은 안 돼요) |
CRON_SECRET | 매일 청소 작업 보호 (아무 영어·숫자 32자 이상) — 비밀. 없으면 청소가 돌지 않아요 |
NEXT_PUBLIC_KAKAO_LOGIN | 1 이면 첫 화면에 "카카오 로그인" 버튼이 보여요. 비워 두면 버튼이 없어요. 빌드할 때 정해지니 바꾸면 다시 배포해요 (공개돼도 괜찮아요) |
NEXT_PUBLIC_APPLE_LOGIN | 1 이면 첫 화면에 "Apple로 계속하기" 버튼이 보여요. 비워 두면 버튼이 없어요. 빌드할 때 정해지니 바꾸면 다시 배포해요 (공개돼도 괜찮아요) |
CLOUDFLARE_ACCOUNT_ID | Cloudflare 계정 ID (32자리). AI 테마의 배경 그림을 그릴 때 써요. 비워 두면 그림 대신 무늬를 넣어요 |
CLOUDFLARE_API_TOKEN | Cloudflare Workers AI 토큰 — 비밀. 계정 ID 와 같이 넣어야 그림을 그려요 |
카카오 로그인 켜기 (선택)
- 카카오 디벨로퍼스에서 앱(KOK)을 만들고, 앱 아이콘을 넣어요. (버튼은 카카오 디자인 안내대로 공식 말풍선 심볼과 '카카오 로그인' 글자를 써요)
- 앱 → 플랫폼 키 → REST API 키를 열어 리다이렉트 URI 에
https://<프로젝트-ref>.supabase.co/auth/v1/callback 을 넣고, 클라이언트 시크릿 코드를 만들고 활성화해요.
- 카카오 로그인 → 사용 설정 → 상태 ON.
- 앱 → 일반 → 비즈니스 정보 → 개인 개발자 비즈 앱 전환 (본인인증과 카카오비즈니스 통합 서비스 약관 동의가 먼저 필요해요). Supabase 는 카카오에 이메일을 늘 함께 요청해서, 이메일 동의항목이 없으면 KOE205 오류가 나요. 이메일 항목은 비즈 앱만 켤 수 있어요.
- 카카오 로그인 → 동의항목: 닉네임·프로필 사진·카카오계정(이메일)을 선택 동의로 켜요.
- Supabase → Authentication → Sign In / Providers → Kakao 를 켜고, Client ID 에 REST API 키, Client Secret 에 클라이언트 시크릿 코드를 넣고, Allow users without an email 을 켜요 (이메일 제공을 거절한 사람도 가입할 수 있게).
- 위 순서를 다 마친 뒤 Vercel 에
NEXT_PUBLIC_KAKAO_LOGIN=1 을 넣고 다시 배포해요.
이메일 없는 카카오 계정은 설정에 '카카오 계정'으로 보이고, 탈퇴 기록은 카카오 회원번호로도 남겨서 같은 날 다시 가입해도 무료 에너지를 또 받지 못해요. 관리자는 구글 로그인만 돼요.
AI 테마 배경 그림 켜기 (선택)
- Cloudflare 에 가입해요 (무료, 카드 없이).
- AI → Workers AI → Use REST API → Create a Workers AI API Token → 만들기 → 토큰을 복사해요. 같은 화면의 Account ID 도 복사해요.
- Vercel 에
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN 을 넣고 다시 배포해요.
무료 몫은 하루 10,000 뉴런(UTC 0시에 다시 참, 그림 약 170장)이고, KOK은 서비스 전체에서 하루 150장까지만 그려요. Cloudflare 가 오늘 몫을 다 썼다고 하면(오류 3036) 그날은 더 부르지 않고, 몫이 없거나 실패하면 무늬를 대신 넣고 알려 줘요. 그림만 다시 그릴 때는 그릴 수 없으면 AI(에너지)를 부르기 전에 알려 줘요. 한 사람은 하루에 AI 테마 10개·AI 그림 10장·사진 20장까지예요.
Apple 로그인 켜기 (선택)
- Apple Developer Program(유료, 해마다)에서 App ID(Sign in with Apple 켜기), Services ID, 키(
.p8)를 만들어요. Services ID 의 Return URL 은 https://<프로젝트-ref>.supabase.co/auth/v1/callback 이에요.
- Supabase → Authentication → Sign In / Providers → Apple 을 켜고, Client IDs 에 Services ID, Secret Key (for OAuth) 에
.p8 로 만든 JWT 를 넣어요.
- 위 순서를 다 마친 뒤 Vercel 에
NEXT_PUBLIC_APPLE_LOGIN=1 을 넣고 다시 배포해요.
- Secret Key(JWT)는 6개월마다 끝나요. 끝나기 전에
.p8 로 새로 만들어 넣어요. 안 하면 Apple 로그인이 멈춰요. .p8 파일은 저장소에 절대 넣지 않아요.
처음 설치
- Supabase SQL Editor 에
supabase/schema.sql 전체를 붙여 넣고 실행해요. 여러 번 실행해도 안전해요. 코드를 새로 올릴 때마다 한 번 더 실행해요. 새 표·칸이 생기기 전에는 새 기능(노트 채팅, 자료 더하기와 버전, 내 테마, 그림 풀이, 채팅 파일, 자료함 정리, 자료 그림, 과목 서랍, 노트·과목 합치기와 옮기기, 단계별 학습, PDF 요약 정리, 저장한 복습 세션)이 꺼진 채로 예전처럼 동작해요.
- Vercel 에 이 저장소를 가져오고 위 환경변수를 넣어 배포해요.
- Supabase → Authentication → URL Configuration 에 사이트 주소(Site URL)와
https://<사이트>/**(Redirect URLs)를 넣어요.
개발
npm install
npm run dev # http://localhost:3000 (환경변수는 .env.local 에)
npm test # 단위 시험 (vitest)
npm run lint
npm run typecheck # next typegen + tsc
npm run check:secrets # 비밀 키처럼 보이는 문자열 검사
RLS 시험 (로컬 Postgres 필요):
cd supabase
psql -d koktest -f test/stub.sql -f schema.sql -f test/rls_test.sql
다음 버전
- v0.2: 문제 세트 공유, 한글·워드·PPT·웹 링크 넣기, 기억 지도, 오프라인 복습, 하루 한 번 알림
- v0.3: 같이 공부하는 방
- v0.4: Pro 결제
