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

작업자 계정 연동 기능에 대한 상세 가이드 문서를 작성했습니다. ## 문서 내용 ### 1. 기능 개요 - 개념 변경 (작업 보고서 표시 → 계정 연동) - 주요 변경사항 설명 ### 2. 기술 상세 - 데이터베이스 스키마 - 백엔드 API 구현 - 프론트엔드 구현 - 한글→영문 변환 로직 ### 3. 사용 가이드 - 신규 작업자 등록 + 계정 생성 - 기존 작업자에 계정 추가 - 계정 연동 해제 - 퇴사 처리 ### 4. 배포 및 운영 - 배포 절차 - 테스트 시나리오 - 문제 해결 가이드 - 보안 고려사항 ### 5. 향후 개선 계획 - 비밀번호 정책 - 계정 관리 UI - 대량 작업 기능 - 알림 기능 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-19 10:29:18 +09:00
parent 1e4dbf10db
commit 6933f67a2e
1 changed files with 476 additions and 0 deletions
--- a/개발로그/2026-01-19_작업자_계정연동_기능.md
+++ 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
+<!-- 계정 생성/연동 -->
+<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`
+- 한글 로마자 표기법: 국립국어원 기준