Skip to main content

JunkBox apps/knowbit 가이드

업무 개요​

  • 공유 Markdown 자료를 원본으로 AI가 지식 카드와 퀴즈를 만들어 주고, 사용자가 학습하고 이력을 복습하는 앱임.
  • 핵심 개념은 원본 문서, 학습 범위(전체 문서·문서 선택), 지식 카드, 퀴즈 세션과 문제(객관식·주관식), 답변과 채점, 학습 이력임.
  • 원본 자료는 권한이 있는 사용자가 공유하고 카드·퀴즈·답변 이력은 사용자별로 분리함.
  • 원본 파일은 읽기만 하며 색인·임베딩 없이 학습 시점에 파일을 직접 읽음.

1. 역할과 책임 경계​

  • apps/knowbit-api는 공유 Markdown 원본의 읽기 전용 조회와 사용자별 카드·퀴즈·채점 이력을 소유하는 FastAPI 앱임. apps/knowbit-ui는 모바일 React 화면이며, API의 SSR 셸이 UI dist와 shared-ui 자산을 제공함.
  • 개발 UI/API 포트는 15012/18012이고 just knowbit-frontend, just knowbit-backend로 실행함. 개발 UI는 LAN 전용 전달기를 사용하고 API는 루프백에 수신함. Tailnet HTTPS 15012 Serve 등록과 LAN UFW 허용은 개발 서버 실행과 별도 작업임.
  • 운영 Compose 서비스명은 junkbox-knowbit, 컨테이너 내부 포트는 8080임. KNOWBIT_BASE_URL 기본값은 https://knowbit.sleepzz.xyz이며 Cloudflare Tunnel 대상은 http://junkbox-knowbit:8080임. Compose·CI 설정과 실제 운영 배포·DNS·Tunnel 공개는 별도 상태임.

2. 인증과 권한​

2.1 진입과 권한​

  • 웹 진입점은 /learn, /history, /cards/{card_id}, /quiz/{session_id}, /history/card/{card_id}, /history/quiz/{session_id}임. /는 /learn으로 이동하고 /health는 헬스 체크임.
  • 모든 학습 API는 Hub JWT Cookie/Header의 KNOWBIT 모듈 권한을 요구함. 웹 셸도 미인증 또는 권한 없음일 때 Hub 로그인으로 required_module=KNOWBIT과 원래 URL을 전달함. 자료는 권한이 있는 사용자에게 공유되지만 학습 이력 API의 카드·퀴즈·답변은 서버에서 owner_user_id로 제한함.

2.2 모바일 화면​

  • 모바일 화면은 shared-ui의 앱 셸·SPA 라우팅·CSS·Pretendard 폰트와 knowbit 앱 아이콘을 사용함.

    • Portal 메뉴 이름은 KnowBit, 상단 이름은 JunkBox KnowBit임.
    • 학습 범위·문서 목록·이력·카드·문제의 모바일 카드는 공통 카드 내부 여백을 사용하며, 하단 고정 액션바의 본문 안전 여백은 공통 셸이 자동 적용함.
    • 문제 유형은 선택 시트, 문제 수 1~5개와 난이도 쉬움·보통·어려움은 공통 모바일 range 입력을 사용함.
    • 서버 렌더링 화면에 web manifest 링크를 연결하지 않음.
  • 문서 선택, 학습 시작, 카드·퀴즈·이력 조회, 답변 제출, 다음 문제, 생성·채점 재시도는 공통 LoadingModal로 작업별 진행 메시지를 표시함. 버튼의 라벨·아이콘은 유지하고 관련 조작을 비활성화함. 작업 종료 시 모달을 닫고 실패 메시지는 화면 오류 영역에 표시함. 이력 목록의 첫 하단 버튼은 학습 홈 아이콘이며 카드·퀴즈 이력 상세의 목록 이동 버튼은 목록 아이콘임. 퀴즈 상세에는 수동 새로고침 버튼을 제공하지 않고, 준비·채점 중인 문제는 이후 이력에서 다시 열어 확인함.

  • 카드·퀴즈 이력 상세의 하단 액션바는 목록 버튼 오른쪽에 빨간 배경 휴지통 삭제 버튼을 제공함. 삭제 확인 뒤 DELETE /api/knowbit/history/{kind}/{item_id}를 호출하고 성공하면 이력 목록으로 이동함. 작업 중에는 관련 버튼을 비활성화하고 LoadingModal로 진행 상태를 표시함. 하단 버튼 폭은 shared-ui의 텍스트 전용·아이콘 전용·혼합형 자동 분배 규칙을 따름.

3. 데이터​

3.1 저장 구조​

  • 기본 DB는 호스트 /sorc001/junkbox/db/knowbit.sqlite3이며 KNOWBIT_DATABASE_URL로 변경할 수 있음. 컨테이너의 /app/db/knowbit.sqlite3은 같은 호스트 DB 폴더 mount를 사용함. 테스트만 임시 SQLite를 사용함.
  • tb_knowbit_card_n, tb_knowbit_quiz_session_m, tb_knowbit_question_n, tb_knowbit_answer_n에 owner, 요청 키, 상태·version, 범위·근거 snapshot, 정답·rubric·결과, 모델·프롬프트 버전을 보존함. 앱 기동 시 누락 스키마를 생성하고 기존 객관식 스키마에 주관식 컬럼을 이관함. 업무 일시는 offset 없는 KST로 저장함.
  • 이력 삭제는 요청자의 owner_user_id로 제한함. 카드 삭제 시 연결된 퀴즈 세션의 card_id를 비워 퀴즈 이력을 보존한 뒤 카드를 삭제함. 퀴즈 세션 삭제 시 외래키 cascade로 해당 문제·답변을 함께 삭제함. 공유 Markdown 원본은 변경하지 않음.

