diff --git a/INDEX.md b/INDEX.md index f3bcb05..0728fc7 100644 --- a/INDEX.md +++ b/INDEX.md @@ -1,158 +1,170 @@ -# SAM 프로젝트 문서 네비게이션 +# SAM 프로젝트 문서 인덱스 -> 📌 **Claude Code를 위한 문서 허브** - 작업별로 필요한 문서를 빠르게 찾아 컨텍스트에 추가하세요. +> **Claude Code 작업 전 필수 확인** - 작업 유형에 맞는 문서를 먼저 읽고 시작하세요. --- -## 🚀 빠른 시작 +## 🎯 작업별 필수 문서 (반드시 먼저 확인) -| 문서 | 용도 | 크기 | -|------|------|------| -| [Quick Start Guide](reference/quick-start.md) | 프로젝트 핵심 규칙 요약 | 5KB | -| [개발 환경 설정](specs/docker-setup.md) | Docker 환경 구축 | 7KB | -| [개발 명령어](reference/dev-commands.md) | 일상 개발 명령어 | 4KB | +| 작업 유형 | 필수 문서 | 용도 | +|----------|----------|------| +| **API 개발** | `standards/api-rules.md` | Service-First, FormRequest, i18n 규칙 | +| **DB 변경** | `specs/database-schema.md` | 테이블 구조, 관계, 컬럼 규칙 | +| **새 기능 구현** | `architecture/system-overview.md` | 전체 아키텍처 이해 | +| **보안 관련** | `architecture/security-policy.md` | 인증/인가, 보안 규칙 | +| **Git 커밋** | `standards/git-conventions.md` | 커밋 메시지, 브랜치 전략 | +| **품질 검증** | `standards/quality-checklist.md` | 코드 품질 체크리스트 | +| **Swagger 작성** | `guides/swagger-guide.md` | API 문서 작성 방법 | +| **품목관리** | `specs/item-master-integration.md` | 품목 시스템 스펙 | +| **게시판** | `specs/board-system-spec.md` | 게시판 시스템 설계 | +| **MES 개발** | `projects/mes/README.md` | MES 프로젝트 개요 | --- -## 📐 규칙 및 원칙 +## 📁 폴더 구조 -개발 시 참고해야 할 규칙과 원칙 문서입니다. - -| 규칙 유형 | 폴더 | 용도 | 예시 | -|----------|------|------|------| -| **코딩 규칙** | [standards/](standards/README.md) | 네이밍 컨벤션, 코드 스타일 | 변수명, 파일명, 포맷팅 | -| **비즈니스 규칙** | [rules/](rules/README.md) | 도메인 로직에서 파생된 규칙 | 품목코드 생성, 검증 규칙 | -| **설계 원칙** | [principles/](principles/README.md) | 아키텍처/설계 결정 기준 | Service-First, API 설계 | - -### 문서 분류 기준 -- **Standards**: "어떻게 코드를 작성할 것인가" (How to write) -- **Rules**: "무엇이 유효한 데이터/상태인가" (What is valid) -- **Principles**: "왜 이렇게 설계하는가" (Why we design) +``` +docs/ +├── standards/ # 개발 표준 - "어떻게 코드를 작성할 것인가" +├── architecture/ # 아키텍처 - "왜 이렇게 설계하는가" +├── rules/ # 비즈니스 규칙 - "무엇이 유효한 데이터인가" +├── specs/ # 기술 스펙 - "무엇을 구현할 것인가" +├── guides/ # 구현 가이드 - "어떻게 구현할 것인가" +├── quickstart/ # 빠른 시작 - 핵심 요약 +├── front/ # 프론트엔드 공유 문서 +├── features/ # 기능별 상세 문서 +├── projects/ # 프로젝트별 문서 (MES, Legacy) +├── history/ # 히스토리 및 로드맵 +├── changes/ # 변경 이력 +└── data/ # 데이터 분석 +``` --- -## 📖 개발 가이드 +## 📚 폴더별 문서 목록 -### Reference (일상 참고 문서) -현재 작업에 필요한 참고 문서입니다. +### standards/ - 개발 표준 +> 코딩 컨벤션, 스타일 가이드, 품질 기준 -- **[API 개발 규칙](reference/api-rules.md)** - Service-First, FormRequest, i18n 규칙 -- **[품질 체크리스트](reference/quality-checklist.md)** - 코드 품질 검증 항목 -- **[Git 규칙](reference/git-conventions.md)** - 커밋 메시지, 브랜치 전략 -- **[시스템 아키텍처](reference/architecture.md)** - SAM 프로젝트 구조 개요 +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [api-rules.md](standards/api-rules.md) | API 개발 규칙 (Service-First, FormRequest, i18n) | API 개발 전 | +| [git-conventions.md](standards/git-conventions.md) | Git 커밋 메시지, 브랜치 전략 | 커밋 전 | +| [quality-checklist.md](standards/quality-checklist.md) | 코드 품질 체크리스트 | PR 전 | -### Specs (환경/스펙 문서) -시스템 스펙과 환경 설정 문서입니다. +### architecture/ - 아키텍처 & 설계 원칙 +> 시스템 설계, 보안 정책, 아키텍처 결정 -- **[데이터베이스 스키마](specs/database-schema.md)** - DB 구조 및 관계도 -- **[DB 관계도](specs/database-relationships.md)** - 테이블 관계 상세 -- **[게시판 시스템](specs/board-system-spec.md)** - 시스템/테넌트 게시판 설계 -- **[보안 정책](specs/security-policy.md)** - 인증/인가, 보안 규칙 -- **[Docker 환경](specs/docker-setup.md)** - Docker 구성 및 설정 -- **[원격 작업 환경](specs/remote-work-setup.md)** - 원격 개발 설정 +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [system-overview.md](architecture/system-overview.md) | 전체 시스템 아키텍처 | 새 기능 설계 전 | +| [security-policy.md](architecture/security-policy.md) | 인증/인가, 보안 규칙 | 보안 관련 작업 전 | -### Features (기능별 문서) -특정 기능의 상세 문서입니다. +### rules/ - 비즈니스 규칙 +> 도메인 로직, 검증 규칙, 상태 전이 -- **[게시판 시스템](features/boards/README.md)** - 시스템/테넌트 게시판 구현 - - [MNG 구현 상세](features/boards/mng-implementation.md) +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [README.md](rules/README.md) | 비즈니스 규칙 개요 | 도메인 로직 구현 전 | -### Guides (구현 가이드) -특정 기능 구현을 위한 매뉴얼입니다. +### specs/ - 기술 스펙 +> 구현 명세, DB 스키마, 시스템 설정 -- **[파일 스토리지 구현](guides/file-storage-guide.md)** - 파일 업로드/다운로드 구현 -- **[Swagger 문서화](guides/swagger-guide.md)** - API 문서 작성 방법 -- **[Item 관리 마이그레이션](guides/item-management-migration.md)** - Item 시스템 전환 가이드 -- **[프로젝트 런칭 로드맵](guides/project-launch-roadmap.md)** - 런칭 준비 현황 및 방향성 +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [database-schema.md](specs/database-schema.md) | DB 구조 및 관계도 | DB 변경 전 | +| [board-system-spec.md](specs/board-system-spec.md) | 게시판 시스템 설계 | 게시판 작업 전 | +| [item-master-integration.md](specs/item-master-integration.md) | 품목관리 통합 스펙 | 품목 관련 작업 전 | +| [docker-setup.md](specs/docker-setup.md) | Docker 환경 구성 | 환경 설정 시 | +| [remote-work-setup.md](specs/remote-work-setup.md) | 원격 개발 설정 | 원격 작업 시 | -### Frontend (프론트엔드 공유 문서) -프론트엔드 개발을 위한 API 연동 가이드입니다. +### guides/ - 구현 가이드 +> 특정 기능 구현을 위한 단계별 매뉴얼 -- **[품목기준관리(ItemMaster) 가이드](front/item-master-guide.md)** - 페이지-섹션-필드 구조, 잠금 기능, API 연동 +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [swagger-guide.md](guides/swagger-guide.md) | Swagger API 문서 작성법 | API 문서 작성 전 | +| [file-storage-guide.md](guides/file-storage-guide.md) | 파일 업로드/다운로드 구현 | 파일 기능 구현 전 | +| [item-management-migration.md](guides/item-management-migration.md) | Item 시스템 전환 가이드 | 마이그레이션 작업 전 | +| [project-launch-roadmap.md](guides/project-launch-roadmap.md) | 런칭 준비 현황 | 런칭 관련 작업 시 | ---- +### quickstart/ - 빠른 시작 +> 핵심 규칙 요약, 자주 쓰는 명령어 -## 📁 프로젝트별 문서 +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [quick-start.md](quickstart/quick-start.md) | 프로젝트 핵심 규칙 요약 | 세션 시작 시 | +| [dev-commands.md](quickstart/dev-commands.md) | 일상 개발 명령어 모음 | 명령어 확인 시 | -### MES 프로젝트 -- **[MES README](projects/mes/README.md)** - MES 프로젝트 개요 -- **[MES Roadmap](projects/mes/MES_PROJECT_ROADMAP.md)** - 개발 로드맵 -- **[Phase 0 Baseline](projects/mes/00_baseline/)** - 초기 분석 문서 +### front/ - 프론트엔드 공유 문서 +> API 연동 가이드, 프론트엔드 스펙 -### Legacy 5130 -- **[Draw Module](projects/legacy-5130/draw-module.md)** - 레거시 드로우 모듈 +| 문서 | 설명 | +|------|------| +| [item-master-guide.md](front/item-master-guide.md) | 품목기준관리 페이지-섹션-필드 구조 | ---- +### features/ - 기능별 문서 -## 📚 히스토리 +| 문서 | 설명 | +|------|------| +| [boards/README.md](features/boards/README.md) | 게시판 시스템 구현 | +| [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 | -### 2025-11 문서 -- **[서버 점검 (2025-11-18)](history/2025-11/server-inspection.md)** - 서버 환경 점검 결과 -- **[Item Master 갭 분석 (2025-11-20)](history/2025-11/item-master-gap-analysis.md)** - Item 마스터 분석 -- **[Item Master 스펙 (2025-11-20)](history/2025-11/item-master-spec.md)** - Item API 스펙 +### projects/ - 프로젝트별 문서 -### 2025-09 문서 -- **[Checkpoint (2025-09-19)](history/2025-09/checkpoint.md)** - 9월 개발 체크포인트 -- **[Database Schema (2025-09-19)](history/2025-09/database-schema.md)** - DB 스키마 스냅샷 -- **[Formula System Analysis](history/2025-09/formula-system-analysis.md)** - 산출식 시스템 분석 +| 프로젝트 | 문서 | 설명 | +|---------|------|------| +| **MES** | [README.md](projects/mes/README.md) | MES 프로젝트 개요 | +| **MES** | [MES_PROJECT_ROADMAP.md](projects/mes/MES_PROJECT_ROADMAP.md) | 개발 로드맵 | +| **Legacy** | [draw-module.md](projects/legacy-5130/draw-module.md) | 레거시 드로우 모듈 | -### Roadmaps -- **[December 2025 Roadmap](history/roadmaps/december-2025.md)** - 12월 개발 계획 +### history/ - 히스토리 + +| 기간 | 문서 | +|------|------| +| **2025-11** | [item-master-gap-analysis.md](history/2025-11/item-master-gap-analysis.md), [item-master-spec.md](history/2025-11/item-master-spec.md) | +| **2025-09** | [checkpoint.md](history/2025-09/checkpoint.md), [database-schema.md](history/2025-09/database-schema.md) | +| **Roadmaps** | [december-2025.md](history/roadmaps/december-2025.md) | --- ## 🏗️ 서브프로젝트 문서 -각 서브프로젝트는 독립적인 `docs/` 디렉토리를 가지고 있습니다. +각 서브프로젝트는 독립적인 `docs/` 디렉토리를 가집니다. | 프로젝트 | 문서 경로 | 설명 | |---------|----------|------| | **API** | [api/docs/INDEX.md](../api/docs/INDEX.md) | REST API 프로젝트 | -| **Admin** | [admin/docs/INDEX.md](../admin/docs/INDEX.md) | Filament 관리자 패널 (점차 deprecated) | -| **MNG** | [mng/docs/INDEX.md](../mng/docs/INDEX.md) | Plain Laravel 관리자 패널 (운영 주력) | -| **React** | [react/docs/[INDEX] DOCUMENTATION-MAP.md](../react/docs/[INDEX]%20DOCUMENTATION-MAP.md) | Next.js 프론트엔드 | - ---- - -## 💡 사용 팁 - -### Claude Code 작업 패턴 - -| 작업 | 참고 문서 | -|------|----------| -| **API 개발** | `reference/api-rules.md` + `CLAUDE.md` | -| **DB 스키마 확인** | `specs/database-schema.md` | -| **품질 검증** | `reference/quality-checklist.md` | -| **과거 분석 검토** | `history/2025-11/item-master-gap-analysis.md` | -| **Swagger 작성** | `guides/swagger-guide.md` + `api/docs/swagger/` | -| **MES 개발** | `projects/mes/README.md` | - -### 문서 네이밍 규칙 -- **소문자 + 하이픈** (kebab-case): `api-rules.md` -- **날짜 포함** (히스토리): `2025-11-20-item-master-spec.md` -- **버전 표기**: `item-db-analysis-v3.md` +| **MNG** | [mng/docs/INDEX.md](../mng/docs/INDEX.md) | Plain Laravel 관리자 (운영 주력) | +| **Admin** | [admin/docs/INDEX.md](../admin/docs/INDEX.md) | Filament 관리자 (deprecated) | +| **React** | [react/docs/](../react/docs/) | Next.js 프론트엔드 | --- ## 📝 문서 작성 가이드 -새 문서를 작성할 때: -1. **크기 목표**: 10KB 이하 (Claude Code 빠른 로딩) -2. **명확한 제목**: 내용을 정확히 반영 -3. **적절한 위치**: reference/specs/history/guides/projects 중 선택 -4. **INDEX 업데이트**: 새 문서는 반드시 INDEX.md에 추가 +### 새 문서 작성 시 +1. **적절한 폴더 선택**: 위 폴더 구조 참고 +2. **파일명**: 소문자 + 하이픈 (kebab-case) +3. **크기 목표**: 10KB 이하 +4. **INDEX 업데이트**: 새 문서는 반드시 이 파일에 추가 + +### 폴더 선택 기준 +- **"어떻게 코드 작성?"** → `standards/` +- **"왜 이렇게 설계?"** → `architecture/` +- **"무엇이 유효한 데이터?"** → `rules/` +- **"무엇을 구현?"** → `specs/` +- **"어떻게 구현?"** → `guides/` --- ## 🔄 문서 구조 변경 이력 -- **2025-12-05**: 규칙 및 원칙 문서 체계 추가 - - standards/ - 코딩 규칙 (네이밍, 스타일) - - rules/ - 비즈니스 규칙 (검증, 도메인 로직) - - principles/ - 설계 원칙 (아키텍처, API 설계) +- **2025-12-05**: 폴더 구조 대폭 재정리 + - `reference/` → `standards/`, `architecture/`, `quickstart/`로 분리 + - `principles/` → `architecture/`로 통합 + - 작업별 필수 문서 가이드 추가 - **2025-11-20**: 문서 구조 대규모 재정리 - - .cursor/docs 삭제 - claudedocs → docs/ 체계화 - - Reference/Specs/History/Guides/Projects 분류 - - 각 서브프로젝트별 docs/ 디렉토리 생성 + - 각 서브프로젝트별 docs/ 디렉토리 생성 \ No newline at end of file diff --git a/architecture/README.md b/architecture/README.md new file mode 100644 index 0000000..e6eec46 --- /dev/null +++ b/architecture/README.md @@ -0,0 +1,20 @@ +# Architecture (아키텍처 & 설계 원칙) + +> 시스템 설계와 아키텍처 결정의 근간 - **"왜 이렇게 설계하는가"** + +## 목적 +- 일관된 아키텍처 결정 기준 제공 +- 기술 부채 방지 +- 확장성과 유지보수성 확보 + +## 문서 목록 + +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [system-overview.md](system-overview.md) | 전체 시스템 아키텍처 | 새 기능 설계 전 | +| [security-policy.md](security-policy.md) | 인증/인가, 보안 규칙 | 보안 관련 작업 전 | + +## 관련 폴더 +- [standards/](../standards/) - 개발 표준 (어떻게 코드를 작성할 것인가) +- [rules/](../rules/) - 비즈니스 규칙 (무엇이 유효한 데이터인가) +- [specs/](../specs/) - 기술 스펙 (무엇을 구현할 것인가) \ No newline at end of file diff --git a/specs/security-policy.md b/architecture/security-policy.md similarity index 100% rename from specs/security-policy.md rename to architecture/security-policy.md diff --git a/reference/architecture.md b/architecture/system-overview.md similarity index 100% rename from reference/architecture.md rename to architecture/system-overview.md diff --git a/principles/README.md b/principles/README.md deleted file mode 100644 index 7751091..0000000 --- a/principles/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Principles (설계 원칙) - -> 시스템 설계와 아키텍처 결정의 근간이 되는 원칙 - -## 목적 -- 일관된 아키텍처 결정 기준 제공 -- 기술 부채 방지 -- 확장성과 유지보수성 확보 - -## 포함 내용 -- 아키텍처 원칙 (Service-First, Multi-tenancy) -- API 설계 원칙 (RESTful, 버전 관리) -- 데이터베이스 설계 원칙 -- 보안 설계 원칙 -- 성능 최적화 원칙 - -## 문서 목록 -| 문서 | 설명 | -|------|------| -| *(작성 예정)* | | - -## 관련 문서 -- [시스템 아키텍처](../reference/architecture.md) - 전체 시스템 구조 -- [API 개발 규칙](../reference/api-rules.md) - API 설계 표준 \ No newline at end of file diff --git a/reference/dev-commands.md b/quickstart/dev-commands.md similarity index 100% rename from reference/dev-commands.md rename to quickstart/dev-commands.md diff --git a/reference/quick-start.md b/quickstart/quick-start.md similarity index 100% rename from reference/quick-start.md rename to quickstart/quick-start.md diff --git a/rules/README.md b/rules/README.md index d5f7af2..fc85d96 100644 --- a/rules/README.md +++ b/rules/README.md @@ -1,6 +1,6 @@ # Rules (비즈니스 규칙) -> 도메인 로직과 비즈니스 요구사항에서 파생된 규칙 +> 도메인 로직에서 파생된 규칙 - **"무엇이 유효한 데이터/상태인가"** ## 목적 - 비즈니스 로직의 명확한 문서화 @@ -15,10 +15,12 @@ - 데이터 무결성 규칙 ## 문서 목록 + | 문서 | 설명 | |------|------| | *(작성 예정)* | | -## 관련 문서 -- [품목기준관리 스펙](../specs/item-master-integration.md) - 품목 관리 명세 -- [보안 정책](../specs/security-policy.md) - 보안 관련 규칙 \ No newline at end of file +## 관련 폴더 +- [standards/](../standards/) - 개발 표준 (어떻게 코드를 작성할 것인가) +- [architecture/](../architecture/) - 설계 원칙 (왜 이렇게 설계하는가) +- [specs/](../specs/) - 기술 스펙 (무엇을 구현할 것인가) \ No newline at end of file diff --git a/standards/README.md b/standards/README.md index 1bd9880..3b1dc13 100644 --- a/standards/README.md +++ b/standards/README.md @@ -1,23 +1,20 @@ -# Standards (코딩 규칙) +# Standards (개발 표준) -> 개발 시 준수해야 할 코딩 컨벤션과 스타일 가이드 +> 코드 작성 방법에 대한 규칙 - **"어떻게 코드를 작성할 것인가"** ## 목적 - 일관된 코드 스타일 유지 - 팀 간 협업 효율성 향상 - 코드 리뷰 기준 명확화 -## 포함 내용 -- 네이밍 컨벤션 (변수, 함수, 클래스, 파일) -- 코드 스타일 (들여쓰기, 주석, 포맷팅) -- 디렉토리 구조 규칙 -- 테스트 작성 규칙 - ## 문서 목록 -| 문서 | 설명 | -|------|------| -| *(작성 예정)* | | -## 관련 문서 -- [API 개발 규칙](../reference/api-rules.md) - API 개발 표준 -- [Git 규칙](../reference/git-conventions.md) - 커밋 메시지, 브랜치 전략 \ No newline at end of file +| 문서 | 설명 | 필수 확인 시점 | +|------|------|--------------| +| [api-rules.md](api-rules.md) | API 개발 규칙 (Service-First, FormRequest, i18n) | API 개발 전 | +| [git-conventions.md](git-conventions.md) | Git 커밋 메시지, 브랜치 전략 | 커밋 전 | +| [quality-checklist.md](quality-checklist.md) | 코드 품질 체크리스트 | PR 전 | + +## 관련 폴더 +- [architecture/](../architecture/) - 설계 원칙 (왜 이렇게 설계하는가) +- [rules/](../rules/) - 비즈니스 규칙 (무엇이 유효한 데이터인가) \ No newline at end of file diff --git a/reference/api-rules.md b/standards/api-rules.md similarity index 100% rename from reference/api-rules.md rename to standards/api-rules.md diff --git a/reference/git-conventions.md b/standards/git-conventions.md similarity index 100% rename from reference/git-conventions.md rename to standards/git-conventions.md diff --git a/reference/quality-checklist.md b/standards/quality-checklist.md similarity index 100% rename from reference/quality-checklist.md rename to standards/quality-checklist.md