sam-docs/plans/docs-plans-cleanup-plan.md

# docs/plans 폴더 정리 계획

> **작성일**: 2026-02-26
> **목적**: docs/plans 폴더의 문서 분류, 통폐합, 히스토리 보관, 인덱스 재작성
> **상태**: ⏳ Phase 1 대기

---

## 📍 현재 진행 상태

| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | Phase 4: 최종 검증 완료 |
| **다음 작업** | 없음 (정리 완료) |
| **진행률** | 4/4 Phase (100%) |
| **마지막 업데이트** | 2026-02-26 |

---

## 1. 개요

### 1.1 배경

`docs/plans/` 폴더에 문서가 누적되면서 다음 문제 발생:
- 같은 도메인에 신/구 문서가 공존 (방향 전환 등으로 새 문서가 생겼으나 이전 문서 미정리)
- 완료된 문서, 폐기된 문서, 진행중인 문서가 혼재
- archive에 37개 개별 파일이 산재 (참조 효율 저하)
- sub/, clodeCheck/ 등 부수 폴더의 역할 불명확

### 1.2 현재 상태

```
docs/plans/                          ← 메인: 44개 md 파일
├── archive/                         ← 완료: 37개 md 파일
├── sub/                             ← 하위계획: 7개 md + archive/
├── clodeCheck/                      ← 코드체크 리포트: 7개 md
├── flow-tests/                      ← 플로우 테스트 JSON: 32개
├── SAM_ERP_Storyboard_D1.0_251218/  ← 스토리보드: 38장
└── index_plans.md                   ← 현재 인덱스
```

### 1.3 성공 기준

- [ ] 모든 메인 문서(44개)가 5단계 중 하나로 분류됨
- [ ] SUPERSEDED 문서가 최신 문서에 병합되어 삭제됨
- [ ] COMPLETED 문서가 archive/HISTORY.md로 요약 통합됨
- [ ] OBSOLETE 문서가 삭제됨
- [ ] sub/, clodeCheck/ 각 파일 처리 완료
- [ ] index_plans.md가 ACTIVE+PLANNED 문서만 반영하여 재작성됨
- [ ] docs/plans/에 ACTIVE + PLANNED 문서만 존재

---

## 2. 확정된 정책

### 2.1 문서 분류 기준 (5단계)

| 분류 | 정의 | 처리 | 최종 위치 |
|------|------|------|----------|
| **ACTIVE** | 현재 진행중이거나 곧 착수할 문서 | 유지, 최신화 | `docs/plans/` |
| **PLANNED** | 확정된 예정 작업, 선행조건 대기 | 유지, 최신화 | `docs/plans/` |
| **SUPERSEDED** | 새 문서로 대체된 이전 문서 | 새 문서에 병합 후 **삭제** | 파일 없음 |
| **COMPLETED** | 완료된 작업 | HISTORY.md에 요약 후 **삭제** | `archive/HISTORY.md` |
| **OBSOLETE** | 방향 전환/폐기된 문서 | **삭제** | 파일 없음 |

### 2.2 SUPERSEDED 판정 기준

같은 도메인에 문서 2개 이상일 때:
- **최신 문서(나중 생성)가 기준** → 이전 문서는 SUPERSEDED
- 이전 문서에만 있는 유용한 내용 → 최신 문서에 병합
- 이전 문서가 최신 문서를 참조하지 않고 독립적 → 내용 비교 후 판단
- 이전 문서가 최신 문서에 참조됨 → 최신 문서에 해당 내용 통합

**통폐합 후보 도메인** (파일명 기반, Phase 1에서 확정):
- 견적: `quote-*` 6개
- 문서시스템: `document-*` 5개
- 품목: `item-*`, `bom-*`, `mng-item-*` 등
- 채번: `tenant-numbering-*`, `mng-numbering-*`

### 2.3 HISTORY.md 구조

```markdown
# 완료 작업 히스토리

## 견적/수주
| 기능 | 완료시기 | 요약 |
|------|---------|------|
| 견적 자동계산 | 2025-12 | 경동 수식 엔진 구현, V2 자동계산 적용 |

## 품목/BOM
| 기능 | 완료시기 | 요약 |
| ... | ... | ... |

## 생산/절곡
...
```

