Center

작업 승인 → 게이트 안전검증 → 작업이력·자격 관리를 하나로 묶은 산업 현장 출입통제 웹입니다.

2026 미래내일 일경험 지원사업 — AI·로봇 안전제어 솔루션 챌린지 4기 팀 Ctrl+Z · 이 저장소는 웹(프론트엔드 + 백엔드 + DB) 범위입니다. 키오스크는 NVIDIA Jetson Orin에서 별도 구현되며, 이 저장소와는 API 계약으로만 만납니다.

---

무엇을 강제하는가

종이 작업허가서와 단순 출입카드는 "확인"에서 멈추고 출입 자체에는 개입하지 않습니다. 이 시스템은 세 가지를 시스템이 강제합니다.

1. 팀장 승인 없이는 키오스크에 작업이 뜨지 않습니다 → 입장 시도 자체가 불가능
2. 자격이 만료되면 검증 단계에 들어가기 전에 차단됩니다
3. 모든 인증·검증·승인이 자동으로 기록되어 사후 추적이 됩니다

---

화면

코드	경로	화면	누가 보나
W1	/login	로그인	전원
—	/signup	가입 신청	계정 없는 사람 (인증 없이 열림)
W2	/requests/new	작업 승인 요청	작업자 · 팀장
W3	/approvals	팀장 승인함	팀장
W4	/dashboard	관제 대시보드	전원
W5	/me	마이페이지	작업자 · 팀장
—	/notes	작업장별 특이사항	전원
—	/admin	계정 관리	안전관리자

/dashboard/sessions/[id] 는 관제에서 작업 제목을 눌러 들어가는 세션 상세입니다. 아래쪽에 게이트 3D 시뮬레이션(Unity WebGL, center-web/public/safety-gate-3d/)이 붙어 있어, 서버가 판정한 검증·문 열림·입장을 그림으로 다시 보여줍니다. 판정은 서버가 하고 3D 는 재생만 합니다.

---

기술

구분	선택	이유
프레임워크	Next.js 16 (App Router)	Route Handler가 백엔드 역할. 서버와 화면을 한 프로젝트에
언어	TypeScript · React 19	권한·상태를 타입으로 좁혀 잘못된 값을 못 만들게
스타일	CSS Modules + 디자인 토큰	경계선을 border가 아니라 inset box-shadow로 그리는 스펙이라 유틸리티 클래스와 안 맞음
DB	Firebase Firestore	실시간 구독이 관제 화면에 그대로 맞음
인증	Firebase Auth + 커스텀 클레임	역할을 토큰에 박아 서버가 검증
실시간	Server-Sent Events	방향이 서버→클라이언트 한쪽뿐이라 WebSocket 불필요

---

설계 원칙

클라이언트는 DB를 직접 만지지 않습니다. Firestore 보안 규칙은 전부 잠겨 있고(center-web/firestore.rules), 서버만 Admin SDK로 접근합니다. 규칙에 로직을 흩어놓으면 나중에 무엇이 무엇을 막는지 추적이 안 됩니다.

권한은 토큰에서 읽습니다. 역할은 Firebase Auth 커스텀 클레임에 있고, 서버가 verifyIdToken으로 확인한 값만 씁니다. 요청 본문의 역할은 믿지 않습니다.

파생값은 저장하지 않습니다. 자격의 유효/임박/만료는 expiresOn에서, 연차는 hiredOn에서 매번 계산합니다. 상태를 컬럼으로 굳히면 배치 없이는 반드시 썩습니다.

젯슨은 관찰만 보고하고 상태를 주장하지 않습니다. 카드 UID를 09:04:12에 읽었다 ✅ / 인원 충족됐으니 문 열어 ❌ 상태 전이와 화면 문구는 서버가 계산해 응답으로 내려줍니다. 계약 전문은 center-web/lib/gate-contract.ts 한 파일입니다.

---

실행

cd center-web
npm install
cp .env.local.example .env.local   # 값을 채워야 동작합니다
npm run dev

