# docs/ 종합 정비 계획

> **작성일**: 2026-02-27
> **상태**: ✅ 전체 완료 (Phase 0~4)
> **목적**: 시스템 실제 분석 기반의 문서 재정비 — 현황 정확성 확보 + 구조 표준화 + 중복 제거

---

## 1. 배경 및 목적

### 1.1 왜 필요한가

docs/ 폴더가 초기에 체계적 분석 없이 점진적으로 쌓여왔으며, 시스템의 실제 상태와 문서 간 괴리가 심각해졌다.

**핵심 문제:**
- DB 스키마 문서가 **50+개 신규 테이블** 미반영 (219개 기록 → 실제 270+개)
- 2026년 2월 추가된 대형 도메인(재무/회계, 전자서명, 설비, AI, 차량) **기능 문서 부재**
- 실행 계획(plans/) 간 중복·대체 관계 미정리
- 문서 내 경로·버전 등 **사실과 다른 기술 정보** 다수
- 문서 정책(폴더 분류, 명명 규칙, 템플릿) 실제 준수율 낮음

### 1.2 목표

| # | 목표 | 완료 기준 |
|---|------|----------|
| G1 | 시스템 현황 문서 정확성 100% | DB 스키마, 아키텍처, 스펙이 실제 코드와 일치 |
| G2 | 모든 활성 도메인에 기능 문서 존재 | features/ 하위 도메인별 README.md |
| G3 | 실행 계획 통합·정리 | 중복 제거, 완료분 아카이브, 인덱스 동기화 |
| G4 | 문서 정책 현행화 | INDEX.md, CLAUDE.md, GUIDE.md 실제 반영 |
| G5 | 중복 데이터 제거 | 동일 내용의 문서 단일 소스(SSOT) 확보 |

### 1.3 범위

```
분석 대상 (소스 코드)          문서화 대상 (docs/)
┌─────────────────────┐       ┌─────────────────────┐
│ api/   (Laravel 12)  │──→   │ system/              │ ← architecture/ + specs/ 통합
│  - 205 Models        │      │ standards/           │
│  - 179 Services      │      │ rules/               │
│  - 131 Controllers   │      │ features/            │
│  - 458 Migrations    │      │ guides/              │
│  - 18 Route domains  │      │ plans/               │ ← 작업 추적 (예정/진행/완료)
├─────────────────────┤       │ projects/            │ ← 프로젝트성 자료 보관
│ react/ (Next.js 15)  │      │ front/               │
│  - 249 Pages         │      │ quickstart/          │
│  - 612 Components    │      │ changes/             │
│  - 91 Server Actions │      │ deploys/             │
├─────────────────────┤       │ data/                │
│ mng/   (Laravel 12)  │      │ history/             │
│  - 171 Controllers   │      └─────────────────────┘
│  - 436 Blade views   │
│  - 185 Models        │
├─────────────────────┤
│ sales/ (추후 개발)    │
│ docker/ (Nginx 등)   │
└─────────────────────┘
```

---

## 2. 현황 감사 결과

### 2.1 시스템 vs 문서 격차 (Critical)

| 영역 | 문서 상태 | 실제 시스템 | 격차 |
|------|----------|-----------|------|
| DB 테이블 수 | 219개 (2026-01-29) | 270+개 추정 | **50+개 미반영** |
| API 도메인 | 일부만 기록 | 18개 라우트 도메인 | features/ 누락 다수 |
| React 페이지 | 미기록 | 249개 페이지 | **프론트 현황 문서 부재** |
| MNG 기능 | 일부만 기록 | 171 컨트롤러, 436 뷰 | **MNG 현황 문서 부재** |
| 기술 스택 | Laravel 11 기록 | Laravel 12 + PHP 8.4 | **버전 불일치** |

### 2.2 미문서화 도메인 (2026년 2월 신규)

