SR-SYSTEM/docs/04-api-spec.md

# API 명세서 (REST API Specification)

## 1. 공통 규격

### Base URL
```
http://{host}:{port}/api/v1
```

### 공통 응답 포맷
```json
// 성공
{ "success": true, "message": "...", "data": { ... } }

// 실패 (비즈니스 예외)
{ "success": false, "message": "...", "errorCode": "XXX_ERR_000", "data": null }
```

### 인증 헤더
```
Authorization: Bearer {jwt_access_token}
```

### 페이지네이션 (목록 조회)
```
Query Params: ?page=0&size=20&sort=createdAt,desc
Response: {
  "content": [...],
  "totalElements": 100,
  "totalPages": 5,
  "number": 0,
  "size": 20
}
```

---

## 2. 직원 (Employee)

### 직원 목록 조회
```
GET /employees
Query: ?roleCode=MANAGER&empStatus=ACTIVE&dispatchStatus=DISPATCHED&page=0&size=20
Response: Page<EmployeeDto>
```

### 직원 단건 조회
```
GET /employees/{empId}
Response: EmployeeDto
```

### 직원 검색 (자동완성)
```
GET /employees/search?keyword=김코딩
Response: [{ empId: 1, name: "김코딩", ... }]
```

### 내 정보 조회
```
GET /employees/me
Response: EmployeeDto (현재 로그인 사용자)
```

### 직원 생성
```
POST /employees
Body: {
  "loginId": "string",
  "password": "string",
  "name": "string",
  "email": "string",
  "roleCode": "EMPLOYEE",
  "joinedDate": "2026-01-01"
}
```

### 직원 수정
```
PUT /employees/{empId}
Body: { "email": "new@company.com", ... }
```

### 직원 삭제 (Soft Delete)
```
DELETE /employees/{empId}
```

---

## 3. 프로젝트 (Project)

### 프로젝트 목록 조회
```
GET /projects
Query: ?type=SI&status=ONGOING&page=0&size=20
```

### 프로젝트 단건 조회
```
GET /projects/{projectId}
```

### 프로젝트 생성
```
POST /projects
Body: {
  "projectType": "SI",
  "projectName": "차세대 시스템 구축",
  "contractCompany": "원청사",
  "endUserCompany": "고객사",
  "contractType": "TURN_KEY",
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "workLocationType": "ON_SITE",
  "workAddress": "서울시 강남구",
  "mainTaskDesc": "...",
  "internalManagerId": 1
}
```

---

## 4. 파견 이력 / 포트폴리오 (Dispatch)

### 파견 이력 목록 (직원별)
```
GET /employees/{empId}/dispatch-histories
```

### 파견 이력 등록
```
POST /dispatch-histories
Body: {
  "empId": 1,
  "projectId": 1,
  "startDate": "2026-01-01",
  "roleTitle": "BACKEND",
  "individualTech": "Java, Spring, Oracle",
  "performedTasks": "..."
}
```

### 포트폴리오 단건 조회
```
GET /dispatch-histories/{dispatchId}
```

---

## 5. SR 티켓 (Ticket)

### 티켓 목록 조회 (칸반)
```
GET /tickets
Query: ?category=BUG&priority=HIGH&status=OPEN&searchKeyword=오라클&page=0&size=50
Response: Page<{
  ticketId, title, priority, status, category,
  requesterName, assigneeName,
  dueDate, createdAt,
  isImminent: boolean  // dueDate - now < 24h
}>
```

### 티켓 단건 상세 조회
```
GET /tickets/{ticketId}
Response: {
  ...ticketInfo,
  comments: [{
    commentId, userId, userName,
    commentText, attachedFileUrl, createdAt
  }]
}
```

### 티켓 생성
```
POST /tickets
Body: {
  "projectId": 1,
  "category": "BUG",
  "priority": "HIGH",
  "title": "오라클 쿼리 튜닝 필요",
  "description": "실행 계획 상 Full Scan 발생..."
}
```

### 티켓 상태 전환
```
PUT /tickets/{ticketId}/status?status=IN_PROGRESS
Body (optional): {
  "assigneeId": 5  // ASSIGNED 또는 IN_PROGRESS 전환 시 필요
}

Status Flow: OPEN → ASSIGNED → IN_PROGRESS → RESOLVED → CLOSED
```

### 티켓 해결 처리
```
PUT /tickets/{ticketId}/resolve
Body: {
  "resolutionNote": "인덱스 재생성 및 통계 갱신 완료"
}
```