.env.local은 저장소에 없습니다. Firebase 콘솔에서 직접 받아야 합니다 — 웹 앱 config 6개(프로젝트 설정 → 내 앱)와 서비스 계정 키(프로젝트 설정 → 서비스 계정). 어떤 값이 어디서 오는지는 .env.local.example 주석에 적어뒀습니다.

스크립트

node --env-file=.env.local scripts/check-firebase.mjs    # 연결 확인
node --env-file=.env.local scripts/seed.mjs              # 컬렉션 생성 + 시드 + 계정 발급
node --env-file=.env.local scripts/reset-requests.mjs    # 시연 전 초기화

seed.mjs는 여러 번 돌려도 안전합니다. 진행중 세션은 실행 시점 기준으로 다시 만들어지므로, 시연 직전에 한 번 돌리면 관제 화면의 경과 시간이 그럴듯해집니다.

seed.mjs를 돌리면 Auth 계정이 다시 만들어져 열어둔 브라우저는 로그아웃됩니다. 다시 로그인하면 됩니다.

계정

아이디 = 사번, 초기 비밀번호 = 사번 + 1234

사번	이름	역할	비밀번호
202533690	김병오	팀장 (승인자)	2025336901234
202533795	윤지윤	안전관리자	2025337951234
202533872	정천호	작업자	2025338721234
202633671	박상하	작업자	2026336711234

사번은 scripts/seed-data.mjs의 TEAM 한 곳에서만 정의합니다 — 세션·요청·출입기록이 전부 사번을 참조해서, 흩어놓으면 하나 바꿀 때 참조를 빠뜨립니다.

---

배포

main에 push하면 Vercel이 자동으로 재배포합니다. 따로 할 일이 없습니다.

• 저장소 — ctrlz-2026/Ctrl-Center-web (조직 ctrlz-2026)
• 배포 — ctrl-center-web.vercel.app
• Vercel 프로젝트 Root Directory는 center-web

환경변수는 저장소가 아니라 Vercel 대시보드에 있습니다 (Settings → Environment Variables). 로컬 .env.local과 같은 10개입니다.

저장소가 Public인 이유 — Vercel Hobby 플랜은 조직의 Private 저장소를 배포하지 못합니다. 비밀키는 .env.local에만 있고 그 파일은 .gitignore에 있어 올라가지 않으므로 공개로 돌렸습니다.

---

다른 컴퓨터에서 이어받기

git clone https://github.com/ctrlz-2026/Ctrl-Center-web.git
cd Ctrl-Center-web/center-web
npm install

그다음 .env.local을 직접 넣어야 합니다 — 저장소에 없습니다. 가장 빠른 방법은 쓰던 컴퓨터의 center-web/.env.local을 그대로 복사하는 것이고, 없으면 Firebase 콘솔에서 다시 받습니다(.env.local.example 주석 참고).

node --env-file=.env.local scripts/check-firebase.mjs   # 연결부터 확인
npm run dev

Firestore는 클라우드에 있으므로 시드를 다시 돌릴 필요가 없습니다. 데이터가 이미 들어 있고, 컴퓨터가 바뀌어도 그대로 보입니다.

---

구조

center-web/
  app/
    (auth)/login/            W1
    (auth)/signup/           가입 신청 (인증 없이 열림)
    (app)/requests/new/      W2
    (app)/approvals/         W3
    (app)/dashboard/         W4
      sessions/[id]/         세션 상세 — 젯슨 시뮬레이션 자리
    (app)/me/                W5
    (app)/notes/             작업장별 특이사항
    (app)/admin/             계정 관리 (안전관리자)
    icon.svg                 파비콘 (ZC 키캡 로고)
    api/
      me/ · requests/        웹용 (Firebase ID 토큰)
      notes/                 작업장별 특이사항
      signup/                가입 신청 — 유일하게 인증 없이 열린 경로
      admin/accounts/        계정 목록 · 역할/비번/활성
        [empNo]/profile/     자격 · 사원증 · 얼굴등록 · 작업배정
        [empNo]/face-template/  얼굴 등록 상태 · 벡터 파일 올리기 · 삭제
      admin/signups/[id]/    가입 승인·거절
      stream/requests/       SSE 실시간
      gate/events/           젯슨 수신구 (기기 키)
      gate/[gateId]/         번들 · 선택된 작업 · 얼굴 등록(사번 확인 · 완료 알림) · 얼굴 벡터 내려받기 (기기 키)
      kiosk/[gateId]/        키오스크 화면용 (작업 선택 · 사원증 태그 · 상태 · 종료)
  components/                Button · Badge · Card · DataTable · Field · Logo · TopNav …
  lib/
    firebase/                client · admin · queries · dashboard · auth-guard · user
    gate-contract.ts         젯슨과 맞추는 계약 (이 파일만 넘기면 됨)
    types.ts                 권한 함수가 여기 한 곳에만 있음
  scripts/                   시드 · 초기화 · 연결확인