| 도메인 | DB 테이블 | API 존재 | 기능 문서 |
|--------|----------|---------|----------|
| 재무/회계 (Finance) | 20+개 | ✅ | ❌ 없음 |
| 전자서명 (E-Sign) | 6개 | ✅ | ❌ 없음 |
| 설비관리 (Equipment) | 6개 | ✅ | ❌ 없음 |
| 차량관리 (Vehicle) | 3개 | ✅ | ❌ 없음 |
| AI/음성 (AI) | 5개 | ✅ | ❌ 없음 |
| 면접 (Interview) | 5개 | ✅ | ❌ 없음 |
| 채번규칙 (Numbering) | 2개 | ✅ | ❌ 없음 |
| 문서서식 (DocTemplate) | 4개 | ✅ | ❌ 없음 |
| 바로빌 연동 확장 | 5개 | ✅ | ❌ 없음 |
| 회의록 (Meeting) | 2개 | ✅ | ❌ 없음 |

### 2.3 부정확한 문서

| 문서 | 문제 | 심각도 |
|------|------|--------|
| `docs/CLAUDE.md` | 경로 `/home/aweso/sam/` (실제: `/Users/kent/...`), Laravel 11 기록 | 🔴 |
| `docs/specs/database-schema.md` | 50+개 테이블 누락, 테이블 수 219로 기록 | 🔴 |
| `docs/TODO.md` | 2025-12-21 이후 미갱신, 보안 이슈 방치 | 🟡 |
| `docs/rules/README.md` | 8개 중 2개만 목록에 있음 | 🟡 |
| `SAM/CLAUDE.md` (루트) | `SAM_QUICK_REFERENCE.md` 등 경로 불일치 | 🟡 |
| `docs/projects/mes/MES_PROGRESS_TRACKER.md` | 2025-11-13 이후 미갱신 | 🟡 |
| `docs/projects/api-integration/PROGRESS.md` | 2025-12-20 이후 미갱신 (90%?) | 🟡 |

### 2.4 계획 문서(plans/) 상태

| 상태 | 수량 | 비고 |
|------|------|------|
| 🟡 진행중 (ACTIVE) | 18개 | 일부 장기 정체 |
| ⚪ 대기 (WAITING) | 19개 | 선행조건 대기 |
| ✅ 완료 (ARCHIVE) | ~40개 | archive/ 이동 완료 |
| ⚠️ 아카이브 필요 | 2개 | `docs-plans-cleanup-plan`, `product-code-traceability-plan` |
| ⚠️ 장기 정체 | 4개 | Phase 4에서 최종 정리 (하단 목록 참조) |

**장기 정체 계획 (3개월+ 미갱신) — Phase 4에서 최종 정리:**

| 계획 | 진행률 | 마지막 갱신 |
|------|--------|-----------|
| `5130-to-mng-migration-plan.md` | 13% | 2025-12-17 |
| `erp-api-development-plan.md` | Phase L 완료 | 2025-12-17 |
| `mng-menu-system-plan.md` | 구현 완료, 테스트 대기 | 2025-12-16 |
| `simulator-ui-enhancement-plan.md` | 60% | 2025-12-30 |

---

## 3. 확정된 결정 사항

> 논의 완료 — 이후 모든 Phase에서 이 기준을 따른다

| # | 결정 | 내용 |
|---|------|------|
| D1 | DB 스키마 분할 | **도메인별 분할** — `system/database/` 하위에 도메인별 파일 |
| D2 | features/ 문서 깊이 | **기능 설명 + 엔드포인트 경로 목록** 포함, 상세 요청/응답은 Swagger 참조 |
| D3 | 파일명 정책 | **한글 허용** — 기술 문서는 영문 kebab-case, 업무/비즈니스 문서는 한글 허용, 혼용 금지 |
| D4 | plans/ vs projects/ | **분리 유지** — plans/=작업 추적(예정→진행→완료), projects/=프로젝트성 자료 보관 |
| D5 | architecture/ + specs/ 통합 | **`system/`으로 통합** — 현황(아키텍처+스펙+인프라)을 하나의 상위 폴더에 |
| D6 | 장기 정체 계획 | **폐기하지 않음** — 한곳에 모아두고 Phase 4(최종 정리)에서 일괄 판단 |
| D7 | changes/ 날짜 포맷 | **`YYYYMMDD_description.md`** 단일 형식으로 통일 |
| D8 | docs/CLAUDE.md 처리 | **삭제** — 유효 내용은 `docs/INDEX.md`에 통합, docs/CLAUDE.md 파일 제거 |
| D9 | docs/front/ 폴더 | **삭제** — 구 front 시절 잔재, 필요한 내용은 적절한 위치로 이동 후 폴더 제거 |
| D10 | plans/ 폴더 | **현행 유지** — 이미 정리 완료, 이번 정비에서 건드리지 않음 |
| D11 | deploys/ops-manual/ | **현행 유지** — 그대로 둠 |

