accura/wbx-spring
1
0
포크 0
코드 이슈 풀 리퀘스트 Actions 패키지 프로젝트 릴리즈 위키 활동
파일
df723f1d5991e2e7ef980621dd325506e8909111
wbx-spring/wbx-spring-core/HanwhaOCN/wtmgr/07-api-spec.md
accura0117 df723f1d59 feat: WTM 멀티프로젝트 플랫폼 구축 (BE + FE 전체 구현) 
Phase 0: wbx-spring-core 라이브러리 전환
- java-library 플러그인, WbxAutoConfiguration, Admin 조건부 활성화
- 루트 settings.gradle + build.gradle (멀티모듈)

Phase 1: wtm-api 모듈 생성
- 23개 JPA Entity, 14개 Controller, 79개 API 엔드포인트
- Flyway V100~V107 MySQL 마이그레이션
- TimesheetRuleEngine, TimesheetApprovalHandler, P6WbsParser

Phase 2: wtm-frontend (Vue 3 + PrimeVue 4)
- 10개 도메인 모듈, 17개 View, 5개 서브컴포넌트
- 반응형 레이아웃 (AppLayout, AppSidebar, AppTopbar)
- BaseCrudTable, BaseFormDialog, BasePageHeader 표준 컴포넌트
- JWT 인터셉터, 역할 기반 메뉴 필터링

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

216 줄
8.9 KiB
Markdown
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 |
---
## 표준 응답 포맷
```json
// 성공 — 단일 객체 (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 보기 고유 링크 복사