tk-factory-services/CLAUDE.md

CLAUDE.md — TK Factory Services

프로젝트 개요

공장관리 플랫폼. 8개 마이크로서비스, 21개+ Docker 컨테이너. Synology NAS 배포, Cloudflare Tunnel.

서비스 맵

서비스	디렉토리	스택	API/Web 포트	DB
Gateway	gateway/	nginx	30000	-
SSO Auth	sso-auth-service/	Node.js	30050	MariaDB
System1 공장관리	system1-factory/	Node.js + nginx	30005/30080	MariaDB
System2 신고	system2-report/	Node.js + nginx	30105/30180	MariaDB
System3 부적합	system3-nonconformance/	FastAPI + nginx	30200/30280	MariaDB
tkuser 사용자	user-management/	Node.js + nginx	30300/30380	MariaDB
tkpurchase 소모품	tkpurchase/	Node.js + nginx	30400/30480	MariaDB
tksafety 안전	tksafety/	Node.js + nginx	30500/30580	MariaDB
tksupport 행정	tksupport/	Node.js + nginx	30600/30680	MariaDB
tkeg BOM	tkeg/	FastAPI + React(Vite)	30700/30780	PostgreSQL

System1에는 FastAPI bridge도 있음 (30008, AI 연동용).

기술 스택

• 프론트엔드: Vanilla JS + Tailwind CDN + Font Awesome (빌드 없음). tkeg만 React+Vite+MUI
• 백엔드(Node): Express + mysql2/Knex. 패턴: Routes → Controllers → Services → Models → DB
• 백엔드(Python): FastAPI + SQLAlchemy (System3, tkeg)
• DB: MariaDB 공유(hyungi) + PostgreSQL(tkeg: tk_bom) + Redis(세션)
• 인증: JWT SSO — sso_token 쿠키(domain=.technicalkorea.net) + localStorage 폴백
• 접근레벨: worker(1) < group_leader(2) < support_team(3) < admin(4) < system(5)

코드 규칙

1. 캐시 버스팅 필수: JS/CSS 수정 시 HTML <script>/<link> 태그의 ?v=YYYYMMDDNN 반드시 갱신
2. API 응답 포맷: { success: true, data: {...}, message: "..." } — res.success(), res.paginated() 등
3. 커밋 메시지: type(scope): 한국어 설명 (예: fix(tkfb): 모바일 레이아웃 수정)
4. CSS 전역: system1-factory → tkfb.css (모든 페이지 로드). 모바일 = @media (max-width: 768px)

배포

전제: Tailscale SSH 키 인증 설정 완료 (hyungi@100.71.132.52)

git push && ssh hyungi@100.71.132.52 "cd /volume1/docker/tk-factory-services && git pull && export PATH=\$PATH:/volume2/@appstore/ContainerManager/usr/bin && docker compose up -d --build <서비스명>"

상세: DEPLOY-GUIDE.md 참조. 아키텍처: ARCHITECTURE.md 참조.

멀티 에이전트 워크플로우

이 프로젝트는 Cowork(설계/검토) + Claude Code(코딩) 멀티 에이전트 방식을 지원한다.

• 워크플로우 가이드: .cowork/WORKFLOW-GUIDE.md
• 스프린트 계획/스펙: .cowork/sprints/sprint-NNN/
• 에러 기록: .cowork/errors/ERROR-LOG.md
• 템플릿: .cowork/templates/

Claude Code Worker는 자신의 섹션 스펙(section-*.md)만 읽고 작업할 것. 다른 섹션 파일 수정 금지.