ShotTrace

사출성형 공장의 생산 실적과 품질 이력을 관리하는 MES. LOT과 설비 상태를 시간 구간으로 잇는 것이 이 시스템의 핵심이다.

제조 IT 22년 경력자 인터뷰로 요구사항을 도출했고, KAMP 공개 실데이터(사출성형기 부품 5,232개 = 샷 2,626번 × 공정변수 24개)를 시간축으로 재생해 사용한다. ISA-95 Level 3에 해당한다.

배포 — https://shot-trace.vercel.app · 로그인 화면의 「둘러보기로 시작」 버튼으로 읽기 전용 체험 현재 상태 — 기능 · 화면 완성 (2026-10-27) · 시연 리허설만 남음 · 2026-08 시작

화면	현황판(실시간) · LOT 추적(+ LLM 대응 가이드) · 품질 · OEE · 실적 입력/정정 · 비가동 · 마스터
데이터베이스	PostgreSQL 마이그레이션 29개 · 표 15 · View 9 · RPC 4 · RLS 역할 3 · 마스터 변경 이력(트리거)
검증	자동 테스트 119 (Vitest 84 · pytest 12 · Playwright 23) · CI · 제약 실험 13/13 · RLS 전수 점검
설계 기록	ADR 19개 — 결정마다 버린 대안 포함

한 문장 · 30초 · 5분 설명 — docs/설명.md

---

왜 시간 구간 조인인가

현장에서 추적하는 목적은 자재가 아니라 **"그 LOT을 만들 때 설비가 어땠나"**이다. 인터뷰에서 이 얘기를 듣고 설계를 바꿨다.

그래서 설비가 보내는 샷(shot)에는 lot_id 가 없다. equipment_id 와 measured_at 만 갖고, LOT 조회는 항상 시간 범위로 조인한다. 설비는 지금 어떤 LOT 을 만드는지 모르기 때문이다(ADR 001).

-- LOT 하나를 클릭하면 이 쿼리가 돈다
SELECT s.*, sp.pass_or_fail, sp.fail_reason
FROM   production_lot l
JOIN   shot s       ON s.equipment_id = l.equip_cd
                   AND s.measured_at >= l.started_at    -- 반열린 구간 [시작, 끝)
                   AND s.measured_at <  l.ended_at
JOIN   shot_part sp ON sp.equipment_id = s.equipment_id
                   AND sp.measured_at  = s.measured_at
                   AND sp.product_id   = l.product_id
WHERE  l.lot_id = :lot_id
ORDER  BY s.measured_at;

24개 공정변수와 불량 여부 · 사유가 이 한 번의 시간 범위 조회로 나온다. 불량이 언제 났고 그 직전 온도 · 압력이 어땠는지가 붙는다.

• 현장 MES 와의 차이 — 현장은 "지금 이 설비가 하는 작업" 에 신호를 쓸 때 묶는다. 이 프로젝트는 읽을 때 잇는다 — 늦게 온 신호와 LOT 경계 수정에 강한 대신 조인 비용을 인덱스로 감당한다
• 인덱스 — 10배 데이터에서 LOT 하나 조회 0.47 ms, 인덱스를 끄면 13.8 ms (차이 4.5배 → 30배) — evidence/perf-10x
• 패밀리 금형 — S14 는 한 샷에 LH · RH 두 부품을 찍는다. 공정변수는 샷의 속성, 품질은 부품의 속성이라 표를 나눴다(ADR 005)
• 겹침 금지 — 같은 설비 · 제품의 LOT 구간이 겹치면 DB 가 거절한다(EXCLUDE · 23P01)

---

아키텍처

flowchart LR
    CSV[(KAMP CSV)] --> SIM[시뮬레이터<br/>Python]
    SIM -- MQTT QoS 1 --> MQ[Mosquitto]
    MQ --> COL[수집기<br/>Python]
    COL -- upsert 멱등 --> DB[(PostgreSQL<br/>Supabase)]
    DB -- 변경 알림 Realtime --> WEB[Next.js<br/>Vercel]
    WEB -- 다시 읽기 · RLS --> DB
    U((작업자 · 관리자)) -- 실적 · 정정 · 비가동 --> WEB
    subgraph compose [docker compose]
        MQ
        COL
    end

