Unimation Korea

Uni Total Contents Solution

교육 콘텐츠 제작부터 리소스 관리, 학습 뷰어까지 하나로 연결합니다

System Overview
UTCS(Uni Total Contents Solution)는 구몬 중국어(KCFL)·한자(KCC)·일본어(KJFL) 교육 콘텐츠를 제작하는 통합 솔루션입니다.
작업 흐름: ① DB Architect에서 OCR·AI 기반 리소스(단어/이미지/오디오) 구축 → ② Contents Maker에서 캔버스 기반 페이지 편집 (드래그앤드롭·필기·음성 활동 설정) → ③ Activity Viewer에서 학습자 관점 테스트 → ④ Publish로 SmartKumon 상위 시스템에 Render Payload v2 형식으로 내보내기.
콘텐츠 단위: SLSP = Subject(과목) → Level(레벨) → Set(세트, 001~020) → Page(페이지, 1a~10b, 총 20장).
인프라: GCP Cloud Run + Cloud SQL(PostgreSQL) + Cloud Storage(GCS). Express API 서버가 모든 패키지를 서브경로로 서빙.
/db-architect
🧠
KUMON DB 관리 시스템
교육 리소스 데이터베이스 구축 도구.
· OCR 업로드: 교재 이미지/PDF → Gemini AI 텍스트 추출 (영역 크롭 방식)
· Asset Pool: 과목별 단어·병음·번역·이미지·오디오 관리
· Page Editor: 활동 스택(드래그/필기/음성) 설정
· 지원 과목: 중국어, 일본어, 한자 (+ Demo 과목)
DB Architect 열기
/editor
🎨
Contents Maker
자유 캔버스 기반 콘텐츠 편집기.
· FreeCanvas: 텍스트/이미지/비디오/버튼 요소를 자유롭게 배치
· 기능 템플릿: 원고 입력 → 병음 드래그드롭·음성인식 요소 자동 생성
· 슬라이드: 같은 페이지 내 서브페이지 (slideIndex 기반)
· Publish: SmartKumon Render Payload v2로 JSON/GCS 내보내기
· 시나리오: sequential/free 모드, 단계별 잠금/해제 제어
콘텐츠 편집기 열기
/viewer
🎮
Activity Viewer
학습자 관점 콘텐츠 실행기.
· 드래그앤드롭: 그룹/정답 매칭, 자석 흡착 효과
· 필기인식: 4가지 모드 (직접/빈칸/후보/연습), Gemini AI 검증
· 음성인식: Web Speech API + 정답 비교
· 슬라이드 네비게이션: 하단 인디케이터로 서브페이지 전환
· 시나리오 진행: LOCKED→ACTIVE→COMPLETE 상태 머신
학습 뷰어 열기
System Monitor
🗄️ Database Overview
PostgreSQL(Cloud SQL) 테이블별 레코드 수. resources(리소스), content_versions(편집 콘텐츠), page_stacks(활동 스택), learning_results(학습 결과) 등 8개 테이블.
로딩 중...
로딩 중...
🌐 Deployment Info
현재 실행 환경 및 GCP 배포 정보
로딩 중...
🔗 SLSP Key Consistency
resources 테이블(Editor) ↔ content_versions 테이블(Viewer) 간 subject 키 비교
검사 중...
⚙️ Edit Mode Consistency
모든 콘텐츠가 freeCanvas 모드인지 확인 (block 모드 잔존 여부)
검사 중...
📦 Version Number Integrity
SLSP별 버전 번호가 순차적인지 확인 (삭제로 인한 갭 검출)
검사 중...
🔄 Data Pipeline Status
Editor → API → DB → Viewer 데이터 흐름 상태
분석 중...
📝 Recent Saves
최근 저장된 콘텐츠 버전 이력
로딩 중...
📐 Content Coverage
Subject × Level별 콘텐츠 제작 진행률
로딩 중...
로딩 중...
🔍 Content Validation
저장된 콘텐츠의 구조적 유효성 검사
검사 중...
🚨 Error Log
API 서버 에러 이력 (인메모리, 최근 50건)
로딩 중...
💡 AI Tools 활용 전략
업그레이드·수정·고도화 시 최적 도구 선택 가이드
🆕 새 기능 추가
/plan → tdd-guide → code-reviewer
🐛 버그 수정
backend-ops → /build-fix → security-reviewer
🏗️ 아키텍처 변경
architect → planner → refactor-cleaner
🚀 GCP 배포
backend-ops → build_deploy.ps1 → /verify
⚠️ 시스템 부담: 이 페이지는 순수 정적 HTML — API 호출 없음, 성능 영향 없음.
✅ 반복 문제 예방: 폰트 CORS 같은 이슈 재발 시 → backend-ops + /build-fix 즉시 투입.
🤖 Specialized Agents ~/.claude/agents/ (15개)
독립 서브프로세스로 실행 — 메인 컨텍스트 보호, 병렬 처리 가능
에이전트역할자동 활성화 시점
backend-ops Express·DB·PM2·Docker·API 라우트, 서버 디버깅 서버 시작/중지, DB 연결, API 에러
build-error-resolver 빌드/TypeScript 에러 최소 diff 수정 빌드 실패, 타입 에러
code-reviewer 코드 품질·보안·유지보수 리뷰 코드 작성/수정 후
security-reviewer OWASP Top 10·인증·입력검증 취약점 탐지 커밋 전, API 작성 후
planner 구현 계획·PRD·아키텍처 설계 문서 생성 복잡한 기능 요청
architect 시스템 설계·확장성·기술 의사결정 아키텍처 변경
tdd-guide 테스트 우선(RED→GREEN→REFACTOR) 80%+ 커버리지 신기능·버그수정
e2e-runner Playwright E2E 테스트 생성·실행·아티팩트 업로드 크리티컬 사용자 플로우
ocr-specialist OCR 크롭·Gemini API·좌표 시스템·레이아웃 분석 (버그 10개 기록) OCR 관련 버그/기능
template-builder 기능 템플릿 설계·병음 분해·드래그드롭 자동 생성 (이슈 7개 기록) 새 템플릿 추가/수정
content-connector UTCS↔SmartKumon 콘텐츠 연결·Render Payload v2·에셋 리라이트 콘텐츠 내보내기/적재
refactor-cleaner 사용하지 않는 코드·중복 제거 (knip, depcheck) 코드 유지보수
doc-updater CODEMAPS·README·문서 업데이트 문서 변경 시
database-reviewer SQL 최적화·스키마·보안·Supabase 모범사례 SQL 작성, 스키마 설계
chief-of-staff 이메일·Slack·메신저 트리아지 및 드래프트 멀티채널 커뮤니케이션
💬 사용법: "backend-ops agent 활용해서 fonts.ts 수정해줘"  |  병렬 실행: 한 메시지에 여러 Agent 동시 투입 가능
⚡ Skills — 슬래시 커맨드
이 프로젝트에서 자주 사용하는 /커맨드
개발 워크플로우
/plan /tdd /build-fix /verify /checkpoint /backend /scenario
코드 품질
/code-review /refactor-clean /test-coverage /simplify
멀티모델 협업
/multi-plan /multi-execute /multi-frontend /multi-backend
학습·자동화
/learn /learn-eval /skill-create /schedule /e2e
🧠 학습된 Skills — 프로젝트 특화 패턴
이 프로젝트의 반복 패턴에서 자동 추출된 재사용 지식 (/.claude/skills/learned/)
zustand-freecanvas-patterns Zustand 슬라이스 + Free Canvas 요소 관리 — 셀렉터 무한루프, 히스토리 N+1, 드래그 성능, autoCache 2026-03-18
dragdrop-group-validation 드래그앤드롭 3-레이어 방어 — onDragOver 차단, onDrop 튕겨내기, 엔진 최종 검증, parseDragData 2026-03-18
highlight-border-injection CSS 애니메이션 동적 주입 — injectHighlightStyles, getHighlightStyle, 에디터↔뷰어 공유, 입력값 보안 검증 2026-03-18
canvas-ai-handwriting Canvas 필기 + AI(Gemini) 검증 — 오프스크린 캔버스, 좌표 스케일링, 레이아웃 보존 2026-03-16
react-preview-verification React 앱 preview_eval/snapshot/network 검증 — 스크린샷 없이 E2E 테스트 2026-03-13
💬 새 패턴 추가: /skill-create — git 히스토리 자동 추출  |  /learn — 현재 세션 패턴 저장
🛠️ 반복 이슈 & 해결 레시피
과거 발생 문제 + 올바른 도구 조합 — 동일 문제 재발 시 즉시 참조
🔤 폰트 CORS 깨짐 Cloud Storage 직접 URL에서 @font-face 로드 시 차단
→ backend-ops → fonts.ts 프록시 /api/fonts/proxy/ 추가 → /build-fix → build_deploy.ps1
📦 빌드 실패 TypeScript 에러, 누락 타입, import 경로 오류
→ build-error-resolver agent → /build-fix → 빌드 재검증
🔗 localhost 참조 배포 후 프론트가 localhost:PORT를 호출
→ Grep으로 localhost 전수 검색 → backend-ops 수정 → /verify
🗄️ DB 연결 불안정 Cloud SQL 소켓 미설정, 환경변수 누락
→ backend-ops → db.ts CLOUD_SQL_CONNECTION_NAME → env.yaml 확인
📁 resources 0건 subject 한글/영문 불일치 (한자 vs hanja)
→ database-reviewer → subjectVariants() 양방향 매칭 → page fallback 쿼리
🖼 OCR 좌표 불일치 Gemini가 % 좌표를 정확히 해석 못함
→ 좌표 지시 대신 cropImageToRegion()으로 이미지 잘라서 전송 → 100% 정확
📝 원문에 병음 들어감 Gemini가 text 필드에 한자 대신 병음 반환
→ 3단계 교정: 프롬프트 강화 → rawResults 매핑 → AI 병음→한자 변환
🚀 SHORT_SHA 비어있음 cloudbuild.yaml 이미지 태그 비어 빌드 실패
→ build_deploy.ps1의 git rev-parse --short HEAD로 명시 전달
🔄 하네스 파이프라인 (Harness Engineering)
Context Reset + Generator/Evaluator 분리 — AI의 자기 평가 실패 방지
📋
Planner
SPEC 설계
→
⚙️
Generator
구현 + 자체점검
→
🔍
Evaluator
엄격 검수
→
✓
합격/재시도
최대 3회
🆕 Context Reset
각 에이전트가 독립 컨텍스트에서 실행 — 장시간 대화의 조급함 방지
🆕 가중 채점 + 자동 반복
디자인 40% + 독창성 30% + 기술 15% + 기능 15% → 7.0+ 합격
🆕 자체 점검 (SELF_CHECK)
Generator가 먼저 자체 검증 후 Evaluator에 전달
🆕 엄격 평가 원칙
"절대 관대하게 보지 마라" — 피드백: 위치+이유+방법 3요소 필수
🤖 서브에이전트 현황 ~/.claude/agents/ (12개)
설치된 에이전트 + 마지막 업데이트 시각
🛡️
security-reviewer
OWASP Top 10 · 취약점 탐지
🔍
code-reviewer
코드 품질 · 유지보수
🏗️
build-error-resolver
빌드/TS 에러 수정
🧪
tdd-guide
테스트 우선 개발
📐
architect
시스템 설계 · 확장성
📝
planner
구현 계획 · PRD
🔧
backend-ops
Express · DB · API
🗄️
database-reviewer
SQL 최적화 · 스키마
🎭
e2e-runner
Playwright E2E 테스트
🧹
refactor-cleaner
데드코드 · 중복 제거
📚
doc-updater
문서 · CODEMAPS
📨
chief-of-staff
커뮤니케이션 트리아지
📤 Publish Status — SmartKumon Export
UTCS에서 제작한 콘텐츠를 SmartKumon 상위 시스템(subject-api)에 전달하기 위한 내보내기 현황.
변환 과정: UTCS 내부 저장 형식 → Render Payload v2 (renderContractVersion:2, 과목코드 매핑, pageKey 파싱, 에셋 URL 리라이트).
1 Set = root 20페이지(1a~10b) + child 최대 3페이지. 각 페이지는 개별 JSON으로 내보내짐.
로딩 중...
Export 방식
① JSON 다운로드 — 검수/로컬 테스트
② GCS 업로드 — 자동화 파이프라인
③ REST API Push — 향후 (subject-api admin)
과목 코드 매핑
hanja → KCC (구몬한자)
chinese → KCFL (구몬중국어)
japanese → KJFL (구몬일어)
GCS 경로 규칙
gs://bucket/publish/
  {code}/{level}/{set}/
    v{version}/
      manifest.json
      pages/{key}.json
