feat(WEB): 공정관리 상세 체크리스트 연동 및 리팩토링 문서 업데이트

- ProcessDetail: 체크리스트 연동 UI 추가 - Process 타입 체크리스트 필드 확장 - 리팩토링 로드맵 및 Phase1 체크리스트 진행상황 업데이트 - claudedocs 인덱스 정리 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 21:49:45 +09:00
parent 14b84cc08d
commit 0643d56194
6 changed files with 126 additions and 63 deletions
--- a/claudedocs/_index.md
+++ b/claudedocs/_index.md
@@ -1,6 +1,6 @@
 # claudedocs 문서 맵

-> 프로젝트 기술 문서 인덱스 (Last Updated: 2026-02-06)
+> 프로젝트 기술 문서 인덱스 (Last Updated: 2026-02-09)

 ## 빠른 참조

@@ -36,6 +36,7 @@ claudedocs/
 ├── material/            # 자재관리
 ├── approval/            # 결재관리
 ├── customer-center/     # 고객센터
+├── refactoring/         # 리팩토링 체크리스트
 └── archive/             # 레거시/완료된 문서
 ```

@@ -334,6 +335,14 @@ claudedocs/

 ---

+## 리팩토링 — `refactoring/`
+
+| 파일 | 설명 |
+|------|------|
+| `[IMPL-2026-02-09] phase1-common-hooks-checklist.md` | Phase 1 공통 훅 추출 체크리스트 (완료) + Phase 3 프로토타입 기록 |
+
+---
+
 ## archive/ - 레거시/완료된 문서

 완료되거나 더 이상 활성화되지 않은 문서들. 참조용으로 보관.
--- a/claudedocs/architecture/[PLAN-2026-02-06]
+++ b/claudedocs/architecture/[PLAN-2026-02-06]
@@ -2,7 +2,7 @@

 **작성일**: 2026-02-06
 **목적**: 전체 코드베이스 리팩토링 포인트 점검 및 실행 계획
-**상태**: 분석 완료, 실행 대기
+**상태**: Phase 1 완료, Phase 3 프로토타입 검증 완료

 ---

@@ -216,24 +216,24 @@ useEffect(() => {

 ## 실행 계획

-### Phase 1: 공통 훅 추출 (1-2주) `프론트 단독` `ROI 최고`
+### Phase 1: 공통 훅 추출 ✅ 완료 (2026-02-09)

-> 새 훅 생성 + 고빈도 페이지 20개 우선 적용
+> 실제 코드 분석 결과 계획 수정 → 실증 기반 리팩토링 실행

-**작업 항목**:
+**실행 결과** (계획 vs 실제):
 ```
- [ ] useListData 훅 생성 (페칭 + 페이지네이션 + 필터 통합)
- [ ] useFormSubmit 훅 생성 (제출 + 로딩 + 에러 + 토스트)
- [ ] usePagination 훅 생성
- [ ] useModal<T> 훅 생성
- [ ] 고빈도 리스트 페이지 10개 마이그레이션
-      - vendors, clients, items, orders, quotes
-      - production, quality, material, hr, accounting 각 1개
- [ ] 고빈도 폼 페이지 10개 마이그레이션
-      - 위 도메인의 등록/수정 폼 각 1개
+기존 계획의 useListData, usePagination, useClientSideFiltering, useModal은
+UniversalListPage 템플릿이 이미 내부 처리 → 불필요 판정.
+
+실제 실행:
+- [x] Step 1: executeServerAction (82개 action.ts 에러처리 래퍼) → ~3,000줄 절감
+- [x] Step 2: useDeleteDialog (6개 파일 삭제 다이얼로그 통합) → ~150줄 절감
+- [x] Step 3: useStatsLoader (7개 파일 stats 로딩 통합) → ~100줄 절감
+- [x] Step 4: React.memo 3개 + any→unknown 7건 + @ts-ignore 0건
 ```

-**예상 효과**: ~8,500줄 절감, 패턴 일관성 +60%
+**실제 효과**: ~3,750줄 절감, 82개 action.ts 패턴 통일, 타입 안전성 향상
+**상세**: `refactoring/[IMPL-2026-02-09] phase1-common-hooks-checklist.md`

 ---

@@ -263,27 +263,32 @@ useEffect(() => {

 ---

-### Phase 3: 액션 파일 제네릭화 (2-3주) `프론트 단독` `최대 코드 감소`
+### Phase 3: 액션 파일 제네릭화 (2-3주) `프론트 단독` `프로토타입 검증 완료`

-> CRUD 서비스 팩토리 생성 + 80개 actions.ts 점진적 마이그레이션
+> CRUD 서비스 팩토리 생성 + actions.ts 점진적 마이그레이션

-**작업 항목**:
+**프로토타입 결과** (2026-02-09):
 ```
