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:
286
dev/quickstart/dev-commands.md
Normal file
286
dev/quickstart/dev-commands.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 개발 명령어 모음
|
||||
|
||||
**업데이트**: 2026-01-28
|
||||
|
||||
---
|
||||
|
||||
## MNG Application (mng/)
|
||||
|
||||
### 개발 서버
|
||||
```bash
|
||||
# 개별 서비스
|
||||
php artisan serve # Laravel server
|
||||
npm run dev # Vite dev server (Tailwind)
|
||||
```
|
||||
|
||||
### 테스트
|
||||
```bash
|
||||
composer test
|
||||
php artisan test
|
||||
```
|
||||
|
||||
### 코드 품질
|
||||
```bash
|
||||
./vendor/bin/pint # PHP CS Fixer (포맷팅)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Application (api/)
|
||||
|
||||
### 개발 서버
|
||||
```bash
|
||||
# 모든 서비스 동시 실행
|
||||
composer dev
|
||||
```
|
||||
|
||||
### 데이터베이스
|
||||
```bash
|
||||
# 마이그레이션 상태 확인
|
||||
php artisan migrate:status
|
||||
|
||||
# 마이그레이션 실행
|
||||
php artisan migrate
|
||||
|
||||
# 마이그레이션 롤백
|
||||
php artisan migrate:rollback --step=N
|
||||
|
||||
# 기존 DB에서 마이그레이션 생성
|
||||
php artisan migrate:generate
|
||||
```
|
||||
|
||||
### API 문서
|
||||
```bash
|
||||
# Swagger 문서 재생성
|
||||
php artisan l5-swagger:generate
|
||||
|
||||
# 접근
|
||||
# - Swagger UI: http://api.sam.kr/api-docs/index.html
|
||||
# - JSON Spec: http://api.sam.kr/docs/api-docs.json
|
||||
```
|
||||
|
||||
### 라우트 관리
|
||||
```bash
|
||||
# 등록된 라우트 목록 확인
|
||||
php artisan route:list
|
||||
|
||||
# 특정 이름 패턴으로 필터
|
||||
php artisan route:list --name=v1.users
|
||||
|
||||
# 특정 경로 패턴으로 필터
|
||||
php artisan route:list --path=api/v1/users
|
||||
|
||||
# 라우트 캐시 (Production)
|
||||
php artisan route:cache
|
||||
|
||||
# 라우트 캐시 클리어
|
||||
php artisan route:clear
|
||||
|
||||
# API 버전 테스트
|
||||
# - 기본 (v1): curl https://api.sam.kr/api/v1/users
|
||||
# - v2 헤더: curl -H "Accept-Version: v2" https://api.sam.kr/api/v1/users
|
||||
# - 쿼리: curl "https://api.sam.kr/api/v1/users?api_version=v2"
|
||||
```
|
||||
|
||||
### 개발 도구
|
||||
```bash
|
||||
# IDE Helper
|
||||
php artisan ide-helper:generate
|
||||
php artisan ide-helper:models
|
||||
|
||||
# 코드 포맷팅
|
||||
./vendor/bin/pint
|
||||
```
|
||||
|
||||
### 스케줄러
|
||||
```bash
|
||||
# 스케줄러 작업 목록 확인
|
||||
php artisan schedule:list
|
||||
|
||||
# 스케줄러 즉시 실행 (테스트)
|
||||
php artisan schedule:run
|
||||
|
||||
# 특정 커맨드 실행
|
||||
php artisan audit:prune
|
||||
php artisan sanctum:prune-expired --hours=24
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend (front/www/)
|
||||
|
||||
### CodeIgniter 3
|
||||
```bash
|
||||
# PHP 의존성 설치
|
||||
composer install
|
||||
|
||||
# 개발 서버
|
||||
php -S localhost:8080
|
||||
|
||||
# Note: front/_Codeigniter/에 CI3 시스템 파일
|
||||
# Main application은 front/www/ 디렉토리
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 공통 (Build & Assets)
|
||||
|
||||
### Frontend Assets
|
||||
```bash
|
||||
# Production build
|
||||
npm run build
|
||||
|
||||
# Development with hot reload
|
||||
npm run dev
|
||||
|
||||
# 개별 디렉토리
|
||||
cd mng && npm run build
|
||||
cd api && npm run build
|
||||
cd react && npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git
|
||||
|
||||
### 상태 확인
|
||||
```bash
|
||||
# 현재 브랜치 및 변경사항
|
||||
git status
|
||||
|
||||
# 브랜치 목록
|
||||
git branch
|
||||
|
||||
# 변경 내용 확인
|
||||
git diff
|
||||
```
|
||||
|
||||
### 커밋
|
||||
```bash
|
||||
# 변경사항 스테이징
|
||||
git add .
|
||||
|
||||
# 커밋
|
||||
git commit -m "type: message"
|
||||
|
||||
# 커밋 로그
|
||||
git log --oneline -10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker
|
||||
|
||||
### 서비스 관리
|
||||
```bash
|
||||
# Docker 서비스 시작
|
||||
docker-compose up -d
|
||||
|
||||
# Docker 서비스 중지
|
||||
docker-compose down
|
||||
|
||||
# Docker 서비스 재시작
|
||||
docker-compose restart
|
||||
|
||||
# Docker 로그 확인
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 환경 확인
|
||||
|
||||
### PHP & Composer
|
||||
```bash
|
||||
# PHP 버전
|
||||
php -v
|
||||
|
||||
# Composer 버전
|
||||
composer -V
|
||||
|
||||
# 설치된 패키지 확인
|
||||
composer show
|
||||
```
|
||||
|
||||
### Node & NPM
|
||||
```bash
|
||||
# Node 버전
|
||||
node -v
|
||||
|
||||
# NPM 버전
|
||||
npm -v
|
||||
|
||||
# 설치된 패키지 확인
|
||||
npm list --depth=0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 유용한 명령어
|
||||
|
||||
### 로그 확인
|
||||
```bash
|
||||
# Laravel 로그 실시간 확인
|
||||
tail -f storage/logs/laravel.log
|
||||
|
||||
# Scheduler 로그 확인
|
||||
tail -f storage/logs/scheduler.log
|
||||
|
||||
# Pail 사용 (Laravel 12)
|
||||
php artisan pail --timeout=0
|
||||
```
|
||||
|
||||
### 캐시 관리
|
||||
```bash
|
||||
# 모든 캐시 클리어
|
||||
php artisan cache:clear
|
||||
|
||||
# 설정 캐시 클리어
|
||||
php artisan config:clear
|
||||
|
||||
# 라우트 캐시 클리어
|
||||
php artisan route:clear
|
||||
|
||||
# 뷰 캐시 클리어
|
||||
php artisan view:clear
|
||||
```
|
||||
|
||||
### 최적화
|
||||
```bash
|
||||
# Production 최적화
|
||||
php artisan optimize
|
||||
|
||||
# Autoload 최적화
|
||||
composer dump-autoload -o
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 트러블슈팅
|
||||
|
||||
### 권한 문제
|
||||
```bash
|
||||
# storage 디렉토리 권한
|
||||
chmod -R 775 storage
|
||||
chmod -R 775 bootstrap/cache
|
||||
```
|
||||
|
||||
### 의존성 재설치
|
||||
```bash
|
||||
# Composer
|
||||
rm -rf vendor
|
||||
composer install
|
||||
|
||||
# NPM
|
||||
rm -rf node_modules
|
||||
npm install
|
||||
```
|
||||
|
||||
### 환경 초기화
|
||||
```bash
|
||||
# .env 파일 복사 (처음 설치 시)
|
||||
cp .env.example .env
|
||||
|
||||
# Application key 생성
|
||||
php artisan key:generate
|
||||
```
|
||||
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