3.2 AI 출제와 채점​

  • 카드와 객관식·주관식 출제는 Hub PromptService와 shared-ai의 KNOWBIT_CARD, KNOWBIT_QUIZ 라우트를 사용함. 주관식 의미 채점은 KNOWBIT_GRADING 라우트를 사용하고 객관식은 저장된 정답 식별자로 서버에서 즉시 채점함. 초기 route 모델은 LiteLLM의 openai/openai/gpt-6-luna임. AI 사용 로그는 Hub internal API에 기록함.
  • KNOWBIT_QUIZ_INSTRUCTION v4는 객관식 정답을 원문의 짧은 핵심 표현으로 복사하고 해당 표현이 연속 인용문에 포함되도록 명시함. Markdown 표·목록·코드 구간의 기호와 순서를 보존하고 출력 스키마의 인용 후보를 사용함. 프롬프트는 Hub SQLite의 버전 관리 저장소에서 관리하고 변경 후 Hub·KnowBit 프롬프트 캐시를 갱신함.
  • 원문의 연속된 소제목 구간을 출력 스키마의 인용 후보로 제공하며 긴 구간은 겹치는 연속 범위로 나눔. 객관식 정답의 바깥쪽 인라인 코드 백틱은 비교 시 정규화하고 인용문은 원문 그대로 검증함. 객관식·주관식 근거 검증을 요청별 Pydantic 출력 모델에도 적용해 공통 shared-ai 구조화 응답 보정에 검증 오류를 전달함. 최초 응답이 잘못되면 같은 요청에서 최대 두 차례 보정하며, 정답·인용문·중복 검증을 통과한 결과만 저장함.
  • 퀴즈 세션은 시작 요청에서 선택한 문제 수만큼 문제·정답·해설을 미리 일괄 생성하고, 답변·채점 후에는 새 문제를 만들지 않고 미리 생성된 다음 문제로 이동함. 세션 내 이전 문제 전체를 대상으로 문제 문장·정답 문구·근거 인용 겹침을 검증해 실질 중복 출제를 최소화하고, 근거 부족이나 중복 검증 반복 실패로 생성에 실패하면 억지로 문제 수를 채우지 않고 이미 만든 문제 수로 세션을 축소함. 일괄 생성 전 구버전 세션처럼 남은 문제 행이 없는 경우 다음 문제 요청에서 해당 문제를 즉석 생성해 이어 풀기를 보장함.
  • 생성 결과는 source ID, 인용문, 선택지·정답, rubric, 출력 길이와 중복 여부를 검증함. 검증 실패는 문제 상태에 기록해 재시도할 수 있음. 검증 통과가 의미 정확성을 보장하지 않으므로 실제 자료의 오출제·오채점은 별도 확인 대상임.

4. 업무 규칙​

  • KNOWBIT_DOCUMENTS_DIR 기본 경로는 /ext001/data001/junkbox/knowbit/documents임. 원본은 하위 경로의 Markdown 파일마다 독립 문서로 취급하고, 첫 H1이 있으면 표시명으로 사용하며 없으면 파일명을 사용함. 같은 표시명은 상대 경로로 구분함.
  • 문서 목록 API는 커서 기반 페이지 단위로 제공하고 문서 선택 시트는 모든 페이지를 조회해 공통 검색·멀티 선택으로 제공함.
    • 전체 선택은 시트의 선택값만 변경하고 학습 범위를 전환하지 않음.
    • 학습 화면은 전체 문서·문서 선택 두 범위를 제공하며, 문서 선택 화면에서 한 개·여러 개·전체를 선택할 수 있음.
    • 서버의 ALL·DOCUMENT·DOCUMENTS 계약은 선택 결과에 따라 사용함.
    • 원본을 직접 읽어 한 요청에 필요한 근거 구간만 context_max_bytes 예산 내에서 선택함.
    • 기본 파일 크기 안전 상한은 16MiB, 근거 입력 상한은 12,000바이트임.
    • 긴 문서의 후반부와 표의 헤더·행, 단어와 뜻, 기존 문답의 질문과 정답 관계를 구간 선택에서 함께 고려함.
  • 루트 밖 경로와 symlink를 거부하고 HTML/script와 원문 속 AI 명령을 신뢰하지 않음. 원본 mount가 없거나 읽을 수 없을 때 빈 자료 목록으로 숨기지 않고 오류로 처리함. 원본 파일은 생성·수정·삭제하지 않으며 운영 Compose에서 읽기 전용으로 마운트함.
  • 원본 변경·삭제 후에도 기존 카드·문제의 근거 snapshot은 SQLite에 남음. 새 목록·학습은 현재 파일을 다시 읽음. 루트가 바뀌면 기존 결과는 열람할 수 있지만 이전 범위에서 추가 출제하지 않음. 문서 색인, RAG, 임베딩, 카테고리, 동기화·Automation 작업은 사용하지 않음.

5. 검증​

  • Docker 이미지는 Knowbit UI dist, shared-ui 자산, API 코드를 포함함. 운영 Compose는 원본과 env를 읽기 전용으로 마운트하고 DB·로그를 별도 볼륨으로 연결함. GitHub Actions의 junkbox-knowbit 선택 빌드·배포 정책은 활성화됨.
  • 합성 100/1,000문서의 페이지 탐색과 긴 문서 후반 구간을 측정하고, 단어집·일반 문서·문답집·혼합 문서·긴 표로 Luna 생성·채점을 검증함. 긴 표 문제는 근거 검증에서 간헐적으로 거부될 수 있음. 사용자 실제 자료 규모·품질과 Android Chrome 실기기 설치는 별도 검증 대상임.