407 lines
12 KiB
Markdown
407 lines
12 KiB
Markdown
# 위젯 승격 완료 보고서
|
|
|
|
**작성일**: 2025-10-28
|
|
**작성자**: AI Assistant
|
|
**상태**: ✅ 완료
|
|
|
|
---
|
|
|
|
## 📋 개요
|
|
|
|
테스트 위젯들이 안정성과 기능성을 검증받아 정식 위젯으로 승격되었습니다.
|
|
|
|
### 🎯 승격 목적
|
|
|
|
1. **기능 통합**: 다중 데이터 소스 지원 기능을 정식 위젯으로 제공
|
|
2. **사용자 경험 개선**: 테스트 버전의 혼란 제거
|
|
3. **유지보수성 향상**: 단일 버전 관리로 코드베이스 간소화
|
|
|
|
---
|
|
|
|
## ✅ 승격된 위젯 목록
|
|
|
|
| # | 테스트 버전 | 파일명 | 정식 subtype | 상태 |
|
|
|---|------------|--------|-------------|------|
|
|
| 1 | MapTestWidgetV2 | `MapTestWidgetV2.tsx` | `map-summary-v2` | ✅ 완료 |
|
|
| 2 | ChartTestWidget | `ChartTestWidget.tsx` | `chart` | ✅ 완료 |
|
|
| 3 | ListTestWidget | `ListTestWidget.tsx` | `list-v2` | ✅ 완료 |
|
|
| 4 | CustomMetricTestWidget | `CustomMetricTestWidget.tsx` | `custom-metric-v2` | ✅ 완료 |
|
|
| 5 | RiskAlertTestWidget | `RiskAlertTestWidget.tsx` | `risk-alert-v2` | ✅ 완료 |
|
|
|
|
**참고**: 파일명은 변경하지 않고, subtype만 변경하여 기존 import 경로 유지
|
|
|
|
---
|
|
|
|
## 📝 변경 사항 상세
|
|
|
|
### 1. 타입 정의 (`types.ts`)
|
|
|
|
#### 변경 전
|
|
```typescript
|
|
| "map-test-v2" // 테스트
|
|
| "chart-test" // 테스트
|
|
| "list-test" // 테스트
|
|
| "custom-metric-test" // 테스트
|
|
| "risk-alert-test" // 테스트
|
|
```
|
|
|
|
#### 변경 후
|
|
```typescript
|
|
| "map-summary-v2" // 정식 (승격)
|
|
| "chart" // 정식 (승격)
|
|
| "list-v2" // 정식 (승격)
|
|
| "custom-metric-v2" // 정식 (승격)
|
|
| "risk-alert-v2" // 정식 (승격)
|
|
```
|
|
|
|
#### 주석 처리된 타입
|
|
```typescript
|
|
// | "map-summary" // (구버전 - 주석 처리: 2025-10-28)
|
|
// | "map-test-v2" // (테스트 버전 - 주석 처리: 2025-10-28)
|
|
// | "chart-test" // (테스트 버전 - 주석 처리: 2025-10-28)
|
|
// | "list" // (구버전 - 주석 처리: 2025-10-28)
|
|
// | "list-test" // (테스트 버전 - 주석 처리: 2025-10-28)
|
|
// | "custom-metric" // (구버전 - 주석 처리: 2025-10-28)
|
|
// | "custom-metric-test"// (테스트 버전 - 주석 처리: 2025-10-28)
|
|
// | "risk-alert" // (구버전 - 주석 처리: 2025-10-28)
|
|
// | "risk-alert-test" // (테스트 버전 - 주석 처리: 2025-10-28)
|
|
```
|
|
|
|
---
|
|
|
|
### 2. 기존 원본 위젯 처리
|
|
|
|
다음 파일들이 주석 처리되었습니다 (삭제 X, 백업 보관):
|
|
|
|
| 파일 | 경로 | 대체 버전 |
|
|
|------|------|----------|
|
|
| `MapSummaryWidget.tsx` | `frontend/components/dashboard/widgets/` | MapTestWidgetV2.tsx |
|
|
| `CustomMetricWidget.tsx` | `frontend/components/dashboard/widgets/` | CustomMetricTestWidget.tsx |
|
|
| `RiskAlertWidget.tsx` | `frontend/components/dashboard/widgets/` | RiskAlertTestWidget.tsx |
|
|
| `ListWidget.tsx` | `frontend/components/admin/dashboard/widgets/` | ListTestWidget.tsx |
|
|
|
|
**주석 처리 형식**:
|
|
```typescript
|
|
/*
|
|
* ⚠️ DEPRECATED - 이 위젯은 더 이상 사용되지 않습니다.
|
|
*
|
|
* 이 파일은 2025-10-28에 주석 처리되었습니다.
|
|
* 새로운 버전: [새 파일명] (subtype: [새 subtype])
|
|
*
|
|
* 변경 이유:
|
|
* - 다중 데이터 소스 지원
|
|
* - 컬럼 매핑 기능 추가
|
|
* - 자동 새로고침 간격 설정 가능
|
|
*
|
|
* 롤백 방법:
|
|
* 1. 이 파일의 주석 제거
|
|
* 2. types.ts에서 기존 subtype 활성화
|
|
* 3. 새 subtype 주석 처리
|
|
*/
|
|
```
|
|
|
|
---
|
|
|
|
### 3. 컴포넌트 렌더링 로직 변경
|
|
|
|
#### A. `CanvasElement.tsx` (편집 모드)
|
|
|
|
**변경 전**:
|
|
```typescript
|
|
element.subtype === "map-test-v2"
|
|
element.subtype === "chart-test"
|
|
element.subtype === "list-test"
|
|
element.subtype === "custom-metric-test"
|
|
element.subtype === "risk-alert-test"
|
|
```
|
|
|
|
**변경 후**:
|
|
```typescript
|
|
element.subtype === "map-summary-v2"
|
|
element.subtype === "chart"
|
|
element.subtype === "list-v2"
|
|
element.subtype === "custom-metric-v2"
|
|
element.subtype === "risk-alert-v2"
|
|
```
|
|
|
|
#### B. `DashboardViewer.tsx` (뷰어 모드)
|
|
|
|
동일한 subtype 변경 적용
|
|
|
|
#### C. `ElementConfigSidebar.tsx` (설정 패널)
|
|
|
|
**다중 데이터 소스 위젯 체크 로직 변경**:
|
|
```typescript
|
|
// 변경 전
|
|
const isMultiDS =
|
|
element.subtype === "map-test-v2" ||
|
|
element.subtype === "chart-test" ||
|
|
element.subtype === "list-test" ||
|
|
element.subtype === "custom-metric-test" ||
|
|
element.subtype === "risk-alert-test";
|
|
|
|
// 변경 후
|
|
const isMultiDS =
|
|
element.subtype === "map-summary-v2" ||
|
|
element.subtype === "chart" ||
|
|
element.subtype === "list-v2" ||
|
|
element.subtype === "custom-metric-v2" ||
|
|
element.subtype === "risk-alert-v2";
|
|
```
|
|
|
|
---
|
|
|
|
### 4. 메뉴 재구성 (`DashboardTopMenu.tsx`)
|
|
|
|
#### 변경 전
|
|
```tsx
|
|
<SelectGroup>
|
|
<SelectLabel>🧪 테스트 위젯 (다중 데이터 소스)</SelectLabel>
|
|
<SelectItem value="map-test-v2">🧪 지도 테스트 V2</SelectItem>
|
|
<SelectItem value="chart-test">🧪 차트 테스트</SelectItem>
|
|
<SelectItem value="list-test">🧪 리스트 테스트</SelectItem>
|
|
<SelectItem value="custom-metric-test">통계 카드</SelectItem>
|
|
<SelectItem value="risk-alert-test">🧪 리스크/알림 테스트</SelectItem>
|
|
</SelectGroup>
|
|
<SelectGroup>
|
|
<SelectLabel>데이터 위젯</SelectLabel>
|
|
<SelectItem value="list">리스트 위젯</SelectItem>
|
|
<SelectItem value="custom-metric">사용자 커스텀 카드</SelectItem>
|
|
<SelectItem value="map-summary">커스텀 지도 카드</SelectItem>
|
|
</SelectGroup>
|
|
```
|
|
|
|
#### 변경 후
|
|
```tsx
|
|
<SelectGroup>
|
|
<SelectLabel>데이터 위젯</SelectLabel>
|
|
<SelectItem value="map-summary-v2">지도</SelectItem>
|
|
<SelectItem value="chart">차트</SelectItem>
|
|
<SelectItem value="list-v2">리스트</SelectItem>
|
|
<SelectItem value="custom-metric-v2">통계 카드</SelectItem>
|
|
<SelectItem value="risk-alert-v2">리스크/알림</SelectItem>
|
|
<SelectItem value="yard-management-3d">야드 관리 3D</SelectItem>
|
|
</SelectGroup>
|
|
```
|
|
|
|
**변경 사항**:
|
|
- 🧪 테스트 위젯 섹션 제거
|
|
- 이모지 및 "테스트" 문구 제거
|
|
- 간결한 이름으로 변경
|
|
|
|
---
|
|
|
|
### 5. 데이터베이스 마이그레이션
|
|
|
|
#### 스크립트 파일
|
|
- **경로**: `db/migrations/999_upgrade_test_widgets_to_production.sql`
|
|
- **실행 방법**: 사용자가 직접 실행 (자동 실행 X)
|
|
|
|
#### 마이그레이션 내용
|
|
|
|
```sql
|
|
-- 1. MapTestWidgetV2 → MapSummaryWidget (v2)
|
|
UPDATE dashboard_layouts
|
|
SET layout_data = jsonb_set(...)
|
|
WHERE layout_data::text LIKE '%"subtype":"map-test-v2"%';
|
|
|
|
-- 2. ChartTestWidget → ChartWidget
|
|
-- 3. ListTestWidget → ListWidget (v2)
|
|
-- 4. CustomMetricTestWidget → CustomMetricWidget (v2)
|
|
-- 5. RiskAlertTestWidget → RiskAlertWidget (v2)
|
|
```
|
|
|
|
#### 검증 쿼리
|
|
|
|
스크립트 실행 후 자동으로 다음을 확인:
|
|
- 각 위젯별 레이아웃 개수
|
|
- 남아있는 테스트 위젯 개수 (0이어야 정상)
|
|
|
|
#### 롤백 스크립트
|
|
|
|
문제 발생 시 사용할 수 있는 롤백 스크립트도 포함되어 있습니다.
|
|
|
|
---
|
|
|
|
## 🎉 승격의 이점
|
|
|
|
### 1. 사용자 경험 개선
|
|
|
|
**변경 전**:
|
|
- 🧪 테스트 위젯 섹션과 정식 위젯 섹션이 분리
|
|
- "테스트" 문구로 인한 혼란
|
|
- 어떤 위젯을 사용해야 할지 불명확
|
|
|
|
**변경 후**:
|
|
- 단일 "데이터 위젯" 섹션으로 통합
|
|
- 간결하고 명확한 위젯 이름
|
|
- 모든 위젯이 정식 버전으로 제공
|
|
|
|
### 2. 기능 강화
|
|
|
|
모든 승격된 위젯은 다음 기능을 제공합니다:
|
|
|
|
- ✅ **다중 데이터 소스 지원**
|
|
- REST API 다중 연결
|
|
- Database 다중 연결
|
|
- REST API + Database 혼합
|
|
- ✅ **컬럼 매핑**: 서로 다른 데이터 소스의 컬럼명 통일
|
|
- ✅ **자동 새로고침**: 데이터 소스별 간격 설정
|
|
- ✅ **수동 새로고침**: 즉시 데이터 갱신
|
|
- ✅ **마지막 새로고침 시간 표시**
|
|
- ✅ **XML/CSV 파싱** (Map, RiskAlert)
|
|
|
|
### 3. 유지보수성 향상
|
|
|
|
- 코드베이스 간소화 (테스트/정식 버전 통합)
|
|
- 단일 버전 관리로 버그 수정 용이
|
|
- 문서화 간소화
|
|
|
|
---
|
|
|
|
## 📊 영향 범위
|
|
|
|
### 영향받는 파일
|
|
|
|
| 카테고리 | 파일 수 | 파일 목록 |
|
|
|---------|--------|----------|
|
|
| 타입 정의 | 1 | `types.ts` |
|
|
| 위젯 파일 (주석 처리) | 4 | `MapSummaryWidget.tsx`, `CustomMetricWidget.tsx`, `RiskAlertWidget.tsx`, `ListWidget.tsx` |
|
|
| 렌더링 로직 | 3 | `CanvasElement.tsx`, `DashboardViewer.tsx`, `ElementConfigSidebar.tsx` |
|
|
| 메뉴 | 1 | `DashboardTopMenu.tsx` |
|
|
| 데이터베이스 | 1 | `999_upgrade_test_widgets_to_production.sql` |
|
|
| 문서 | 3 | `테스트_위젯_누락_기능_분석_보고서.md`, `컬럼_매핑_사용_가이드.md`, `위젯_승격_완료_보고서.md` |
|
|
| **총계** | **13** | |
|
|
|
|
### 영향받는 사용자
|
|
|
|
- **기존 테스트 위젯 사용자**: SQL 마이그레이션 실행 필요
|
|
- **새 사용자**: 자동으로 정식 위젯 사용
|
|
- **개발자**: 새로운 subtype 참조 필요
|
|
|
|
---
|
|
|
|
## 🔧 롤백 방법
|
|
|
|
문제 발생 시 다음 순서로 롤백할 수 있습니다:
|
|
|
|
### 1. 코드 롤백
|
|
|
|
```bash
|
|
# Git으로 이전 커밋으로 되돌리기
|
|
git revert <commit-hash>
|
|
|
|
# 또는 주석 처리된 원본 파일 복구
|
|
# 1. 주석 제거
|
|
# 2. types.ts에서 기존 subtype 활성화
|
|
# 3. 새 subtype 주석 처리
|
|
```
|
|
|
|
### 2. 데이터베이스 롤백
|
|
|
|
```sql
|
|
-- 롤백 스크립트 실행
|
|
-- 파일: db/migrations/999_rollback_widget_upgrade.sql
|
|
|
|
BEGIN;
|
|
|
|
UPDATE dashboard_layouts
|
|
SET layout_data = jsonb_set(
|
|
layout_data,
|
|
'{elements}',
|
|
(
|
|
SELECT jsonb_agg(
|
|
CASE
|
|
WHEN elem->>'subtype' = 'map-summary-v2' THEN jsonb_set(elem, '{subtype}', '"map-test-v2"'::jsonb)
|
|
WHEN elem->>'subtype' = 'chart' THEN jsonb_set(elem, '{subtype}', '"chart-test"'::jsonb)
|
|
WHEN elem->>'subtype' = 'list-v2' THEN jsonb_set(elem, '{subtype}', '"list-test"'::jsonb)
|
|
WHEN elem->>'subtype' = 'custom-metric-v2' THEN jsonb_set(elem, '{subtype}', '"custom-metric-test"'::jsonb)
|
|
WHEN elem->>'subtype' = 'risk-alert-v2' THEN jsonb_set(elem, '{subtype}', '"risk-alert-test"'::jsonb)
|
|
ELSE elem
|
|
END
|
|
)
|
|
FROM jsonb_array_elements(layout_data->'elements') elem
|
|
)
|
|
)
|
|
WHERE layout_data::text LIKE '%"-v2"%' OR layout_data::text LIKE '%"chart"%';
|
|
|
|
COMMIT;
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ 테스트 체크리스트
|
|
|
|
승격 후 다음 사항을 확인하세요:
|
|
|
|
### 코드 레벨
|
|
- [x] TypeScript 컴파일 에러 없음
|
|
- [x] 모든 import 경로 정상 작동
|
|
- [x] Prettier 포맷팅 적용
|
|
|
|
### 기능 테스트
|
|
- [ ] 대시보드 편집 모드에서 위젯 추가 가능
|
|
- [ ] 데이터 소스 연결 정상 작동
|
|
- [ ] 자동 새로고침 정상 작동
|
|
- [ ] 뷰어 모드에서 정상 표시
|
|
- [ ] 저장/불러오기 정상 작동
|
|
- [ ] 기존 대시보드 레이아웃 정상 로드 (마이그레이션 후)
|
|
|
|
### 데이터베이스
|
|
- [ ] SQL 마이그레이션 스크립트 문법 검증
|
|
- [ ] 백업 수행
|
|
- [ ] 마이그레이션 실행
|
|
- [ ] 검증 쿼리 확인
|
|
|
|
---
|
|
|
|
## 📚 관련 문서
|
|
|
|
1. [테스트 위젯 누락 기능 분석 보고서](./테스트_위젯_누락_기능_분석_보고서.md)
|
|
- 원본 vs 테스트 위젯 비교 분석
|
|
- 승격 결정 근거
|
|
|
|
2. [컬럼 매핑 사용 가이드](./컬럼_매핑_사용_가이드.md)
|
|
- 다중 데이터 소스 활용법
|
|
- 컬럼 매핑 기능 설명
|
|
|
|
3. [SQL 마이그레이션 스크립트](../db/migrations/999_upgrade_test_widgets_to_production.sql)
|
|
- 데이터베이스 마이그레이션 가이드
|
|
- 롤백 방법 포함
|
|
|
|
---
|
|
|
|
## 🎯 다음 단계
|
|
|
|
### 즉시 수행
|
|
1. [ ] 프론트엔드 빌드 및 배포
|
|
2. [ ] SQL 마이그레이션 스크립트 실행 (사용자)
|
|
3. [ ] 기능 테스트 수행
|
|
|
|
### 향후 계획
|
|
1. [ ] 사용자 피드백 수집
|
|
2. [ ] 성능 모니터링
|
|
3. [ ] 추가 기능 개발 (필요 시)
|
|
|
|
---
|
|
|
|
**승격 완료일**: 2025-10-28
|
|
**작성자**: AI Assistant
|
|
**상태**: ✅ 완료
|
|
|
|
---
|
|
|
|
## 📞 문의
|
|
|
|
문제 발생 시 다음 정보를 포함하여 문의하세요:
|
|
|
|
1. 발생한 오류 메시지
|
|
2. 브라우저 콘솔 로그
|
|
3. 사용 중인 위젯 및 데이터 소스
|
|
4. 마이그레이션 실행 여부
|
|
|
|
---
|
|
|
|
**이 보고서는 위젯 승격 작업의 완전한 기록입니다.**
|
|
|