sam-docs/INDEX.md

SAM 프로젝트 문서 인덱스

Claude Code 작업 전 필수 확인 — 작업 유형에 맞는 문서를 먼저 읽고 시작하세요. 최종 갱신: 2026-02-27

---

🎯 작업별 필수 문서

작업 유형	필수 문서	용도
API 개발	standards/api-rules.md	Service-First, FormRequest, i18n 규칙
DB 변경	system/database/README.md	테이블 구조, 관계, 컬럼 규칙
새 기능 구현	system/overview.md	전체 아키텍처 이해
보안 관련	system/security-policy.md	인증/인가, 보안 규칙
Git 커밋	standards/git-conventions.md	커밋 메시지, 브랜치 전략
품질 검증	standards/quality-checklist.md	코드 품질 체크리스트
Swagger 작성	guides/swagger-guide.md	API 문서 작성 방법
품목관리	rules/item-policy.md	품목 정책 (유형, 예약어, API 규칙)
단가관리	rules/pricing-policy.md	원가/판매가 계산, 리비전 관리
견적관리	features/quotes/README.md	견적 시스템, BOM 계산, 10단계 로직
운영 배포	plans/production-deployment-plan.md	운영 환경 배포 계획
서버 운영	deploys/ops-manual/README.md	서버 운영 매뉴얼
MES 개발	projects/mes/README.md	MES 프로젝트 개요

---

📁 폴더 구조

docs/
├── system/            # 시스템 현황 — 아키텍처, DB 스키마, 인프라 (architecture/ + specs/ 통합)
├── standards/         # 개발 표준 — "어떻게 코드를 작성할 것인가"
├── rules/             # 비즈니스 규칙 — "무엇이 유효한 데이터인가"
├── features/          # 기능별 상세 — 도메인별 기능 문서
├── guides/            # 구현 가이드 — "어떻게 구현할 것인가"
├── quickstart/        # 빠른 시작 — 핵심 요약, 명령어
├── plans/             # 작업 추적 — 예정 → 진행 → 완료 → archive/
├── projects/          # 프로젝트 자료 — 프로젝트성 분석, 설계, 참고
├── deploys/           # 운영 매뉴얼 — 서버 운영, 배포
├── changes/           # 변경 이력
├── data/              # 데이터 분석
├── history/           # 히스토리 기록
├── api/               # API 통합 문서
├── requests/          # 요청/기획 문서
└── assets/            # BI 등 정적 자산

---

📚 폴더별 문서 목록

system/ — 시스템 현황

아키텍처, DB 스키마, 기술 스펙, 인프라 (기존 architecture/ + specs/ 통합)

문서	설명
overview.md	전체 시스템 아키텍처 (api/react/mng 구조, 기술 스택)
api-structure.md	API 서버 구조 (~1,027 엔드포인트, 18 도메인)
react-structure.md	React 프론트엔드 구조 (249 페이지, 612 컴포넌트)
mng-structure.md	MNG 관리자 패널 구조 (171 컨트롤러, 436 뷰)
docker-setup.md	Docker 환경 + CI/CD (7 서비스, Jenkins)
database/README.md	DB 스키마 인덱스 (220 모델, 32 도메인, 459 마이그레이션)

DB 도메인별 스키마:

문서	포함 도메인
database/tenants.md	테넌트, 사용자, 권한 (63 모델)
database/products.md	제품, 품목, 설계 (21 모델)
database/sales.md	영업, 수주, 견적 (18 모델)
database/production.md	생산, 시공, 자재, 품질 (20 모델)
database/finance.md	재무, 회계
database/hr.md	인사, 면접
database/documents.md	문서, 전자서명 (19 모델)
database/commons.md	공통, 게시판, 감사 (17 모델)
database/stats.md	통계 (21 모델, sam_stat DB)

이관 완료 (architecture/ + specs/ → system/):

문서	설명
security-policy.md	보안 정책 (다층 방어, Sanctum, RBAC)
scaling-roadmap.md	10K 테넌트 스케일링 로드맵
board-system-spec.md	게시판 시스템 설계 스펙
item-master-integration.md	품목 마스터 통합 설계
remote-work-setup.md	원격 개발 설정 (DEPRECATED)
erp-analysis/	ERP 스토리보드 분석 (9개 파일)

