refactor: [docs] 팀별 폴더 구조 재편 (공유/개발/프론트/기획)
- 개발팀 전용 폴더 dev/ 생성 (standards, guides, quickstart, changes, deploys, data, history, dev_plans 이동) - 프론트엔드 전용 폴더 frontend/ 생성 (api/ → frontend/api-specs/) - 기획팀 폴더 requests/ 생성 - plans/ → dev/dev_plans/ 이름 변경 - README.md 신규 (사람용 안내), INDEX.md 재작성 (Claude Code용) - resources.md 신규 (노션 링크용, assets/brochure 이관 예정) - CURRENT_WORKS.md 삭제, TODO.md → dev/ 이동 - 전체 참조 경로 업데이트 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
242
dev/quickstart/quick-start.md
Normal file
242
dev/quickstart/quick-start.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# 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)
|
||||
```
|
||||
|
||||
**자세히:** [`docs/quickstart/dev-commands.md`](./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([...]);
|
||||
}
|
||||
```
|
||||
|
||||
**자세히:** [`docs/standards/api-rules.md`](../standards/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 타입 사용
|
||||
```
|
||||
|
||||
**자세히:** [`docs/standards/quality-checklist.md`](../standards/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 테스트 작성
|
||||
```
|
||||
|
||||
**자세히:** [`docs/standards/git-conventions.md`](../standards/git-conventions.md)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 프로젝트 구조
|
||||
|
||||
```
|
||||
SAM/
|
||||
├── api/ # Laravel 12 REST API (독립)
|
||||
├── mng/ # Laravel 12 + Blade/Tailwind (독립)
|
||||
├── react/ # Next.js 15 프론트엔드 (독립)
|
||||
├── docs/ # 기술 문서
|
||||
├── design/ # 디자인 시스템 (Storybook)
|
||||
├── planning/ # 기획 문서
|
||||
├── sales/ # 영업자 사이트 (추후)
|
||||
├── docker/ # Docker 설정
|
||||
│
|
||||
├── CLAUDE.md # 프로젝트 개요
|
||||
├── CURRENT_WORKS.md # 현재 작업 현황
|
||||
│
|
||||
└── docs/ # 상세 문서
|
||||
├── system/ # 시스템 현황 (아키텍처, DB, 인프라)
|
||||
├── standards/ # 개발 표준
|
||||
├── quickstart/ # 빠른 시작 가이드
|
||||
└── mes/ # MES/ERP 프로젝트 문서
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 환경 정보
|
||||
|
||||
| 환경 | 도메인 | 특징 |
|
||||
|------|--------|------|
|
||||
| 로컬 | sam.kr | Docker, HMR |
|
||||
| 개발 | codebridge-x.com | 클라우드, 수동 배포 |
|
||||
| 운영 | TBD | 설정 중 |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 더 자세한 정보
|
||||
|
||||
| 주제 | 문서 |
|
||||
|------|------|
|
||||
| **프로젝트 개요** | [`CLAUDE.md`](../../CLAUDE.md) |
|
||||
| **현재 작업** | [`CURRENT_WORKS.md`](../CURRENT_WORKS.md) |
|
||||
| **API 규칙** | [`docs/standards/api-rules.md`](../standards/api-rules.md) |
|
||||
| **개발 명령어** | [`docs/quickstart/dev-commands.md`](./dev-commands.md) |
|
||||
| **품질 체크리스트** | [`docs/standards/quality-checklist.md`](../standards/quality-checklist.md) |
|
||||
| **Git 규칙** | [`docs/standards/git-conventions.md`](../standards/git-conventions.md) |
|
||||
| **DB 스키마** | [`docs/system/database/README.md`](../system/database/README.md) |
|
||||
| **MES 프로젝트** | [`docs/projects/mes/README.md`](../projects/mes/README.md) |
|
||||
|
||||
---
|
||||
|
||||
**업데이트**: 2025-12-26
|
||||
Reference in New Issue
Block a user