.cursorrules

# Jiny Modules 패키지 커서 규칙

## 개요
이 파일은 Jiny Modules 패키지에서 모듈을 개발할 때 따라야 할 규칙과 가이드라인을 정의합니다. 커서는 이 규칙을 참고하여 일관성 있고 표준에 맞는 코드를 생성해야 합니다.

## 1. 모듈 생성 규칙

### 1.1 패키지명 규칙
- 소문자만 사용: `auth`, `uikit`, `payment`
- 단일 단어 권장: `user-management` → `usermanagement`
- 하이픈(-) 또는 언더스코어(_) 사용 금지
- 숫자로 시작하지 않음
- 의미있는 이름 사용

### 1.2 네임스페이스 규칙
- 기본 네임스페이스: `Jiny\{Package}`
- 예: `auth` → `Jiny\Auth`
- 하위 네임스페이스: `Jiny\{Package}\App\Http\Controllers`

### 1.3 뷰 네임스페이스 규칙
- 형식: `jiny-{package}`
- 예: `auth` → `jiny-auth`

## 2. 파일 구조 규칙

### 2.1 표준 디렉토리 구조
```
jiny/{package}/
├── app/
│   ├── Http/Controllers/     # 컨트롤러
│   ├── Http/Middleware/      # 미들웨어
│   ├── Models/              # 모델
│   ├── Services/            # 서비스 클래스
│   ├── Console/Commands/    # 콘솔 명령어
│   └── Providers/          # 서비스 프로바이더
├── database/
│   ├── migrations/          # 마이그레이션
│   └── seeders/            # 시더
├── resources/
│   ├── views/              # 뷰 파일
│   ├── css/                # CSS 파일
│   ├── js/                 # JavaScript 파일
│   └── lang/               # 언어 파일
├── routes/                 # 라우트 파일
├── config/                 # 설정 파일
├── docs/                   # 문서
├── tests/                  # 테스트
└── composer.json           # Composer 설정
```

### 2.2 파일명 규칙
- 클래스 파일: PascalCase (`AuthController.php`)
- 뷰 파일: kebab-case (`user-list.blade.php`)
- 설정 파일: 소문자 (`auth.php`)

## 3. 코딩 규칙

### 3.1 클래스명 규칙
- PascalCase 사용: `AuthController`, `UserModel`
- 명확하고 의미있는 이름
- 접미사로 역할 표시: `Controller`, `Model`, `Service`

### 3.2 메서드명 규칙
- camelCase 사용: `getUserData()`, `createUser()`
- 동사로 시작
- 명확하고 구체적인 이름

### 3.3 변수명 규칙
- camelCase 사용: `$userData`, `$isActive`
- 의미있는 이름 사용
- 약어 사용 금지

## 4. 서비스 프로바이더 규칙

### 4.1 기본 구조
```php
<?php

namespace Jiny\{Package};

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\Facades\View;

class {Package}ServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->registerServices();
        $this->registerConfig();
    }

    public function boot(): void
    {
        $this->registerViews();
        $this->registerRoutes();
        $this->registerComponents();
        $this->registerPublishes();
    }
}
```

### 4.2 서비스 바인딩 규칙
```php
// ✅ 권장
$this->app->singleton('{package}.service', function($app) {
    return new \Jiny\{Package}\App\Services\{Package}Service();
});

// ❌ 비권장
$this->app->singleton('{package}Service', function($app) {
    return new {Package}Service();
});
```

## 5. 컨트롤러 규칙

### 5.1 기본 CRUD 메서드
```php
class {Package}Controller extends Controller
{
    public function index() { }
    public function create() { }
    public function store(Request $request) { }
    public function show($id) { }
    public function edit($id) { }
    public function update(Request $request, $id) { }
    public function destroy($id) { }
}
```

### 5.2 입력 검증 규칙
```php
$validated = $request->validate([
    'name' => 'required|string|max:255',
    'description' => 'nullable|string',
    'active' => 'boolean',
]);
```

## 6. 모델 규칙

### 6.1 기본 구조
```php
class {Package} extends Model
{
    protected $fillable = [
        'name',
        'description',
        'active',
    ];

    protected $casts = [
        'active' => 'boolean',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    // 스코프 메서드들
    public function scopeActive($query) { }
    public function scopeInactive($query) { }
}
```

