sam-docs/INDEX.md

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	API 개발 규칙 (Service-First, FormRequest, i18n)	API 개발 전
git-conventions.md	Git 커밋 메시지, 브랜치 전략	커밋 전
quality-checklist.md	코드 품질 체크리스트	PR 전

architecture/ - 아키텍처 & 설계 원칙

시스템 설계, 보안 정책, 아키텍처 결정

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

rules/ - 비즈니스 규칙

도메인 로직, 검증 규칙, 상태 전이

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

specs/ - 기술 스펙

구현 명세, DB 스키마, 시스템 설정

문서	설명	필수 확인 시점
database-schema.md	DB 구조 및 관계도	DB 변경 전
board-system-spec.md	게시판 시스템 설계	게시판 작업 전
item-master-integration.md	품목관리 연동 설계	품목 연동 구현 시
docker-setup.md	Docker 환경 구성	환경 설정 시
remote-work-setup.md	원격 개발 설정	원격 작업 시

guides/ - 구현 가이드

특정 기능 구현을 위한 단계별 매뉴얼

문서	설명	필수 확인 시점
swagger-guide.md	Swagger API 문서 작성법	API 문서 작성 전
file-storage-guide.md	파일 업로드/다운로드 구현	파일 기능 구현 전
item-management-migration.md	Item 시스템 전환 가이드	마이그레이션 작업 전
project-launch-roadmap.md	런칭 준비 현황	런칭 관련 작업 시
production-env-sync.md	운영 전환 시 .env 동기화 절차	테스트→운영 전환 시
server-how-it-works.md	서버 인프라 시리즈 ① 서버 동작 원리	신규 합류 시
nginx-fastcgi-guide.md	서버 인프라 시리즈 ② Nginx & FastCGI	Nginx/FastCGI 개념 이해 시
php-fpm-guide.md	서버 인프라 시리즈 ③ PHP-FPM	PHP-FPM 개념 이해 시
jenkins-setup-guide.md	Jenkins CI/CD 셋업 가이드	Jenkins 설치/설정 시

quickstart/ - 빠른 시작

핵심 규칙 요약, 자주 쓰는 명령어

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

front/ - 프론트엔드 공유 문서

API 연동 가이드, 프론트엔드 스펙

문서	설명
item-master-guide.md	품목기준관리 페이지-섹션-필드 구조

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

data/ - 데이터 분석

시스템 분석, 데이터 모델링

문서	설명
analysis/item-db-analysis.md	Item DB/API 분석 최종본

contracts/ - 전자계약서 버전 관리

DOCX 배포본 + Markdown 추적본 + 자동화 스크립트

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

plans/ - 개발 계획

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

문서	설명
SAM_ERP_Storyboard_D1.4_260116.md	ERP 전체 스토리보드 D1.4 (167p PDF → 마크다운 변환, 14개 섹션 146개 화면)
SAM_ERP_Storyboard_D1.4.md	ERP 스토리보드 D1.4 AI 최적화 버전 (구조화된 한글 마크다운, 15개 섹션)
SAM_ERP_회계관리_Storyboard_D1.6.md	ERP 회계관리 스토리보드 D1.6 (65p PDF → 마크다운 변환)
SAM_General_Rule_Storyboard_D1.0.md	General Rule 스토리보드 D1.0 (43p PDF → 마크다운 변환, UIUX 공통 규칙)
production-deployment-plan.md	운영 환경 배포 계획 (CI/CD, 서버 아키텍처)
integrated-master-plan.md	통합 개선 계획 — 제품코드 추적성 + 검사 단위 구조 (마스터)
integrated-phase-0-1.md	통합 Phase 0-1: 사전 조사 + product_code 전파 수정
integrated-phase-2.md	통합 Phase 2: 절곡 검사 분석/설계 + 견적/품질 개선
integrated-phase-3.md	통합 Phase 3: 절곡 검사 동적 구현
integrated-test-scenarios.md	통합 계획 기능 단위 테스트 시나리오 (11개 FU)
product-code-traceability-plan.md	제품코드 추적성 계획 (아카이브 — 통합 계획 참조)
document-system-improvement-plan.md	검사 단위 구조 정비 계획 (아카이브 — 통합 계획 참조)

features/ - 기능별 문서

문서	설명
barobill-kakaotalk/README.md	바로빌 카카오톡 (알림톡/친구톡) 연동
boards/README.md	게시판 시스템 구현
boards/mng-implementation.md	MNG 게시판 구현 상세
hr/attendance-management-spec.md	근태관리 기획서 (화면/데이터/비즈니스규칙/API)
hr/hr-api-analysis.md	HR API 분석 (근태/직원/부서)
quotes/README.md	견적 시스템 분석 (BOM 계산, 10단계 로직)
business-card-request.md	명함신청 관리 (3단계 워크플로우: 요청→제작의뢰→처리완료)
academy/fire-shutter-image-prompts.md	방화셔터 백과사전 이미지 생성 프롬프트 (Gemini용)

projects/ - 프로젝트별 문서

프로젝트	문서	설명
MES	README.md	MES 프로젝트 개요
MES	MES_PROJECT_ROADMAP.md	개발 로드맵
Legacy	draw-module.md	레거시 드로우 모듈

history/ - 히스토리

기간	문서
2025-11	item-master-gap-analysis.md, item-master-spec.md, front-requests/, item-master-archived/
2025-09	checkpoint.md, database-schema.md
Roadmaps	december-2025.md

---

🏗️ 서브프로젝트 문서

각 서브프로젝트는 독립적인 docs/ 디렉토리를 가집니다.

프로젝트	문서 경로	설명
API	api/docs/INDEX.md	REST API 프로젝트
MNG	mng/docs/INDEX.md	Plain Laravel 관리자 (운영 주력)
React	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/ 디렉토리 생성