---

standards/ — 개발 표준

코딩 컨벤션, 스타일 가이드, 품질 기준

문서	설명	필수 확인 시점
api-rules.md	API 개발 규칙 (Service-First, FormRequest, i18n)	API 개발 전
git-conventions.md	Git 커밋 메시지, 브랜치 전략	커밋 전
quality-checklist.md	코드 품질 체크리스트	PR 전
pagination-policy.md	페이지네이션 표준	목록 API 구현 시
options-column-policy.md	JSON options 컬럼 표준 정책 (마이그레이션, 모델, 쿼리)	테이블 생성/확장 시

---

rules/ — 비즈니스 규칙

도메인 로직, 검증 규칙, 정책

문서	설명	필수 확인 시점
README.md	비즈니스 규칙 개요	도메인 로직 구현 전
item-policy.md	품목 정책 (유형, 예약어, API 규칙)	품목 관련 작업 전
pricing-policy.md	단가 정책 (원가/판매가, 리비전)	단가 관련 작업 전
customer-pricing.md	고객 안내용 서비스 요금표	고객 요금 안내 시
partner-commission.md	영업파트너 수당 체계 및 정산	수당/정산 관련 작업 전
billing-policy.md	내부용 원가/마진/코드참조 (CONFIDENTIAL)	과금 코드 개발 전
client-policy.md	고객사 관리 정책	고객 관련 작업 전
attendance-api.md	근태 API 규칙	근태 관련 작업 전
department-tree-api.md	부서 트리 API 규칙	부서 관련 작업 전
employee-api.md	직원 API 규칙	직원 관련 작업 전
numbering-rules.md	채번규칙 (패턴 기반 자동 번호 생성)	채번 로직 수정 전

---

features/ — 기능별 문서

도메인별 기능 상세 (기능 설명 + 엔드포인트 경로 + Swagger 참조)

문서	설명
quotes/README.md	견적 시스템 (BOM 계산, 10단계 로직)
boards/README.md	게시판 시스템 구현
boards/mng-implementation.md	MNG 게시판 구현 상세
hr/attendance-management-spec.md	근태관리 기획서
hr/hr-api-analysis.md	HR API 분석 (근태/직원/부서)
barobill-kakaotalk/README.md	바로빌 카카오톡 + 세금계산서 연동
business-card-request.md	명함신청 관리 (DB 마이그레이션만 존재, 문서 미작성)
sales/README.md	영업 관리 (면접 시나리오 포함)
crm/README.md	CRM (거래처, 미수금, 미지급금)
finance/README.md	재무 관리 (14개 하위 문서)
card-vehicle/README.md	법인카드·차량 관리
settlement/README.md	정산 관리
esign/README.md	전자서명 (계약·OTP·PDF 합성)
documents/README.md	문서관리 (EAV 기반 서식·결재)
ai/README.md	AI 분석 리포트 (Gemini 연동)
equipment/README.md	설비관리 (MNG 전용)

---

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 가이드	서버 이해 시
php-fpm-guide.md	PHP-FPM 가이드	서버 이해 시
jenkins-setup-guide.md	Jenkins CI/CD 셋업	Jenkins 설치/설정 시
auto-login-guide.md	MNG→DEV 자동 로그인	자동 로그인 구현 시
erp-api-list.md	ERP API 목록 (List vs Detail 구분)	프론트 API 연동 시
erp-api-detail.md	ERP API 상세 스펙	프론트 API 연동 시
item-master-guide.md	품목기준관리 페이지-섹션-필드 구조	품목 UI 구현 시
item-master-items-api.md	ItemMaster & Items API 문서	품목 API 연동 시

---

quickstart/ — 빠른 시작

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

문서	설명
quick-start.md	프로젝트 핵심 규칙 요약
dev-commands.md	일상 개발 명령어 모음

---

plans/ — 작업 추적

예정 → 진행 → 완료 → archive/ (이미 정리 완료, 현행 유지)

문서	설명
index_plans.md	계획 인덱스 (ACTIVE + PLANNED)
GUIDE.md	계획 문서 작성 가이드

---

projects/ — 프로젝트 자료

프로젝트성 분석, 설계, 참고 자료 (지속 보관)

