TK-FB-Project/개발로그/2026-01-19_작업자_계정연동_기능.md

작업자-계정 연동 기능 가이드

작업 일시

2026-01-19

작업 개요

작업자 관리 시스템에 계정 자동 생성/연동 기능을 추가하여, 작업자가 개인 계정으로 로그인하고 나의 대시보드에 접근할 수 있도록 개선했습니다.

주요 변경사항

1. 개념 변경

이전 (폐기):

• 작업 보고서 표시 여부 (show_in_work_reports)
• 현장직/사무직 구분
• 퇴사 처리

현재 (개선):

• 🔐 계정 생성/연동 (자동 로그인 계정 생성)
• 🏭 현장직/사무직 구분
• 🚪 퇴사 처리

2. 데이터베이스 변경

마이그레이션

• 파일: api.hyungi.net/db/migrations/20260119095549_add_worker_display_fields.js
• 변경 내용:
  • employment_status ENUM('employed', 'resigned') 컬럼 추가
  • show_in_work_reports 컬럼 제거 (사용 안 함)

Workers 테이블 구조 (주요 컬럼)

CREATE TABLE workers (
  worker_id INT PRIMARY KEY AUTO_INCREMENT,
  worker_name VARCHAR(100) NOT NULL,
  job_type VARCHAR(50),
  status ENUM('active', 'inactive') DEFAULT 'active',
  employment_status ENUM('employed', 'resigned') DEFAULT 'employed',
  salary DECIMAL(12,2) NULL,
  base_annual_leave INT DEFAULT 15,
  -- ... 기타 컬럼
);

Users-Workers 관계

SELECT
  w.*,
  u.user_id,
  u.username
FROM workers w
LEFT JOIN users u ON w.worker_id = u.worker_id;

• user_id가 NULL → 계정 없음
• user_id가 있음 → 계정 연동됨

3. 백엔드 API 구현

WorkerController.js 변경사항

작업자 생성 API (POST /api/workers)

// 요청 Body
{
  "worker_name": "홍길동",
  "job_type": "worker",
  "status": "active",
  "employment_status": "employed",
  "create_account": true  // ← 계정 생성 여부
}

• create_account: true → 자동으로 users 테이블에 계정 생성
  • Username: 한글 이름 → 영문 변환 (예: 홍길동 → hong.gildong)
  • Password: 초기 비밀번호 "1234" (bcrypt 해시)
  • Role: User 역할 자동 할당

작업자 수정 API (PUT /api/workers/:worker_id)

// 계정 생성
create_account: true & 기존 계정 없음
→ users 테이블에 계정 생성

// 계정 연동 해제
create_account: false & 기존 계정 있음
→ UPDATE users SET worker_id = NULL WHERE worker_id = :id

WorkerModel.js 변경사항

작업자 조회 시 user_id 포함

// getAll(), getById() 수정
SELECT
  w.*,
  CASE WHEN w.status = 'active' THEN 1 ELSE 0 END AS is_active,
  u.user_id  -- ← 계정 연동 여부 확인용
FROM workers w
LEFT JOIN users u ON w.worker_id = u.worker_id

4. 프론트엔드 구현

worker-management.html 변경

모달 UI (3가지 상태 관리):

<!-- 계정 생성/연동 -->
<label>
  <input type="checkbox" id="hasAccount">
  <span>🔐 계정 생성/연동</span>
</label>
<small>체크 시 로그인 계정이 자동 생성됩니다 (나의 대시보드, 연차/출퇴근 관리 가능)</small>

<!-- 현장직/사무직 구분 -->
<label>
  <input type="checkbox" id="isActive" checked>
  <span>🏭 현장직 (활성화)</span>
</label>
<small>체크: 현장직 (출퇴근 관리 필요) / 체크 해제: 사무직 (출퇴근 관리 불필요)</small>

<!-- 퇴사 처리 -->
<label>
  <input type="checkbox" id="isResigned">
  <span style="color: #ef4444;">🚪 퇴사 처리</span>
</label>
<small style="color: #ef4444;">퇴사한 작업자로 표시됩니다. 작업 보고서에서 제외됩니다</small>

worker-management.js 변경

작업자 카드 렌더링

// 계정 연동 상태 표시
const hasAccount = worker.user_id !== null;

// 이름 옆에 아이콘 표시
${worker.worker_name}
${hasAccount ? '<span style="color: #10b981;">🔐</span>' : ''}

// 메타 정보에 계정 상태 표시
${hasAccount ?
  '<span style="color: #10b981;">🔐 계정 연동됨</span>' :
  '<span style="color: #9ca3af;">⚪ 계정 없음</span>'}