API: POST /api/publish/export (JSON)  |  POST /api/publish/gcs (GCS)
🎬 Recent Features & Changes
최근 구현된 기능 및 변경사항
📤 Publish Export (2026-04-07)
SmartKumon Render Payload v2 변환 + JSON 다운로드 + GCS 업로드.
publishTransform.ts | POST /api/publish/export | POST /api/publish/gcs
🧩 기능 템플릿 시스템 (2026-04-06)
원고 입력 → 요소 자동 생성. 병음 드래그 드롭(2A_22b_Drag) + 단어 음성인식(2A_21a).
슬라이드(서브페이지) 시스템: slideIndex 기반 다중 원고 지원.
🖼 OCR 이미지 크롭 방식 (2026-04-06)
영역 선택 → 이미지 크롭 → 잘린 이미지만 Gemini에 전송 (좌표 지시 X).
이미지 영역 WebP 추출 + 단어별 수동 이미지 연결(🖼 버튼).
🔄 SLSP 자동 로드 (2026-04-07)
페이지 선택 시 서버에서 최신 콘텐츠 자동 로드. DB 불러오기 시 이미지→텍스트 자동 연결.
Asset Pool: set 전체 리소스 로드 + 중복 제거 기능.
🎬 비디오 요소
Free Canvas에 비디오 요소 추가. 로컬 파일 업로드 (200MB, mp4/webm/ogg/mov/avi/mkv).
API: POST /api/resources/upload-video
📐 z-index 관리
bringToFront/sendToBack + 자동 정규화. 컨텍스트 메뉴 & 키보드 단축키 (Ctrl+]/Ctrl+[).
normalizeZIndices: 순서 유지하며 1부터 재할당.
✏️ 필기 UI 통일
DrawingToolbar 공통 컴포넌트. SVG 아이콘 기반 [↩] [🗑] N획 [🔍 분석].
AnalysisPopup: Portal 렌더링 + 등급별 그라데이션 헤더.
⌨️ 키보드 단축키
Ctrl+Z/Y: Undo/Redo | Arrow: 1px 이동 | Shift+Arrow: 10px 이동
정렬/분배: 컨텍스트 메뉴에서 다중 선택 시 사용 가능
🔧 외곽선 통일
에디터 설정값이 미리보기/뷰어에 그대로 반영. 텍스트 영역 기본: 투명 배경 + 테두리 없음.
API Server
Contents Maker
Activity Viewer
Resource DB