diff --git a/개발로그/2026-01-19_작업자_계정연동_기능.md b/개발로그/2026-01-19_작업자_계정연동_기능.md new file mode 100644 index 0000000..78af11d --- /dev/null +++ b/개발로그/2026-01-19_작업자_계정연동_기능.md @@ -0,0 +1,476 @@ +# 작업자-계정 연동 기능 가이드 + +## 작업 일시 +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 + + +체크 시 로그인 계정이 자동 생성됩니다 (나의 대시보드, 연차/출퇴근 관리 가능) + + + +체크: 현장직 (출퇴근 관리 필요) / 체크 해제: 사무직 (출퇴근 관리 불필요) + + + +퇴사한 작업자로 표시됩니다. 작업 보고서에서 제외됩니다 +``` + +#### worker-management.js 변경 + +**작업자 카드 렌더링** +```javascript +// 계정 연동 상태 표시 +const hasAccount = worker.user_id !== null; + +// 이름 옆에 아이콘 표시 +${worker.worker_name} +${hasAccount ? '🔐' : ''} + +// 메타 정보에 계정 상태 표시 +${hasAccount ? + '🔐 계정 연동됨' : + '⚪ 계정 없음'} +``` + +**저장 시 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` +- 한글 로마자 표기법: 국립국어원 기준