• Level 2 → 3 — 실제 공장이라면 센서 → PLC → 게이트웨이가 MQTT 앞단에 붙는다. 그 부분만 시뮬레이터로 대체했고 브로커 이후는 실제와 구조가 같다
• 알림은 신호, 값은 DB 에서 — 화면은 "바뀌었다" 는 알림이 오면 서버에서 다시 읽는다(1초 throttle). 알림을 놓쳐도 틀리지 않는다(ADR 012)
• 두 시각 — 샷은 이벤트 시각(측정)과 처리 시각(수신)을 따로 갖는다(ADR 010)
• 입구는 친절, 문지기는 RLS — 로그인 · 화면 이동은 proxy 가 안내하고, 무엇을 읽고 쓸 수 있는지는 DB 의 RLS 가 정한다(ADR 013)

---

기록과 무결성

무엇	어떻게	기록
역할	viewer(읽기) · worker(실적 · 비가동 쓰기) · admin(마스터) — 역할은 표에, 바꾸면 즉시	ADR 013
장부는 고치지 않는다	실적 · 비가동에 UPDATE · DELETE 정책이 없다. 정정 = 취소 장부의 빨간 줄 + 새 줄	ADR 013 · 014
같은 제출은 한 줄	제출마다 번호표(request_id UNIQUE) — 더블클릭 · 재전송	ADR 013
정정은 한 번에 · 한 번만	취소 + 새 줄을 함수 하나(트랜잭션)로 · 동시 정정은 취소 장부의 PK 가 거절	ADR 014
마스터는 지우지 않는다	사유 명단은 사용 중지 · admin 만 · 가리키는 기록이 있으면 FK 가 막는다	ADR 015
OEE	가동률 × 성능 × 품질 · 셋업은 손실 · 성능은 샷 수 · 100% 상한과 자르기 전 값	ADR 016
LLM 대응 가이드	그 LOT 의 숫자만 보내고 근거는 변수 이름만 받는다 — 화면의 숫자는 DB 에서 · worker 만 · 저장해서 다시 쓴다	ADR 017

전체 표와 관계는 docs/schema.md (ERD) 에 있다.

---

LLM 대응 가이드 — 같은 버튼, 다른 데이터, 다른 답

불량이 난 LOT 에서 버튼을 누르면 그 LOT 의 숫자(변수별 양품/불량 평균 · 불량 위치 · 비가동)만 Claude 에게 보내고, 의심 원인과 점검할 곳을 받는다. 회색 근거 줄의 숫자는 Claude 가 쓴 게 아니라 DB 에서 센 값이다 — Claude 는 근거가 된 변수의 이름만 고른다(ADR 017).

불량이 초반에 몰린 LOT	불량이 흩어진 LOT
"LOT 초반 연속된 샷에 몰려 있다" · z 가 큰 변수 셋	"데이터만으로는 단정할 수 없다" · 약한 후보 하나 (+1.0σ)

한 번에 약 25 ~ 40원 · worker 만 누를 수 있다 · 만든 가이드는 저장해 다시 쓴다. 키가 없거나 크레딧이 끝나면 이 버튼만 멈춘다.

---

검증

