# TK Factory Services — 시스템 아키텍처

## 전체 구조

21개 컨테이너, Docker Compose 기반, Cloudflare Tunnel로 외부 노출.

```
[Cloudflare Tunnel] → tk-cloudflared
    ├── tkfb.technicalkorea.net   → tk-gateway:80      (로그인 + 대시보드 + 공유JS)
    ├── tkfb.technicalkorea.net   → tk-system1-web:80   (공장관리)
    ├── tkreport.technicalkorea.net → tk-system2-web:80  (신고)
    ├── tkqc.technicalkorea.net   → tk-system3-web:80   (부적합관리)
    ├── tkuser.technicalkorea.net → tk-tkuser-web:80    (통합관리)
    ├── tkpurchase.technicalkorea.net → tk-tkpurchase-web:80 (구매관리)
    ├── tksafety.technicalkorea.net → tk-tksafety-web:80 (안전관리)
    └── tksupport.technicalkorea.net → tk-tksupport-web:80 (행정지원)
```

## 서비스 목록

| 서비스 | 컨테이너명 | 로컬 포트 | 내부 포트 | 역할 |
|---|---|---|---|---|
| **Gateway** | tk-gateway | 30000 | 80 | 로그인/대시보드/공유JS + SSO·API 프록시 |
| **System1 API** | tk-system1-api | 30005 | 3005 | 공장관리 백엔드 (Node.js) |
| **System1 Web** | tk-system1-web | 30080 | 80 | 공장관리 프론트엔드 (nginx) |
| **System1 FastAPI** | tk-system1-fastapi | 30008 | 8000 | FastAPI Bridge |
| **System2 API** | tk-system2-api | 30105 | 3005 | 신고 백엔드 (Node.js) |
| **System2 Web** | tk-system2-web | 30180 | 80 | 신고 프론트엔드 (nginx) |
| **System3 API** | tk-system3-api | 30200 | 8000 | 부적합관리 백엔드 (FastAPI) |
| **System3 Web** | tk-system3-web | 30280 | 80 | 부적합관리 프론트엔드 (nginx) |
| **User API** | tk-tkuser-api | 30300 | 3000 | 사용자관리 백엔드 (Node.js) |
| **User Web** | tk-tkuser-web | 30380 | 80 | 사용자관리 프론트엔드 (nginx) |
| **Purchase API** | tk-tkpurchase-api | 30400 | 3000 | 구매관리 백엔드 (Node.js) |
| **Purchase Web** | tk-tkpurchase-web | 30480 | 80 | 구매관리 프론트엔드 (nginx) |
| **Safety API** | tk-tksafety-api | 30500 | 3000 | 안전관리 백엔드 (Node.js) |
| **Safety Web** | tk-tksafety-web | 30580 | 80 | 안전관리 프론트엔드 (nginx) |
| **Support API** | tk-tksupport-api | 30600 | 3000 | 행정지원 백엔드 (Node.js) |
| **Support Web** | tk-tksupport-web | 30680 | 80 | 행정지원 프론트엔드 (nginx) |
| **SSO Auth** | tk-sso-auth | 30050 | 3000 | SSO 인증 서비스 (Node.js) |
| **MariaDB** | tk-mariadb | 30306 | 3306 | 메인 데이터베이스 |
| **Redis** | tk-redis | — | 6379 | 세션/캐시 |
| **phpMyAdmin** | tk-phpmyadmin | 30880 | 80 | DB 관리 도구 |
| **Cloudflared** | tk-cloudflared | — | — | Cloudflare Tunnel 에이전트 |

## 요청 흐름

```
브라우저 → Cloudflare DNS → Cloudflare Tunnel → cloudflared 컨테이너
    → 서브도메인별 라우팅 → 해당 web 컨테이너 (nginx)
        → /api/   → 해당 API 컨테이너
        → /auth/  → sso-auth 컨테이너
        → /uploads/ → API 컨테이너 (파일 서빙)
        → 나머지  → 정적 파일 (SPA fallback)
```

## SSO 인증 흐름

1. 사용자가 아무 서비스 접근 → 프론트엔드 JS가 `sso_token` 쿠키 확인
2. 토큰 없음/만료 → `tkfb.technicalkorea.net/dashboard`로 리다이렉트 (redirect 파라미터 포함)
3. 로그인 폼 제출 → `POST /auth/login` → sso-auth가 JWT 발급
4. 쿠키 설정: `sso_token`, `sso_user`, `sso_refresh_token` (domain=`.technicalkorea.net`)
5. redirect 파라미터가 있으면 원래 페이지로, 없으면 대시보드 표시
6. 각 서비스의 API는 `Authorization: Bearer <token>` 헤더로 인증 검증

## CORS 관리

- **sso-auth**: `sso-auth-service/config/` — 모든 `*.technicalkorea.net` 서브도메인 허용
- **system1-factory API**: `system1-factory/api/config/cors.js` — 허용 origin 명시적 관리
- 로컬 네트워크(192.168.x.x)는 자동 허용

## 공유 JS

Gateway(`/shared/`)에서 서빙:
- `notification-bell.js` — 알림 벨 UI, 모든 서비스에서 로딩
- `nav-header.js` — 공통 네비게이션 헤더

각 서비스의 core.js에서 동적 로딩:
```
프로덕션: https://tkfb.technicalkorea.net/shared/notification-bell.js
로컬:     http://localhost:30000/shared/notification-bell.js
```

## 신규 서비스 추가 체크리스트

1. `<service>/api/` + `<service>/web/` 디렉토리 생성 (Dockerfile 포함)
2. `docker-compose.yml`에 api + web 서비스 추가 (포트 할당)
3. `cloudflared.depends_on`에 web 서비스 추가
4. Cloudflare Tunnel 대시보드에서 서브도메인 → 컨테이너 라우팅 추가
5. `sso-auth-service/config/`에 새 origin 추가
6. `system1-factory/api/config/cors.js`에 새 origin 추가 (API 호출 시)
7. 알림 벨 사용 시: core.js에 `_loadNotificationBell()` 함수 추가
8. 로그인 리다이렉트: `tkfb.technicalkorea.net/dashboard?redirect=` 패턴 사용

## 배포 절차

```bash
# 로컬에서 push
git push

# NAS에서 pull + rebuild
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 <서비스명>"
```

전체 재시작: `docker compose up -d --build`
특정 서비스만: `docker compose up -d --build gateway system1-web`