sam-docs/dev/dev_plans/org-chart-service-migration-plan.md

조직도 서비스 이관 기획서

작성일: 2026-03-22 상태: API 구현 완료, React 문서 제공 대상: MNG → API + React (서비스 이관) 위치: 서비스 > 인사관리 > 조직도

---

1. 개요

1.1 목적

MNG 백오피스의 조직도 관리 기능을 서비스(API + React)로 이관한다. 기존 MNG의 Alpine.js + SortableJS 기반 UI를 REST API + React 구조로 재구현하며, 멀티테넌트 격리를 API 레이어에서 강화한다.

1.2 배경

• MNG R&D > 조직도 관리 메뉴로 v1.0 구현 완료 (2026-03-06)
• 부서 CRUD + 트리 + 사용자 배치 API는 이미 존재 (DepartmentController)
• 조직도 전용 기능(직원 일괄 이동, 부서 순서/계층 변경, 숨기기)이 API에 없었음
• MNG는 session('selected_tenant_id') 수동 격리 → API는 BelongsToTenant 글로벌 스코프

1.3 이관 범위

구분	MNG (현재)	API + React (이관 후)
백엔드	RdController 직접 로직	OrgChartService + OrgChartController + FormRequest
프론트	Alpine.js + SortableJS	React (Next.js) + @dnd-kit
인증	세션 기반	Bearer 토큰 + BelongsToTenant
데이터	withoutGlobalScopes() 수동	글로벌 스코프 자동 격리
API 문서	없음	Swagger

---

2. 현재 MNG 기능 분석

2.1 MNG 엔드포인트 (RdController)

Route	Method	설명
/rd/org-chart	GET	조직도 페이지 (트리+직원+회사정보)
/rd/org-chart/assign	POST	직원 부서 배치
/rd/org-chart/unassign	POST	직원 미배치 처리
/rd/org-chart/reorder	POST	직원 일괄 이동
/rd/org-chart/reorder-depts	POST	부서 트리 순서/계층 변경
/rd/org-chart/toggle-hide	POST	부서 숨기기/표시 토글

2.2 데이터 모델

• 부서: departments 테이블 (자기참조 parent_id, sort_order, options.orgchart_hidden)
• 직원: tenant_user_profiles 테이블 (department_id로 소속 관리)
• 회사: tenants 테이블 (company_name, ceo_name)

2.3 기존 API 구현 (DepartmentController)

기능	상태
부서 CRUD	✅
부서 트리 조회 (/tree)	✅
사용자 배정 (attachUser/detachUser)	✅ (department_user 피벗)
조직도 전용 기능	❌ → 이번 이관 대상

---

3. API 설계

3.1 신규 엔드포인트 (/v1/org-chart)

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	부서 숨기기 토글

3.2 주요 응답 구조

GET /v1/org-chart:

{
  "company": { "name": "...", "ceo_name": "..." },
  "departments": [{ "id": 1, "name": "...", "children": [...], "employees": [...] }],
  "hidden_departments": [{ "id": 5, "name": "..." }],
  "unassigned": [{ "id": 12, "display_name": "...", "position_label": "..." }],
  "stats": { "total": 50, "assigned": 42, "unassigned": 8 }
}

---

4. API 구현 상세

4.1 파일 구조

api/
├── app/Http/Controllers/Api/V1/OrgChartController.php  (신규)
├── app/Http/Requests/OrgChart/
│   ├── AssignRequest.php
│   ├── UnassignRequest.php
│   ├── ReorderEmployeesRequest.php
│   ├── ReorderDepartmentsRequest.php
│   └── ToggleHideRequest.php
├── app/Services/OrgChartService.php                     (신규)
├── app/Models/Tenants/Department.php                    (수정: options cast)
├── app/Swagger/v1/OrgChartApi.php                       (신규)
└── routes/api/v1/hr.php                                 (수정: 라우트 추가)

4.2 설계 결정

• 별도 OrgChartController/Service 분리: 기존 DepartmentController(13개 메서드)와 관심사 분리
• TenantUserProfile.department_id 기반: MNG와 동일하게 직원의 소속 부서 필드 직접 사용
• 순환 참조 방지: reorderDepartments에서 parent_id 변경 시 자손→조상 순환 검증

---

5. React 구현 (FE 가이드)

별도 문서: docs/frontend/v1/org-chart-fe-guide.md

---

6. 인증 및 권한

6.1 React → API

• authenticatedFetch 사용 (HttpOnly 쿠키 기반 Sanctum)
• auth:sanctum 미들웨어 자동 적용 (HR 라우트 그룹)

6.2 MNG → API (해당 없음)

• MNG는 기존 코드를 유지하고 자체 DB 직접 접근
• 이관 완료 후 MNG 메뉴를 숨기고 React로 안내

---

7. 구현 순서

Phase	작업	상태
1	Department 모델 options cast 추가	✅ 완료
2	OrgChartService + FormRequest 5개 생성	✅ 완료
3	OrgChartController + Route 등록	✅ 완료
4	Swagger 문서 (OrgChartApi.php)	✅ 완료
5	React FE 구현	📋 문서 제공
6	통합 테스트 + MNG 메뉴 전환	⏳ 대기

---

8. MNG 기존 코드 처리

• MNG RdController.orgChart* 메서드 → 유지 (삭제하지 않음)
• React 구현 완료 후 MNG 메뉴에서 조직도를 비활성화하고 서비스로 안내

---

9. 체크리스트

API

• OrgChartService 8개 메서드 구현
• OrgChartController FormRequest DI 적용
• 순환 참조 방지 검증 (reorderDepartments)
• Department 모델 options cast 추가
• Swagger 문서 생성 확인
• Pint 포맷팅 통과

React

• org-chart-fe-guide.md 기반 구현
• 드래그 앤 드롭 (부서/직원)
• 미배치 직원 패널
• 부서 숨기기/복원

---

관련 문서

문서	경로
조직도 시스템 (MNG)	projects/org-chart/README.md
부서 API 규칙	rules/department-tree-api.md
직원 API 규칙	rules/employee-api.md
React FE 가이드	frontend/v1/org-chart-fe-guide.md
이관 현황	system/migration-status.md

---

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