docs/
  backend-design.md          스키마 · API · 실시간 설계 · 결정 기록
  screenshots/               화면 캡처

고칠 때 어디를 보나

바꾸고 싶은 것	파일
누가 무엇을 할 수 있나	lib/types.ts (권한 함수가 여기에만 있음)
색·모서리·여백	app/tokens/center.css (개별 화면 CSS 말고 여기)
사번·시드 데이터	scripts/seed-data.mjs
젯슨과의 약속	lib/gate-contract.ts
왜 그렇게 했는지	docs/backend-design.md

---

현재 상태

동작하는 것 — 로그인·권한 3역할, 회원가입과 관리자 승인, 계정 관리(비밀번호 초기화·역할 변경·비활성화), 자격/사원증/얼굴등록/작업배정 관리, 승인 워크플로우 (Firestore 영속), 실시간 관제, 작업장별 특이사항, 개인별 출입기록, 젯슨 수신구(중복 제거·형식 검증). 전부 배포돼 있습니다.

결정해서 굳힌 것 (배경은 docs/backend-design.md)

• 문이 열리면 곧 작업 시작 — "문은 열렸는데 아직 작업 전" 상태를 두지 않습니다
• 팀장도 작업을 신청하고, 본인 요청을 본인이 승인합니다. 팀장도 현장에 들어가는데 승인자가 한 명뿐이라 막으면 게이트를 통과할 수 없습니다. 대신 selfApproved로 기록에 남깁니다
• 작업 배정과 자격은 별개의 조건입니다. 배정 확인은 서버, 자격 확인은 게이트
• 얼굴 사진은 저장하지 않습니다. 젯슨이 만든 특징 벡터만 안전관리자가 파일로 올려 등록하고, 암호화해 보관하며 게이트 기기만 내려받습니다 (브라우저로는 다시 나가지 않습니다)

아직인 것

• PPE 학습 클래스 확정 대기: ppeItems.yoloClass가 helmet 외 전부 null. 모델이 못 잡는 항목을 작업코드 필수 보호구에 넣으면 착용하고 서 있어도 영원히 통과 못 합니다.
• 사원증 실물 배송 대기: employeeCards가 TEMP-* UID, pending: true (관리자 콘솔에서 실물 UID를 넣을 수 있게는 해뒀습니다)
• 게이트 세션 상태 계산: 인원 충족·해정 판정은 젯슨 연동 후
• 첫 로그인 비밀번호 변경 강제: 초기 비밀번호가 사번에서 유추되는 값입니다
• 작업코드 표기: 글자 하나(A~H, J)를 씁니다. 팀장 「작업 기준 설계」 표는 A-3·B-7 형식이지만 뒤 숫자가 인원·시간·위험도 어느 것과도 무관한 임의값이라, 내용은 표 그대로 두고 표기만 줄였습니다(팀 결정 2026-09-01). 대조표는 scripts/seed-data.mjs 의 workCodes 주석 참고. I 는 숫자 1 로 읽혀 건너뜁니다
• G-2 확인 대기: 표에 도장부스 필수 PPE 로 안전모가 없습니다(다른 작업과 달라 눈에 띔). 자격도 "관련 안전교육 이수"로만 적혀 있어 정식 명칭이 필요합니다
• PRD 아키텍처 충돌: PRD 8장은 "젯슨이 서버, 웹은 시각화 클라이언트"인데 현재 구현은 반대. 하이브리드 안을 회의 안건으로 올려둔 상태