저장 시 create_account 전송

const workerData = {
  worker_name: document.getElementById('workerName').value.trim(),
  // ... 기타 필드
  create_account: document.getElementById('hasAccount').checked
};

daily-work-report.js 변경

작업자 필터링 로직 단순화

// 이전: show_in_work_reports & employment_status 체크
// 현재: 퇴사자만 제외 (계정 여부 무관)
workers = allWorkers.filter(worker => {
  const notResigned = worker.employment_status !== 'resigned';
  return notResigned;
});

→ 계정 여부와 관계없이 모든 재직자 표시

5. 한글→영문 변환 로직

파일: api.hyungi.net/utils/hangulToRoman.js

변환 규칙:

// 예시
홍길동 → hong.gildong
김철수 → kim.cheolsu
이영희 → lee.yeonghui

// 중복 처리
홍길동 (기존) → hong.gildong
홍길동 (신규) → hong.gildong2
홍길동 (또 다른) → hong.gildong3

구현 방식:

1. 한글 유니코드 분해 (초성/중성/종성)
2. 국립국어원 표기법 기준으로 로마자 변환
3. 성.이름 형태로 조합
4. 중복 체크 후 숫자 접미사 추가

핵심 기능

1. 계정 자동 생성

• 작업자 등록/수정 시 "🔐 계정 생성/연동" 체크
• 자동으로 한글 이름 → 영문 username 변환
• 초기 비밀번호: 1234 (첫 로그인 후 변경 권장)
• User 역할 자동 할당

2. 계정 연동 해제

• 체크 해제 시 users.worker_id = NULL로 연동 해제
• 작업자 정보는 유지, 로그인만 불가능하게 변경
• 계정 데이터는 삭제되지 않음 (재연동 가능)

3. 작업 보고서 표시

• 계정 여부와 무관하게 모든 재직자 표시
• 퇴사자(employment_status='resigned')만 제외
• 관리자/사무직도 작업 보고서에 포함됨

4. UI 표시

• 작업자 카드: 🔐 아이콘으로 계정 연동 상태 표시
• "🔐 계정 연동됨" / "⚪ 계정 없음" 상태 표시
• 퇴사자: 빨간색 오버레이 "🚪 퇴사" 표시

배포 절차

1. 서버 접속

ssh user@server
cd /path/to/TK-FB-Project

2. 자동 배포 (권장)

cd api.hyungi.net

# Git Pull로 최신 코드 받기
git pull

# 배포 스크립트 실행
chmod +x deploy.sh  # 처음 한 번만
./deploy.sh

스크립트가 자동으로:

1. ✅ Git Pull
2. ✅ NPM Install (package.json 변경 시)
3. ✅ 데이터베이스 마이그레이션 (확인 후 실행)
4. ✅ PM2 서버 재시작
5. ✅ 상태 확인

3. 수동 배포

# 1. Git Pull
git pull

# 2. 의존성 설치 (필요시)
npm install

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

# 4. PM2 재시작
pm2 reload ecosystem.config.js --env production

# 5. 상태 확인
pm2 list
pm2 logs hyungi-api

4. 배포 후 확인

# API 응답 확인
curl http://localhost:20005/health

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

# 로그 확인
pm2 logs hyungi-api

사용 방법

1. 신규 작업자 등록 + 계정 생성

1. 작업자 관리 페이지 접속
2. "➕ 새 작업자 등록" 클릭
3. 작업자 정보 입력
4. "🔐 계정 생성/연동" 체크 ✅
5. 저장

결과:

• workers 테이블에 작업자 생성
• users 테이블에 로그인 계정 자동 생성
• username: hong.gildong (한글 이름 자동 변환)
• password: 1234 (초기 비밀번호)

2. 기존 작업자에 계정 추가

1. 작업자 카드 클릭 (수정 모드)
2. "🔐 계정 생성/연동" 체크 ✅
3. 저장

결과:

• 기존 작업자 정보 유지
• users 테이블에 계정 추가
• 즉시 로그인 가능

3. 계정 연동 해제

1. 작업자 카드 클릭
2. "🔐 계정 생성/연동" 체크 해제 ❌
3. 저장

결과:

• 작업자 정보는 유지
• users.worker_id = NULL (연동 해제)
• 로그인 불가능 (계정은 삭제 안 됨)

4. 퇴사 처리

1. 작업자 카드 클릭
2. "🚪 퇴사 처리" 체크 ✅
3. 저장

결과:

• employment_status = 'resigned'
• 작업 보고서 작성 시 목록에서 제외
• 작업자 관리에서 빨간색 "🚪 퇴사" 표시

테스트 시나리오

시나리오 1: 신규 작업자 + 계정 생성

