tk-factory-services/ARCHITECTURE.md

TK Factory Services - 데이터 아키텍처 가이드

서비스 구조

서비스	서브도메인	역할	포트
tkuser	tkuser.technicalkorea.net	통합 관리 (기본 데이터)	API 30300, Web 30380
tkfactory (System 1)	tkfactory.technicalkorea.net	공장 관리	API 30005, Web 30080
tkreport (System 2)	tkreport.technicalkorea.net	안전 신고	API 30105, Web 30180
tkqc (System 3)	tkqc.technicalkorea.net	부적합 관리	API 30200, Web 30280
SSO Auth	-	인증 (로그인/토큰)	30050
Gateway	technicalkorea.net	SSO 라우팅	30000

데이터 소유권 (Data Ownership)

1. 기본 데이터 → tkuser API

모든 시스템에서 공통으로 사용하는 마스터 데이터는 tkuser에서 관리합니다.

데이터	설명	DB 테이블
사용자	계정, 역할, 비밀번호	sso_users
페이지 권한	사용자별 페이지 접근 권한	user_page_permissions
프로젝트	프로젝트 목록 및 설정	projects
작업장	공장(카테고리) → 작업장 계층, 구역지도	workplace_categories, workplaces, workplace_map_regions
설비	설비 마스터, 사진, 배치도 위치	equipments, equipment_photos
부서	부서/조직 구조	departments
작업자	작업자 인력 관리	workers
작업/공정	공정(work_types) → 작업(tasks) 계층	work_types, tasks
휴가 유형	연차/반차/특별휴가 유형 정의	vacation_types
연차 배정	작업자별 연간 연차 일수 배정/사용 추적	vacation_balance_details

다른 시스템은 tkuser API를 호출하여 기본 데이터를 조회합니다.

2. 신고 데이터 → tkreport (System 2) API

안전 신고와 관련된 트랜잭션 데이터는 System 2에서 관리합니다.

데이터	설명
안전 신고	신고 접수, 처리 현황
작업 이슈	작업 관련 이슈 리포트
신고 첨부파일	사진, 문서 등

3. 관리 현황 데이터 → 해당 시스템 API

각 시스템 고유의 운영 데이터는 해당 시스템에서 관리합니다.

System 1 (tkfactory)

데이터	설명
TBM 기록	일일 TBM 체크리스트
작업 보고서	일일/주간 작업 보고
출퇴근 기록	체크인/체크아웃
근태/휴가	휴가 신청 및 관리
순회 점검	일일 순회점검 결과

System 3 (tkqc)

데이터	설명
부적합 이슈	NCR 접수, 처리, 폐기
일일 공수	작업자별 일일 공수 입력
보고서	일일/주간/월간 보고서

tkuser API 엔드포인트

경로	설명
GET/POST /api/users	사용자 CRUD
GET/POST /api/permissions	페이지 권한 관리
GET/POST /api/projects	프로젝트 관리
GET/POST /api/workers	작업자 관리
GET/POST /api/departments	부서 관리
GET/POST /api/workplaces	작업장·카테고리·구역지도 관리
GET/POST /api/equipments	설비·사진 관리
GET/POST /api/tasks	공정(work_types)·작업(tasks) 관리
GET/POST /api/vacations	휴가 유형·연차 배정 관리

데이터 흐름

┌───────────────────────────────────────────────────────────┐
│                     tkuser (통합 관리)                       │
│  사용자 / 프로젝트 / 작업장·설비 / 부서 / 작업·공정 / 휴가   │
│                      [MariaDB]                            │
└──────────┬──────────────┬──────────────┬──────────────────┘
           │              │              │
     API 조회         API 조회       API 조회
           │              │              │
    ┌──────▼──────┐ ┌─────▼──────┐ ┌────▼───────────┐
    │  tkfactory  │ │  tkreport  │ │     tkqc       │
    │  공장 관리   │ │  안전 신고  │ │  부적합 관리    │
    │  [MariaDB]  │ │  [MariaDB] │ │  [PostgreSQL]  │
    └─────────────┘ └────────────┘ └────────────────┘

인증 구조

사용자 로그인 → SSO Auth → JWT 토큰 (sso_token 쿠키)
                           ↓
              .technicalkorea.net 전체 공유
                           ↓
         각 시스템에서 쿠키로 인증 확인

• JWT 토큰은 .technicalkorea.net 도메인 쿠키로 설정
• 모든 서브도메인에서 자동으로 인증 공유
• 각 시스템 API는 동일한 SSO_JWT_SECRET으로 토큰 검증

페이지 권한 체계

권한은 tkuser에서 중앙 관리하며, 각 시스템은 API를 호출하여 권한을 확인합니다.

시스템	권한 키 접두사	예시
System 1	s1.*	s1.work.tbm, s1.admin.projects
System 2	-	전체 허용 (권한 관리 불필요)
System 3	(접두사 없음)	issues_dashboard, daily_work

권한 우선순위:

1. user_page_permissions 테이블에 명시적 설정이 있으면 해당 값 사용
2. 없으면 DEFAULT_PAGES의 default_access 값 사용

배포

# 전체 서비스
docker compose up -d --build

# 개별 서비스
docker compose up -d --build tkuser-api tkuser-web
docker compose up -d --build system1-api system1-web
docker compose up -d --build system2-api system2-web
docker compose up -d --build system3-api system3-web