- [ ] createCrudService<TApi, TFront> 팩토리 함수 구현
-      - getList, getById, create, update, delete, bulkDelete
-      - transform / reverseTransform 자동 적용
-      - 에러 핸들링 표준화
- [ ] 공통 transform 유틸리티 (lib/transformers/)
-      - API snake_case → 프론트 camelCase 자동 변환
-      - 날짜 문자열 파싱 공통화
- [ ] 고빈도 도메인 마이그레이션 (10개)
-      - orders, quotes, clients, vendors
-      - production, quality, material
-      - hr/employee, hr/vacation, accounting
- [ ] 나머지 70개 점진적 마이그레이션
+- [x] createCrudService 팩토리 구현 (src/lib/api/create-crud-service.ts)
+- [x] RankManagement/actions.ts 마이그레이션 (111줄 → 77줄, -31%)
+- [x] Server Action 호환성 검증 완료 (5/5 CRUD 정상 동작)
+- [x] 래퍼 함수 방식 채택 (Next.js Server Action 인식 보장)
 ```

-**예상 효과**: ~24,000줄 → ~8,000줄 (67% 감소)
+**검증된 사실**:
+- Server Action + 팩토리 패턴 호환성 문제 없음
+- 래퍼 함수 필요 (직접 re-export는 미검증)
+- Tier 분류: Tier 1 정형 CRUD (~60%, 100% 적용) / Tier 2 CRUD+특수 (~25%, 부분 적용) / Tier 3 복잡 도메인 (~15%, 미적용)
+
+**남은 작업**:
+```
+- [ ] Tier 1 settings 도메인 마이그레이션 (8개)
+- [ ] Tier 1 기타 정형 CRUD 마이그레이션 (~40개)
+- [ ] Tier 2 CRUD 부분 팩토리 적용 (~20개)
+- [ ] PositionApiData 등 공통 API 타입 추출
+```
+
+**예상 효과**: Tier 1 기준 ~31% 코드 감소, 새 도메인 추가 시간 30분→5분

 ---

@@ -310,26 +315,29 @@ useEffect(() => {

 ---

-### Phase 5: 성능 + 타입 정리 (1-2주) `프론트 단독`
+### Phase 5: 성능 + 타입 정리 (1-2주) `프론트 단독` `일부 Phase 1에서 선처리`

 > React.memo 적용 + any 제거 + 타입 통합

-**작업 항목**:
+**Phase 1에서 선처리된 항목** (2026-02-09):
 ```
- [ ] React.memo 적용 (리스트 아이템 컴포넌트 30+개)
-      - WorkItemCard, CommentItem, ProjectCard 등
-      - *Row, *Item, *Card 패턴 전수 조사
+- [x] React.memo 3개 적용 (InfoField, CommentItem, WorkItemCard)
+- [x] any→unknown 7건 (logger.ts)
+- [x] action error handler any 50+곳 (executeServerAction으로 자동 해결)
+- [x] @ts-ignore 0건 (이미 제거 완료)
+```
+
+**남은 작업**:
+```
+- [ ] React.memo 추가 적용 (나머지 리스트 아이템 컴포넌트)
 - [ ] 대형 컴포넌트 useCallback 적용
-      - MainDashboard, WorkerScreen, DynamicItemForm
- [ ] any 타입 제거 (102곳)
-      - Phase 1: types/ 파일 (4개)
-      - Phase 2: action error handler (50+ 파일)
-      - Phase 3: 컴포넌트 props (20개)
+- [ ] any 타입 잔여 92건
+      - items/ 도메인 60건 (복잡도 높음, 별도 작업)
+      - Form 에러 캐스팅 26건 (RHF 타입 시스템 변경 필요)
+      - dev/ 프로토타입 6건 (비프로덕션)
 - [ ] 공통 타입 라이브러리 정리
      - types/shared/ 폴더 생성
      - ApiResponse<T>, PaginatedResponse<T>, FormState<T> 등
-      - 엔티티별 정규 타입 단일화
- [ ] @ts-ignore / eslint-disable 제거 (25개 파일)
 ```

 **예상 효과**: 리스트 렌더링 30-50% 개선, 타입 안전성 +60%
@@ -338,27 +346,27 @@ useEffect(() => {

 ## 전체 예상 효과 요약

-| 지표 | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 | 합계 |
-|------|---------|---------|---------|---------|---------|------|
-| 코드 절감 | ~8,500줄 | (구조 개선) | ~16,000줄 | ~5,000줄 | (품질 개선) | **~29,500줄** |
+| 지표 | Phase 1 ✅ | Phase 2 | Phase 3 | Phase 4 | Phase 5 | 합계 |
+|------|-----------|---------|---------|---------|---------|------|
+| 코드 절감 | ~3,750줄 (실측) | (구조 개선) | ~3,300줄 (실측 기반 추정) | ~5,000줄 | (품질 개선) | **~12,000줄+** |
 | 패턴 일관성 | +60% | +50% | +40% | +80% | +60% | 종합 개선 |
 | 유지보수성 | 높음 | 매우 높음 | 높음 | 중간 | 중간 | 종합 개선 |
-| 위험도 | 낮음 | 중간 | 중간 | 낮음 | 낮음 | - |
+| 위험도 | 낮음 | 중간 | 낮음 (검증됨) | 낮음 | 낮음 | - |

 ---

 ## 병렬 진행 가능 조합

 ```
