# SAM 프로젝트 문서 인덱스

> **Claude Code 작업 전 필수 확인** - 작업 유형에 맞는 문서를 먼저 읽고 시작하세요.

---

## 🎯 작업별 필수 문서 (반드시 먼저 확인)

| 작업 유형 | 필수 문서 | 용도 |
|----------|----------|------|
| **TODO 확인** | `TODO.md` | 긴급/중요 이슈 및 개선사항 추적 |
| **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 문서 작성 방법 |
| **품목관리** | `rules/item-policy.md` | 품목 정책 (유형, 예약어, API 규칙) |
| **게시판** | `specs/board-system-spec.md` | 게시판 시스템 설계 |
| **단가관리** | `rules/pricing-policy.md` | 원가/판매가 계산, 리비전 관리 |
| **운영 배포** | `plans/production-deployment-plan.md` | 운영 환경 배포 계획 (CI/CD, 서버 아키텍처) |
| **서버 동작 원리** | `guides/server-how-it-works.md` | 요청 흐름, 배포 원리 이해 |
| **과금정책 (고객용)** | `rules/customer-pricing.md` | 고객 안내용 서비스 요금표 |
| **과금정책 (파트너)** | `rules/partner-commission.md` | 영업파트너 수당 체계 및 정산 |
| **과금정책 (내부용)** | `rules/billing-policy.md` | 내부용 원가/마진/코드참조 (CONFIDENTIAL) |
| **견적관리** | `features/quotes/README.md` | 견적 시스템, BOM 계산, 10단계 로직 |
| **MES 개발** | `projects/mes/README.md` | MES 프로젝트 개요 |

---

## 📁 폴더 구조

```
docs/
├── plans/          # 🆕 개발 계획 - 임시 (작업 완료 후 정리 → 삭제)
├── standards/      # 개발 표준 - "어떻게 코드를 작성할 것인가"
├── architecture/   # 아키텍처 - "왜 이렇게 설계하는가"
├── rules/          # 비즈니스 규칙 - "무엇이 유효한 데이터인가"
├── specs/          # 기술 스펙 - "무엇을 구현할 것인가"
├── guides/         # 구현 가이드 - "어떻게 구현할 것인가"
├── quickstart/     # 빠른 시작 - 핵심 요약
├── front/          # 프론트엔드 공유 문서
├── features/       # 기능별 상세 문서
├── projects/       # 프로젝트별 문서 (MES, Legacy)
├── history/        # 히스토리 및 로드맵
├── contracts/      # 전자계약서 버전 관리
├── changes/        # 변경 이력
└── data/           # 데이터 분석
```

---

## 📚 폴더별 문서 목록

### standards/ - 개발 표준
> 코딩 컨벤션, 스타일 가이드, 품질 기준

| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [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 전 |

### architecture/ - 아키텍처 & 설계 원칙
> 시스템 설계, 보안 정책, 아키텍처 결정

| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [system-overview.md](architecture/system-overview.md) | 전체 시스템 아키텍처 | 새 기능 설계 전 |
| [security-policy.md](architecture/security-policy.md) | 인증/인가, 보안 규칙 | 보안 관련 작업 전 |
| [scaling-roadmap-10k-tenants.md](architecture/scaling-roadmap-10k-tenants.md) | 10,000 테넌트 스케일링 로드맵 | 확장 전략 검토 시 |

### rules/ - 비즈니스 규칙
> 도메인 로직, 검증 규칙, 상태 전이

| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [README.md](rules/README.md) | 비즈니스 규칙 개요 | 도메인 로직 구현 전 |
| [item-policy.md](rules/item-policy.md) | 품목 정책 (유형 체계, 예약어, API 규칙) | 품목 관련 작업 전 |
| [pricing-policy.md](rules/pricing-policy.md) | 단가 정책 (원가/판매가 계산, 리비전 관리) | 단가 관련 작업 전 |
| [customer-pricing.md](rules/customer-pricing.md) | 고객 안내용 서비스 요금표 | 고객 요금 안내 시 |
| [partner-commission.md](rules/partner-commission.md) | 영업파트너 수당 체계 및 정산 | 수당/정산 관련 작업 전 |
| [billing-policy.md](rules/billing-policy.md) | 내부용 원가/마진/코드참조 (CONFIDENTIAL) | 과금 코드 개발 전 |

### specs/ - 기술 스펙
> 구현 명세, DB 스키마, 시스템 설정

| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [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) | 원격 개발 설정 | 원격 작업 시 |

### guides/ - 구현 가이드
> 특정 기능 구현을 위한 단계별 매뉴얼

| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [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) | 런칭 준비 현황 | 런칭 관련 작업 시 |
| [production-env-sync.md](guides/production-env-sync.md) | 운영 전환 시 .env 동기화 절차 | 테스트→운영 전환 시 |
| [server-how-it-works.md](guides/server-how-it-works.md) | 서버 인프라 시리즈 ① 서버 동작 원리 | 신규 합류 시 |
| [nginx-fastcgi-guide.md](guides/nginx-fastcgi-guide.md) | 서버 인프라 시리즈 ② Nginx & FastCGI | Nginx/FastCGI 개념 이해 시 |
| [php-fpm-guide.md](guides/php-fpm-guide.md) | 서버 인프라 시리즈 ③ PHP-FPM | PHP-FPM 개념 이해 시 |
| [jenkins-setup-guide.md](guides/jenkins-setup-guide.md) | Jenkins CI/CD 셋업 가이드 | Jenkins 설치/설정 시 |

### quickstart/ - 빠른 시작
> 핵심 규칙 요약, 자주 쓰는 명령어

| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [quick-start.md](quickstart/quick-start.md) | 프로젝트 핵심 규칙 요약 | 세션 시작 시 |
| [dev-commands.md](quickstart/dev-commands.md) | 일상 개발 명령어 모음 | 명령어 확인 시 |

### front/ - 프론트엔드 공유 문서
> API 연동 가이드, 프론트엔드 스펙

| 문서 | 설명 |
|------|------|
| [item-master-guide.md](front/item-master-guide.md) | 품목기준관리 페이지-섹션-필드 구조 |

> 날짜별 API 요청 문서는 `history/2025-11/front-requests/`로 이동됨

### data/ - 데이터 분석
> 시스템 분석, 데이터 모델링

| 문서 | 설명 |
|------|------|
| [analysis/item-db-analysis.md](data/analysis/item-db-analysis.md) | Item DB/API 분석 최종본 |

### contracts/ - 전자계약서 버전 관리
> DOCX 배포본 + Markdown 추적본 + 자동화 스크립트

| 문서 | 설명 |
|------|------|
| [CHANGELOG.md](contracts/CHANGELOG.md) | 전체 개정이력 |
| [revisions.json](contracts/revisions.json) | 개정 데이터 |
| [docx/](contracts/docx/) | DOCX 배포본 (전자서명용 4종, 바로 사용 가능) |
| [markdown/](contracts/markdown/) | Markdown 추적본 (Git diff용 4종) |
| [scripts/extract_to_markdown.py](contracts/scripts/extract_to_markdown.py) | DOCX → Markdown 추출 |
| [scripts/sync_check.py](contracts/scripts/sync_check.py) | DOCX ↔ Markdown 동기화 검증 |

### plans/ - 개발 계획
> 임시 개발 계획 문서 (작업 완료 후 정리 → 삭제)

| 문서 | 설명 |
|------|------|
| [SAM_ERP_Storyboard_D1.4_260116.md](plans/SAM_ERP_Storyboard_D1.4_260116.md) | ERP 전체 스토리보드 D1.4 (167p PDF → 마크다운 변환, 14개 섹션 146개 화면) |
| [SAM_ERP_Storyboard_D1.4.md](plans/SAM_ERP_Storyboard_D1.4.md) | ERP 스토리보드 D1.4 AI 최적화 버전 (구조화된 한글 마크다운, 15개 섹션) |
| [SAM_ERP_회계관리_Storyboard_D1.6.md](plans/SAM_ERP_회계관리_Storyboard_D1.6.md) | ERP 회계관리 스토리보드 D1.6 (65p PDF → 마크다운 변환) |
| [SAM_General_Rule_Storyboard_D1.0.md](plans/SAM_General_Rule_Storyboard_D1.0.md) | General Rule 스토리보드 D1.0 (43p PDF → 마크다운 변환, UIUX 공통 규칙) |
| [production-deployment-plan.md](plans/production-deployment-plan.md) | 운영 환경 배포 계획 (CI/CD, 서버 아키텍처) |

### features/ - 기능별 문서

| 문서 | 설명 |
|------|------|
| [barobill-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 (알림톡/친구톡) 연동 |
| [boards/README.md](features/boards/README.md) | 게시판 시스템 구현 |
| [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 |
| [hr/hr-api-analysis.md](features/hr/hr-api-analysis.md) | HR API 분석 (근태/직원/부서) |
| [quotes/README.md](features/quotes/README.md) | 견적 시스템 분석 (BOM 계산, 10단계 로직) |
| [academy/fire-shutter-image-prompts.md](features/academy/fire-shutter-image-prompts.md) | 방화셔터 백과사전 이미지 생성 프롬프트 (Gemini용) |

### projects/ - 프로젝트별 문서

| 프로젝트 | 문서 | 설명 |
|---------|------|------|
| **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) | 레거시 드로우 모듈 |

### 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), [front-requests/](history/2025-11/front-requests/), [item-master-archived/](history/2025-11/item-master-archived/) |
| **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/` 디렉토리를 가집니다.

| 프로젝트 | 문서 경로 | 설명 |
|---------|----------|------|
| **API** | [api/docs/INDEX.md](../api/docs/INDEX.md) | REST API 프로젝트 |
| **MNG** | [mng/docs/INDEX.md](../mng/docs/INDEX.md) | Plain Laravel 관리자 (운영 주력) |
| **React** | [react/docs/](../react/docs/) | Next.js 프론트엔드 |

---

## 📝 문서 작성 가이드

### 새 문서 작성 시
1. **적절한 폴더 선택**: 위 폴더 구조 참고
2. **파일명**: 소문자 + 하이픈 (kebab-case)
3. **크기 목표**: 10KB 이하
4. **INDEX 업데이트**: 새 문서는 반드시 이 파일에 추가

### 폴더 선택 기준
- **"개발 계획/작업 예정"** → `plans/` (임시, 완료 후 삭제)
- **"어떻게 코드 작성?"** → `standards/`
- **"왜 이렇게 설계?"** → `architecture/`
- **"무엇이 유효한 데이터?"** → `rules/`
- **"무엇을 구현?"** → `specs/`
- **"어떻게 구현?"** → `guides/`

### plans/ 워크플로우
1. 개발 계획 문서를 `plans/`에 작성
2. 작업 진행
3. 완료 후 결과물을 해당 프로젝트 docs에 정리
4. plan 문서 삭제

### plans/flow-tests/
API Flow Tester에서 생성되는 JSON 파일 저장 경로
- 경로: `plans/flow-tests/*.json`
- 용도: MNG API Flow Tester 테스트 시나리오
- 예시: `item-master-page-api-flow.json`, `client-api-flow.json`

---

## 🔄 문서 구조 변경 이력

- **2026-01-28**: API 라우터 분리 및 버전 폴백 시스템 구현
  - `routes/api.php` → 13개 도메인별 파일로 분리 (1,479줄 → 61줄)
  - `ApiVersionMiddleware` 추가 (헤더/쿼리 기반 버전 선택, v2→v1 폴백)
  - `standards/api-rules.md` 라우팅 섹션 업데이트
  - `architecture/system-overview.md` 라우팅 구조 업데이트

- **2025-12-09**: 품목 정책 통합 문서 생성
  - `rules/item-policy.md` 생성 (4개 문서 통합)
  - 삭제: `specs/ITEM-MASTER-INDEX.md`, `specs/item-master-field-key-validation.md`, `specs/item-master-field-integration.md`, `plans/items-api-unified-plan.md`
  - 품목 관련 정책을 rules/ 디렉토리로 이동

- **2025-12-09**: Item Master 문서 정리 및 인덱스 생성
  - `specs/ITEM-MASTER-INDEX.md` 생성 (개발 현황/필요 항목 정리)
  - `history/2025-11/item-master-archived/` 생성 (구버전 문서 아카이브)
  - 중복 문서 정리 (front-requests → history 이동)

- **2025-12-09**: 문서 정리 및 통합
  - 중복 분석 문서 삭제 (v2, DB_Modeling)
  - `SAM_Item_DB_API_Analysis_v3_FINAL.md` → `item-db-analysis.md` 리네임
  - `ITEM_MASTER_FIELD_INTEGRATION_PLAN.md` → `item-master-field-integration.md` 리네임
  - `HR_API_ANALYSIS.md` → `features/hr/hr-api-analysis.md` 이동
  - 날짜 접두사 front 문서 → `history/2025-11/front-requests/` 이동
  - api/docs에서 프로젝트 문서 분리 (swagger, api-flows만 유지)

- **2025-12-09**: api/docs 문서 통합
  - `api/docs/analysis/` → `docs/data/analysis/` 이동
  - `api/docs/front/` → `docs/front/` 병합
  - `api/docs/specs/` → `docs/specs/` 병합
  - api/docs에는 API 구성/설정 문서만 유지 (swagger, api-flows)

- **2025-12-09**: `plans/` 폴더 추가
  - 개발 계획 문서용 임시 폴더
  - 작업 완료 후 정리 → 삭제 워크플로우

- **2025-12-05**: 폴더 구조 대폭 재정리
  - `reference/` → `standards/`, `architecture/`, `quickstart/`로 분리
  - `principles/` → `architecture/`로 통합
  - 작업별 필수 문서 가이드 추가

- **2025-11-20**: 문서 구조 대규모 재정리
  - claudedocs → docs/ 체계화
  - 각 서브프로젝트별 docs/ 디렉토리 생성