- 기능 도메인별 섹션으로 구분
- 각 항목: 기능명 + 완료시기 + 한줄 요약 (상세 불필요)
- 현재 archive/ 37개 + 이번 정리에서 COMPLETED로 분류된 문서 모두 포함

### 2.4 sub/, clodeCheck/ 처리 원칙

Phase 1에서 **문서별로 판단** (D 옵션):

**sub/ 각 파일 → 아래 중 택1:**
- A. 메인 승격: 아직 유효 → `docs/plans/`로 이동
- B. 상위 문서에 병합: 내용이 상위 계획에 포함 가능
- C. 삭제: 이미 반영되었거나 폐기

**clodeCheck/ 각 파일 → 아래 중 택1:**
- A. 삭제: 일회성 리포트
- B. HISTORY.md에 요약: 한 줄 이력으로 보관

### 2.5 변경하지 않는 대상

| 폴더 | 이유 |
|------|------|
| `flow-tests/` | 운영 도구 (JSON 테스트 케이스) |
| `SAM_ERP_Storyboard_D1.0_251218/` | 디자인 참조 (스토리보드) |

---

## 3. 실행 계획 (4 Phase)

### Phase 1: 분류 (읽기 전용)

**목표**: 모든 문서를 5단계 중 하나로 분류

**작업 절차**:
1. 메인 44개 문서의 내용을 읽고 분류 판정
2. sub/ 7개 문서의 상위 문서 관계 파악 후 분류 판정
3. clodeCheck/ 7개 리포트의 보관 가치 판정
4. 현재 archive/ 37개 문서의 요약 정보 추출 (HISTORY.md용)
5. 분류 결과 테이블 작성 → 사용자 확인

**산출물**: 아래 테이블 완성

#### 3.1.1 메인 문서 분류 결과

| # | 파일명 | 분류 | 비고 |
|---|--------|------|------|
| 1 | 5130-to-mng-migration-plan.md | ACTIVE | 13% 진행중 |
| 2 | api-explorer-development-plan.md | PLANNED | 미착수 |
| 3 | bending-info-auto-generation-plan.md | PLANNED | 설계 확정, 착수 대기 |
| 4 | bending-material-input-mapping-plan.md | PLANNED | GAP 분석 완료 |
| 5 | bending-preproduction-stock-plan.md | COMPLETED | 14/14 완료 |
| 6 | bom-item-mapping-plan.md | ACTIVE | 66% Phase 3 검증 잔여 |
| 7 | card-management-section-plan.md | ACTIVE | 50% 모달 연동 진행중 |
| 8 | dashboard-api-integration-plan.md | ACTIVE | 45% Phase 2 예정 |
| 9 | db-backup-system-plan.md | ACTIVE | 79% 서버 작업 3건 잔여 |
| 10 | db-trigger-audit-system-plan.md | COMPLETED | 94% 옵션만 잔여 |
| 11 | dev-toolbar-plan.md | ACTIVE | 38% Phase 2-4 진행중 |
| 12 | document-management-system-plan.md | SUPERSEDED | → document-system-master.md |
| 13 | document-system-master.md | ACTIVE | Phase 4-5 마스터 문서 |
| 14 | document-system-mid-inspection.md | ACTIVE | 5/6 결재만 남음 |
| 15 | document-system-work-log.md | ACTIVE | 3/4+α React 연동 잔여 |
| 16 | dummy-data-seeding-plan.md | PLANNED | 미착수 |
| 17 | employee-user-linkage-plan.md | PLANNED | 미착수 |
| 18 | erp-api-development-plan.md | ACTIVE | Phase L 진행중 |
| 19 | esign-alimtalk-integration.md | PLANNED | 카카오 채널 개설 후 착수 |
| 20 | fg-code-consolidation-plan.md | ACTIVE | 분석완료, Phase 1 착수 전 |
| 21 | hotfix-20260119-action-plan.md | OBSOLETE | 일회성 핫픽스 이력 |
| 22 | incoming-inspection-document-integration-plan.md | PLANNED | 분석만 완료 |
| 23 | incoming-inspection-templates-plan.md | ACTIVE | 83% 4종 품목 대기 |
| 24 | intermediate-inspection-report-plan.md | PLANNED | 검토 대기 |
| 25 | item-inventory-management-plan.md | PLANNED | 설계 확정, 구현 대기 |
| 26 | item-master-data-alignment-plan.md | ACTIVE | 섀도잉 정리 재수행 |
| 27 | items-migration-kyungdong-plan.md | SUPERSEDED | → kd-items-migration-plan.md (archive) |
| 28 | kd-orders-migration-plan.md | PLANNED | 선행조건 미충족 |
| 29 | kd-quote-logic-plan.md | ACTIVE | 80% Phase 5 직전 |
| 30 | mng-item-field-management-plan.md | PLANNED | 미착수 |
| 31 | mng-menu-system-plan.md | ACTIVE | 구현완료, 테스트 잔여 |
| 32 | mng-numbering-rule-management-plan.md | PLANNED | 미착수 |
| 33 | monthly-expense-integration-plan.md | PLANNED | 미착수 |
| ~~34~~ | ~~product-code-traceability-plan.md~~ | **제외** | 진행중 - 정리 대상 아님 |
| 35 | quote-calculation-api-plan.md | PLANNED | 설계 완료, 미착수 |
| 36 | quote-management-8issues-plan.md | PLANNED | 컨펌 대기 |
| 37 | quote-management-url-migration-plan.md | COMPLETED | 92% 잔여 사소 |
| 38 | quote-order-sync-improvement-plan.md | PLANNED | 승인 대기 |
| 39 | quote-system-development-plan.md | SUPERSEDED | → kd-quote-logic-plan.md |
| 40 | react-api-integration-plan.md | ACTIVE | 기능별 API 연동 진행중 |
| 41 | react-mock-remaining-tasks.md | SUPERSEDED | → react-mock-to-api-migration-plan.md |
| 42 | react-mock-to-api-migration-plan.md | ACTIVE | Mock→API 전환 진행중 |
| 43 | receiving-management-analysis-plan.md | PLANNED | 분석 완료, 개발 대기 |
| 44 | simulator-ui-enhancement-plan.md | ACTIVE | 60% Phase 2 진행중 |
| 45 | tenant-id-compliance-plan.md | PLANNED | 실행 대기 |
| 46 | tenant-numbering-system-plan.md | PLANNED | 미착수 |

