SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 문서 폴더 구조 대폭 재정리

Browse Source 
폴더 재구성:
- reference/ → standards/, architecture/, quickstart/로 분리
- principles/ → architecture/로 통합
- specs/security-policy.md → architecture/로 이동

새 구조:
- standards/: 개발 표준 (어떻게 코드를 작성할 것인가)
- architecture/: 아키텍처 & 설계 원칙 (왜 이렇게 설계하는가)
- rules/: 비즈니스 규칙 (무엇이 유효한 데이터인가)
- specs/: 기술 스펙 (무엇을 구현할 것인가)
- guides/: 구현 가이드 (어떻게 구현할 것인가)
- quickstart/: 빠른 시작

INDEX.md 개선:
- 작업별 필수 문서 테이블 추가
- 폴더별 문서 목록 및 필수 확인 시점 명시
- 폴더 선택 기준 가이드 추가
This commit is contained in:
권혁성
2025-12-05 21:43:29 +09:00
parent 02a27f2bba
commit 88644c88ab
12 changed files with 154 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
INDEX.md
View File

@@ -1,158 +1,170 @@
# SAM 프로젝트 문서 네비게이션
# SAM 프로젝트 문서 인덱스
> 📌 **Claude Code를 위한 문서 허브** - 작업별로 필요한 문서를 빠르게 찾아 컨텍스트에 추가하세요.
> **Claude Code 작업 전 필수 확인** - 작업 유형에 맞는 문서를 먼저 읽고 시작하세요.
---
## 🚀 빠른 시작
## 🎯 작업별 필수 문서 (반드시 먼저 확인)
| 문서 | 용도 | 크기 |
|------|------|------|
| [Quick Start Guide](reference/quick-start.md) | 프로젝트 핵심 규칙 요약 | 5KB |
| [개발 환경 설정](specs/docker-setup.md) | Docker 환경 구축 | 7KB |
| [개발 명령어](reference/dev-commands.md) | 일상 개발 명령어 | 4KB |
| 작업 유형 | 필수 문서 | 용도 |
|----------|----------|------|
| **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 문서 작성 방법 |
| **품목관리** | `specs/item-master-integration.md` | 품목 시스템 스펙 |
| **게시판** | `specs/board-system-spec.md` | 게시판 시스템 설계 |
| **MES 개발** | `projects/mes/README.md` | MES 프로젝트 개요 |
---
## 📐 규칙 및 원칙
## 📁 폴더 구조
개발 시 참고해야 할 규칙과 원칙 문서입니다.
| 규칙 유형 | 폴더 | 용도 | 예시 |
|----------|------|------|------|
| **코딩 규칙** | [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)
```
docs/
├── standards/ # 개발 표준 - "어떻게 코드를 작성할 것인가"
├── architecture/ # 아키텍처 - "왜 이렇게 설계하는가"
├── rules/ # 비즈니스 규칙 - "무엇이 유효한 데이터인가"
├── specs/ # 기술 스펙 - "무엇을 구현할 것인가"
├── guides/ # 구현 가이드 - "어떻게 구현할 것인가"
├── quickstart/ # 빠른 시작 - 핵심 요약
├── front/ # 프론트엔드 공유 문서
├── features/ # 기능별 상세 문서
├── projects/ # 프로젝트별 문서 (MES, Legacy)
├── history/ # 히스토리 및 로드맵
├── changes/ # 변경 이력
└── data/ # 데이터 분석
```
---
## 📖 개발 가이드
## 📚 폴더별 문서 목록
### Reference (일상 참고 문서)
현재 작업에 필요한 참고 문서입니다.
### standards/ - 개발 표준
> 코딩 컨벤션, 스타일 가이드, 품질 기준
- **[API 개발 규칙](reference/api-rules.md)** - Service-First, FormRequest, i18n 규칙
- **[품질 체크리스트](reference/quality-checklist.md)** - 코드 품질 검증 항목
- **[Git 규칙](reference/git-conventions.md)** - 커밋 메시지, 브랜치 전략
- **[시스템 아키텍처](reference/architecture.md)** - SAM 프로젝트 구조 개요
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [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 전 |
### Specs (환경/스펙 문서)
시스템 스펙과 환경 설정 문서입니다.
### architecture/ - 아키텍처 & 설계 원칙
> 시스템 설계, 보안 정책, 아키텍처 결정
- **[데이터베이스 스키마](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)** - 원격 개발 설정
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [system-overview.md](architecture/system-overview.md) | 전체 시스템 아키텍처 | 새 기능 설계 전 |
| [security-policy.md](architecture/security-policy.md) | 인증/인가, 보안 규칙 | 보안 관련 작업 전 |
### Features (기능별 문서)
특정 기능의 상세 문서입니다.
### rules/ - 비즈니스 규칙
> 도메인 로직, 검증 규칙, 상태 전이
- **[게시판 시스템](features/boards/README.md)** - 시스템/테넌트 게시판 구현
- [MNG 구현 상세](features/boards/mng-implementation.md)
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [README.md](rules/README.md) | 비즈니스 규칙 개요 | 도메인 로직 구현 전 |
### Guides (구현 가이드)
특정 기능 구현을 위한 매뉴얼입니다.
### specs/ - 기술 스펙
> 구현 명세, DB 스키마, 시스템 설정
- **[파일 스토리지 구현](guides/file-storage-guide.md)** - 파일 업로드/다운로드 구현
- **[Swagger 문서화](guides/swagger-guide.md)** - API 문서 작성 방법
- **[Item 관리 마이그레이션](guides/item-management-migration.md)** - Item 시스템 전환 가이드
- **[프로젝트 런칭 로드맵](guides/project-launch-roadmap.md)** - 런칭 준비 현황 및 방향성
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [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) | 원격 개발 설정 | 원격 작업 시 |
### Frontend (프론트엔드 공유 문서)
프론트엔드 개발을 위한 API 연동 가이드입니다.
### guides/ - 구현 가이드
> 특정 기능 구현을 위한 단계별 매뉴얼
- **[품목기준관리(ItemMaster) 가이드](front/item-master-guide.md)** - 페이지-섹션-필드 구조, 잠금 기능, API 연동
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [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) | 런칭 준비 현황 | 런칭 관련 작업 시 |
---
### quickstart/ - 빠른 시작
> 핵심 규칙 요약, 자주 쓰는 명령어
## 📁 프로젝트별 문서
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [quick-start.md](quickstart/quick-start.md) | 프로젝트 핵심 규칙 요약 | 세션 시작 시 |
| [dev-commands.md](quickstart/dev-commands.md) | 일상 개발 명령어 모음 | 명령어 확인 시 |
### MES 프로젝트
- **[MES README](projects/mes/README.md)** - MES 프로젝트 개요
- **[MES Roadmap](projects/mes/MES_PROJECT_ROADMAP.md)** - 개발 로드맵
- **[Phase 0 Baseline](projects/mes/00_baseline/)** - 초기 분석 문서
### front/ - 프론트엔드 공유 문서
> API 연동 가이드, 프론트엔드 스펙
### Legacy 5130
- **[Draw Module](projects/legacy-5130/draw-module.md)** - 레거시 드로우 모듈
| 문서 | 설명 |
|------|------|
| [item-master-guide.md](front/item-master-guide.md) | 품목기준관리 페이지-섹션-필드 구조 |
---
### features/ - 기능별 문서
## 📚 히스토리
| 문서 | 설명 |
|------|------|
| [boards/README.md](features/boards/README.md) | 게시판 시스템 구현 |
| [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 |
### 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 스펙
### projects/ - 프로젝트별 문서
### 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)** - 산출식 시스템 분석
| 프로젝트 | 문서 | 설명 |
|---------|------|------|
| **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) | 레거시 드로우 모듈 |
### Roadmaps
- **[December 2025 Roadmap](history/roadmaps/december-2025.md)** - 12월 개발 계획
### 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) |
| **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/` 디렉토리를 가지고 있습니다.
각 서브프로젝트는 독립적인 `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`
| **MNG** | [mng/docs/INDEX.md](../mng/docs/INDEX.md) | Plain Laravel 관리자 (운영 주력) |
| **Admin** | [admin/docs/INDEX.md](../admin/docs/INDEX.md) | Filament 관리자 (deprecated) |
| **React** | [react/docs/](../react/docs/) | Next.js 프론트엔드 |
---
## 📝 문서 작성 가이드
새 문서를 작성할 때:
1. **크기 목표**: 10KB 이하 (Claude Code 빠른 로딩)
2. **명확한 제목**: 내용을 정확히 반영
3. **적절한 위치**: reference/specs/history/guides/projects 중 선택
4. **INDEX 업데이트**: 새 문서는 반드시 INDEX.md에 추가
### 새 문서 작성 시
1. **적절한 폴더 선택**: 위 폴더 구조 참고
2. **파일명**: 소문자 + 하이픈 (kebab-case)
3. **크기 목표**: 10KB 이하
4. **INDEX 업데이트**: 새 문서는 반드시 이 파일에 추가
### 폴더 선택 기준
- **"어떻게 코드 작성?"** → `standards/`
- **"왜 이렇게 설계?"** → `architecture/`
- **"무엇이 유효한 데이터?"** → `rules/`
- **"무엇을 구현?"** → `specs/`
- **"어떻게 구현?"** → `guides/`
---
## 🔄 문서 구조 변경 이력
- **2025-12-05**: 규칙 및 원칙 문서 체계 추가
- standards/ - 코딩 규칙 (네이밍, 스타일)
- rules/ - 비즈니스 규칙 (검증, 도메인 로직)
- principles/ - 설계 원칙 (아키텍처, API 설계)
- **2025-12-05**: 폴더 구조 대폭 재정리
- `reference/` → `standards/`, `architecture/`, `quickstart/`로 분리
- `principles/` → `architecture/`로 통합
- 작업별 필수 문서 가이드 추가
- **2025-11-20**: 문서 구조 대규모 재정리
- .cursor/docs 삭제
- claudedocs → docs/ 체계화
- Reference/Specs/History/Guides/Projects 분류
- 각 서브프로젝트별 docs/ 디렉토리 생성
- 각 서브프로젝트별 docs/ 디렉토리 생성

20
architecture/README.md Normal file
View File

@@ -0,0 +1,20 @@
# Architecture (아키텍처 & 설계 원칙)
> 시스템 설계와 아키텍처 결정의 근간 - **"왜 이렇게 설계하는가"**
## 목적
- 일관된 아키텍처 결정 기준 제공
- 기술 부채 방지
- 확장성과 유지보수성 확보
## 문서 목록
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [system-overview.md](system-overview.md) | 전체 시스템 아키텍처 | 새 기능 설계 전 |
| [security-policy.md](security-policy.md) | 인증/인가, 보안 규칙 | 보안 관련 작업 전 |
## 관련 폴더
- [standards/](../standards/) - 개발 표준 (어떻게 코드를 작성할 것인가)
- [rules/](../rules/) - 비즈니스 규칙 (무엇이 유효한 데이터인가)
- [specs/](../specs/) - 기술 스펙 (무엇을 구현할 것인가)

0
specs/security-policy.md → architecture/security-policy.md
View File

0
reference/architecture.md → architecture/system-overview.md
View File

24
principles/README.md
View File

@@ -1,24 +0,0 @@
# Principles (설계 원칙)
> 시스템 설계와 아키텍처 결정의 근간이 되는 원칙
## 목적
- 일관된 아키텍처 결정 기준 제공
- 기술 부채 방지
- 확장성과 유지보수성 확보
## 포함 내용
- 아키텍처 원칙 (Service-First, Multi-tenancy)
- API 설계 원칙 (RESTful, 버전 관리)
- 데이터베이스 설계 원칙
- 보안 설계 원칙
- 성능 최적화 원칙
## 문서 목록
| 문서 | 설명 |
|------|------|
| *(작성 예정)* | |
## 관련 문서
- [시스템 아키텍처](../reference/architecture.md) - 전체 시스템 구조
- [API 개발 규칙](../reference/api-rules.md) - API 설계 표준

0
reference/dev-commands.md → quickstart/dev-commands.md
View File

0
reference/quick-start.md → quickstart/quick-start.md
View File

10
rules/README.md
View File

@@ -1,6 +1,6 @@
# Rules (비즈니스 규칙)
> 도메인 로직과 비즈니스 요구사항에서 파생된 규칙
> 도메인 로직에서 파생된 규칙 - **"무엇이 유효한 데이터/상태인가"**
## 목적
- 비즈니스 로직의 명확한 문서화
@@ -15,10 +15,12 @@
- 데이터 무결성 규칙
## 문서 목록
| 문서 | 설명 |
|------|------|
| *(작성 예정)* | |
## 관련 문서
- [품목기준관리 스펙](../specs/item-master-integration.md) - 품목 관리 명세
- [보안 정책](../specs/security-policy.md) - 보안 관련 규칙
## 관련 폴더
- [standards/](../standards/) - 개발 표준 (어떻게 코드를 작성할 것인가)
- [architecture/](../architecture/) - 설계 원칙 (왜 이렇게 설계하는가)
- [specs/](../specs/) - 기술 스펙 (무엇을 구현할 것인가)

25
standards/README.md
View File

@@ -1,23 +1,20 @@
# Standards (코딩 규칙)
# Standards (개발 표준)
> 개발 시 준수해야 할 코딩 컨벤션과 스타일 가이드
> 코드 작성 방법에 대한 규칙 - **"어떻게 코드를 작성할 것인가"**
## 목적
- 일관된 코드 스타일 유지
- 팀 간 협업 효율성 향상
- 코드 리뷰 기준 명확화
## 포함 내용
- 네이밍 컨벤션 (변수, 함수, 클래스, 파일)
- 코드 스타일 (들여쓰기, 주석, 포맷팅)
- 디렉토리 구조 규칙
- 테스트 작성 규칙
## 문서 목록
| 문서 | 설명 |
|------|------|
| *(작성 예정)* | |
## 관련 문서
- [API 개발 규칙](../reference/api-rules.md) - API 개발 표준
- [Git 규칙](../reference/git-conventions.md) - 커밋 메시지, 브랜치 전략
| 문서 | 설명 | 필수 확인 시점 |
|------|------|--------------|
| [api-rules.md](api-rules.md) | API 개발 규칙 (Service-First, FormRequest, i18n) | API 개발 전 |
| [git-conventions.md](git-conventions.md) | Git 커밋 메시지, 브랜치 전략 | 커밋 전 |
| [quality-checklist.md](quality-checklist.md) | 코드 품질 체크리스트 | PR 전 |
## 관련 폴더
- [architecture/](../architecture/) - 설계 원칙 (왜 이렇게 설계하는가)
- [rules/](../rules/) - 비즈니스 규칙 (무엇이 유효한 데이터인가)

0
reference/api-rules.md → standards/api-rules.md
View File

0
reference/git-conventions.md → standards/git-conventions.md
View File

0
reference/quality-checklist.md → standards/quality-checklist.md
View File