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