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

API 명세서 (REST API Specification)

1. 공통 규격

Base URL

http://{host}:{port}/api/v1

공통 응답 포맷

// 성공
{ "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