기타 2026-05-22 10KB 읽기 13분

academy.crowny.org v2.1 — 상용화 준비 완료

날짜: 2026-05-22 도메인: academy.crowny.org (포트 9865) 결제 도메인: pay.crowny.org (포트 9866, 별도 세션) 선행 작업: 2026-05-21-academy-고도화-패스드림+더이룸학원.md

개요

v2.0 (모듈 11개 + 시드 + 4 HTML) 위에 상용 운영 가능한 인프라 6 트랙을 병렬 구축. 결제는 stub만 두고 pay.crowny.org로 분리.

6 트랙 결과

Phase 6 — 운영 인프라

lib/config.js — .env 자체 파서 (dotenv 의존성 없음)
lib/logger.js — stdout 색상 + logs/{date}.log 파일 기록, 레벨 필터
lib/error-handler.js — wrapAPIHandler + 전역 uncaughtException/unhandledRejection 처리
lib/health.js — 4 헬스 엔드포인트 + 요청/에러 카운터
ecosystem.config.js — PM2 설정 (dev/production env)
scripts/{start,stop,restart,status}.sh — PM2 또는 nohup 자동 분기
.env.example + .gitignore

헬스체크:

/health — 라이브니스 (단순 OK)
/health/ready — 모듈 11/11 + 데이터 디렉토리 + 메모리 → ready/degraded/down
/health/metrics — uptime, requests, errors, errorRate, memory
/health/version — 버전, 빌드시간, 모듈 prefix 목록

Phase 7 — 보안

lib/auth.js — Bearer ADMIN_TOKEN / X-Academy-Token, PBKDF2 (100,000 iter, sha512), crypto.timingSafeEqual
lib/rate-limit.js — 슬라이딩 윈도우 1분, 60/300/∞ (일반/학원/관리자), X-RateLimit-* 헤더, 429 + Retry-After
lib/validators.js — 타입/스키마/HTML escape/한국 휴대폰 등
lib/security.js — 보안 헤더 + CORS 화이트리스트 + 통합 securityCheck
lib/auth-routes.js — /api/auth/{login,issue-token,revoke-token,whoami,change-password,register}

보안 정책:

공개: /health, /api/status, /api/credit/plans, /api/dt5/sdgs, /api/tutorial/*, /api/auth/login, 정적 파일
보호: 모든 POST/PUT/DELETE 및 학생/반/출결/수납/상담/채점/리포트/알림/만다라트/외부AI/진단/시뮬레이터
관리자: /api/auth/{issue,revoke}-token, /api/adapters/*

Phase 8 — 백업/복원/마이그레이션

scripts/backup.sh — 일별 백업 (시드 제외), 7일 보존, SHA256
scripts/restore.sh — SHA256 검증 + 이전 데이터 자동 백업 + JSON 유효성 검증 + 실패 시 롤백
scripts/verify-data.sh — JSON 파싱 + 필수 필드 + 참조 무결성
scripts/migrate.sh — migrations/NNN-*.sh 순차 실행 + 실패 시 롤백
scripts/install-cron.sh — macOS LaunchAgent / Linux crontab (새벽 3시)
첫 백업 테스트 통과 (191 파일, 121KB, SHA256 OK)

Phase 9 — 외부 어댑터 인터페이스

adapters/base.js — BaseAdapter (healthCheck, log, _requireKey, _fetch)
adapters/kakao.js — mock / kakao-biz / nhn-toast
adapters/ocr.js — mock / tesseract / passdream / naver-clova / google-vision
adapters/external-ai/{mathflat,gge,passdream}.js — 각 mock/live
adapters/pay-stub.js — pay.crowny.org:9866으로 위임 (mock/live), 6 결제수단 (카드/카카오페이/네이버페이/토스페이/페이코/계좌이체/포네)
adapters/index.js — 레지스트리 + healthAll + getModes
adapters/status-routes.js — /api/adapters/status (관리자) + /api/adapters/config
adapters/PAY_INTERFACE.md — pay.crowny.org 구현 명세 (엔드포인트, webhook HMAC, 결제 흐름)
adapters/README.md — 환경변수 매핑 + 전환 체크리스트

Phase 10 — 디자인 표준 + 관리자 SPA (verdant 톤)

public/assets/tokens.css — 디자인 토큰 (verdant 컬러 팔레트, 폰트, 간격)
public/assets/components.css — 버튼/카드/입력/태그/알림/스피너/모달/탭/테이블
public/assets/app.js — hash router + API 헬퍼 (X-Academy-Token 자동 첨부) + 토스트 + 차트 헬퍼
public/index.html (v2 교체, v1은 index.html.v1.backup)
public/views/ — 모듈별 부분 뷰 11개 (dashboard/attendance/classes/consult/credit/diagnosis/dt5/extai/mandalart/notify 등)

Phase 11 — 운영 매뉴얼 + 온보딩 (160쪽, 5,267줄)

docs/학원장-가이드.md — 5분 시작 + 30일 로드맵 + 모듈별 2-3p + FAQ 20개
docs/온보딩-체크리스트.md — Day 0~30 (58 항목)
docs/데모영상-스크립트.md — 60초 릴스 + 3분 풀버전
docs/운영매뉴얼.md — 서버/로그/백업/장애 5 시나리오 + 보안/API 키
docs/영업자료.md — 30초~30분 미팅별 피치 + 경쟁사 비교 + 가격 정책
docs/도입사례-더이룸학원.md — 검증 케이스 (네이버 733% 증가)
docs/FAQ.md — 30개 질문
docs/개인정보처리방침.md — 학원법 + 개인정보보호법 컴플라이언스

검증 결과

node server.js:

[modules] 11/11 라우터 로드됨
[auth] auth-routes 로드됨
[adapters] 어댑터 상태 라우트 로드됨
[server] started on port 9865 (env=development)
[server] health: /health /health/ready /health/metrics /health/version

엔드포인트 매트릭스:

경로	응답	의도
`/health`	200	공개
`/api/credit/plans`	200	공개
`/api/dt5/sdgs`	200	공개
`/api/tutorial/start` POST	200	공개 (튜토리얼)
`/api/students` GET	401	보호 (인증 필요)
`/api/scoring/list`	401	보호
`/api/adapters/status`	401	관리자 전용

Rate limit 헤더: X-RateLimit-Limit: 60, X-RateLimit-Remaining: 58, X-RateLimit-Reset: 60

디렉토리 구조 (최종)

crowny-academy/
├── server.js                       (라우터 + 보안 + 어댑터 통합)
├── ecosystem.config.js              (PM2)
├── .env.example, .gitignore
├── CLAUDE.md                       (v2.1)
├── adapters/                       (9 JS + README + PAY_INTERFACE)
│   ├── base.js, kakao.js, ocr.js, pay-stub.js, index.js, status-routes.js
│   └── external-ai/{mathflat,gge,passdream}.js
├── lib/                            (9 JS + SECURITY_INTEGRATION.md)
│   ├── auth.js, rate-limit.js, validators.js, security.js, auth-routes.js
│   └── config.js, logger.js, error-handler.js, health.js
├── modules/                        (10 모듈, scoring/report/notify/credit/tutorial/dt5/mandalart/external-ai/diagnosis/simulator)
├── 한선씨/                          (10 동반파일)
├── public/                         (4 HTML + assets + views/11개)
├── scripts/                        (21 파일: 운영/백업/시드/마이그레이션)
├── migrations/                     (2 마이그레이션 스크립트)
├── backups/                        (자동 백업 저장소)
├── docs/                           (11 문서: 마스터플랜/요약/매뉴얼/가이드/FAQ 등)
├── logs/                           (일별 로그)
└── 데이터/
    ├── 학생/반/출결/.../시드/      (운영 + 165 JSON 시드)
    └── 인증/                       (토큰 0600 권한)

환경변수 (.env.example)

NODE_ENV=production
PORT=9865
LOG_LEVEL=info
DATA_DIR=./데이터
ADMIN_TOKEN=<32-byte hex>
RATE_LIMIT_PER_MIN=60
KAKAO_MODE=mock           # → kakao-biz 전환 시 BIZ_TOKEN 필요
KAKAO_BIZ_TOKEN=
KAKAO_SENDER_KEY=
OCR_PROVIDER=mock         # → passdream/tesseract/naver-clova/google-vision
PASSDREAM_API_KEY=
MATHFLAT_MODE=mock
MATHFLAT_API_KEY=
GGE_MODE=mock
GGE_API_KEY=
PAY_MODE=mock             # → live 시 pay.crowny.org:9866 위임
PAY_URL=http://pay.crowny.org:9866
PAY_SECRET=               # HMAC webhook 서명
SEED_AUTO_LOAD=false      # 빈 데이터에서 자동 시드 로드

상용 도입 절차

cp .env.example .env → 키 채우기
node -e "require('crypto').randomBytes(32).toString('hex')" > .admin-token → ADMIN_TOKEN 발급
bash scripts/install-cron.sh install → 일별 백업 자동화
pm2 start ecosystem.config.js --env production
(선택) 시드 로드: bash scripts/load-seed.sh
카카오 비즈채널 신청 → KAKAO_MODE=kakao-biz
외부 AI 키 발급 (매쓰플랫/GGE/패스드림)
pay.crowny.org 서버 기동 → PAY_MODE=live

pay.crowny.org (별도 세션)

본 시스템과 별도 도메인. 포트 9866 예약 완료. 구현 명세:

/Users/ef/crowny-academy/adapters/PAY_INTERFACE.md
엔드포인트: /api/checkout, /api/checkout/:id, /api/refund, /api/methods
Webhook: pay → academy /api/credit/payment-webhook (HMAC 서명)
결제수단: 카드, 카카오페이, 네이버페이, 토스페이, 페이코, 계좌이체, 포네

잔여 이슈

백업 매니페스트 jq 파싱 경고 — backup.sh에서 일부 jq 호출에 unmatched brace. 백업 자체는 OK
시드 자동 로드 — SEED_AUTO_LOAD=true 시 동작 확인 필요
OCR 실제 연동 — 패스드림 API 키 필요 (현재 mock)
카카오 알림톡 — 비즈채널 발급 후 KAKAO_BIZ_TOKEN 적용 필요
arch.crowny.org 디자인 시스템 — verdant 톤 자체 정의로 완성, 실제 arch에서 가져오는 작업은 별도
HTTPS — gateway가 처리, 본 서버는 HTTP만

다음 단계

pay.crowny.org 별도 세션 진행
더이룸학원 실제 PoC (시드 → 실 데이터 교체)
카카오 비즈채널 + 패스드림/매쓰플랫/GGE 키 발급
학원 5~10개 미팅 (영업자료 활용)
60초 인스타 릴스 영상 제작