무엇	결과	어디
단위 테스트	화면 규칙을 순수함수로 — OEE · 파레토 · 기준 범위 · 비가동 구간 · 원장 잇기 · 가이드 근거 등 80 · 수집기 5 (가짜 DB) · ETL 7 (경계값)	apps/web/lib/*.test.ts · services/collector/ · scripts/etl/
E2E	23 — 둘러보기로 시작 · 품질 파레토 → 그 유형의 LOT · 비로그인 차단 · viewer 잠금 · 정렬 · 시연 토글 · 차트 툴팁 · 현황판 합계 = 품질 + LOT 밖 부품 — DB 에 아무것도 안 쓰는 흐름만	apps/web/e2e/
CI	푸시마다 web(tsc · Vitest) · python(pytest) · e2e(Playwright)	.github/workflows/ci.yml
제약 실험	종류별로 일부러 어겨 13/13 막힘 (PK · UNIQUE · FK · CHECK · EXCLUDE · NOT NULL)	evidence/constraints-reject
RLS 전수 점검	역할 5 × 테이블 · View · 함수 23 — 모든 칸이 예상대로	scripts/verify/rls_matrix.py
성능	10배 데이터 · 인덱스 차이 30배	evidence/perf-10x
프론트 품질	Lighthouse 접근성 6화면 100 · SEO 63 은 일부러(사내 시스템)	evidence/lighthouse

---

기술 스택

영역	선택
DB	Supabase (PostgreSQL) — 스키마는 SQL 마이그레이션으로만 · RLS · EXCLUDE · plpgsql RPC
웹	Next.js 16 App Router · React 19 · TypeScript · Server Actions · Zod
스타일 · UI	Tailwind · shadcn/ui · Recharts
실시간	Supabase Realtime (Postgres Changes) — 알림은 신호, 값은 서버가 다시 읽는다
파이프라인	시뮬레이터 · 수집기 Python(paho-mqtt) · Mosquitto · Docker Compose
ETL	Python · pandas
LLM	Claude API (Anthropic SDK · 구조화 출력) — 서버에서만
테스트 · CI	Vitest · pytest · Playwright · GitHub Actions
배포	Vercel (웹) · 수집기와 브로커는 로컬 compose (ADR 011)

---

폴더 구조

db/migrations/     스키마의 유일한 진실 (001 ~ 029 · 29개). 대시보드 클릭으로 바꾸지 않는다
apps/web/          Next.js — app/ 화면 · lib/ 조회 · OEE 계산 · e2e/ Playwright
services/
  simulator/       CSV 를 시간순 MQTT 발행 (Python)
  collector/       MQTT 구독 → DB 적재 (Python) · compose 서비스 · 테스트
scripts/
  etl/             CSV → Supabase 적재 (Python, 일회성) · 테스트
  verify/          RLS · 제약 · 정정 확인 스크립트 (역할별로 실제 로그인)
  perf/            10배 데이터 실험 (perf 스키마)
  demo/            데모 LOT 열기 · 닫기 · 치우기
docs/
  decisions/       ADR — 설계 결정과 버린 대안
  evidence/        EXPLAIN · 제약 실험 · Lighthouse
  schema.md        ERD
  설명.md           10초 · 30초 · 5분 설명

---

데이터셋

KAMP(인공지능 중소벤처 제조 플랫폼)에서 공개한 사출성형기 AI 데이터셋을 사용한다. 용량 문제로 저장소에 포함하지 않았다. data/ 폴더에 labeled_data.csv를 두면 ETL 스크립트가 읽는다.

원본 7,996행에는 완전 중복 2,764행이 섞여 있었고(ADR 004), 45개 컬럼 중 12개는 전 구간 0 인 죽은 컬럼이었다(ADR 003). 데이터가 설계를 반박한 기록은 ADR 004 · 005 · 006 에 있다.

---

시작하기

새로 합류한다면 → docs/인수인계.md — 일하는 방식 · 환경 · 다음 할 일 지금 어디까지 왔나 → docs/progress.md 왜 그렇게 했나 → docs/decisions/

돌려보기

docker compose up -d --build                            브로커 + 수집기 (코드를 바꿨으면 --build)
python services/simulator/replay.py --live --limit 30   "지금부터" 1배속 재생
cd apps/web && npm run dev                              화면

테스트

cd apps/web && npm test                                 Vitest
cd apps/web && npm run e2e                              Playwright (개발 서버를 스스로 띄운다)
pytest scripts/etl services/collector                   pytest (pip install -r requirements-dev.txt)

데모용 LOT 을 열고 닫는 SQL 은 scripts/demo/demo_lot.sql 에 있다. 🔴 --live 없이 돌리면 원본 시각 그대로라 이미 있는 행을 덮어쓴다(멱등). 숫자가 안 움직인다.