### 6.2 액세서/뮤테이터 규칙
```php
// 액세서
public function getStatusAttribute() { }

// 뮤테이터
public function setNameAttribute($value) { }
```

## 7. 라우트 규칙

### 7.1 웹 라우트
```php
Route::prefix('{package}')->name('{package}.')->group(function () {
    Route::get('/', [{Package}Controller::class, 'index'])->name('index');
    Route::get('/create', [{Package}Controller::class, 'create'])->name('create');
    Route::post('/', [{Package}Controller::class, 'store'])->name('store');
    Route::get('/{id}', [{Package}Controller::class, 'show'])->name('show');
    Route::get('/{id}/edit', [{Package}Controller::class, 'edit'])->name('edit');
    Route::put('/{id}', [{Package}Controller::class, 'update'])->name('update');
    Route::delete('/{id}', [{Package}Controller::class, 'destroy'])->name('destroy');
});
```

### 7.2 API 라우트
```php
Route::prefix('{package}')->group(function () {
    Route::get('/', [{Package}Controller::class, 'index']);
    Route::post('/', [{Package}Controller::class, 'store']);
    Route::get('/{id}', [{Package}Controller::class, 'show']);
    Route::put('/{id}', [{Package}Controller::class, 'update']);
    Route::delete('/{id}', [{Package}Controller::class, 'destroy']);
});
```

## 8. 뷰 규칙

### 8.1 기본 레이아웃
```blade
@extends('layouts.app')

@section('content')
<div class="container">
    <div class="row justify-content-center">
        <div class="col-md-8">
            <div class="card">
                <div class="card-header">{{ $title ?? '{Package}' }}</div>
                <div class="card-body">
                    @yield('{package}-content')
                </div>
            </div>
        </div>
    </div>
</div>
@endsection
```

### 8.2 테이블 뷰
```blade
<div class="table-responsive">
    <table class="table table-striped">
        <thead>
            <tr>
                <th>ID</th>
                <th>이름</th>
                <th>설명</th>
                <th>상태</th>
                <th>작업</th>
            </tr>
        </thead>
        <tbody>
            @forelse(${package}s as ${package})
                <tr>
                    <td>{{ ${package}->id }}</td>
                    <td>{{ ${package}->name }}</td>
                    <td>{{ ${package}->description }}</td>
                    <td>
                        <span class="badge badge-{{ ${package}->active ? 'success' : 'secondary' }}">
                            {{ ${package}->active ? '활성' : '비활성' }}
                        </span>
                    </td>
                    <td>
                        <div class="btn-group">
                            <a href="{{ route('{package}.show', ${package}->id) }}" class="btn btn-sm btn-info">보기</a>
                            <a href="{{ route('{package}.edit', ${package}->id) }}" class="btn btn-sm btn-warning">수정</a>
                            <form action="{{ route('{package}.destroy', ${package}->id) }}" method="POST" class="d-inline">
                                @csrf
                                @method('DELETE')
                                <button type="submit" class="btn btn-sm btn-danger" onclick="return confirm('정말 삭제하시겠습니까?')">삭제</button>
                            </form>
                        </div>
                    </td>
                </tr>
            @empty
                <tr>
                    <td colspan="5" class="text-center">데이터가 없습니다.</td>
                </tr>
            @endforelse
        </tbody>
    </table>
</div>
```

## 9. 설정 파일 규칙

### 9.1 기본 설정 구조
```php
<?php

return [
    'enabled' => env('{PACKAGE}_ENABLED', true),
    'debug' => env('{PACKAGE}_DEBUG', false),
    'version' => '1.0.0',
    'name' => '{Package}',
    'description' => '{Package} 모듈',
    'per_page' => env('{PACKAGE}_PER_PAGE', 15),
    'cache_ttl' => env('{PACKAGE}_CACHE_TTL', 3600),
];
```

## 10. 테스트 규칙

### 10.1 기능 테스트
```php
class {Package}Test extends TestCase
{
    use RefreshDatabase;

    public function test_index_page() { }
    public function test_create_page() { }
    public function test_store_method() { }
    public function test_show_page() { }
    public function test_edit_page() { }
    public function test_update_method() { }
    public function test_destroy_method() { }
}
```

