accura/wbx-spring
1
0
포크 0
코드 이슈 풀 리퀘스트 Actions 패키지 프로젝트 릴리즈 위키 활동
파일
9707a6eeb1a66cbe5d27cd5a9b6337b50a62f27c
wbx-spring/plans/wtmgr/07-api-spec.md
accura0117 9707a6eeb1 feat: FE 화면 구현 완료 + 샘플 데이터 + 결재라인 연동 
- WBS/TEAL 화면 실제 구현 (TreeTable, FileUpload, 버전관리)
- 시수이력/결재이력 화면 구현 (DataTable, Filter, Timeline)
- 비밀번호변경 화면 추가
- 로그인 snake_case 응답 매핑 수정
- Vite 프록시 8081 포트 수정
- auth guard에서 fetchMe 자동 호출
- V108 샘플 데이터 (10명 사용자, 4주 시수 215건, 결재 9건)
- 배너 추가 (WBX Spring)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:17:32 +09:00

8.9 KiB
Raw Blame 히스토리

07. REST API 스펙 요약

API 설계 원칙

  • Prefix: 모든 API는 /api/wtm/ prefix 사용 (WBX GW /api/gw/와 분리)
  • RESTful 네이밍: 복수형 명사 (/api/wtm/projects, /api/wtm/timesheets)
  • 표준 HTTP 메서드: GET/POST/PUT/DELETE
  • 페이징: WBX 호환 — ?skip=0&limit=20 (+ Spring Pageable 변환)
  • 응답 포맷 (WBX 호환):
    • 단일 객체: { "id": 1, ... } (response_path = "")
    • 목록: { "items": [...], "total": 150 } (response_path = "items")
    • 에러: { "detail": "...", "code": "..." } (FastAPI detail 키 호환)
  • 인증: Authorization: Bearer {JWT} (WBX 공유 JWT)
  • API 문서: SpringDoc OpenAPI (/swagger-ui) — 개발 모드만

전체 API 목록

Auth (인증)

Method Path 설명 Phase
POST /api/wtm/auth/login 내부 ID/PW 로그인 → JWT 발급 PH1-1
GET /api/wtm/auth/sso Azure Entra ID SSO 시작 PH1-1
GET /api/wtm/auth/sso/callback SSO 콜백 → JWT 발급 PH1-1
POST /api/wtm/auth/refresh Access Token 갱신 PH1-1
POST /api/wtm/auth/logout 로그아웃 PH1-1
POST /api/wtm/auth/password/reset 비밀번호 재설정 요청 PH1-1
PUT /api/wtm/auth/password/change 비밀번호 변경 PH1-1
GET /api/wtm/auth/me 내 정보 (역할 포함) PH1-1

Users (사용자)

Method Path 설명 Phase
GET /api/wtm/users 사용자 목록 (검색/필터) PH1-1
GET /api/wtm/users/{id} 사용자 상세 PH1-1
PUT /api/wtm/users/{id} 사용자 수정 PH1-1
PUT /api/wtm/users/{id}/roles 역할 부여/변경 PH1-1
POST /api/wtm/users/upload/internal 내부 인력 Excel 업로드 (No.1) PH1-1
POST /api/wtm/users/upload/subcontractor 외주 인력 Excel 업로드 (No.4) PH1-1
GET /api/wtm/users/upload/template 업로드 템플릿 다운로드 PH1-1
GET /api/wtm/admin/access-logs SA 액세스 로그 (No.24) PH1-2

Projects (프로젝트)

Method Path 설명 Phase
GET /api/wtm/projects 프로젝트 목록 PH1-1
POST /api/wtm/projects 프로젝트 생성 (No.25) PH1-1
GET /api/wtm/projects/{id} 프로젝트 상세 PH1-1
PUT /api/wtm/projects/{id} 프로젝트 수정 (No.26~28) PH1-1
GET /api/wtm/projects/my 내 배정 프로젝트 목록 (No.51~53) PH1-1
GET /api/wtm/projects/{id}/members 프로젝트 멤버 목록 PH1-1
POST /api/wtm/projects/{id}/members 멤버 배정 (No.47~48) PH1-1

WBS

Method Path 설명 Phase
POST /api/wtm/projects/{id}/wbs/upload P6 WBS 파일 업로드 (No.31) PH1-1
GET /api/wtm/projects/{id}/wbs/versions WBS 버전 목록 PH1-1
GET /api/wtm/projects/{id}/wbs/versions/{ver} WBS 트리 조회 PH1-1
POST /api/wtm/projects/{id}/wbs/versions/{ver}/activate 버전 활성화 PH1-1
GET /api/wtm/projects/{id}/canonical-wbs Canonical WBS 트리 (No.33~35) PH1-1
GET /api/wtm/projects/{id}/wbs/compare 버전 비교 (No.29) PH1-2

TEAL

Method Path 설명 Phase
POST /api/wtm/projects/{id}/teal/upload TEAL 업로드 (No.36~41) PH1-1
GET /api/wtm/projects/{id}/teal/versions TEAL 버전 목록 PH1-1
GET /api/wtm/projects/{id}/teal/active 활성 TEAL (시수 입력용) PH1-1
GET /api/wtm/projects/{id}/teal/by-wbs/{wbsId} WBS별 Activity 목록 PH1-1

Timesheets (시수)