### D3 파일명 규칙 상세

```
✅ 기술 문서 (코드 참조):  api-rules.md, database-schema.md
✅ 업무/비즈니스 문서:     영업파트너가이드북.md, 수당지급.md
❌ 혼용 금지:             영업partner가이드.md, 메뉴badge기능.md
```

### D5 system/ 폴더 구조

```
system/                              ← architecture/ + specs/ 통합
├── overview.md                      ← 전체 시스템 아키텍처
├── database/                        ← DB 스키마 (D1: 도메인별 분할)
│   ├── README.md                    ← 전체 테이블 인덱스 + 도메인 맵
│   ├── tenants.md                   ← 테넌트/인증/권한
│   ├── production.md                ← 생산/작업지시/BOM
│   ├── finance.md                   ← 재무/회계
│   ├── sales.md                     ← 영업/견적/수주
│   ├── hr.md                        ← 인사/근태/급여
│   ├── items.md                     ← 품목/자재/재고
│   ├── documents.md                 ← 문서/서식/전자서명
│   ├── commons.md                   ← 공통(파일, 메뉴, 게시판, 감사로그)
│   └── others.md                    ← 설비, 차량, AI, 면접, 바로빌 등
├── api-structure.md                 ← API 라우트 도메인·엔드포인트 현황
├── react-structure.md               ← React 페이지·컴포넌트·패턴 현황
├── mng-structure.md                 ← MNG 컨트롤러·뷰·패턴 현황
├── security-policy.md               ← 보안 정책
├── scaling-roadmap.md               ← 스케일링 로드맵
├── docker-setup.md                  ← Docker/인프라 환경
├── remote-work-setup.md             ← 원격 접속 설정
├── board-system-spec.md             ← 게시판 시스템 스펙
└── item-master-integration.md       ← 품목 마스터 통합 스펙
```

---

## 4. 작업 계획

### Phase 0: 문서 정책 재정립 (선행 필수)

> 이후 모든 작업의 기준이 되므로 먼저 확정

| # | 작업 | 산출물 |
|---|------|--------|
| 0-1 | docs/ 폴더 구조 정책 재정의 (D5 system/ 통합 반영) | 폴더 구조 확정 |
| 0-2 | 문서 분류 기준 확정 (폴더별 역할, 중복 방지 SSOT 규칙) | 분류 가이드 |
| 0-3 | 파일명·포맷·템플릿 표준 확정 (D3 반영) | 표준 문서 |
| 0-4 | `docs/CLAUDE.md` 유효 내용 → `INDEX.md` 통합, 파일 삭제 (D8) | INDEX.md 갱신 |
| 0-5 | `docs/front/` 필요 내용 이관 후 폴더 삭제 (D9) | front/ 제거 |
| 0-6 | `changes/` 기존 파일명 → `YYYYMMDD_description.md` 통일 (D7) | 파일명 변경 |

**Phase 0 결정 사항 모두 확정됨 (D1~D9)**

---

### Phase 1: 시스템 현황 문서화 (최우선)

> 실제 코드를 분석하여 "지금 시스템이 어떤 상태인가"를 정확하게 기록
> 산출물은 모두 `system/` 폴더에 배치

#### 1-A. DB 스키마 전면 재작성

| # | 작업 | 상세 |
|---|------|------|
| 1A-1 | 전체 마이그레이션 분석 (458개) | 테이블 목록, 컬럼, 관계 추출 |
| 1A-2 | 도메인별 테이블 그룹핑 | 기존 + 신규 도메인 분류 |
| 1A-3 | `system/database/` 도메인별 파일 작성 | README.md(인덱스) + 도메인별 스키마 |
| 1A-4 | 기존 `specs/database-schema.md` 폐기 처리 | system/database/로 이전 완료 표기 |

