진로 잠재력 내비게이터

초·중·고 학교급을 학생이 직접 고르면, 그 수준에 맞는 문항 세트로 DISC·MBTI·다중지능·RIASEC 네 가지 검사를 풀고 곧바로 채점 결과를 봅니다. 네 검사를 모두 마치면 학교급에 맞춰 조언 수준이 달라지는 AI 종합 진로보고서를 만들어 인쇄·워드 저장·텍스트 복사로 내보낼 수 있습니다. Node.js와 Express로 만든 작은 웹앱이라 npm start 한 줄로 돌아가고, 학생 답변은 서버가 아니라 학생 브라우저에만 저장됩니다.

배포(인터넷 주소 만들기)는 DEPLOY.md에 따로 정리해 두었습니다.

바로 써 보기: https://gg-web-cmd.github.io/jinro-navigator/ — 깃허브 페이지스에는 서버가 없어 AI 대신 기본 분석 엔진으로 보고서가 만들어집니다.

---

1. 학교급별 문항 구성

학생이 첫 화면에서 초등학생 / 중학생 / 고등학생 중 하나를 고릅니다. 고른 급에 따라 척도(유형) 하나당 문항 수가 달라지고(초 3 · 중 5 · 고 7), 그래서 총 문항 수도 달라집니다. 아래 숫자는 node scripts/check-questions.mjs 를 실제로 돌려 나온 값입니다.

🌱 초등학생 (4~6학년) — 총 66문항 · 약 15분

검사	문항 수	응답 방식	앱 표시 예상 시간
DISC 행동유형	12문항 (유형당 3)	5점 리커트	약 3분
MBTI 성격유형	12문항 (지표당 3)	A/B 둘 중 하나	약 3분
다중지능(MI)	24문항 (지능 8개 × 3)	4점 리커트	약 5분
RIASEC 직업흥미	18문항 (유형당 3)	4점 리커트	약 4분
합계	66문항	—	약 15분

🌿 중학생 — 총 110문항 · 약 25분

검사	문항 수	응답 방식	앱 표시 예상 시간
DISC 행동유형	20문항 (유형당 5)	5점 리커트	약 5분
MBTI 성격유형	20문항 (지표당 5)	A/B 둘 중 하나	약 5분
다중지능(MI)	40문항 (지능 8개 × 5)	4점 리커트	약 8분
RIASEC 직업흥미	30문항 (유형당 5)	4점 리커트	약 7분
합계	110문항	—	약 25분

🌳 고등학생 — 총 154문항 · 약 35분

검사	문항 수	응답 방식	앱 표시 예상 시간
DISC 행동유형	28문항 (유형당 7)	5점 리커트	약 6분
MBTI 성격유형	28문항 (지표당 7)	A/B 둘 중 하나	약 6분
다중지능(MI)	56문항 (지능 8개 × 7)	4점 리커트	약 13분
RIASEC 직업흥미	42문항 (유형당 7)	4점 리커트	약 10분
합계	154문항	—	약 35분

여기에 종합 보고서 생성 시간 1~2분이 더 붙습니다(앱 안내 문구 기준). 초등급은 문항뿐 아니라 척도 라벨과 유형 설명도 쉬운 말 버전으로 바뀝니다. (예: "매우 그렇다" → "완전 나야")

문항 내용은 2026년 기준으로 새로 썼습니다

• 생성형 AI(챗봇으로 찾은 답을 다시 확인하기), 숏폼 영상 만들기, 기후·환경 같은 지금 아이들의 생활 소재가 문항에 들어 있습니다.
• 유형 설명과 직업 예시도 2026년 시점에 맞춰 갱신했습니다.
• 프롬프트에도 2026년 공통 지침이 들어 있어, AI 보고서가 "이 직업은 사라진다" 같은 겁주는 표현을 쓰지 않고, AI를 함께 쓰는 도구로 삼아 일하는 모습을 그려 주도록 되어 있습니다. (lib/prompt.js 의 ERA_2026)