프로젝트	문서	설명
index_projects.md	프로젝트 인덱스
MES	README.md	MES 프로젝트 개요
MES	MES_PROJECT_ROADMAP.md	개발 로드맵
5130 이관	MASTER_PLAN.md	레거시 이관 마스터 플랜
API 연동	MASTER_PLAN.md	React↔API 연동
Legacy	draw-module.md	레거시 드로우 모듈
견적	quotation/	견적 프로젝트 자료
전자서명	e-sign/	전자서명 프로젝트 자료

---

deploys/ — 운영 매뉴얼

서버 운영, 배포 (현행 유지)

문서	설명
ops-manual/README.md	서버 운영 매뉴얼 (11부 구성)

---

changes/ — 변경 이력

파일명 형식: YYYYMMDD_description.md

---

data/ — 데이터 분석

문서	설명
analysis/item-db-analysis.md	Item DB/API 분석 최종본
analysis/bom-item-mapping-analysis.md	BOM-품목 매핑 분석

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, 서버 아키텍처)
attendance-management-plan.md	근태현황 개발 계획 (Phase 1~2, HTMX 기반)
leave-management-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/	REST API 프로젝트
MNG	mng/docs/	Plain Laravel 관리자
React	react/docs/	Next.js 프론트엔드

---

📝 문서 작성 규칙

폴더 선택 기준

질문	폴더
"시스템이 현재 어떤 상태인가?"	system/
"어떻게 코드를 작성할 것인가?"	standards/
"무엇이 유효한 데이터인가?"	rules/
"이 기능은 어떻게 동작하는가?"	features/
"어떻게 구현할 것인가?"	guides/
"무슨 작업을 할 것인가?"	plans/
"프로젝트 자료를 보관하고 싶다"	projects/
"무엇이 변경되었는가?"	changes/

파일명 규칙

유형	규칙	예시
기술 문서 (코드 참조)	영문 kebab-case	api-rules.md, database-schema.md
업무/비즈니스 문서	한글 허용	영업파트너가이드북.md, 수당지급.md
변경 이력	YYYYMMDD_description.md	20260205_sus_inspection_template.md
폴더 인덱스	README.md (대문자)	features/finance/README.md
혼용 금지	한글+영문 섞지 않음	❌ 영업partner가이드.md

크기 제한

• 목표: 10KB 이하
• 초과 시 도메인별로 분할

문서 구조 템플릿

정책/규칙 문서 (rules/, standards/)

# 제목

> **작성일**: YYYY-MM-DD
> **상태**: 설계 확정

---

## 1. 개요
## 2. 핵심 원칙
## 3. 상세 규칙
## 4. API 엔드포인트 (해당 시)
## 관련 문서

---

**최종 업데이트**: YYYY-MM-DD

변경 이력 문서 (changes/)

# 변경 내용 요약

**날짜:** YYYY-MM-DD

## 변경 개요
## 수정된 파일
## 상세 변경 사항
## 테스트 체크리스트

작성 스타일

항목	규칙
언어	한글 기본, 코드/경로/기술 식별자만 영어
어조	서술형 ("X 한다")
경고	> **경고: ...** 블록인용
금지/필수	❌ 금지, ✅ 필수
우선순위	🔴 필수, 🟡 중요, 🟢 권장
코드 블록	반드시 언어 지정 (php, bash 등)
인라인 코드	파일 경로, 메서드명, 변수명에 백틱
구분선	--- 주요 섹션 사이

새 문서 작성 시 체크리스트

• 적절한 폴더에 배치
• 파일명 규칙 준수
• 문서 구조 템플릿 준수
• 이 INDEX.md에 등록

---

🔄 문서 정비 진행 현황

참조: docs-comprehensive-update-plan.md

Phase	작업	상태
Phase 0	문서 정책 재정립	✅ 완료
Phase 1	시스템 현황 문서화 (DB, API, React, MNG, Docker)	✅ 완료 (14개 문서)
Phase 2	기존 문서 정비 (architecture/+specs/ → system/ 이관)	⏳ 대기
Phase 3	신규 도메인 기능 문서 작성	⏳ 대기
Phase 4	최종 검증 및 INDEX 갱신	⏳ 대기