#### 1-B. API 시스템 현황

| # | 작업 | 상세 |
|---|------|------|
| 1B-1 | 18개 라우트 도메인별 엔드포인트 경로 목록 | routes/api/v1/ 분석 |
| 1B-2 | 모델-서비스-컨트롤러 매핑 현황 | 205 모델 기준 도메인 분류 |
| 1B-3 | 인증/권한 구조 현황 | Sanctum + Spatie Permission |
| 1B-4 | `system/overview.md` 작성 | 전체 아키텍처 + 기술 스택 (Laravel 12, PHP 8.4) |
| 1B-5 | `system/api-structure.md` 작성 | API 도메인·라우트 현황 |

#### 1-C. React(프론트엔드) 현황

| # | 작업 | 상세 |
|---|------|------|
| 1C-1 | 페이지 라우트 구조 현황 | 249개 페이지, 도메인별 분류 |
| 1C-2 | 컴포넌트 아키텍처 현황 | Atomic Design: 55 ui + 3 atoms + 11 molecules + 12 organisms |
| 1C-3 | 상태관리·API연동 패턴 현황 | Zustand 13 stores, 91 Server Actions |
| 1C-4 | `system/react-structure.md` 작성 | Next.js 15, React 19, Tailwind v4 |

#### 1-D. MNG(관리자) 현황

| # | 작업 | 상세 |
|---|------|------|
| 1D-1 | 컨트롤러·뷰 도메인 구조 현황 | 171 컨트롤러, 436 블레이드 |
| 1D-2 | HTMX + DaisyUI 프론트 패턴 현황 | 서버 렌더링, Vite 7 |
| 1D-3 | api ↔ mng 모델 공유/차이 현황 | 205(api) vs 185(mng) 비교 |
| 1D-4 | `system/mng-structure.md` 작성 | MNG 전체 구조 현황 |

#### 1-E. 인프라/환경 현황

| # | 작업 | 상세 |
|---|------|------|
| 1E-1 | Docker 구성 현황 분석 | 컨테이너, 네트워크, 볼륨 |
| 1E-2 | 도메인·환경 구성 현황 정리 | *.sam.kr(로컬), codebridge-x.com(개발) |
| 1E-3 | `system/docker-setup.md` 갱신 | 현재 Docker 구성 반영 |

---

### Phase 2: 기존 문서 정비

> 부정확한 정보 수정, 폴더 이관, 불필요한 문서 정리

#### 2-A. 폴더 구조 이관

| # | 작업 | 상세 |
|---|------|------|
| 2A-1 | `architecture/` → `system/` 이관 | 파일 이동 + 내용 갱신 |
| 2A-2 | `specs/` → `system/` 이관 | 파일 이동 + 내용 갱신 |
| 2A-3 | 기존 폴더 제거 또는 리다이렉트 안내 | 혼란 방지 |

#### 2-B. 부정확 문서 수정

| # | 대상 | 수정 내용 |
|---|------|----------|
| 2B-1 | `docs/CLAUDE.md` | 경로 수정 (`/Users/kent/...`), Laravel 12, 역할 재정의 |
| 2B-2 | `SAM/CLAUDE.md` (루트) | 문서 참조 경로 수정, system/ 반영 |
| 2B-3 | `docs/TODO.md` | 현행화 — 해결된 항목 정리, 미해결 항목 갱신 |
| 2B-4 | `docs/rules/README.md` | 실제 8개 파일 목록과 동기화 |
| 2B-5 | `docs/standards/quality-checklist.md` | 현재 기준에 맞게 갱신 |

#### ~~2-C. 계획 문서 정리~~ → 제외 (D10: plans/ 이미 정리 완료, 건드리지 않음)

#### 2-D. 구조 표준화

| # | 작업 | 상세 |
|---|------|------|
| 2D-1 | `changes/` 파일명 포맷 통일 | 단일 날짜 형식 적용 |
| 2D-2 | `guides/` 파일명 정리 | D3 기준 적용 (한글/영문 혼용 수정) |
| 2D-3 | `projects/` 프로젝트별 상태 갱신 | PROGRESS.md 현행화 |
| 2D-4 | 중복 문서 통합 | 동일 주제 다중 문서 → SSOT 확보 |

