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

## 작업 일시
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 테이블 구조 (주요 컬럼)
```sql
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 관계
```sql
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`)
```javascript
// 요청 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`)
```javascript
// 계정 생성
create_account: true & 기존 계정 없음
→ users 테이블에 계정 생성

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

#### WorkerModel.js 변경사항

**작업자 조회 시 user_id 포함**
```javascript
// 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가지 상태 관리):
```html
<!-- 계정 생성/연동 -->
<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 변경

**작업자 카드 렌더링**
```javascript
// 계정 연동 상태 표시
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 전송**
```javascript
const workerData = {
  worker_name: document.getElementById('workerName').value.trim(),
  // ... 기타 필드
  create_account: document.getElementById('hasAccount').checked
};
```

#### daily-work-report.js 변경

**작업자 필터링 로직 단순화**
```javascript
// 이전: 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`

**변환 규칙**:
```javascript
// 예시
홍길동 → 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. 서버 접속
```bash
ssh user@server
cd /path/to/TK-FB-Project
```

### 2. 자동 배포 (권장)
```bash
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. 수동 배포
```bash
# 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. 배포 후 확인
```bash
# 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'"
**원인**: 마이그레이션 미실행

**해결**:
```bash
cd api.hyungi.net
npm run db:migrate
```

### 2. 계정 생성 실패
**원인**: User 역할이 roles 테이블에 없음

**해결**:
```sql
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`
- 한글 로마자 표기법: 국립국어원 기준