docs: [종합정비] 계획 문서 추가

- docs/plans/docs-comprehensive-update-plan.md
- 11개 설계 결정(D1~D11), 4개 Phase 실행 기록 포함
- 상태: 전체 완료

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-02-27 18:03:30 +09:00
parent ae7e139d12
commit 81f3c4deef

View File

@@ -0,0 +1,414 @@
# 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 대상 제외) |