---

### Phase 3: 신규 도메인 기능 문서 작성

> Phase 1 현황 분석 결과를 바탕으로 누락된 기능 문서 신규 작성
> 각 문서: 기능 설명 + 엔드포인트 경로 목록 + Swagger 참조 안내 (D2)

| # | 도메인 | 위치 | 우선순위 |
|---|--------|------|---------|
| 3-1 | 재무/회계 (Finance) | `features/finance/` 확장 | 🔴 |
| 3-2 | 전자서명 (E-Sign) | `features/esign/` 신규 | 🔴 |
| 3-3 | 설비관리 (Equipment) | `features/equipment/` 신규 | 🟡 |
| 3-4 | 차량관리 (Vehicle) | `features/card-vehicle/` 확장 | 🟡 |
| 3-5 | AI/음성 | `features/ai/` 신규 | 🟢 |
| 3-6 | 면접 시스템 | `features/hr/` 확장 | 🟢 |
| 3-7 | 채번규칙 | `rules/numbering-rules.md` 신규 | 🟢 |
| 3-8 | 문서서식 템플릿 | `features/documents/` 확장 | 🟢 |
| 3-9 | 바로빌 연동 확장 | `features/barobill-kakaotalk/` 확장 | 🟢 |
| 3-10 | 회의록 | `features/meeting/` 신규 | 🟢 |

---

### Phase 4: 최종 검증 및 정리

> 모든 Phase 완료 후 — 문서 전체 정합성 확인 + 장기 정체 계획 최종 판단

| # | 작업 | 상세 |
|---|------|------|
| 4-1 | `docs/INDEX.md` 전면 재작성 | system/ 반영, 모든 문서 네비게이션 |
| 4-2 | `docs/CLAUDE.md` 최종 갱신 | 정확한 경로·정책·폴더 구조 반영 |
| 4-3 | `SAM/CLAUDE.md` 동기화 | docs/ 참조 경로 최종 확인 |
| 4-4 | 교차 참조 검증 | 문서 간 링크 유효성 확인 |
| 4-5 | 문서 크기 검증 | 10KB 초과 문서 분할 |
| ~~4-6~~ | ~~장기 정체 계획 최종 정리~~ | 제외 (D10: plans/ 건드리지 않음) |

---

## 5. 의존 관계 및 실행 순서

```
Phase 0 (정책 재정립)
    │
    ├──→ Phase 1-A (DB 스키마)    ──┐
    ├──→ Phase 1-B (API 현황)      ├──→ Phase 3 (신규 기능 문서)
    ├──→ Phase 1-C (React 현황)    │         │
    ├──→ Phase 1-D (MNG 현황)      │         │
    └──→ Phase 1-E (인프라 현황)  ──┘         │
              │                               │
              ├──→ Phase 2 (기존 문서 정비)  ──┘
              │                               │
              └──────────────────────────────→ Phase 4 (최종 검증 + 장기계획 정리)
```

- **Phase 0** → 모든 Phase의 선행 조건
- **Phase 1 (A~E)** → 병렬 가능
- **Phase 2** → Phase 1과 부분 병렬 가능 (2-B, 2-C는 독립 선행 가능)
- **Phase 2-A** (폴더 이관) → Phase 1 이후 (system/ 내용이 먼저 작성되어야 이관 가능)
- **Phase 3** → Phase 1 완료 후 (현황 기반)
- **Phase 4** → 모든 Phase 완료 후

---

## 6. 예상 산출물

| Phase | 주요 산출물 |
|-------|-----------|
| 0 | 문서 정책서 (폴더 구조, 분류 기준, 명명 규칙, 템플릿, SSOT 원칙) |
| 1-A | `system/database/` — README.md + 도메인별 스키마 파일 (~9개) |
| 1-B | `system/overview.md` + `system/api-structure.md` |
| 1-C | `system/react-structure.md` |
| 1-D | `system/mng-structure.md` |
| 1-E | `system/docker-setup.md` 갱신 |
| 2 | 정비된 기존 문서 + architecture/specs/ → system/ 이관 |
| 3 | 10개 도메인 기능 문서 (신규/확장) |
| 4 | INDEX.md + SAM/CLAUDE.md 최종본 |