보고서 조언이 급마다 다릅니다

학교급	보고서에서 달라지는 부분
초등	학과·전공·대학·입시 이야기를 한 글자도 쓰지 않습니다. "관심 가져볼 만한 학과 5가지"는 "더 알고 싶은 직업 세계 5가지" 로, SWOT은 "나의 보물지도"(잘하는 것 / 더 크는 중인 것 / 나를 도와줄 기회 / 조심할 점)로 바뀝니다.
중학	자유학기(자유학년) 주제선택·진로탐색, 동아리 선택, 3학년 2학기 진로연계학기와 연결합니다. 고교 유형(일반고·특성화고·특목고·마이스터고) 힌트를 한 단락 넣되 단정하지 않습니다. 학과는 계열 수준으로만 넓게 제시합니다.
고교	고교학점제 선택과목을 일반선택 / 진로선택 / 융합선택으로 나눠 추천하고, 학생부 관점(탐구활동·독서·동아리)을 제시하며, 학과는 실제 존재하는 구체적 학과명으로 씁니다. 입시 제도·합격 가능성은 단정하지 않습니다.

이 차이는 AI 보고서뿐 아니라 키 없이 도는 폴백 보고서에도 똑같이 적용됩니다. 다만 위 괄호 안의 네 칸 이름은 AI에게 주는 지시문(lib/prompt.js) 기준이고, 폴백 보고서(lib/fallback.js)는 같은 네 칸을 "내가 이미 가진 보물 / 더 키우면 좋을 보물 / 나를 도와줄 사람과 기회 / 조심하면 좋은 것"이라는 조금 다른 말로 씁니다.

---

2. 빠른 시작

1) Node.js가 깔려 있는지 확인

node -v

v18.0.0 이상이면 됩니다(package.json 의 engines 가 >=18). 숫자가 안 나오고 오류가 뜨면 nodejs.org에서 LTS 버전을 설치한 뒤 터미널을 새로 열어 다시 확인하세요.

2) 프로젝트 폴더로 이동

cd C:\vibe\진로

3) 필요한 패키지 설치 (처음 한 번만)

npm install

설치되는 것은 express 와 dotenv 두 개뿐입니다.

4) 설정 파일(.env) 만들기

copy .env.example .env

macOS·Linux라면 이렇게 합니다.

cp .env.example .env

API 키가 없어도 앱은 동작합니다. 아래 3번 항목을 보고 키를 넣으면 AI 보고서가, 비워 두면 기본 분석 엔진 보고서가 나옵니다.

5) 문항 데이터가 정상인지 확인 (선택)

npm run check

"모든 검사를 통과했습니다"가 나오면 문항 수·유형 분포·중복 여부가 모두 정상입니다.

6) 서버 실행

npm start

터미널에 아래처럼 뜨면 성공입니다.

  진로 잠재력 내비게이터 서버가 시작되었습니다.
  접속 주소  : http://localhost:3000
  AI 연결    : 설정됨 (모델 solar-pro4)
  종료하려면 Ctrl + C 를 누르세요.

7) 브라우저로 접속

http://localhost:3000

서버를 끄려면 터미널에서 Ctrl + C 를 누릅니다. 파일을 고치면서 작업할 때는 npm start 대신 아래를 쓰면 서버 파일이 바뀔 때 자동으로 재시작됩니다.

npm run dev

---

3. Upstage API 키 발급과 .env 작성

