docs: 문서 폴더 구조 대폭 재정리
폴더 재구성: - reference/ → standards/, architecture/, quickstart/로 분리 - principles/ → architecture/로 통합 - specs/security-policy.md → architecture/로 이동 새 구조: - standards/: 개발 표준 (어떻게 코드를 작성할 것인가) - architecture/: 아키텍처 & 설계 원칙 (왜 이렇게 설계하는가) - rules/: 비즈니스 규칙 (무엇이 유효한 데이터인가) - specs/: 기술 스펙 (무엇을 구현할 것인가) - guides/: 구현 가이드 (어떻게 구현할 것인가) - quickstart/: 빠른 시작 INDEX.md 개선: - 작업별 필수 문서 테이블 추가 - 폴더별 문서 목록 및 필수 확인 시점 명시 - 폴더 선택 기준 가이드 추가
This commit is contained in:
243
quickstart/quick-start.md
Normal file
243
quickstart/quick-start.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# SAM 개발 빠른 참조
|
||||
|
||||
**5분 가이드** - 일상 개발에 필요한 핵심 규칙
|
||||
|
||||
---
|
||||
|
||||
## 🚀 개발 명령어
|
||||
|
||||
```bash
|
||||
# 전체 서비스 시작
|
||||
composer dev # Laravel + Queue + Pail + Vite
|
||||
|
||||
# 개별 명령어
|
||||
php artisan migrate # DB 마이그레이션
|
||||
./vendor/bin/pint # 코드 포맷팅
|
||||
php artisan test # 테스트 실행
|
||||
npm run dev # Vite HMR (프론트엔드)
|
||||
|
||||
# API 문서
|
||||
# http://api.sam.kr/api-docs/index.html (Swagger)
|
||||
```
|
||||
|
||||
**자세히:** [`claudedocs/SAM/dev_commands.md`](./claudedocs/SAM/dev_commands.md)
|
||||
|
||||
---
|
||||
|
||||
## 📝 API 개발 3대 원칙
|
||||
|
||||
### 1️⃣ Service-First
|
||||
```php
|
||||
// ✅ Good
|
||||
class ProductController {
|
||||
public function index(Request $request, ProductService $service) {
|
||||
return ApiResponse::handle(fn() =>
|
||||
$service->getList($request->validated())
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ Bad - Controller에 비즈니스 로직
|
||||
public function index() {
|
||||
$products = Product::where('tenant_id', auth()->user()->tenant_id)->get();
|
||||
}
|
||||
```
|
||||
|
||||
### 2️⃣ Multi-tenant (BelongsToTenant)
|
||||
```php
|
||||
// ✅ Good - 모든 모델에 적용
|
||||
class Product extends Model {
|
||||
use BelongsToTenant, SoftDeletes, ModelTrait;
|
||||
}
|
||||
|
||||
// ❌ Bad - tenant_id 필터링 누락
|
||||
Product::all(); // 전체 테넌트 데이터 노출 위험
|
||||
```
|
||||
|
||||
### 3️⃣ FormRequest 검증
|
||||
```php
|
||||
// ✅ Good
|
||||
public function store(StoreProductRequest $request, ProductService $service) {
|
||||
return ApiResponse::handle(fn() =>
|
||||
$service->create($request->validated())
|
||||
);
|
||||
}
|
||||
|
||||
// ❌ Bad - Controller에서 직접 검증
|
||||
public function store(Request $request) {
|
||||
$validated = $request->validate([...]);
|
||||
}
|
||||
```
|
||||
|
||||
**자세히:** [`claudedocs/SAM/api_rules.md`](./claudedocs/SAM/api_rules.md)
|
||||
|
||||
---
|
||||
|
||||
## ✅ 커밋 전 5분 체크리스트
|
||||
|
||||
```bash
|
||||
# 1. 핵심 규칙 확인
|
||||
□ Service-First (비즈니스 로직 → Service)
|
||||
□ FormRequest 사용 (Controller 검증 금지)
|
||||
□ BelongsToTenant + SoftDeletes 적용
|
||||
□ i18n 키 사용 (직접 문자열 금지)
|
||||
|
||||
# 2. 코드 품질
|
||||
□ Pint 포맷팅 실행: ./vendor/bin/pint
|
||||
□ PHPStan 검사 통과 (있는 경우)
|
||||
□ 테스트 실행: php artisan test
|
||||
|
||||
# 3. Swagger 문서화
|
||||
□ @OA\Tag, @OA\Schema 작성
|
||||
□ ApiKeyAuth + BearerAuth 명시
|
||||
□ Request/Response 예시 추가
|
||||
|
||||
# 4. 데이터베이스
|
||||
□ Migration 파일에 COMMENT 추가
|
||||
□ Foreign Key 최소화 (설계 시에만)
|
||||
□ created_by, updated_by, deleted_by 컬럼 확인
|
||||
|
||||
# 5. Git
|
||||
□ 의미 있는 커밋 메시지
|
||||
□ feat/fix/refactor/docs 타입 사용
|
||||
```
|
||||
|
||||
**자세히:** [`claudedocs/SAM/quality_checklist.md`](./claudedocs/SAM/quality_checklist.md)
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ 데이터베이스 규칙
|
||||
|
||||
### 필수 컬럼
|
||||
```php
|
||||
Schema::create('products', function (Blueprint $table) {
|
||||
$table->id()->comment('ID');
|
||||
$table->foreignId('tenant_id')->comment('테넌트 ID');
|
||||
|
||||
// 비즈니스 컬럼...
|
||||
|
||||
$table->foreignId('created_by')->nullable()->comment('생성자 ID');
|
||||
$table->foreignId('updated_by')->nullable()->comment('수정자 ID');
|
||||
$table->foreignId('deleted_by')->nullable()->comment('삭제자 ID');
|
||||
$table->timestamps();
|
||||
$table->softDeletes();
|
||||
});
|
||||
```
|
||||
|
||||
### 감사 로그
|
||||
- **보관 기간:** 13개월
|
||||
- **대상:** 모든 Create/Update/Delete 작업
|
||||
- **실패 허용:** 감사 로그 실패 시 비즈니스 로직 계속 진행
|
||||
|
||||
---
|
||||
|
||||
## 🔐 인증 & 권한
|
||||
|
||||
### API 인증 흐름
|
||||
```
|
||||
1. API Key (X-API-KEY) - 애플리케이션 인증
|
||||
2. Sanctum Token (Bearer) - 사용자 인증
|
||||
```
|
||||
|
||||
### 권한 체계
|
||||
```
|
||||
Menu (메뉴)
|
||||
↓ has
|
||||
Permission (권한)
|
||||
↓ belongs to
|
||||
Role (역할)
|
||||
↓ belongs to
|
||||
Department (부서)
|
||||
↓ has
|
||||
User (사용자)
|
||||
```
|
||||
|
||||
**3-State 시스템:**
|
||||
- **Inherit** (상속): 상위 권한 따름
|
||||
- **Allow** (허용): 명시적 허용
|
||||
- **Deny** (거부): 명시적 거부
|
||||
|
||||
---
|
||||
|
||||
## 📦 Git 커밋 형식
|
||||
|
||||
```bash
|
||||
# 형식
|
||||
[type]: 간결한 제목
|
||||
|
||||
- 변경 상세 내용 1
|
||||
- 변경 상세 내용 2
|
||||
|
||||
# 타입
|
||||
feat: 새로운 기능
|
||||
fix: 버그 수정
|
||||
refactor: 리팩토링
|
||||
docs: 문서 변경
|
||||
style: 코드 포맷팅
|
||||
test: 테스트 추가
|
||||
chore: 기타 작업
|
||||
|
||||
# 예시
|
||||
feat: 제품 카테고리 관리 API 구현
|
||||
|
||||
- ProductCategoryService 추가
|
||||
- Swagger 문서화 완료
|
||||
- PHPUnit 테스트 작성
|
||||
```
|
||||
|
||||
**자세히:** [`claudedocs/SAM/git_conventions.md`](./claudedocs/SAM/git_conventions.md)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 프로젝트 구조
|
||||
|
||||
```
|
||||
SAM/
|
||||
├── api/ # Laravel 12 REST API (독립)
|
||||
├── admin/ # Laravel 12 + Filament v3 (독립)
|
||||
├── react/ # React 19 프론트엔드 (독립)
|
||||
├── docker/ # Docker 설정
|
||||
│
|
||||
├── CLAUDE.md # 프로젝트 개요
|
||||
├── CURRENT_WORKS.md # 현재 작업 현황
|
||||
├── SAM_QUICK_REFERENCE.md # 이 파일
|
||||
│
|
||||
└── claudedocs/ # 상세 문서
|
||||
├── SAM/ # SAM 프로젝트 문서
|
||||
│ ├── api_rules.md
|
||||
│ ├── dev_commands.md
|
||||
│ ├── quality_checklist.md
|
||||
│ ├── git_conventions.md
|
||||
│ └── database_schema.md
|
||||
│
|
||||
└── mes/ # MES/ERP 프로젝트 문서
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 환경 정보
|
||||
|
||||
| 환경 | 도메인 | 특징 |
|
||||
|------|--------|------|
|
||||
| 로컬 | sam.kr | Docker, HMR |
|
||||
| 개발 | codebridge-x.com | 클라우드, 수동 배포 |
|
||||
| 운영 | TBD | 설정 중 |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 더 자세한 정보
|
||||
|
||||
| 주제 | 문서 |
|
||||
|------|------|
|
||||
| **프로젝트 개요** | [`CLAUDE.md`](./CLAUDE.md) |
|
||||
| **현재 작업** | [`CURRENT_WORKS.md`](./CURRENT_WORKS.md) |
|
||||
| **API 규칙** | [`claudedocs/SAM/api_rules.md`](./claudedocs/SAM/api_rules.md) |
|
||||
| **개발 명령어** | [`claudedocs/SAM/dev_commands.md`](./claudedocs/SAM/dev_commands.md) |
|
||||
| **품질 체크리스트** | [`claudedocs/SAM/quality_checklist.md`](./claudedocs/SAM/quality_checklist.md) |
|
||||
| **Git 규칙** | [`claudedocs/SAM/git_conventions.md`](./claudedocs/SAM/git_conventions.md) |
|
||||
| **DB 스키마** | [`claudedocs/SAM/database_schema.md`](./claudedocs/SAM/database_schema.md) |
|
||||
| **MES 프로젝트** | [`claudedocs/mes/README.md`](./claudedocs/mes/README.md) |
|
||||
|
||||
---
|
||||
|
||||
**업데이트**: 2025-11-18
|
||||
Reference in New Issue
Block a user