1. 작업자명: 홍길동
2. 계정 생성: ✅
3. 저장

→ 확인사항:
- workers 테이블: worker_name = '홍길동'
- users 테이블: username = 'hong.gildong', worker_id = (생성된 ID)
- 로그인 가능: hong.gildong / 1234

시나리오 2: 계정 없는 작업자

1. 작업자명: 김철수
2. 계정 생성: ❌
3. 저장

→ 확인사항:
- workers 테이블: worker_name = '김철수'
- users 테이블: 해당 worker_id 없음
- 작업자 카드: "⚪ 계정 없음" 표시
- 작업 보고서: 여전히 목록에 표시됨

시나리오 3: 계정 추가 (기존 작업자)

1. 기존 작업자 "김철수" 선택
2. 계정 생성: ❌ → ✅ 변경
3. 저장

→ 확인사항:
- users 테이블: username = 'kim.cheolsu' 추가
- 작업자 카드: "🔐 계정 연동됨" 표시
- 로그인 가능: kim.cheolsu / 1234

시나리오 4: 중복 이름 처리

1. 작업자명: 홍길동 (두 번째)
2. 계정 생성: ✅
3. 저장

→ 확인사항:
- username = 'hong.gildong2' (자동으로 숫자 접미사)

시나리오 5: 퇴사자

1. 작업자 선택
2. 퇴사 처리: ✅
3. 저장

→ 확인사항:
- employment_status = 'resigned'
- 작업자 카드: 빨간색 오버레이 "🚪 퇴사"
- 일일 작업보고서: 작업자 목록에서 제외됨

보안 고려사항

1. 초기 비밀번호

• 모든 자동 생성 계정: 초기 비밀번호 1234
• 반드시 첫 로그인 후 변경하도록 안내 필요
• 향후 개선: 비밀번호 강제 변경 로직 추가

2. 계정 연동 해제

• 계정 데이터는 삭제하지 않음 (users.worker_id = NULL)
• 재연동 시 기존 비밀번호 유지
• 완전 삭제가 필요하면 users 테이블에서 직접 DELETE

3. 권한 관리

• 자동 생성된 계정: User 역할
• 관리자 권한이 필요하면 수동으로 변경 필요

문제 해결

1. 마이그레이션 에러: "Unknown column 'employment_status'"

원인: 마이그레이션 미실행

해결:

cd api.hyungi.net
npm run db:migrate

2. 계정 생성 실패

원인: User 역할이 roles 테이블에 없음

해결:

INSERT INTO roles (name, description) VALUES ('User', '일반 사용자');

3. Username 중복 에러

원인: 동일한 이름이 너무 많음 (hong.gildong999까지 다 사용)

해결: 수동으로 username 지정 (향후 개선 필요)

4. 계정 연동 해제가 안 됨

원인: API 요청에 create_account: false 전송 안 됨

해결: 브라우저 캐시 삭제 (Ctrl+F5) 후 재시도

향후 개선 계획

1. 비밀번호 정책

• 초기 비밀번호 랜덤 생성
• 첫 로그인 시 비밀번호 강제 변경
• 이메일/SMS로 초기 비밀번호 전송

2. 계정 관리 UI

• 작업자 관리에서 비밀번호 재설정 기능
• 계정 잠금/해제 기능
• 로그인 이력 조회

3. 대량 작업

• CSV 업로드로 여러 작업자 일괄 등록
• 일괄 계정 생성 기능

4. 알림 기능

• 계정 생성 시 작업자에게 알림
• 비밀번호 변경 알림

파일 목록

백엔드

• api.hyungi.net/db/migrations/20260119095549_add_worker_display_fields.js (수정)
• api.hyungi.net/controllers/workerController.js (수정)
• api.hyungi.net/models/workerModel.js (수정)
• api.hyungi.net/utils/hangulToRoman.js (기존)
• api.hyungi.net/deploy.sh (신규)
• api.hyungi.net/DEPLOY.md (신규)

프론트엔드

• web-ui/pages/management/worker-management.html (수정)
• web-ui/js/worker-management.js (수정)
• web-ui/js/daily-work-report.js (수정)

문서

• 개발로그/2026-01-19_작업자_계정연동_기능.md (본 문서)

관련 커밋

• bea62df - refactor: 작업자 관리 개선 - 계정 연동 기능으로 변경
• 1e4dbf1 - feat: 배포 자동화 스크립트 추가

참고 자료

• 이전 개발로그: 개발로그/2026-01-19_계정통합_연차출근관리.md
• 배포 가이드: api.hyungi.net/DEPLOY.md
• 한글 로마자 표기법: 국립국어원 기준