sam-docs/INDEX.md

# SAM 프로젝트 문서 네비게이션

> 📌 **Claude Code를 위한 문서 허브** - 작업별로 필요한 문서를 빠르게 찾아 컨텍스트에 추가하세요.

---

## 🚀 빠른 시작

| 문서 | 용도 | 크기 |
|------|------|------|
| [Quick Start Guide](reference/quick-start.md) | 프로젝트 핵심 규칙 요약 | 5KB |
| [개발 환경 설정](specs/docker-setup.md) | Docker 환경 구축 | 7KB |
| [개발 명령어](reference/dev-commands.md) | 일상 개발 명령어 | 4KB |

---

## 📐 규칙 및 원칙

개발 시 참고해야 할 규칙과 원칙 문서입니다.

| 규칙 유형 | 폴더 | 용도 | 예시 |
|----------|------|------|------|
| **코딩 규칙** | [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)

---

## 📖 개발 가이드

### Reference (일상 참고 문서)
현재 작업에 필요한 참고 문서입니다.

- **[API 개발 규칙](reference/api-rules.md)** - Service-First, FormRequest, i18n 규칙
- **[품질 체크리스트](reference/quality-checklist.md)** - 코드 품질 검증 항목
- **[Git 규칙](reference/git-conventions.md)** - 커밋 메시지, 브랜치 전략
- **[시스템 아키텍처](reference/architecture.md)** - SAM 프로젝트 구조 개요

### Specs (환경/스펙 문서)
시스템 스펙과 환경 설정 문서입니다.

- **[데이터베이스 스키마](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)** - 원격 개발 설정

### Features (기능별 문서)
특정 기능의 상세 문서입니다.

- **[게시판 시스템](features/boards/README.md)** - 시스템/테넌트 게시판 구현
  - [MNG 구현 상세](features/boards/mng-implementation.md)

### Guides (구현 가이드)
특정 기능 구현을 위한 매뉴얼입니다.

- **[파일 스토리지 구현](guides/file-storage-guide.md)** - 파일 업로드/다운로드 구현
- **[Swagger 문서화](guides/swagger-guide.md)** - API 문서 작성 방법
- **[Item 관리 마이그레이션](guides/item-management-migration.md)** - Item 시스템 전환 가이드
- **[프로젝트 런칭 로드맵](guides/project-launch-roadmap.md)** - 런칭 준비 현황 및 방향성

### Frontend (프론트엔드 공유 문서)
프론트엔드 개발을 위한 API 연동 가이드입니다.

- **[품목기준관리(ItemMaster) 가이드](front/item-master-guide.md)** - 페이지-섹션-필드 구조, 잠금 기능, API 연동

---

## 📁 프로젝트별 문서

### MES 프로젝트
- **[MES README](projects/mes/README.md)** - MES 프로젝트 개요
- **[MES Roadmap](projects/mes/MES_PROJECT_ROADMAP.md)** - 개발 로드맵
- **[Phase 0 Baseline](projects/mes/00_baseline/)** - 초기 분석 문서

### Legacy 5130
- **[Draw Module](projects/legacy-5130/draw-module.md)** - 레거시 드로우 모듈

---

## 📚 히스토리

### 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 스펙

### 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)** - 산출식 시스템 분석

### Roadmaps
- **[December 2025 Roadmap](history/roadmaps/december-2025.md)** - 12월 개발 계획

---

## 🏗️ 서브프로젝트 문서

각 서브프로젝트는 독립적인 `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`

---

## 📝 문서 작성 가이드

새 문서를 작성할 때:
1. **크기 목표**: 10KB 이하 (Claude Code 빠른 로딩)
2. **명확한 제목**: 내용을 정확히 반영
3. **적절한 위치**: reference/specs/history/guides/projects 중 선택
4. **INDEX 업데이트**: 새 문서는 반드시 INDEX.md에 추가

---

## 🔄 문서 구조 변경 이력

- **2025-12-05**: 규칙 및 원칙 문서 체계 추가
  - standards/ - 코딩 규칙 (네이밍, 스타일)
  - rules/ - 비즈니스 규칙 (검증, 도메인 로직)
  - principles/ - 설계 원칙 (아키텍처, API 설계)

- **2025-11-20**: 문서 구조 대규모 재정리
  - .cursor/docs 삭제
  - claudedocs → docs/ 체계화
  - Reference/Specs/History/Guides/Projects 분류
  - 각 서브프로젝트별 docs/ 디렉토리 생성