### 10.2 단위 테스트
```php
class {Package}ServiceTest extends TestCase
{
    use RefreshDatabase;

    public function test_get_all_{package}s() { }
    public function test_get_active_{package}s() { }
    public function test_create_{package}() { }
    public function test_update_{package}() { }
    public function test_delete_{package}() { }
}
```

## 11. 치환 변수 규칙

### 11.1 기본 치환 변수
- `{{package}}` - 패키지명 (소문자)
- `{{package_lower}}` - 패키지명 (소문자)
- `{{package_upper}}` - 패키지명 (대문자)
- `{{package_studly}}` - 패키지명 (StudlyCase)
- `{{Package}}` - 패키지명 (PascalCase)
- `{{namespace}}` - 네임스페이스
- `{{class}}` - 서비스 프로바이더 클래스명
- `{{view_namespace}}` - 뷰 네임스페이스
- `{{module_title}}` - 모듈 제목
- `{{table}}` - 테이블명 (복수형)
- `{{vendor}}` - 벤더명

### 11.2 사용 예시
```bash
# auth 모듈 생성 시
php artisan module:make auth

# 치환 결과
{{package}} → auth
{{Package}} → Auth
{{namespace}} → Jiny\Auth
{{class}} → AuthServiceProvider
{{view_namespace}} → jiny-auth
{{table}} → auths
```

## 12. 성능 최적화 규칙

### 12.1 캐시 사용
```php
public function getAll()
{
    return Cache::tags('{package}')->remember('{package}.all', 3600, function () {
        return {Package}::all();
    });
}
```

### 12.2 N+1 문제 방지
```php
public function index()
{
    ${package}s = {Package}::with(['relations'])->get();
    return view('jiny-{package}::index', compact('{package}s'));
}
```

## 13. 보안 규칙

### 13.1 입력 검증
```php
$validated = $request->validate([
    'name' => 'required|string|max:255',
    'description' => 'nullable|string|max:1000',
    'active' => 'boolean',
]);
```

### 13.2 권한 확인
```php
public function destroy($id)
{
    ${package} = {Package}::findOrFail($id);

    if (!auth()->user()->can('delete', ${package})) {
        abort(403);
    }

    $this->{package}Service->delete($id);
}
```

## 14. 문서화 규칙

### 14.1 README.md 구조
```markdown
# {Package} 모듈

## 개요
{Package} 모듈은 Laravel 기반의 {package} 기능을 제공합니다.

## 설치
```bash
composer require jiny/{package}
```

## 설정
`config/app.php`에 서비스 프로바이더를 등록하세요:
```php
'providers' => [
    Jiny\{Package}\{Package}ServiceProvider::class,
],
```

## 사용법
### 라우트
```php
Route::get('/{package}', [{Package}Controller::class, 'index']);
```

### 뷰
```php
return view('jiny-{package}::index');
```

## 라이선스
MIT License
```

## 15. 배포 규칙

### 15.1 설정 파일 발행
```bash
php artisan vendor:publish --tag={package}-config
```

### 15.2 마이그레이션 실행
```bash
php artisan vendor:publish --tag={package}-migrations
php artisan migrate
```

### 15.3 캐시 클리어
```bash
php artisan config:clear
php artisan route:clear
php artisan view:clear
```

## 16. 커서 사용 지침

### 16.1 모듈 생성 시
- `php artisan module:make {package}` 명령어 사용
- 패키지명은 소문자, 단일 단어로 지정
- 생성된 파일들을 위의 규칙에 따라 수정

### 16.2 모듈 설치 시
- `php artisan module:install {url}` 명령어 사용
- GitHub URL 형식 준수: `https://github.com/owner/repo`
- `--branch` 옵션으로 특정 브랜치 설치 가능
- `--force` 옵션으로 기존 모듈 덮어쓰기 가능

### 16.3 코드 작성 시
- 위의 네이밍 컨벤션을 따라야 함
- 치환 변수를 올바르게 사용해야 함
- 표준 파일 구조를 유지해야 함

### 16.4 문서 작성 시
- README.md는 위의 구조를 따라야 함
- API 문서는 명확하고 구체적으로 작성해야 함
- 예시 코드를 포함해야 함

이 규칙을 따라 Jiny Modules 패키지의 일관성과 품질을 유지하세요.