이 앱의 AI 보고서는 Upstage의 Solar 모델(https://api.upstage.ai/v1/chat/completions)을 호출합니다.

키 발급

1. https://console.upstage.ai 에 접속해 로그인(또는 회원가입)합니다.
2. 콘솔에서 API Keys(API 키) 메뉴로 들어갑니다.
3. 새 키를 발급하고, 화면에 표시된 키 문자열을 복사합니다. 키는 발급 직후에만 전체가 보이는 경우가 많으니 그 자리에서 복사해 두세요.
4. 사용량과 잔여 크레딧도 같은 콘솔에서 확인할 수 있습니다. (콘솔 화면 구성은 서비스 쪽 사정으로 바뀔 수 있습니다.)

.env 작성

프로젝트 폴더(= server.js 가 있는 폴더)의 .env 파일을 메모장으로 열고 아래처럼 채웁니다.

UPSTAGE_API_KEY=up_여기에_발급받은_키를_붙여넣기
UPSTAGE_MODEL=solar-pro4
PORT=3000

• 따옴표 없이, = 앞뒤에 빈칸 없이 붙여 씁니다.
• .env 를 고친 뒤에는 서버를 껐다 다시 켜야 반영됩니다.
• UPSTAGE_MODEL 은 특별한 이유가 없으면 그대로 두세요. 비워 두면 solar-pro4 가 쓰입니다.
• PORT 는 3000번이 이미 쓰이고 있을 때만 바꾸면 됩니다.

이 세 개가 이 앱이 읽는 환경변수의 전부입니다.

⚠️ 키는 절대 깃허브에 올리지 마세요

• API 키는 비밀번호와 같습니다. 공개 저장소에 올라간 키는 자동 수집 봇이 몇 분 만에 찾아내 남의 결제로 쓰입니다.
• 이 프로젝트의 .gitignore 에는 이미 .env 와 .env.* 가 들어 있고 .env.example 만 예외로 두었습니다. .env.example 만 커밋하고 .env 는 절대 커밋하지 마세요.
• 키를 코드 안(server.js 등)에 직접 적어 넣지 마세요.
• 실수로 올렸다면 커밋을 지우는 것만으로는 부족합니다. Upstage 콘솔에서 해당 키를 즉시 폐기(revoke)하고 새 키를 발급하세요. 자세한 사고 대처 순서는 DEPLOY.md 2번에 있습니다.
• 학생 PC에 프로젝트 폴더를 통째로 복사해 나눠 줄 때도 .env 는 빼고 주세요.

---

4. 키가 없어도 완전히 동작합니다 (폴백 보고서)

키를 넣지 않았거나, 넣었는데 호출이 실패해도 앱은 오류 화면 대신 보고서를 반드시 돌려줍니다. lib/fallback.js 의 규칙 기반 엔진이 검사 결과를 그대로 읽어 학교급에 맞는 보고서를 만들어 줍니다.

폴백으로 넘어가는 경우는 세 가지이고, 각각 화면에 다른 안내 문구가 뜹니다.

상황	화면 안내
.env 에 키가 없음	"AI 연결 설정이 아직 되어 있지 않아, 기본 분석 엔진으로 보고서를 만들었어요."
키 오류·네트워크 오류·120초 시간 초과	"AI 서버와 연결이 원활하지 않아, 기본 분석 엔진으로 보고서를 만들었어요."
같은 IP에서 1시간에 30회 초과	"지금 보고서 요청이 많아 기본 분석 엔진으로 보고서를 만들었어요."

폴백 보고서도 학생의 실제 점수·유형·순위를 정확히 반영하고, 초등이면 "나의 보물지도", 중학이면 자유학기·고교 유형, 고교면 고교학점제 선택과목까지 급별로 다르게 나옵니다. 다만 AI 보고서처럼 네 검사를 자유롭게 엮어 새 문장을 쓰지는 못하고 미리 준비된 설명을 조합하므로, 학생마다 겹치는 문장이 생깁니다.

보고서 화면 위쪽에 어떤 엔진으로 만들었는지 표시되고(solar-pro4 또는 rule-based), 폴백일 때는 안내 상자와 함께 "🔄 다시 생성" 버튼으로 재시도할 수 있습니다.

참고: 키를 넣지 않으면 서버가 Upstage를 아예 호출하지 않습니다. 즉 검사 결과가 외부로 나가지 않습니다. 개인정보가 특히 조심스러운 상황이라면 키 없이 운영하는 것도 정당한 선택지입니다.

---

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