# 조직도 React 프론트엔드 구현 가이드

> **작성일**: 2026-03-22
> **상태**: API 완료, FE 구현 대기
> **대상**: React (Next.js) 프론트엔드 개발자
> **페이지 URL**: `/hr/org-chart`

---

## 1. 개요

MNG의 조직도 관리 기능을 React로 재구현한다. API는 이미 구현 완료(`/v1/org-chart`).
드래그 앤 드롭으로 직원 배치, 부서 순서/계층 변경, 부서 숨기기 기능을 제공한다.

---

## 2. API 엔드포인트

| Method | Path | 설명 |
|--------|------|------|
| GET | `/v1/org-chart` | 조직도 전체 (트리+직원+통계) |
| GET | `/v1/org-chart/stats` | 통계 (전체/배치/미배치) |
| GET | `/v1/org-chart/unassigned?q=` | 미배치 직원 검색 |
| POST | `/v1/org-chart/assign` | 직원 → 부서 배치 |
| POST | `/v1/org-chart/unassign` | 직원 미배치 처리 |
| PUT | `/v1/org-chart/reorder-employees` | 직원 일괄 이동 |
| PUT | `/v1/org-chart/reorder-departments` | 부서 순서/계층 변경 |
| PATCH | `/v1/org-chart/departments/{id}/toggle-hide` | 부서 숨기기 토글 |

> Swagger UI: `/api-docs` → "OrgChart" 태그 참조

---

## 3. 응답 구조

### 3.1 GET `/v1/org-chart`

```json
{
  "success": true,
  "data": {
    "company": {
      "name": "주일산업",
      "ceo_name": "홍길동"
    },
    "departments": [
      {
        "id": 1,
        "name": "경영지원팀",
        "code": "MGT",
        "parent_id": null,
        "sort_order": 1,
        "is_active": true,
        "orgchart_hidden": false,
        "children": [],
        "employees": [
          {
            "id": 5,
            "user_id": 3,
            "department_id": 1,
            "display_name": "김과장",
            "position_label": "과장"
          }
        ]
      }
    ],
    "hidden_departments": [
      { "id": 5, "name": "해외사업팀", "code": "OVS" }
    ],
    "unassigned": [
      { "id": 12, "user_id": 8, "display_name": "이사원", "position_label": "사원" }
    ],
    "stats": {
      "total": 50,
      "assigned": 42,
      "unassigned": 8
    }
  }
}
```

### 3.2 요청 바디 예시

**POST `/v1/org-chart/assign`**:
```json
{ "employee_id": 5, "department_id": 3 }
```

**PUT `/v1/org-chart/reorder-employees`**:
```json
{
  "moves": [
    { "employee_id": 5, "department_id": 3 },
    { "employee_id": 6, "department_id": null }
  ]
}
```

**PUT `/v1/org-chart/reorder-departments`**:
```json
{
  "orders": [
    { "id": 1, "parent_id": null, "sort_order": 0 },
    { "id": 2, "parent_id": 1, "sort_order": 1 }
  ]
}
```

**PATCH `/v1/org-chart/departments/{id}/toggle-hide`**:
```json
{ "hidden": true }
```

---

## 4. 컴포넌트 구조 (제안)

```
src/
├── app/[locale]/(protected)/hr/
│   └── org-chart/
│       └── page.tsx                    ← 페이지 진입점
├── components/hr/org-chart/
│   ├── index.tsx                       ← 메인 컨테이너
│   ├── OrgChartTree.tsx                ← 부서 트리 렌더링
│   ├── DepartmentNode.tsx              ← 부서 카드 (접기/펼치기, 숨기기)
│   ├── EmployeeCard.tsx                ← 직원 카드 (드래그 가능)
│   ├── UnassignedPanel.tsx             ← 미배치 직원 패널 (검색 포함)
│   ├── HiddenDepartmentsPanel.tsx      ← 숨겨진 부서 복원 패널
│   ├── OrgChartStats.tsx               ← 상단 통계 표시
│   ├── CompanyHeader.tsx               ← 회사명 + CEO 표시
│   ├── actions.ts                      ← Server Actions
│   └── types.ts                        ← TypeScript 타입 정의
```

---

## 5. UI 구성 (MNG 참조)

MNG 조직도 UI: `mng/resources/views/rd/org-chart.blade.php`