---

## 7. 확정된 폴더 구조 (Phase 0 완료 후 목표)

```
docs/
├── INDEX.md                     ← 마스터 네비게이션
├── CURRENT_WORKS.md             ← docs 작업 추적
│                                  (CLAUDE.md 삭제 → INDEX.md 통합 — D8)
│
├── system/                      ← 🆕 시스템 현황 (architecture/ + specs/ 통합)
│   ├── overview.md              ← 전체 아키텍처 + 기술 스택
│   ├── database/                ← DB 스키마 (도메인별)
│   ├── api-structure.md         ← API 도메인·라우트 현황
│   ├── react-structure.md       ← React 구조 현황
│   ├── mng-structure.md         ← MNG 구조 현황
│   ├── security-policy.md       ← 보안 정책
│   ├── scaling-roadmap.md       ← 스케일링
│   ├── docker-setup.md          ← Docker/인프라
│   └── ...                      ← 기타 스펙
│
├── standards/                   ← 코딩 표준·컨벤션
├── rules/                       ← 비즈니스 규칙·정책
├── features/                    ← 기능별 상세 문서
├── guides/                      ← 구현 가이드·매뉴얼
│                                  (front/ 삭제 — D9)
├── quickstart/                  ← 개발자 빠른 시작
│
├── plans/                       ← 작업 추적 (예정 → 진행 → 완료 → archive/)
│   ├── index_plans.md
│   ├── GUIDE.md
│   ├── [계획 문서들]
│   └── archive/
│
├── projects/                    ← 프로젝트성 자료 (분석, 설계, 참고)
├── changes/                     ← 변경 이력
├── deploys/                     ← 운영 매뉴얼
├── data/                        ← 데이터 분석
├── history/                     ← 히스토리 기록
├── api/                         ← API 통합 문서
├── requests/                    ← 요청/기획 문서
└── assets/                      ← BI 등 정적 자산
```

---

## 변경 이력

| 날짜 | 변경 내용 |
|------|----------|
| 2026-02-27 | 초안 작성 — 시스템 분석 결과 기반 계획 수립 |
| 2026-02-27 | Q1~Q6 결정 사항 반영 — D1~D6 확정, Phase별 산출물 구체화 |
| 2026-02-27 | D7~D9 추가 확정 — 날짜 포맷, CLAUDE.md→INDEX.md 통합, front/ 삭제 |
| 2026-02-27 | D10~D11 추가 — plans/, deploys/ops-manual/ 현행 유지(건드리지 않음) |
| 2026-02-27 | Phase 0 완료 — INDEX.md 재작성, CLAUDE.md→INDEX.md 통합, front/→guides/ 이관, changes/ 포맷 통일 |
| 2026-02-27 | Phase 1 완료 — system/ 문서 14개 작성 (overview, api-structure, react-structure, mng-structure, docker-setup, database/README + 9개 도메인 스키마) |
| 2026-02-27 | Phase 2 완료 — 2-A: architecture/+specs/→system/ 이관(6개 이동, 4개 폐기), 2-B: rules/README.md 갱신, 경로 참조 수정(13개 파일), 2-D: changes/ 파일명 D7 통일(3개), guides/ D3 위반 수정(1개) |
| 2026-02-27 | Phase 3 완료 — 7개 도메인 문서 작성: esign/(1), documents/(1), ai/(1), equipment/(1), numbering-rules(1), finance/ 확장(9+README갱신), barobill/ 확장(API 설정 섹션). 건너뜀: Vehicle(문서 완성), Interview(문서 완성), Meeting(API 미구현) |
| 2026-02-27 | Phase 4 완료 — INDEX.md 링크검증(96개 중 1개 깨짐→수정), 교차참조검증(7개 파일 11개 깨진링크→전수 수정), SAM/CLAUDE.md 동기화(docs/ 참조 이상 없음, root 참조 깨짐 5건은 docs/ 범위 밖), 문서크기검증(활성 문서 모두 10KB 이내, plans/history/projects는 D10/D11 대상 제외) |