#### 3.1.2 sub/ 문서 분류 결과

| # | 파일명 | 처리 | 상위 문서 | 비고 |
|---|--------|:----:|----------|------|
| 1 | categories-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |
| 2 | contract-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |
| 3 | items-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |
| 4 | order-management-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |
| 5 | pricing-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |
| 6 | site-management-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |
| 7 | structure-review-plan.md | C (삭제) | construction-api (archive) | 상위 완료 |

#### 3.1.3 clodeCheck/ 문서 분류 결과

| # | 파일명 | 처리 | 비고 |
|---|--------|:----:|------|
| 1 | attendance-management_2026-01-14_23-30-00.md | A (삭제) | 일회성 E2E 리포트 |
| 2 | bank-transactions_2026-01-15_test-report.md | A (삭제) | 일회성 테스트 리포트 |
| 3 | card-transactions_2026-01-15_test-report.md | A (삭제) | 일회성 테스트 리포트 |
| 4 | employee-register_2026-01-14_20-00-00.md | A (삭제) | 일회성 테스트 리포트 |
| 5 | salary-management_2026-01-15_10-30-00.md | A (삭제) | 일회성 테스트 리포트 |
| 6 | sales-management_2026-01-15_test-report.md | A (삭제) | 일회성 테스트 리포트 |
| 7 | withdrawal-management_2026-01-15_test-report.md | A (삭제) | 일회성 테스트 리포트 |

**Phase 1 완료 기준**: 위 3개 테이블 완성 + 사용자 승인

---

### Phase 2: 통폐합 (승인 후)

**목표**: SUPERSEDED 문서를 최신 문서에 병합

**작업 절차**:
1. Phase 1에서 SUPERSEDED로 분류된 문서 목록 확인
2. 각 SUPERSEDED 문서 → 대응하는 최신 문서 매핑
3. 이전 문서에만 있는 유용한 내용 추출
4. 최신 문서에 병합 (필요한 내용만)
5. **건별로 사용자 확인** (또는 일괄 승인 선택)
6. 확인 후 이전 문서 삭제

