feat: 구독/결제 API 확장 (Plan, Subscription, Payment)

- Plan/Subscription/Payment 모델에 상태 상수, 스코프, 헬퍼 메서드 추가
- PlanService, SubscriptionService, PaymentService 생성
- PlanController, SubscriptionController, PaymentController 생성
- FormRequest 9개 생성 (Plan 3개, Subscription 3개, Payment 3개)
- Swagger 문서 3개 생성 (PlanApi, SubscriptionApi, PaymentApi)
- API 라우트 22개 등록 (Plan 7개, Subscription 8개, Payment 7개)
- Pint 코드 스타일 정리

app/Models/Tenants/Plan.php

@@ -2,18 +2,68 @@
 
 namespace App\Models\Tenants;
 
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\SoftDeletes;
 
 /**
+ * 요금제 모델
+ *
+ * @property int $id
+ * @property string $name 요금제명
+ * @property string $code 요금제 코드
+ * @property string|null $description 설명
+ * @property float $price 가격
+ * @property string $billing_cycle 결제 주기
+ * @property array|null $features 기능 목록
+ * @property bool $is_active 활성 여부
+ *
  * @mixin IdeHelperPlan
  */
 class Plan extends Model
 {
     use SoftDeletes;
 
+    // =========================================================================
+    // 상수 정의
+    // =========================================================================
+
+    /** 결제 주기 */
+    public const BILLING_MONTHLY = 'monthly';
+
+    public const BILLING_YEARLY = 'yearly';
+
+    public const BILLING_LIFETIME = 'lifetime';
+
+    public const BILLING_CYCLES = [
+        self::BILLING_MONTHLY,
+        self::BILLING_YEARLY,
+        self::BILLING_LIFETIME,
+    ];
+
+    /** 결제 주기 라벨 */
+    public const BILLING_CYCLE_LABELS = [
+        self::BILLING_MONTHLY => '월간',
+        self::BILLING_YEARLY => '연간',
+        self::BILLING_LIFETIME => '평생',
+    ];
+
+    // =========================================================================
+    // 모델 설정
+    // =========================================================================
+
     protected $fillable = [
-        'name', 'code', 'description', 'price', 'billing_cycle', 'features', 'is_active',
+        'name',
+        'code',
+        'description',
+        'price',
+        'billing_cycle',
+        'features',
+        'is_active',
+        'created_by',
+        'updated_by',
+        'deleted_by',
     ];
 
     protected $casts = [
@@ -22,8 +72,103 @@ class Plan extends Model
         'price' => 'float',
     ];
 
-    public function subscriptions()
+    protected $attributes = [
+        'is_active' => true,
+        'billing_cycle' => self::BILLING_MONTHLY,
+    ];
+
+    // =========================================================================
+    // 스코프
+    // =========================================================================
+
+    /**
+     * 활성 요금제만
+     */
+    public function scopeActive(Builder $query): Builder
+    {
+        return $query->where('is_active', true);
+    }
+
+    /**
+     * 결제 주기별 필터
+     */
+    public function scopeOfCycle(Builder $query, string $cycle): Builder
+    {
+        return $query->where('billing_cycle', $cycle);
+    }
+
+    // =========================================================================
+    // 관계
+    // =========================================================================
+
+    public function subscriptions(): HasMany
     {
         return $this->hasMany(Subscription::class);
     }
+
+    // =========================================================================
+    // 접근자
+    // =========================================================================
+
+    /**
+     * 결제 주기 라벨
+     */
+    public function getBillingCycleLabelAttribute(): string
+    {
+        return self::BILLING_CYCLE_LABELS[$this->billing_cycle] ?? $this->billing_cycle;
+    }
+
+    /**
+     * 포맷된 가격
+     */
+    public function getFormattedPriceAttribute(): string
+    {
+        return number_format($this->price).'원';
+    }
+
+    /**
+     * 활성 구독 수
+     */
+    public function getActiveSubscriptionCountAttribute(): int
+    {
+        return $this->subscriptions()
+            ->where('status', Subscription::STATUS_ACTIVE)
+            ->count();
+    }
+
+    // =========================================================================
+    // 헬퍼 메서드
+    // =========================================================================
+
+    /**
+     * 월 환산 가격 계산
+     */
+    public function getMonthlyPrice(): float
+    {
+        return match ($this->billing_cycle) {
+            self::BILLING_YEARLY => round($this->price / 12, 2),
+            self::BILLING_LIFETIME => 0,
+            default => $this->price,
+        };
+    }
+
+    /**
+     * 연 환산 가격 계산
+     */
+    public function getYearlyPrice(): float
+    {
+        return match ($this->billing_cycle) {
+            self::BILLING_MONTHLY => $this->price * 12,
+            self::BILLING_LIFETIME => 0,
+            default => $this->price,
+        };
+    }
+
+    /**
+     * 특정 기능 포함 여부
+     */
+    public function hasFeature(string $feature): bool
+    {
+        return in_array($feature, $this->features ?? [], true);
+    }
 }