### 티켓 삭제 (Soft Delete)
```
DELETE /tickets/{ticketId}
```

---

## 6. 티켓 댓글 (Ticket Comment)

### 댓글 목록 조회
```
GET /tickets/{ticketId}/comments
```

### 댓글 등록
```
POST /tickets/{ticketId}/comments
Body: {
  "commentText": "분석 스크립트 첨부합니다.",
  "attachedFileUrl": "https://..."
}
```

### 댓글 삭제
```
DELETE /tickets/{ticketId}/comments/{commentId}
```

---

## 7. 업무 보고서 (Report)

### 보고서 목록 조회
```
GET /reports
Query: ?reportType=WEEKLY&status=SUBMITTED&userId=1&page=0&size=20
```

### 보고서 단건 조회
```
GET /reports/{reportId}
```

### 보고서 생성
```
POST /reports
Body: {
  "dispatchId": 1,
  "reportType": "WEEKLY",
  "targetDate": "2026-05-21",
  "completedTasks": "본사 시스템 SR 3건 해결 완료",
  "plannedTasks": "차주 성능 테스트 진행",
  "issuesAndRisks": "납기 일정 협의 필요",
  "status": "DRAFT"
}
```

### 보고서 상태 변경 (제출)
```
PUT /reports/{reportId}/status?status=SUBMITTED
```

### 보고서 결재 처리 (관리자 전용)
```
PUT /reports/{reportId}/review
Body: {
  "status": "APPROVED",
  "reviewComment": "수고하셨습니다."
}
// 또는
Body: {
  "status": "REJECTED",
  "reviewComment": "완료 실적 내역 SR 상세 분석 내용 보강 요망"
}
```

### 보고서 삭제 (DRAFT 상태만)
```
DELETE /reports/{reportId}
```

---

## 8. IT 자산 (Equipment)

### 장비 목록 조회
```
GET /equipment
Query: ?type=LAPTOP&status=AVAILABLE&manufacturer=Apple&page=0&size=20
```

### 장비 단건 조회
```
GET /equipment/{equipId}
```

### 장비 등록
```
POST /equipment
Body: {
  "equipmentType": "LAPTOP",
  "manufacturer": "Apple",
  "modelName": "MacBook Pro 16 M3",
  "serialNumber": "F2G8H3J9K1",
  "assetCode": "HQ-LP-2026-0001",
  "specifications": { "cpu": "M3 Pro", "ram": "36GB", "ssd": "512GB" },
  "purchaseDate": "2026-01-15",
  "warrantyExpDate": "2028-01-15"
}
```

### 장비 정보 수정
```
PUT /equipment/{equipId}
```

### 장비 삭제 (Soft Delete)
```
DELETE /equipment/{equipId}
```

### 장비 지급
```
POST /equipment/{equipId}/assign
Body: {
  "assigneeId": 2,
  "conditionNote": "미개봉 신품"
}
- 낙관적 락(version) 충돌 시 409 Conflict
```

### 장비 반납
```
PUT /equipment/{equipId}/return
Body: {
  "conditionNote": "액정 파손 - 수리 필요"
}
```

### 장비 지급 이력 조회
```
GET /equipment/{equipId}/assignments
```

### 장비 유지보수 등록
```
POST /equipment/{equipId}/maintenance
Body: {
  "maintenanceType": "REPAIR",
  "issueDescription": "키보드 침수 작동 불가",
  "actionTaken": "키보드 상판 교체 완료",
  "cost": 150000
}
```

### 장비 유지보수 이력 조회
```
GET /equipment/{equipId}/maintenances
```

---

## 9. 교육 (Training)

### 교육 진도 조회 (내 것)
```
GET /training/me
Response: [{ courseName, progressRate, status, updatedAt }]
```

### 직원별 교육 진도 조회 (관리자)
```
GET /training?userId=1
```

### 교육 진도 업데이트
```
PUT /training/{progressId}
Body: { "progressRate": 80, "status": "ONGOING" }
```

### 교육 요약 (관리자 대시보드)
```
GET /training/summary
Response: [{ courseName, totalEnrolled, completedCount, avgProgress }]
```

---

## 10. 알림 (Notification)

### 읽지 않은 알림 카운트
```
GET /notifications/unread
Response: { "count": 3 }
```

### 내 알림 목록
```
GET /notifications?page=0&size=20
```

### 알림 읽음 처리
```
PUT /notifications/{notificationId}/read
```