Method Path 설명 Phase
GET /api/wtm/timesheets/week 주간 시수 조회/생성 PH1-1
POST /api/wtm/timesheets/{id}/entries 시수 항목 저장 PH1-1
PUT /api/wtm/timesheets/{id}/entries/batch 주간 일괄 저장 PH1-1
DELETE /api/wtm/timesheets/{id}/entries/{entryId} 항목 삭제 PH1-1
POST /api/wtm/timesheets/{id}/submit 시수 제출 (결재 요청) PH1-1
POST /api/wtm/timesheets/upload Excel 일괄 업로드 PH1-1
GET /api/wtm/timesheets/upload/template Excel 템플릿 다운로드 PH1-1
GET /api/wtm/timesheets/history 내 시수 이력 PH1-1

Approvals (결재)

Method Path 설명 Phase
GET /api/wtm/approvals/pending 내 결재 대기 목록 PH1-1
POST /api/wtm/approvals/{id}/approve 승인 PH1-1
POST /api/wtm/approvals/{id}/reject 반려 PH1-1
POST /api/wtm/approvals/batch-approve 일괄 승인 PH1-1
POST /api/wtm/approvals/{id}/comments 코멘트 PH1-1
GET /api/wtm/approvals/{id} 결재 상세 PH1-1
GET /api/wtm/approvals/history 결재 처리 이력 PH1-1
GET /api/wtm/approvals/overdue 초과 미처리 목록 (No.75) PH1-2

Reports (리포트)

Method Path 설명 Phase
GET /api/wtm/reports/project-hours 프로젝트별 시수 (No.82) PH1-1
GET /api/wtm/reports/project-hours/export Excel 다운로드 PH1-1
GET /api/wtm/reports/wbs-hours WBS Level별 시수 (No.83) PH1-1
GET /api/wtm/reports/wbs-hours/export Excel 다운로드 PH1-1
GET /api/wtm/reports/phase-ratio Phase별 비율 (No.85) PH1-2
GET /api/wtm/reports/np-ratio NP 비율 (No.86) PH1-2

Home (대시보드)

Method Path 설명 Phase
GET /api/wtm/home/dashboard 역할별 대시보드 데이터 PH1-1
GET /api/wtm/home/notifications 알림 목록 (미승인 등) PH1-1

표준 응답 포맷

// 성공 — 단일 객체 (apis.response_path = "")
{ "id": 1, "weekStartDate": "2025-04-07", "status": "DRAFT", "entries": [...] }

// 성공 — 목록 + 페이징 (apis.response_path = "items")
{
  "items": [...],
  "total": 150,
  "skip": 0,
  "limit": 20
}

// 에러 — WBX 호환 (detail 키 사용)
{
  "detail": "주간 합계 54시간 — 최대 52h 초과",
  "code": "TIMESHEET_RULE_001"
}

WBX 호환 핵심: 에러는 detail 키 (FastAPI 형식), 목록은 items 키

Overhead Types (Non-Project 카테고리 관리)

Method Path 설명 Phase
GET /api/wtm/overhead-types Overhead 유형 목록 PH1-1
POST /api/wtm/overhead-types Overhead 유형 생성 (SA) PH1-1
PUT /api/wtm/overhead-types/{id} Overhead 유형 수정 (SA) PH1-1

Work Rules (근무 규칙 설정)

Method Path 설명 Phase
GET /api/wtm/work-rules 근무 규칙 조회 (일 8h, 주 52h, Location별) PH1-1
PUT /api/wtm/work-rules 근무 규칙 수정 (SA) PH1-1

Resource Assignment (인력 배정)

Method Path 설명 Phase
GET /api/wtm/projects/{id}/assignments 프로젝트 인력 배정 목록 PH1-1
POST /api/wtm/projects/{id}/assignments 인력 배정 (PM) PH1-1
PUT /api/wtm/projects/{id}/assignments/{assignId} 배정 수정 PH1-1
DELETE /api/wtm/projects/{id}/assignments/{assignId} 배정 해제 PH1-1
GET /api/wtm/projects/{id}/assignments/available 배정 가능 인력 조회 PH1-1

WBS-Discipline (WBS-Discipline 매핑)

Method Path 설명 Phase
GET /api/wtm/projects/{id}/wbs-disciplines WBS별 Discipline 매핑 조회 PH1-1
PUT /api/wtm/projects/{id}/wbs-disciplines WBS-Discipline 매핑 저장 PH1-1

HR Integration (SAP BTP 연동)

Method Path 설명 Phase
POST /api/wtm/integration/hr/upload SA 수동 Excel 업로드 PH1-2
POST /api/wtm/integration/hr/sync SAP BTP 자동 동기화 수신 PH1-2

Cognite Export (데이터 연계)

Method Path 설명 Phase
GET /api/wtm/integration/cognite/export Cognite Export (Employee/Project/WBS/Time Fact) PH2

총 API 수

모듈 PH1-1차 PH1-2차 PH2 합계
Auth 8 0 0 8
Users 7 1 0 8
Projects 7 0 0 7
WBS 5 2 0 7
TEAL 4 0 0 4
Timesheets 8 0 0 8
Approvals 7 1 0 8
Reports 4 2 3 9
Home 2 0 0 2
Overhead Types 3 0 0 3
Work Rules 2 0 0 2
Resource Assign 5 0 0 5
WBS-Discipline 2 0 0 2
HR Integration 0 2 0 2
Cognite 0 0 1 1
합계 67 6 6 79

11-requirements-traceability.md에서 추가된 API 반영 (Overhead Types, Work Rules, Resource Assign, WBS-Discipline, HR Integration, Cognite)

새 Issue에서 참조 Git Blame 보기 고유 링크 복사