diff --git a/plans/docs-comprehensive-update-plan.md b/plans/docs-comprehensive-update-plan.md new file mode 100644 index 0000000..dc02f49 --- /dev/null +++ b/plans/docs-comprehensive-update-plan.md @@ -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 대상 제외) | \ No newline at end of file