아이디 + 비밀번호(bcrypt 해시) + JWT. 화면은 frontend/login_ui/My Page.dc.html.
| 요청 | 본문 | 성공 | 실패 |
|---|---|---|---|
POST /api/auth/signup |
{ username, password, name, employee_no } |
201 { token, user } |
400 형식 오류, 409 USERNAME_TAKEN, 409 EMPLOYEE_NO_TAKEN |
POST /api/auth/login |
{ username, password, remember? } |
200 { token, user } |
401 INVALID_CREDENTIALS |
POST /api/auth/find-id |
{ name, employee_no } |
200 { username } |
400, 404 NOT_FOUND |
POST /api/auth/reset-password |
{ username, name, employee_no, password } |
200 { ok: true } |
400, 404 NOT_FOUND, 403 DEMO_ACCOUNT |
GET /api/auth/demo-accounts |
없음 | 200 { accounts, password } |
꺼져 있으면 { accounts: [], password: null } |
GET /api/auth/me |
헤더 Authorization: Bearer <token> |
200 { user } |
401 AUTH_REQUIRED, 401 TOKEN_INVALID |
user는{ id, username, role, name, employee_no }.role은trainee(신입사원) 또는admin(관리자). 회원가입은 항상trainee로 만든다.id는 UUID이고, 다른 테이블의user_id는 이 값을 쓴다.- 실패 응답은
{ error, code? }.error는 화면에 그대로 보여 줄 수 있는 한국어 문장이다. - 아이디: 영문 소문자·숫자·
_, 420자. 비밀번호: 8자 이상, UTF-8 72바이트 이하(bcrypt 한도). 이름: 120자. 사번: 영문·숫자·-3~20자, 대문자로 저장. - 없는 아이디와 틀린 비밀번호는 같은 응답을 준다(아이디 존재 여부를 알려 주지 않는다).
- 토큰 유효기간:
remember: true(로그인 상태 유지)면 7일, 아니면 12시간. 로그아웃은 프론트가 토큰을 지우는 것으로 한다.
GET /api/admin/trainees?include_demo=false (토큰 필요, admin만. 아니면 403 ADMIN_ONLY. include_demo는 선택)
{
"checkpoint_data": true,
"sections": ["ironmaking", "steelmaking", "continuous_casting", "rolling"],
"demo_sections": ["steelmaking", "continuous_casting", "rolling"],
"include_demo": true,
"trainees": [{
"id": "uuid", "username": "trainee01", "name": "김신입", "employee_no": "T2026001", "is_demo": false,
"created_at": "ISO", "last_activity": "ISO | null",
"sections": { "ironmaking": { "understanding": 0.92, "passed": true, "attempts": 1 }, "steelmaking": null },
"passed_sections": 1,
"misconceptions": { "open": 0, "resolved": 1 }
}]
}sections.{섹션}: 끝낸 체크포인트가 없으면null.understanding은 마지막으로 끝낸 시도의 이해도,passed는 한 번이라도 통과했는지.- 오개념은 개수만 준다. 설명·답변 원문은 본인만 본다.
- 체크포인트 테이블(
attempts,misconceptions)이 아직 없으면checkpoint_data: false와 빈 기록을 준다. - 실제 계정과 시연 계정을 섞어서 준다.
is_demo: true는 시연 계정(trainee02~20,users.is_demo)이고 화면에서 'demo' 배지를 붙인다.?include_demo=false면 시연 계정을 빼고 실제 계정만 준다.true·false밖의 값은400 INVALID_INCLUDE_DEMO. demo_sections: final 루브릭이 없어 시연 개념 목록(content/demo/sections.json)으로 계산한 섹션. 이 섹션은 시연 기록(origin = 'seed')만 센다.- 시연 기록:
npm run db:seed-demo [seed]가trainee0208·18·19), 진행 중 4(0920의 시연 기록(seed)을 지우고 다시 만든다(trainee01은 실제 테스트 계정이라 만들지 않음). 관리자 화면에서 골고루 보이게 사람마다 진도를 정해 둔다: 수료 8(0312), 재도전 필요 4(1316), 미시작 2(17·20), 시연용 trainee02는 정해 둔 시나리오(제선 재도전 뒤 통과, 제강 재도전 필요). 상태는 seed와 상관없이 같고, 점수·오개념 같은 세부 기록은 seed가 같으면 같다(예:npm run db:seed-demo -- 58).
GET /api/admin/report.csv?include_demo=false (토큰 필요, admin만): 위 신입사원 통계를 엑셀에서 바로 열리는 CSV(UTF-8 BOM, CRLF)로 내려받는다. 파일 이름은 신입사원_학습현황_YYYYMMDD.csv(filename*), 한 줄에 한 명: 이름·아이디·사번·시연 계정·상태(수료/재도전 필요/진행 중/미시작, 관리자 화면과 같은 규칙)·통과 공정·공정별 이해도(%)·결과·시도 횟수·미해결/해결 오개념 개념 수·마지막 학습(한국 시간)·가입일. 오개념 내용·답변 원문은 넣지 않는다. =·+·-·@로 시작하는 글은 엑셀이 수식으로 읽지 않게 '를 붙인다(backend/src/admin/report.ts).
GET /api/admin/trainees/:id (토큰 필요, admin만): 신입사원 한 명 상세. 관리자 화면에서 사람을 누르면 오른쪽 패널로 보여 준다(backend/src/admin/trainee-detail.ts). 신입사원이 아니거나 없으면 404 TRAINEE_NOT_FOUND.
trainee:/api/admin/trainees의 그 사람 항목과 같다(같은 숫자).sections[]: 공정 순서대로{ section, name, demo, stat, in_progress, concepts, attempts }.stat은 목록의 섹션 통계,in_progress는 끝나지 않은 시도의{ state, done, total },concepts[]는 지금 루브릭(없으면 시연 목록) 개념별{ concept_id, name, score, final_verdict }(묻지 않은 개념은score: null),attempts[]는 끝낸 시도{ kind, completed_at, understanding, unlocked }(오래된 순서).- 오개념은
trainee.misconceptions의 개수만 준다. 설명·답변 원문은 주지 않는다.
GET /api/admin/concepts?section=ironmaking&include_demo=false (토큰 필요, admin만. section·include_demo는 선택): 신입사원이 끝낸 체크포인트(재도전 포함)의 첫 질문 판정으로 섹션·개념별 asked, partial, wrong, assisted, final_wrong을 집계하고 미해결 오개념 수 open을 돌려준다. 지금 final 루브릭(없는 섹션은 시연 개념 목록)에 있는 개념은 화면용 개념 이름 name도 붙는다. include_demo는 /api/admin/trainees와 같다. 관리자 화면의 개념 순위는 이 DB 응답으로 계산한다.
final_wrong: 재확인 판정도wrong인 수.open: 신입사원 전체의 미해결 오개념 수(체크포인트·학습 모드 모두).concept_id는 루브릭 개념 id다(시연 기록은 설비 id). 답변 원문·오개념 설명·사용자 id는 주지 않는다.section이 섹션 4개 중 하나가 아니면400 INVALID_SECTION. 체크포인트 테이블(attempts,concept_results)이 없으면 빈 목록을 준다.
GET /api/admin/ai-summary?section=ironmaking (토큰 필요, admin만. section은 선택): 오답률 높은 개념을 Gemini가 "보강할 내용" 1~2문장으로 정리한다.
{ "summary": "고로에서 코크스의 역할은 …", "concepts": [{ "section": "ironmaking", "concept_id": "coke_reduction", "name": "고로에서 코크스의 역할" }],
"generated_at": "2026-10-06T01:32:00.000Z", "cached": false }- 입력은
/api/admin/concepts와 같은 집계에서 지금 final 루브릭 개념(name있음) 중 정답이 아닌 첫 답변이 있는 개념 상위 5개의 숫자와 공정·개념 이름뿐이다. 답변 원문·오개념 설명·사용자 id는 LLM에 보내지 않는다. - 집계할 기록이 없으면 LLM을 부르지 않고
summary: null. - 같은 집계면 10분 동안 저장한 요약을 준다(
cached: true). 기록이 바뀌면 새로 만든다. - LLM 호출은 관리자 계정의 하루 호출 수(
LLM_DAILY_LIMIT)에 함께 센다. 넘으면429 USAGE_LIMIT. GEMINI_API_KEY가 없거나 호출이 실패하면503/502 LLM_UNAVAILABLE. 화면은 요약 대신 안내 문장을 보여 주고 나머지는 그대로 쓴다.
메일 발송 수단이 없어서 이름 + 사번으로 본인 확인을 한다.
- 아이디 찾기: 이름과 사번이 맞으면 아이디를 그대로 보여 준다.
- 비밀번호 찾기: 아이디·이름·사번이 모두 맞으면 바로 새 비밀번호로 바꾼다.
- 확인에 실패하면 0.5초 늦게 답해 대입 시도를 느리게 한다.
- 이름과 사번을 아는 사람은 비밀번호를 바꿀 수 있으므로 시연·사내용 수준이다. 실제 운영 전에 메일·관리자 승인 같은 확인 수단을 팀에서 정한다.
서버가 시작할 때 없는 계정만 만든다. 비밀번호는 모두 같다(기본 steel-2026-demo, .env의 DEMO_PASSWORD로 변경).
| 아이디 | 역할 | 이름 | 사번 |
|---|---|---|---|
trainee01 ~ trainee20 |
trainee | 김신입, 이신입, 박신입, 최신입, 정다은 … 전소율(20명, demo-accounts.ts) |
T2026001 ~ T2026020 |
admin01 |
admin | 관리자 | A2026001 |
- 로그인 화면의 일반 사용자 / 관리자 토글이
GET /api/auth/demo-accounts로 계정을 받아, 누르면 아이디·비밀번호 칸을 채운다. 목록에 사번은 내보내지 않는다. - 시연 계정은 여럿이 같이 쓰므로 비밀번호 재설정을 막는다(
403 DEMO_ACCOUNT). - 외부에 열 때는
DEMO_ACCOUNTS=off로 끈다(계정 생성과 목록 모두 꺼짐). DEMO_PASSWORD는 새로 만드는 계정에만 적용된다. 이미 만든 계정의 비밀번호는 바꾸지 않는다.
- 서버가
/login을frontend/login_ui/My Page.dc.html로 보낸다. 파일을 브라우저에서 바로 열면 API를 부를 수 없다. - 토큰은 로그인 상태 유지면
localStorage, 아니면sessionStorage의st-rookie-token에 둔다. - 첫 화면에서
GET /api/auth/me로 확인하고,401이면 토큰을 지우고 로그인 화면을 보여 준다. - 다른
/api요청에는Authorization: Bearer <token>헤더를 붙인다.
.env의JWT_SECRET으로 서명한다. 비어 있으면 실행할 때마다 임시 키를 만들어서, 서버를 다시 켜면 로그인이 모두 풀린다.- 계정은 SQLite
users테이블(backend/src/db/migrations/003_users.sql)에 저장한다. DB 위치는DB_PATH, 기본값data/st-rookie.sqlite.
GET /api/me/misconceptions[?section=ironmaking] (토큰 필요, 없으면 401 AUTH_REQUIRED)
- 로그인한 본인의 오개념만 최근 것부터 준다(라우트
backend/src/me/routes.ts, SQL은me/repository.ts). 다른 사람의 기록은 어떤 값을 넣어도 볼 수 없다(사용자는 토큰으로만 정한다). - 항목:
id, section, concept_id, source, label, summary, answer_text, resolved, created_at, resolved_at. label: 학습 모드(source=learning)는 "대화 중 감지됨", 체크포인트는 "이해도 확인"(backend/src/learning/labels.ts, 학습자 메모와 같은 라벨).
GET /api/me/dashboard (토큰 필요, trainee만): 본인의 trainee 통계, review_concepts, misconceptions, 섹션 목록과 checkpoint_data를 돌려준다. 다른 신입사원의 이름이나 학습 기록은 포함하지 않는다.
/api요청에Authorization: Bearer <token>이 있으면 토큰의 사용자 id(users.id)로 구분한다. 체크포인트(userIdOf(req)), 학습 모드·LLM 사용량(currentUserId())이 모두 이 id를 쓴다. 토큰이 틀리거나 만료됐으면 401TOKEN_INVALID.- [임시] 토큰이 없으면 예전처럼
X-User-Id헤더, 그것도 없으면demo-user. 모든 화면이 토큰을 보내게 되면 지운다. - 관리자 통계는
users.id기준이므로, 토큰을 보내기 전에 헤더 이름으로 쌓인 기록은 통계에 잡히지 않는다.
- 화면이 저장된 토큰(
st-rookie-token)을/api요청에 붙여야 한다: 3D 페이지 학습 채팅(learning-chat.js), 체크포인트 테스트 페이지(checkpoint-test.html). - 새 신입사원 대시보드는
/api/me/dashboard, 관리자 대시보드는/api/admin/trainees와/api/admin/concepts의 DB 응답을 표시한다.