**산출물**: 통폐합 매핑 테이블

| SUPERSEDED 문서 | 병합 대상 (최신) | 병합 내용 요약 | 승인 |
|----------------|-----------------|---------------|------|
| (Phase 1 결과) | | | |

**Phase 2 완료 기준**: 모든 SUPERSEDED 문서 처리 + 사용자 승인

---

### Phase 3: 정리

**목표**: COMPLETED/OBSOLETE 처리, HISTORY.md 작성, 인덱스 재작성

**병렬 가능한 작업**:

**3-A. HISTORY.md 작성**
1. 현재 archive/ 37개 문서에서 기능명 + 완료시기 + 한줄요약 추출
2. Phase 1에서 COMPLETED로 분류된 메인 문서도 동일 처리
3. 기능 도메인별로 분류하여 HISTORY.md 작성
4. archive/ 개별 파일 삭제

**3-B. OBSOLETE 삭제**
1. Phase 1에서 OBSOLETE로 분류된 문서 삭제
2. sub/ 처리 (Phase 1 판정에 따라)
3. clodeCheck/ 처리 (Phase 1 판정에 따라)

**3-C. index_plans.md 재작성** (3-A, 3-B 완료 후)
1. ACTIVE + PLANNED 문서만 기능 도메인별로 정리
2. 각 문서의 상태/진행률 반영
3. HISTORY.md 링크 포함

**Phase 3 완료 기준**: 폴더에 ACTIVE+PLANNED만 남음 + index 재작성 완료

---

### Phase 4: 검증

**목표**: 최종 구조 확인

**체크리스트**:
- [ ] docs/plans/에 ACTIVE + PLANNED 문서만 존재
- [ ] archive/에 HISTORY.md만 존재
- [ ] sub/, clodeCheck/ 정리 완료
- [ ] index_plans.md가 실제 파일과 일치
- [ ] 삭제된 문서 중 필요한 내용이 누락되지 않았는지 확인
- [ ] flow-tests/, Storyboard 폴더 영향 없음

---

## 4. 작업 시 주의사항

### 4.0 정리 제외 대상

아래 문서는 정리/분류/통폐합 대상에서 **제외**한다:
- `product-code-traceability-plan.md` — 현재 진행중
- **이 정리 작업 이후 신규 생성되는 문서** — GUIDE.md 원칙에 따라 생성되므로 정리 불필요

### 4.1 삭제 전 확인 원칙
- 문서 삭제 전 반드시 내용을 읽고 유용한 정보 유무 확인
- SUPERSEDED 삭제 시 최신 문서에 병합 완료 확인 후 삭제
- **git에서 복구 가능하므로** 과도한 보수적 판단 불필요

### 4.2 판단 기준 우선순위
- 최신 문서 > 이전 문서
- 구체적 구현 내용 > 추상적 계획
- 현재 시스템에 적용된 내용 > 적용 예정이었던 내용

### 4.3 변경 승인 정책

| 분류 | 예시 | 승인 |
|------|------|------|
| ✅ 즉시 가능 | Phase 1 분류 테이블 작성 | 불필요 (읽기 전용) |
| ⚠️ 컨펌 필요 | 문서 병합, 삭제, HISTORY.md 작성 | **Phase별 사용자 승인** |
| 🔴 금지 | flow-tests/, Storyboard 수정 | 별도 협의 |

---

## 5. 변경 이력

| 날짜 | 항목 | 변경 내용 |
|------|------|----------|
| 2026-02-26 | 문서 초안 | 정책 수립 완료, 4 Phase 계획 작성 |
| 2026-02-26 | Phase 1~4 완료 | 분류→통폐합→정리→검증 전 과정 완료 |

---

## 6. 참고 문서

- **문서 가이드**: `docs/plans/GUIDE.md` ← 정리 시 준수할 최소 원칙
- **현재 인덱스**: `docs/plans/index_plans.md`
- **문서 인덱스**: `docs/INDEX.md`
- **프로젝트 구조**: `CLAUDE.md`

---

*이 문서는 /plan 스킬로 생성되었습니다.*