SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
be0eb83f4f1b363a00af04453d38fb0fe8558291
sam-docs/INDEX.md
김보곤 c2784e1fe7 docs: [standards] JSON options 컬럼 표준 정책 문서 작성 
- 컬럼 분류 기준 (전용 컬럼 vs options JSON)
- 마이그레이션/모델/서비스 표준 패턴
- 구현 수준 4단계 가이드 (L1~L4)
- MySQL JSON 경로 쿼리 패턴
- 체크리스트 포함
2026-02-27 22:10:26 +09:00

391 lines
19 KiB
Markdown
Raw Blame History

# 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](system/overview.md) | 전체 시스템 아키텍처 (api/react/mng 구조, 기술 스택) |
| [api-structure.md](system/api-structure.md) | API 서버 구조 (~1,027 엔드포인트, 18 도메인) |
| [react-structure.md](system/react-structure.md) | React 프론트엔드 구조 (249 페이지, 612 컴포넌트) |
| [mng-structure.md](system/mng-structure.md) | MNG 관리자 패널 구조 (171 컨트롤러, 436 뷰) |
| [docker-setup.md](system/docker-setup.md) | Docker 환경 + CI/CD (7 서비스, Jenkins) |
| [database/README.md](system/database/README.md) | DB 스키마 인덱스 (220 모델, 32 도메인, 459 마이그레이션) |
**DB 도메인별 스키마:**
| 문서 | 포함 도메인 |
|------|-----------|
| [database/tenants.md](system/database/tenants.md) | 테넌트, 사용자, 권한 (63 모델) |
| [database/products.md](system/database/products.md) | 제품, 품목, 설계 (21 모델) |
| [database/sales.md](system/database/sales.md) | 영업, 수주, 견적 (18 모델) |
| [database/production.md](system/database/production.md) | 생산, 시공, 자재, 품질 (20 모델) |
| [database/finance.md](system/database/finance.md) | 재무, 회계 |
| [database/hr.md](system/database/hr.md) | 인사, 면접 |
| [database/documents.md](system/database/documents.md) | 문서, 전자서명 (19 모델) |
| [database/commons.md](system/database/commons.md) | 공통, 게시판, 감사 (17 모델) |
| [database/stats.md](system/database/stats.md) | 통계 (21 모델, sam_stat DB) |
**이관 완료 (architecture/ + specs/ → system/):**
| 문서 | 설명 |
|------|------|
| [security-policy.md](system/security-policy.md) | 보안 정책 (다층 방어, Sanctum, RBAC) |
| [scaling-roadmap.md](system/scaling-roadmap.md) | 10K 테넌트 스케일링 로드맵 |
| [board-system-spec.md](system/board-system-spec.md) | 게시판 시스템 설계 스펙 |
| [item-master-integration.md](system/item-master-integration.md) | 품목 마스터 통합 설계 |
| [remote-work-setup.md](system/remote-work-setup.md) | 원격 개발 설정 (DEPRECATED) |
| [erp-analysis/](system/erp-analysis/) | ERP 스토리보드 분석 (9개 파일) |
---
### 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 전 |
| [pagination-policy.md](standards/pagination-policy.md) | 페이지네이션 표준 | 목록 API 구현 시 |
| [options-column-policy.md](standards/options-column-policy.md) | JSON options 컬럼 표준 정책 (마이그레이션, 모델, 쿼리) | 테이블 생성/확장 시 |
---
### 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) | 과금 코드 개발 전 |
| [client-policy.md](rules/client-policy.md) | 고객사 관리 정책 | 고객 관련 작업 전 |
| [attendance-api.md](rules/attendance-api.md) | 근태 API 규칙 | 근태 관련 작업 전 |
| [department-tree-api.md](rules/department-tree-api.md) | 부서 트리 API 규칙 | 부서 관련 작업 전 |
| [employee-api.md](rules/employee-api.md) | 직원 API 규칙 | 직원 관련 작업 전 |
| [numbering-rules.md](rules/numbering-rules.md) | 채번규칙 (패턴 기반 자동 번호 생성) | 채번 로직 수정 전 |
---
### features/ — 기능별 문서
> 도메인별 기능 상세 (기능 설명 + 엔드포인트 경로 + Swagger 참조)
| 문서 | 설명 |
|------|------|
| [quotes/README.md](features/quotes/README.md) | 견적 시스템 (BOM 계산, 10단계 로직) |
| [boards/README.md](features/boards/README.md) | 게시판 시스템 구현 |
| [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 |
| [hr/attendance-management-spec.md](features/hr/attendance-management-spec.md) | 근태관리 기획서 |
| [hr/hr-api-analysis.md](features/hr/hr-api-analysis.md) | HR API 분석 (근태/직원/부서) |
| [barobill-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 + 세금계산서 연동 |
| ~~business-card-request.md~~ | 명함신청 관리 (DB 마이그레이션만 존재, 문서 미작성) |
| [sales/README.md](features/sales/README.md) | 영업 관리 (면접 시나리오 포함) |
| [crm/README.md](features/crm/README.md) | CRM (거래처, 미수금, 미지급금) |
| [finance/README.md](features/finance/README.md) | 재무 관리 (14개 하위 문서) |
| [card-vehicle/README.md](features/card-vehicle/README.md) | 법인카드·차량 관리 |
| [settlement/README.md](features/settlement/README.md) | 정산 관리 |
| [esign/README.md](features/esign/README.md) | 전자서명 (계약·OTP·PDF 합성) |
| [documents/README.md](features/documents/README.md) | 문서관리 (EAV 기반 서식·결재) |
| [ai/README.md](features/ai/README.md) | AI 분석 리포트 (Gemini 연동) |
| [equipment/README.md](features/equipment/README.md) | 설비관리 (MNG 전용) |
---
### 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 가이드 | 서버 이해 시 |
| [php-fpm-guide.md](guides/php-fpm-guide.md) | PHP-FPM 가이드 | 서버 이해 시 |
| [jenkins-setup-guide.md](guides/jenkins-setup-guide.md) | Jenkins CI/CD 셋업 | Jenkins 설치/설정 시 |
| [auto-login-guide.md](guides/auto-login-guide.md) | MNG→DEV 자동 로그인 | 자동 로그인 구현 시 |
| [erp-api-list.md](guides/erp-api-list.md) | ERP API 목록 (List vs Detail 구분) | 프론트 API 연동 시 |
| [erp-api-detail.md](guides/erp-api-detail.md) | ERP API 상세 스펙 | 프론트 API 연동 시 |
| [item-master-guide.md](guides/item-master-guide.md) | 품목기준관리 페이지-섹션-필드 구조 | 품목 UI 구현 시 |
| [item-master-items-api.md](guides/item-master-items-api.md) | ItemMaster & Items API 문서 | 품목 API 연동 시 |
---
### quickstart/ — 빠른 시작
> 핵심 규칙 요약, 자주 쓰는 명령어
| 문서 | 설명 |
|------|------|
| [quick-start.md](quickstart/quick-start.md) | 프로젝트 핵심 규칙 요약 |
| [dev-commands.md](quickstart/dev-commands.md) | 일상 개발 명령어 모음 |
---
### plans/ — 작업 추적
> 예정 → 진행 → 완료 → archive/ (이미 정리 완료, 현행 유지)
| 문서 | 설명 |
|------|------|
| [index_plans.md](plans/index_plans.md) | 계획 인덱스 (ACTIVE + PLANNED) |
| [GUIDE.md](plans/GUIDE.md) | 계획 문서 작성 가이드 |
---
### projects/ — 프로젝트 자료
> 프로젝트성 분석, 설계, 참고 자료 (지속 보관)
| 프로젝트 | 문서 | 설명 |
|---------|------|------|
| [index_projects.md](projects/index_projects.md) | 프로젝트 인덱스 | |
| **MES** | [README.md](projects/mes/README.md) | MES 프로젝트 개요 |
| **MES** | [MES_PROJECT_ROADMAP.md](projects/mes/MES_PROJECT_ROADMAP.md) | 개발 로드맵 |
| **5130 이관** | [MASTER_PLAN.md](projects/5130-migration/MASTER_PLAN.md) | 레거시 이관 마스터 플랜 |
| **API 연동** | [MASTER_PLAN.md](projects/api-integration/MASTER_PLAN.md) | React↔API 연동 |
| **Legacy** | [draw-module.md](projects/legacy-5130/draw-module.md) | 레거시 드로우 모듈 |
| **견적** | [quotation/](projects/quotation/) | 견적 프로젝트 자료 |
| **전자서명** | [e-sign/](projects/e-sign/) | 전자서명 프로젝트 자료 |
---
### deploys/ — 운영 매뉴얼
> 서버 운영, 배포 (현행 유지)
| 문서 | 설명 |
|------|------|
| [ops-manual/README.md](deploys/ops-manual/README.md) | 서버 운영 매뉴얼 (11부 구성) |
---
### changes/ — 변경 이력
> 파일명 형식: `YYYYMMDD_description.md`
---
### data/ — 데이터 분석
| 문서 | 설명 |
|------|------|
| [analysis/item-db-analysis.md](data/analysis/item-db-analysis.md) | Item DB/API 분석 최종본 |
| [analysis/bom-item-mapping-analysis.md](data/analysis/bom-item-mapping-analysis.md) | BOM-품목 매핑 분석 |
### 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, 서버 아키텍처) |
| [attendance-management-plan.md](plans/attendance-management-plan.md) | 근태현황 개발 계획 (Phase 1~2, HTMX 기반) |
| [leave-management-plan.md](plans/leave-management-plan.md) | 휴가관리 모듈 개발 계획 (연차 발생/신청/승인/정책) |
### 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/attendance-management-spec.md](features/hr/attendance-management-spec.md) | 근태관리 기획서 (화면/데이터/비즈니스규칙/API) |
| [hr/hr-api-analysis.md](features/hr/hr-api-analysis.md) | HR API 분석 (근태/직원/부서) |
| [quotes/README.md](features/quotes/README.md) | 견적 시스템 분석 (BOM 계산, 10단계 로직) |
| [business-card-request.md](features/business-card-request.md) | 명함신청 관리 (3단계 워크플로우: 요청→제작의뢰→처리완료) |
| [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/](../api/docs/) | REST API 프로젝트 |
| **MNG** | [mng/docs/](../mng/docs/) | Plain Laravel 관리자 |
| **React** | [react/docs/](../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/`)
```markdown
# 제목
> **작성일**: YYYY-MM-DD
> **상태**: 설계 확정
---
## 1. 개요
## 2. 핵심 원칙
## 3. 상세 규칙
## 4. API 엔드포인트 (해당 시)
## 관련 문서
---
**최종 업데이트**: YYYY-MM-DD
```
#### 변경 이력 문서 (`changes/`)
```markdown
# 변경 내용 요약
**날짜:** YYYY-MM-DD
## 변경 개요
## 수정된 파일
## 상세 변경 사항
## 테스트 체크리스트
```
### 작성 스타일
| 항목 | 규칙 |
|------|------|
| **언어** | 한글 기본, 코드/경로/기술 식별자만 영어 |
| **어조** | 서술형 ("X 한다") |
| **경고** | `> **경고: ...**` 블록인용 |
| **금지/필수** | `❌` 금지, `✅` 필수 |
| **우선순위** | `🔴 필수`, `🟡 중요`, `🟢 권장` |
| **코드 블록** | 반드시 언어 지정 (```php, ```bash 등) |
| **인라인 코드** | 파일 경로, 메서드명, 변수명에 백틱 |
| **구분선** | `---` 주요 섹션 사이 |
### 새 문서 작성 시 체크리스트
- [ ] 적절한 폴더에 배치
- [ ] 파일명 규칙 준수
- [ ] 문서 구조 템플릿 준수
- [ ] 이 INDEX.md에 등록
---
## 🔄 문서 정비 진행 현황
> 참조: [docs-comprehensive-update-plan.md](plans/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 갱신 | ⏳ 대기 |
Reference in New Issue View Git Blame Copy Permalink