TK-FB-Project/docs/TBM_DEPLOYMENT_GUIDE.md

TBM 시스템 배포 가이드

📋 개요

TBM (Tool Box Meeting) 시스템은 아침 안전 회의 및 팀 구성 관리를 위한 기능입니다.

배포일: 2026-01-20 버전: 1.0.0

---

🗄️ 데이터베이스 마이그레이션

필수 마이그레이션 파일

본 서버에 배포 시 반드시 실행해야 할 마이그레이션:

1. 20260120000000_create_tbm_system.js - TBM 시스템 테이블 생성
2. 20260120000001_add_tbm_page.js - TBM 페이지 등록

생성되는 테이블

1. tbm_sessions - TBM 세션 (아침 미팅)

CREATE TABLE `tbm_sessions` (
  `session_id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  `session_date` DATE NOT NULL COMMENT 'TBM 날짜',
  `leader_id` INT NOT NULL COMMENT '팀장 worker_id',
  `project_id` INT NULL COMMENT '프로젝트 ID',
  `work_location` VARCHAR(200) NULL COMMENT '작업 장소',
  `work_description` TEXT NULL COMMENT '작업 내용',
  `safety_notes` TEXT NULL COMMENT '안전 관련 특이사항',
  `status` ENUM('draft', 'completed', 'cancelled') DEFAULT 'draft' COMMENT '상태',
  `start_time` TIME NULL COMMENT 'TBM 시작 시간',
  `end_time` TIME NULL COMMENT 'TBM 종료 시간',
  `created_by` INT NOT NULL COMMENT '생성자 user_id',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX `idx_session_date_leader` (`session_date`, `leader_id`),
  FOREIGN KEY (`leader_id`) REFERENCES `workers` (`worker_id`),
  FOREIGN KEY (`project_id`) REFERENCES `projects` (`project_id`) ON DELETE SET NULL,
  FOREIGN KEY (`created_by`) REFERENCES `users` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

2. tbm_team_assignments - TBM 팀 구성

CREATE TABLE `tbm_team_assignments` (
  `assignment_id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  `session_id` INT UNSIGNED NOT NULL COMMENT 'TBM 세션 ID',
  `worker_id` INT NOT NULL COMMENT '팀원 worker_id',
  `assigned_role` VARCHAR(100) NULL COMMENT '역할/담당',
  `work_detail` TEXT NULL COMMENT '세부 작업 내용',
  `is_present` BOOLEAN DEFAULT TRUE COMMENT '출석 여부',
  `absence_reason` TEXT NULL COMMENT '결석 사유',
  `assigned_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY `uk_session_worker` (`session_id`, `worker_id`),
  FOREIGN KEY (`session_id`) REFERENCES `tbm_sessions` (`session_id`) ON DELETE CASCADE,
  FOREIGN KEY (`worker_id`) REFERENCES `workers` (`worker_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

3. tbm_safety_checks - 안전 체크리스트 마스터

CREATE TABLE `tbm_safety_checks` (
  `check_id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  `check_category` VARCHAR(50) NOT NULL COMMENT '카테고리 (PPE, EQUIPMENT, ENVIRONMENT, EMERGENCY)',
  `check_item` VARCHAR(200) NOT NULL COMMENT '체크 항목',
  `description` TEXT NULL COMMENT '설명',
  `display_order` INT DEFAULT 0 COMMENT '표시 순서',
  `is_required` BOOLEAN DEFAULT TRUE COMMENT '필수 체크 여부',
  `is_active` BOOLEAN DEFAULT TRUE COMMENT '활성 여부',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX `idx_check_category` (`check_category`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

초기 데이터 (17개 항목):

• PPE (개인 보호 장비): 5개
• EQUIPMENT (장비 점검): 4개
• ENVIRONMENT (작업 환경): 4개
• EMERGENCY (비상 대응): 3개

4. tbm_safety_records - 안전 체크 기록

CREATE TABLE `tbm_safety_records` (
  `record_id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  `session_id` INT UNSIGNED NOT NULL COMMENT 'TBM 세션 ID',
  `check_id` INT UNSIGNED NOT NULL COMMENT '체크 항목 ID',
  `is_checked` BOOLEAN DEFAULT FALSE COMMENT '체크 여부',
  `notes` TEXT NULL COMMENT '비고/특이사항',
  `checked_by` INT NULL COMMENT '체크한 user_id',
  `checked_at` TIMESTAMP NULL COMMENT '체크 시간',
  UNIQUE KEY `uk_session_check` (`session_id`, `check_id`),
  FOREIGN KEY (`session_id`) REFERENCES `tbm_sessions` (`session_id`) ON DELETE CASCADE,
  FOREIGN KEY (`check_id`) REFERENCES `tbm_safety_checks` (`check_id`),
  FOREIGN KEY (`checked_by`) REFERENCES `users` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

5. team_handovers - 작업 인계

CREATE TABLE `team_handovers` (
  `handover_id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  `session_id` INT UNSIGNED NOT NULL COMMENT 'TBM 세션 ID',
  `from_leader_id` INT NOT NULL COMMENT '인계자 worker_id',
  `to_leader_id` INT NOT NULL COMMENT '인수자 worker_id',
  `handover_date` DATE NOT NULL COMMENT '인계 날짜',
  `handover_time` TIME NULL COMMENT '인계 시간',
  `reason` ENUM('half_day', 'early_leave', 'emergency', 'other') NOT NULL COMMENT '인계 사유',
  `handover_notes` TEXT NULL COMMENT '인계 내용',
  `worker_ids` TEXT NULL COMMENT '인계하는 작업자 IDs (JSON array)',
  `is_confirmed` BOOLEAN DEFAULT FALSE COMMENT '인수 확인 여부',
  `confirmed_at` TIMESTAMP NULL COMMENT '인수 확인 시간',
  `confirmed_by` INT NULL COMMENT '인수 확인자 user_id',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX `idx_session_handover_date` (`session_id`, `handover_date`),
  FOREIGN KEY (`session_id`) REFERENCES `tbm_sessions` (`session_id`) ON DELETE CASCADE,
  FOREIGN KEY (`from_leader_id`) REFERENCES `workers` (`worker_id`),
  FOREIGN KEY (`to_leader_id`) REFERENCES `workers` (`worker_id`),
  FOREIGN KEY (`confirmed_by`) REFERENCES `users` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

---

🚀 배포 절차

1. 데이터베이스 마이그레이션 실행

# 본 서버에서 실행
cd /path/to/api.hyungi.net

# 환경 변수 설정 (필요 시)
export DB_HOST=your_db_host
export DB_PORT=your_db_port
export DB_USER=your_db_user
export DB_PASSWORD=your_db_password
export DB_NAME=hyungi

# 마이그레이션 실행
npm run db:migrate

# 또는 직접 실행
npx knex migrate:latest --knexfile knexfile.js

2. 마이그레이션 확인

# 마이그레이션 상태 확인
npx knex migrate:status --knexfile knexfile.js

# 테이블 생성 확인
mysql -u root -p -e "SHOW TABLES LIKE 'tbm%'" hyungi
mysql -u root -p -e "SHOW TABLES LIKE 'team_handovers'" hyungi

# 안전 체크리스트 초기 데이터 확인
mysql -u root -p -e "SELECT check_category, COUNT(*) as count FROM tbm_safety_checks GROUP BY check_category" hyungi

예상 결과:

+----------------+-------+
| check_category | count |
+----------------+-------+
| PPE            |     5 |
| EQUIPMENT      |     4 |
| ENVIRONMENT    |     4 |
| EMERGENCY      |     3 |
+----------------+-------+

3. API 서버 재시작

# PM2 사용 시
pm2 restart api-hyungi

# 또는 직접 재시작
pm2 stop api-hyungi
pm2 start ecosystem.config.js --env production

4. 페이지 권한 확인

# TBM 페이지가 pages 테이블에 등록되었는지 확인
mysql -u root -p -e "SELECT * FROM pages WHERE page_key='tbm'\G" hyungi

예상 결과:

        page_id: [auto_increment]
       page_key: tbm
      page_name: TBM 관리
      page_path: /pages/work/tbm.html
       category: work
    description: Tool Box Meeting - 아침 안전 회의 및 팀 구성 관리
  is_admin_only: 0
  display_order: 10

---

📡 API 엔드포인트

TBM 세션 관리

• POST /api/tbm/sessions - TBM 세션 생성
• GET /api/tbm/sessions/date/:date - 특정 날짜의 TBM 세션 목록
• GET /api/tbm/sessions/:sessionId - TBM 세션 상세 조회
• PUT /api/tbm/sessions/:sessionId - TBM 세션 수정
• POST /api/tbm/sessions/:sessionId/complete - TBM 세션 완료

팀 구성 관리

• POST /api/tbm/sessions/:sessionId/team - 팀원 추가 (단일)
• POST /api/tbm/sessions/:sessionId/team/batch - 팀원 일괄 추가
• GET /api/tbm/sessions/:sessionId/team - 팀 구성 조회
• DELETE /api/tbm/sessions/:sessionId/team/:workerId - 팀원 제거

안전 체크리스트

• GET /api/tbm/safety-checks - 모든 안전 체크 항목 조회
• GET /api/tbm/sessions/:sessionId/safety - 안전 체크 기록 조회
• POST /api/tbm/sessions/:sessionId/safety - 안전 체크 일괄 저장

작업 인계

• POST /api/tbm/handovers - 작업 인계 생성
• POST /api/tbm/handovers/:handoverId/confirm - 작업 인계 확인
• GET /api/tbm/handovers/date/:date - 특정 날짜의 인계 목록
• GET /api/tbm/handovers/pending - 나에게 온 미확인 인계 건

통계 및 리포트

• GET /api/tbm/statistics/tbm?startDate=&endDate= - TBM 통계
• GET /api/tbm/statistics/leaders?startDate=&endDate= - 리더별 통계

---

🔐 권한 설정

1. 관리자가 페이지 권한 설정

1. 관리자 계정으로 로그인
2. /pages/admin/page-access.html 접속
3. 권한을 부여할 사용자 선택
4. "TBM 관리" 페이지 체크
5. 저장

2. 기본 권한 (권장)

• 그룹장 (Leader): TBM 페이지 접근 권한 부여 필요
• 관리자 (Admin): 자동으로 모든 페이지 접근 가능
• 일반 작업자 (User): 필요에 따라 부여

---

📁 파일 구조

백엔드 (API)

api.hyungi.net/
├── db/migrations/
│   ├── 20260120000000_create_tbm_system.js      # TBM 테이블 생성
│   └── 20260120000001_add_tbm_page.js           # TBM 페이지 등록
├── models/
│   └── tbmModel.js                               # TBM 데이터 모델
├── controllers/
│   └── tbmController.js                          # TBM 컨트롤러
├── routes/
│   └── tbmRoutes.js                              # TBM 라우트
└── config/
    └── routes.js                                 # 라우트 등록 (수정됨)

프론트엔드 (Web UI)

web-ui/
├── pages/work/
│   └── tbm.html                                  # TBM 페이지
└── js/
    └── tbm.js                                    # TBM JavaScript (예정)

---

⚠️ 주의사항

1. 외래 키 제약 조건

• workers 테이블의 worker_id는 signed INT(11)
• users 테이블의 user_id는 signed INT(11)
• projects 테이블의 PK는 project_id (NOT id)
• 외래 키 컬럼은 반드시 signed INT로 선언 (unsigned 사용 금지)

2. 데이터 정합성

• TBM 세션 삭제 시 관련 팀 구성, 안전 체크 기록 자동 삭제 (CASCADE)
• 작업자 삭제 시 관련 TBM 세션도 삭제됨 (workers 테이블의 CASCADE 설정)

3. 백업

마이그레이션 실행 전 반드시 데이터베이스 백업:

mysqldump -u root -p hyungi > backup_before_tbm_$(date +%Y%m%d_%H%M%S).sql

4. 롤백

문제 발생 시 롤백:

# 한 단계 롤백
npx knex migrate:rollback --knexfile knexfile.js

# 또는 백업 복구
mysql -u root -p hyungi < backup_before_tbm_YYYYMMDD_HHMMSS.sql

---

✅ 배포 체크리스트

배포 전 확인:

• 데이터베이스 백업 완료
• 마이그레이션 파일 본 서버에 복사 완료
• 환경 변수 설정 확인 (DB 접속 정보)
• 마이그레이션 실행 완료
• 5개 테이블 생성 확인
• tbm_safety_checks 초기 데이터 (17개) 확인
• pages 테이블에 TBM 페이지 등록 확인
• API 서버 재시작 완료
• API 엔드포인트 테스트 (최소 1개)
• TBM 페이지 접속 테스트
• 권한 설정 테스트 (그룹장 계정)

---

🔍 테스트 방법

1. API 테스트

# 안전 체크 항목 조회
curl -X GET http://localhost:20005/api/tbm/safety-checks \
  -H "Authorization: Bearer YOUR_TOKEN"

# 오늘 날짜의 TBM 세션 조회
curl -X GET http://localhost:20005/api/tbm/sessions/date/2026-01-20 \
  -H "Authorization: Bearer YOUR_TOKEN"

2. 웹 페이지 테스트

1. 그룹장 계정으로 로그인
2. /pages/work/tbm.html 접속
3. "새 TBM 시작" 버튼 클릭
4. TBM 세션 생성 및 팀 구성

---

📞 문제 해결

문제 1: 마이그레이션 실패 (errno: 150)

원인: 외래 키 제약 조건 오류 (데이터 타입 불일치) 해결: 마이그레이션 파일에서 외래 키 컬럼을 signed INT로 수정

문제 2: API 엔드포인트 404

원인: 라우트 등록 누락 또는 서버 미재시작 해결:

pm2 logs api-hyungi --lines 50  # 로그 확인
pm2 restart api-hyungi          # 서버 재시작

문제 3: TBM 페이지 접근 불가

원인: 페이지 권한 미설정 해결: 관리자가 /pages/admin/page-access.html에서 권한 부여

---

📝 변경 이력

v1.0.0 (2026-01-20)

• TBM 시스템 초기 배포
• 5개 테이블 생성
• 17개 안전 체크리스트 항목
• API 엔드포인트 17개
• 페이지 권한 시스템 연동

---

📚 관련 문서

• 작업자-계정 연동 가이드
• 페이지 권한 관리 가이드
• 데이터베이스 스키마

---

작성자: Claude 최종 수정일: 2026-01-20