-[독립 진행 가능]
-├─ Phase 1 (공통 훅) ──→ 즉시 시작
-├─ Phase 5 (성능/타입) ─→ 즉시 시작 (Phase 1과 병렬)
+[완료]
+├─ Phase 1 (공통 훅) ──→ ✅ 완료 (2026-02-09)
 │
-[Phase 1 완료 후]
-├─ Phase 2 (God 컴포넌트 분리) ──→ 훅 활용하여 분리
-├─ Phase 3 (액션 제네릭화) ────→ 독립 진행 가능
+[즉시 시작 가능]
+├─ Phase 2 (God 컴포넌트 분리) ──→ Phase 1 훅 활용
+├─ Phase 3 (액션 제네릭화) ────→ 프로토타입 검증 완료, 본격 마이그레이션 가능
+├─ Phase 5 (성능/타입) ─────→ 일부 Phase 1에서 선처리됨
 │
-[Phase 1+3 완료 후]
+[Phase 3 완료 후]
 └─ Phase 4 (템플릿 통일) ─────→ 훅 + 서비스 활용
 ```

@@ -383,6 +391,8 @@ useEffect(() => {
 | 날짜 | 변경 내용 |
 |------|-----------|
 | 2026-02-06 | 초기 작성 - 전체 코드베이스 분석 기반 5 Phase 로드맵 |
+| 2026-02-09 | Phase 1 완료 반영 - 실측 기반 효과 수치 보정 (8,500줄→3,750줄), executeServerAction/useDeleteDialog/useStatsLoader 3개 훅 생성 완료 |
+| 2026-02-09 | Phase 3 프로토타입 검증 완료 - createCrudService 팩토리 생성, RankManagement 5/5 CRUD 정상, Server Action 호환성 확인 |

 ---

--- a/claudedocs/refactoring/[IMPL-2026-02-09]
+++ b/claudedocs/refactoring/[IMPL-2026-02-09]
@@ -285,3 +285,6 @@ const { data: stats } = useStatsLoader(getProcessStats, { total: 0, active: 0, i
 | 2026-02-09 | **Step 3 완료** - useStatsLoader 훅 생성(45줄) 및 7개 파일 적용 (3개 스킵). Construction 패턴(5개: Contract, ConstructionManagement, Bidding, Estimate, ProgressBilling) - useState+useEffect→useStatsLoader 1줄 전환. Standard 패턴(2개: InspectionList, ShipmentList) - reload 함수 활용하여 getList 내 stats 리로드 단순화. 스킵: ProcessListClient(stats UI 미사용), WorkOrderList(tabCounts 동기화 복잡), OrderManagementListClient(stats 완전 미사용). 타입체크 0 에러. |
 | 2026-02-09 | **Step 4 완료** - React.memo 3개 적용(InfoField, CommentItem, WorkItemCard - 리스트 반복 렌더링 대상). any→unknown 7건(logger.ts). @ts-ignore 0건(이미 제거됨). 잔여 any 92건은 items/ 도메인(60건, 복잡도 높음), dev/ 프로토타입(6건), Form 에러캐스팅(26건, RHF 타입 변경 필요)으로 별도 작업 필요. |
 | 2026-02-09 | **Phase 1 전체 완료** - Step 1(executeServerAction 82개 파일) + Step 2(useDeleteDialog 6개 파일) + Step 3(useStatsLoader 7개 파일) + Step 4(React.memo 3개 + any→unknown 7건 + @ts-ignore 0건). |
+| 2026-02-09 | **Phase 1 자동 검증 통과** - TypeScript 0 에러(기존 QuoteRegistrationV2만), 미사용 import 0건, executeServerAction 59파일 일관 패턴, 핵심 훅 3개 무결성 확인. |
+| 2026-02-09 | **Phase 1 수동 검증 통과** - 화면 버디 검수 완료. |
+| 2026-02-09 | **Phase 3 프로토타입 검증** - `createCrudService` 팩토리 생성(`src/lib/api/create-crud-service.ts`). RankManagement/actions.ts 마이그레이션(111줄→77줄). 직급관리 5/5 CRUD 정상 동작 확인. Server Action 호환성 검증 완료. |