5493788800
- 28개 엔드포인트 전체 명세 (요청/응답 포맷 포함) - 상태 흐름도, 탭 구성, 버튼 조건 등 UI 가이드 - INDEX.md에 frontend/api-specs/ 섹션 등록
701 lines
17 KiB
Markdown
701 lines
17 KiB
Markdown
# 결재관리 API 명세
|
|
|
|
> **작성일**: 2026-03-11
|
|
> **상태**: 개발 완료 (API 배포됨)
|
|
> **Base URL**: `api.codebridge-x.com` (운영) / `api.dev.codebridge-x.com` (개발)
|
|
|
|
---
|
|
|
|
## 1. 개요
|
|
|
|
결재관리 시스템의 전체 API 명세. 기안, 결재, 참조, 위임, 완료함 등 모든 결재 워크플로우를 지원한다.
|
|
|
|
### 1.1 인증
|
|
|
|
모든 요청에 다음 헤더가 필요하다:
|
|
|
|
```
|
|
X-API-KEY: {api_key}
|
|
Authorization: Bearer {token}
|
|
```
|
|
|
|
### 1.2 공통 응답 형식
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "조회되었습니다.",
|
|
"data": { ... }
|
|
}
|
|
```
|
|
|
|
에러 시:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "에러 메시지"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 상태 흐름도
|
|
|
|
```
|
|
┌──────────┐
|
|
│ draft │ 임시저장
|
|
└────┬─────┘
|
|
│ submit (상신)
|
|
▼
|
|
┌──────────┐
|
|
┌────►│ pending │ 결재 진행중
|
|
│ └──┬─┬─┬──┘
|
|
│ │ │ │
|
|
release- │ hold │ │ │ approve (각 단계)
|
|
hold │ ▼ │ │ │
|
|
│ ┌──────┐│ │ │
|
|
└─┤on_hold││ │ │ 보류
|
|
└──────┘│ │ │
|
|
│ │ │
|
|
┌───────────────┘ │ └──────────────┐
|
|
│ cancel (회수) │ │ reject (반려)
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
│cancelled │ │ approved │ │ rejected │
|
|
└──────────┘ └──────────┘ └──────────┘
|
|
│
|
|
│ submit (재상신)
|
|
▼
|
|
┌──────────┐
|
|
│ pending │
|
|
└──────────┘
|
|
```
|
|
|
|
### 2.1 상태값
|
|
|
|
| 상태 | 값 | 설명 | UI 배지 색상 |
|
|
|------|---|------|-------------|
|
|
| 임시저장 | `draft` | 작성 중, 아직 미상신 | gray |
|
|
| 진행중 | `pending` | 결재 진행 중 | blue |
|
|
| 승인 | `approved` | 최종 승인 완료 | green |
|
|
| 반려 | `rejected` | 결재자가 반려 | red |
|
|
| 회수 | `cancelled` | 기안자가 회수 | yellow |
|
|
| 보류 | `on_hold` | 결재자가 보류 | orange |
|
|
|
|
### 2.2 결재 단계 유형
|
|
|
|
| 유형 | 값 | 설명 |
|
|
|------|---|------|
|
|
| 결재 | `approval` | 승인/반려 권한 |
|
|
| 합의 | `agreement` | 승인/반려 권한 (다른 부서) |
|
|
| 참조 | `reference` | 열람만 가능 |
|
|
|
|
### 2.3 결재 단계 상태
|
|
|
|
| 상태 | 값 | 설명 |
|
|
|------|---|------|
|
|
| 대기 | `pending` | 아직 미처리 |
|
|
| 승인 | `approved` | 승인함 |
|
|
| 반려 | `rejected` | 반려함 |
|
|
| 건너뜀 | `skipped` | 전결/회수로 건너뜀 |
|
|
| 보류 | `on_hold` | 보류 중 |
|
|
|
|
---
|
|
|
|
## 3. 목록 API (탭별)
|
|
|
|
### 3.1 기안함 (내가 기안한 문서)
|
|
|
|
```
|
|
GET /api/v1/approvals/drafts
|
|
```
|
|
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
|
|---------|------|:----:|------|
|
|
| `status` | string | - | `draft`, `pending`, `approved`, `rejected`, `cancelled`, `on_hold` |
|
|
| `search` | string | - | 제목/문서번호 검색 |
|
|
| `sort_by` | string | - | `created_at`(기본), `drafted_at`, `completed_at`, `title`, `status` |
|
|
| `sort_dir` | string | - | `asc`, `desc`(기본) |
|
|
| `per_page` | int | - | 페이지당 건수 (기본 20) |
|
|
| `page` | int | - | 페이지 번호 |
|
|
|
|
**응답 데이터** (페이지네이션):
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"document_number": "APR-20260311-0001",
|
|
"title": "출장 품의서",
|
|
"status": "pending",
|
|
"is_urgent": false,
|
|
"drafted_at": "2026-03-11 10:00:00",
|
|
"completed_at": null,
|
|
"created_at": "2026-03-11",
|
|
"form": {
|
|
"id": 1,
|
|
"name": "품의서",
|
|
"code": "request",
|
|
"category": "request"
|
|
},
|
|
"drafter": {
|
|
"id": 10,
|
|
"name": "홍길동",
|
|
"tenant_profile": {
|
|
"department": { "id": 3, "name": "영업부" },
|
|
"position_key": "manager"
|
|
}
|
|
},
|
|
"steps": [
|
|
{
|
|
"id": 1,
|
|
"step_order": 1,
|
|
"step_type": "approval",
|
|
"status": "approved",
|
|
"approver_name": "김팀장",
|
|
"approver_department": "영업부",
|
|
"approver_position": "팀장",
|
|
"comment": null,
|
|
"acted_at": "2026-03-11 11:00:00",
|
|
"approver": {
|
|
"id": 5,
|
|
"name": "김팀장"
|
|
}
|
|
},
|
|
{
|
|
"id": 2,
|
|
"step_order": 2,
|
|
"step_type": "approval",
|
|
"status": "pending",
|
|
"approver_name": "박부장",
|
|
"approver_department": "영업부",
|
|
"approver_position": "부장",
|
|
"approver": {
|
|
"id": 8,
|
|
"name": "박부장"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"current_page": 1,
|
|
"last_page": 3,
|
|
"per_page": 20,
|
|
"total": 52
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.2 기안함 현황 카드
|
|
|
|
```
|
|
GET /api/v1/approvals/drafts/summary
|
|
```
|
|
|
|
파라미터 없음.
|
|
|
|
```json
|
|
{
|
|
"total": 52,
|
|
"draft": 3,
|
|
"pending": 12,
|
|
"approved": 30,
|
|
"rejected": 7
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.3 결재함 (내가 결재할 문서)
|
|
|
|
```
|
|
GET /api/v1/approvals/inbox
|
|
```
|
|
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
|
|---------|------|:----:|------|
|
|
| `status` | string | - | `requested`(내 차례), `scheduled`(예정), `completed`(처리완료), `rejected`(내가 반려) |
|
|
| `sort_by` | string | - | `created_at`(기본), `drafted_at`, `completed_at`, `title` |
|
|
| `sort_dir` | string | - | `asc`, `desc`(기본) |
|
|
| `start_date` | string | - | `YYYY-MM-DD` 시작일 |
|
|
| `end_date` | string | - | `YYYY-MM-DD` 종료일 |
|
|
| `per_page` | int | - | 페이지당 건수 |
|
|
| `page` | int | - | 페이지 번호 |
|
|
|
|
> **`requested`**: 현재 내가 처리해야 할 문서 (내 차례)
|
|
> **`scheduled`**: 아직 내 차례가 아닌 문서 (앞 결재자가 미처리)
|
|
|
|
---
|
|
|
|
### 3.4 결재함 현황 카드
|
|
|
|
```
|
|
GET /api/v1/approvals/inbox/summary
|
|
```
|
|
|
|
```json
|
|
{
|
|
"requested": 5,
|
|
"scheduled": 3,
|
|
"completed": 20,
|
|
"rejected": 2
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.5 참조함 (내가 참조된 문서)
|
|
|
|
```
|
|
GET /api/v1/approvals/reference
|
|
```
|
|
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
|
|---------|------|:----:|------|
|
|
| `is_read` | boolean | - | `true`(읽음), `false`(안읽음) |
|
|
| `sort_by` | string | - | `created_at`(기본), `drafted_at`, `completed_at`, `title` |
|
|
| `sort_dir` | string | - | `asc`, `desc`(기본) |
|
|
| `per_page` | int | - | 페이지당 건수 |
|
|
| `page` | int | - | 페이지 번호 |
|
|
|
|
---
|
|
|
|
### 3.6 완료함 (내 기안 완료 + 내가 처리한 문서)
|
|
|
|
```
|
|
GET /api/v1/approvals/completed
|
|
```
|
|
|
|
IndexRequest와 동일한 파라미터 사용.
|
|
|
|
---
|
|
|
|
### 3.7 완료함 현황 카드
|
|
|
|
```
|
|
GET /api/v1/approvals/completed/summary
|
|
```
|
|
|
|
```json
|
|
{
|
|
"approved": 25,
|
|
"rejected": 5,
|
|
"cancelled": 2,
|
|
"unread": 3
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.8 뱃지 카운트 (사이드바/GNB용)
|
|
|
|
```
|
|
GET /api/v1/approvals/badge-counts
|
|
```
|
|
|
|
```json
|
|
{
|
|
"pending": 5,
|
|
"draft": 2,
|
|
"reference_unread": 3,
|
|
"completed_unread": 1
|
|
}
|
|
```
|
|
|
|
> **UI 활용**: 사이드바 메뉴 옆에 `pending` 뱃지, 참조 탭에 `reference_unread` 뱃지 등
|
|
|
|
---
|
|
|
|
## 4. 문서 CRUD
|
|
|
|
### 4.1 문서 상세
|
|
|
|
```
|
|
GET /api/v1/approvals/{id}
|
|
```
|
|
|
|
상세 응답에는 `form.template` (양식 필드 정의), 전체 `steps` 목록, 연결된 `linkable` 문서 데이터가 포함된다.
|
|
|
|
---
|
|
|
|
### 4.2 문서 생성 (임시저장 또는 즉시 상신)
|
|
|
|
```
|
|
POST /api/v1/approvals
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `form_id` | int | O* | 결재 양식 ID (`form_code`와 택1) |
|
|
| `form_code` | string | O* | 결재 양식 코드 (`form_id`와 택1) |
|
|
| `title` | string | O | 제목 (최대 200자) |
|
|
| `content` | object | O | 양식 데이터 (JSON) |
|
|
| `body` | string | - | 본문 HTML |
|
|
| `is_urgent` | boolean | - | 긴급 여부 |
|
|
| `department_id` | int | - | 기안 부서 ID |
|
|
| `line_id` | int | - | 결재선 템플릿 ID |
|
|
| `attachments` | int[] | - | 첨부파일 ID 배열 |
|
|
| `submit` | boolean | - | `true`면 즉시 상신 |
|
|
| `steps` | array | 조건* | 결재선 (`submit=true`일 때 필수) |
|
|
|
|
**steps 배열 항목**:
|
|
|
|
| 필드 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| `step_type` (또는 `type`) | string | `approval`, `agreement`, `reference` |
|
|
| `approver_id` (또는 `user_id`) | int | 결재자 ID |
|
|
| `step_order` | int | 순서 (생략 시 자동 부여) |
|
|
|
|
```json
|
|
{
|
|
"form_code": "request",
|
|
"title": "출장 품의서",
|
|
"content": {
|
|
"destination": "부산",
|
|
"purpose": "거래처 미팅",
|
|
"amount": 500000
|
|
},
|
|
"submit": true,
|
|
"steps": [
|
|
{ "step_type": "approval", "user_id": 5 },
|
|
{ "step_type": "approval", "user_id": 8 },
|
|
{ "step_type": "reference", "user_id": 12 }
|
|
]
|
|
}
|
|
```
|
|
|
|
> **참고**: `submit: false`이면 임시저장만 하고 `steps`는 선택 사항이다.
|
|
|
|
---
|
|
|
|
### 4.3 문서 수정 (임시저장 상태만)
|
|
|
|
```
|
|
PATCH /api/v1/approvals/{id}
|
|
```
|
|
|
|
모든 필드 선택적. `steps`를 전달하면 기존 결재선을 교체한다.
|
|
|
|
---
|
|
|
|
### 4.4 문서 삭제 (임시저장/반려 상태만)
|
|
|
|
```
|
|
DELETE /api/v1/approvals/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 워크플로우 액션
|
|
|
|
### 5.1 상신 (임시저장 → 진행중)
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/submit
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `steps` | array | - | 새 결재선 (생략 시 기존 결재선 사용) |
|
|
|
|
> **재상신**: 반려 상태에서도 호출 가능. 반려 이력이 `rejection_history`에 자동 저장되고, `resubmit_count`가 1 증가한다.
|
|
|
|
---
|
|
|
|
### 5.2 승인
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/approve
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `comment` | string | - | 승인 의견 (최대 1000자) |
|
|
|
|
> 현재 내 차례인 결재 단계만 승인 가능. 마지막 결재자가 승인하면 문서 상태가 `approved`로 변경된다.
|
|
|
|
---
|
|
|
|
### 5.3 반려
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/reject
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `comment` | string | **O** | 반려 사유 (필수, 최대 1000자) |
|
|
|
|
---
|
|
|
|
### 5.4 회수 (기안자만)
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/cancel
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `recall_reason` | string | - | 회수 사유 (최대 1000자) |
|
|
|
|
> 첫 번째 결재자가 이미 처리한 경우 회수 불가 (에러 반환).
|
|
|
|
---
|
|
|
|
### 5.5 보류 (현재 결재자만)
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/hold
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `comment` | string | **O** | 보류 사유 (필수, 최대 1000자) |
|
|
|
|
---
|
|
|
|
### 5.6 보류 해제 (보류한 결재자만)
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/release-hold
|
|
```
|
|
|
|
파라미터 없음. 보류 상태를 다시 진행중으로 되돌린다.
|
|
|
|
---
|
|
|
|
### 5.7 전결 (현재 결재자가 최종 승인)
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/pre-decide
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `comment` | string | - | 전결 의견 (최대 1000자) |
|
|
|
|
> 현재 결재자 이후의 모든 단계를 `skipped`로 변경하고 문서를 `approved`로 확정한다.
|
|
|
|
---
|
|
|
|
### 5.8 복사 재기안
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/copy
|
|
```
|
|
|
|
파라미터 없음. 완료/반려/회수된 문서를 복사하여 새 임시저장 문서를 생성한다. 결재선(스냅샷 포함)도 함께 복사된다.
|
|
|
|
**응답**: 새로 생성된 Approval 객체
|
|
|
|
---
|
|
|
|
## 6. 참조 열람 관리
|
|
|
|
### 6.1 참조 열람 처리
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/read
|
|
```
|
|
|
|
### 6.2 참조 미열람 처리
|
|
|
|
```
|
|
POST /api/v1/approvals/{id}/unread
|
|
```
|
|
|
|
### 6.3 완료함 일괄 읽음 처리
|
|
|
|
```
|
|
POST /api/v1/approvals/completed/mark-read
|
|
```
|
|
|
|
> 기안자의 미읽음 완료 문서를 일괄로 읽음 처리한다.
|
|
|
|
---
|
|
|
|
## 7. 위임 관리
|
|
|
|
부재 시 다른 사용자에게 결재 권한을 위임한다.
|
|
|
|
### 7.1 위임 목록
|
|
|
|
```
|
|
GET /api/v1/approvals/delegations
|
|
```
|
|
|
|
---
|
|
|
|
### 7.2 위임 생성
|
|
|
|
```
|
|
POST /api/v1/approvals/delegations
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
|------|------|:----:|------|
|
|
| `delegate_id` | int | **O** | 대리자 ID |
|
|
| `start_date` | string | **O** | 시작일 (`YYYY-MM-DD`, 오늘 이후) |
|
|
| `end_date` | string | **O** | 종료일 (`YYYY-MM-DD`, 시작일 이후) |
|
|
| `form_ids` | int[] | - | 특정 양식만 위임 (생략 시 전체) |
|
|
| `notify_delegator` | boolean | - | 위임자에게 알림 여부 |
|
|
| `reason` | string | - | 위임 사유 (최대 500자) |
|
|
|
|
---
|
|
|
|
### 7.3 위임 수정
|
|
|
|
```
|
|
PATCH /api/v1/approvals/delegations/{id}
|
|
```
|
|
|
|
모든 필드 선택적. `is_active: false`로 비활성화 가능.
|
|
|
|
---
|
|
|
|
### 7.4 위임 삭제
|
|
|
|
```
|
|
DELETE /api/v1/approvals/delegations/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 결재 양식 API
|
|
|
|
### 8.1 양식 목록
|
|
|
|
```
|
|
GET /api/v1/approval-forms
|
|
```
|
|
|
|
### 8.2 활성 양식 목록 (기안 시 드롭다운용)
|
|
|
|
```
|
|
GET /api/v1/approval-forms/active
|
|
```
|
|
|
|
### 8.3 양식 상세
|
|
|
|
```
|
|
GET /api/v1/approval-forms/{id}
|
|
```
|
|
|
|
### 8.4 양식 생성
|
|
|
|
```
|
|
POST /api/v1/approval-forms
|
|
```
|
|
|
|
### 8.5 양식 수정
|
|
|
|
```
|
|
PATCH /api/v1/approval-forms/{id}
|
|
```
|
|
|
|
### 8.6 양식 삭제
|
|
|
|
```
|
|
DELETE /api/v1/approval-forms/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 결재선 템플릿 API
|
|
|
|
### 9.1 결재선 목록
|
|
|
|
```
|
|
GET /api/v1/approval-lines
|
|
```
|
|
|
|
### 9.2 결재선 상세
|
|
|
|
```
|
|
GET /api/v1/approval-lines/{id}
|
|
```
|
|
|
|
### 9.3 결재선 생성
|
|
|
|
```
|
|
POST /api/v1/approval-lines
|
|
```
|
|
|
|
### 9.4 결재선 수정
|
|
|
|
```
|
|
PATCH /api/v1/approval-lines/{id}
|
|
```
|
|
|
|
### 9.5 결재선 삭제
|
|
|
|
```
|
|
DELETE /api/v1/approval-lines/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 화면 구성 가이드
|
|
|
|
### 10.1 메인 탭 구조
|
|
|
|
```
|
|
┌─────────┬─────────┬─────────┬─────────┐
|
|
│ 기안함 │ 결재함 │ 참조함 │ 완료함 │
|
|
│ (drafts)│ (inbox) │(reference│(completed│
|
|
│ │ [5] │) [3] │) [1] │
|
|
└─────────┴─────────┴─────────┴─────────┘
|
|
```
|
|
|
|
- 각 탭의 뱃지 숫자는 `GET /badge-counts`로 가져온다
|
|
- `pending` → 결재함 뱃지
|
|
- `reference_unread` → 참조함 뱃지
|
|
- `completed_unread` → 완료함 뱃지
|
|
|
|
### 10.2 결재함 서브 필터
|
|
|
|
| 필터 | status 값 | 설명 |
|
|
|------|----------|------|
|
|
| 결재 요청 | `requested` | 현재 내 차례 (액션 버튼 표시) |
|
|
| 예정 | `scheduled` | 내 차례 대기 |
|
|
| 처리 완료 | `completed` | 내가 처리한 문서 |
|
|
| 반려 | `rejected` | 내가 반려한 문서 |
|
|
|
|
### 10.3 문서 상세 페이지 액션 버튼
|
|
|
|
| 조건 | 표시할 버튼 |
|
|
|------|-----------|
|
|
| 내가 기안자 + `draft`/`rejected` | 수정, 삭제, 상신 |
|
|
| 내가 기안자 + `pending`/`on_hold` | 회수 |
|
|
| 내가 현재 결재자 + `pending` | 승인, 반려, 보류, 전결 |
|
|
| 내가 보류한 결재자 + `on_hold` | 보류해제 |
|
|
| `approved`/`rejected`/`cancelled` | 복사 재기안 |
|
|
| 내가 참조자 | 열람/미열람 토글 |
|
|
|
|
### 10.4 결재선 표시
|
|
|
|
결재 단계를 순서대로 표시한다. 각 단계에 스냅샷 정보를 사용한다:
|
|
|
|
```
|
|
[1] 결재 | 김팀장 (영업부/팀장) → 승인 ✓ (2026-03-11 11:00)
|
|
[2] 결재 | 박부장 (영업부/부장) → 대기 중 ◯
|
|
[3] 합의 | 이과장 (재무부/과장) → 대기 중 ◯
|
|
[4] 참조 | 정대리 (인사부/대리) → 미열람
|
|
```
|
|
|
|
> **스냅샷 필드**: `approver_name`, `approver_department`, `approver_position`은 결재선 생성 시점의 정보가 저장된다. 결재자가 부서 이동해도 결재 당시 정보가 유지된다.
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- `dev/dev_plans/approval-system-unification-plan.md` - 결재 시스템 통합 계획서
|
|
- `frontend/api-specs/document-api-integration.md` - 문서 API 연동 명세
|
|
|
|
---
|
|
|
|
**최종 업데이트**: 2026-03-11
|