### 5.1 화면 레이아웃

```
┌───────────────────────────────────────────────────────┐
│  조직도 관리          전체 50명 | 배치 42명 | 미배치 8명  │  ← 헤더 + 통계
├───────────────────────────────────────────────────────┤
│ ┌─미배치 직원──────┐  ┌─조직도 트리───────────────────┐ │
│ │ 🔍 검색          │  │ ┌──────────────────────────┐ │ │
│ │                  │  │ │ 회사명                    │ │ │
│ │ ▪ 이사원 (사원)  │  │ │ CEO: 홍길동               │ │ │
│ │ ▪ 박대리 (대리)  │  │ └──────────────────────────┘ │ │
│ │                  │  │                              │ │
│ │  (드래그 가능)   │  │ ┌─경영지원팀 (MGT)──────────┐ │ │
│ │                  │  │ │ 김과장 (과장) [미배치 ✕]   │ │ │
│ │                  │  │ │ 최대리 (대리) [미배치 ✕]   │ │ │
│ │                  │  │ └──────────────────────────┘ │ │
│ │                  │  │ ┌─생산팀 (PRD)───────────────┐ │ │
│ │                  │  │ │ ...                        │ │ │
│ │                  │  │ └────────────────────────────┘ │ │
│ └──────────────────┘  └──────────────────────────────┘ │
│ ┌─숨겨진 부서──────────────────────────────────────────┐ │
│ │ 해외사업팀 [복원]  영업3팀 [복원]                     │ │
│ └──────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────┘
```

### 5.2 인터랙션

| 동작 | 효과 | API 호출 |
|------|------|---------|
| 미배치 직원 → 부서 드래그 | 직원 배치 | `POST /assign` 또는 `PUT /reorder-employees` |
| 부서 내 직원 → 미배치 패널 드래그 | 직원 미배치 | `POST /unassign` |
| 부서 카드 드래그 (순서 변경) | 부서 순서/계층 변경 | `PUT /reorder-departments` |
| 부서 카드 더블클릭 → "숨기기" | 조직도에서 숨김 | `PATCH /departments/{id}/toggle-hide` |
| 숨겨진 부서 "복원" 클릭 | 조직도에 다시 표시 | `PATCH /departments/{id}/toggle-hide` |

---

## 6. 드래그 앤 드롭 구현

### 6.1 라이브러리 권장

- **@dnd-kit**: React 전용, 접근성 지원, 트리 구조 지원
- **대안**: react-beautiful-dnd (유지보수 중단), react-dnd

### 6.2 핵심 구현 포인트

1. **직원 드래그**: 미배치 패널 ↔ 부서 카드 간 이동
2. **부서 드래그**: 부서 카드 간 순서/계층 변경 (parent_id + sort_order)
3. **순환 참조 방지**: 부서를 자기 자손에 드롭하면 무시 (API에서도 검증하지만 UI에서도 방지)
4. **Optimistic Update**: 드래그 완료 시 로컬 상태 즉시 업데이트 → API 호출 → 실패 시 롤백

### 6.3 상태 관리

```
초기 로딩: GET /v1/org-chart → 로컬 상태 세팅
  ├── departments (트리 구조)
  ├── unassigned (미배치 직원 배열)
  ├── hiddenDepartments (숨겨진 부서 배열)
  ├── stats (통계)
  └── company (회사 정보)

변경 시: API 호출 → 성공 시 로컬 상태 업데이트
```

---

## 7. MNG 참고 파일

| 파일 | 설명 |
|------|------|
| `mng/app/Http/Controllers/RdController.php` (L38-208) | 조직도 컨트롤러 로직 |
| `mng/resources/views/rd/org-chart.blade.php` | 조직도 UI (Alpine.js + SortableJS) |
| `mng/app/Models/Tenants/Department.php` | Department 모델 (options cast) |

---

## 관련 문서

| 문서 | 경로 |
|------|------|
| 이관 계획서 | `dev/dev_plans/org-chart-service-migration-plan.md` |
| 조직도 시스템 (MNG) | `projects/org-chart/README.md` |
| React 아키텍처 | `frontend/v1/01-architecture.md` |
| API 패턴 | `frontend/v1/02-api-pattern.md` |
| 인증 흐름 | `frontend/v1/07-auth-flow.md` |

---

**최종 업데이트**: 2026-03-22