feat(API): Model 및 관계 추가

- HandoverReport, HandoverReportItem, HandoverReportManager 모델 추가
- SiteBriefing 모델 추가
- StructureReview, FcmSendLog, Position, Salary 수정
- Order 모델 정리

Co-Authored-By: Claude <noreply@anthropic.com>

app/Models/Construction/HandoverReport.php

@@ -0,0 +1,254 @@
+<?php
+
+namespace App\Models\Construction;
+
+use App\Models\Members\User;
+use App\Traits\BelongsToTenant;
+use App\Traits\ModelTrait;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * 인수인계보고서 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property string $report_number
+ * @property int|null $contract_id
+ * @property string $site_name
+ * @property int|null $partner_id
+ * @property string|null $partner_name
+ * @property int|null $contract_manager_id
+ * @property string|null $contract_manager_name
+ * @property int|null $construction_pm_id
+ * @property string|null $construction_pm_name
+ * @property int $total_sites
+ * @property float $contract_amount
+ * @property string|null $contract_date
+ * @property string|null $contract_start_date
+ * @property string|null $contract_end_date
+ * @property string|null $completion_date
+ * @property string $status
+ * @property bool $has_secondary_piping
+ * @property float $secondary_piping_amount
+ * @property string|null $secondary_piping_note
+ * @property bool $has_coating
+ * @property float $coating_amount
+ * @property string|null $coating_note
+ * @property array|null $external_equipment_cost
+ * @property string|null $special_notes
+ * @property bool $is_active
+ * @property int|null $created_by
+ * @property int|null $updated_by
+ * @property int|null $deleted_by
+ * @property \Illuminate\Support\Carbon|null $created_at
+ * @property \Illuminate\Support\Carbon|null $updated_at
+ * @property \Illuminate\Support\Carbon|null $deleted_at
+ */
+class HandoverReport extends Model
+{
+    use BelongsToTenant, ModelTrait, SoftDeletes;
+
+    protected $table = 'handover_reports';
+
+    // 상태 상수
+    public const STATUS_PENDING = 'pending';
+
+    public const STATUS_COMPLETED = 'completed';
+
+    protected $fillable = [
+        'tenant_id',
+        'report_number',
+        'contract_id',
+        'site_name',
+        'partner_id',
+        'partner_name',
+        'contract_manager_id',
+        'contract_manager_name',
+        'construction_pm_id',
+        'construction_pm_name',
+        'total_sites',
+        'contract_amount',
+        'contract_date',
+        'contract_start_date',
+        'contract_end_date',
+        'completion_date',
+        'status',
+        'has_secondary_piping',
+        'secondary_piping_amount',
+        'secondary_piping_note',
+        'has_coating',
+        'coating_amount',
+        'coating_note',
+        'external_equipment_cost',
+        'special_notes',
+        'is_active',
+        'created_by',
+        'updated_by',
+        'deleted_by',
+    ];
+
+    protected $casts = [
+        'total_sites' => 'integer',
+        'contract_amount' => 'decimal:2',
+        'contract_date' => 'date:Y-m-d',
+        'contract_start_date' => 'date:Y-m-d',
+        'contract_end_date' => 'date:Y-m-d',
+        'completion_date' => 'date:Y-m-d',
+        'has_secondary_piping' => 'boolean',
+        'secondary_piping_amount' => 'decimal:2',
+        'has_coating' => 'boolean',
+        'coating_amount' => 'decimal:2',
+        'external_equipment_cost' => 'array',
+        'is_active' => 'boolean',
+    ];
+
+    protected $attributes = [
+        'is_active' => true,
+        'status' => self::STATUS_PENDING,
+        'total_sites' => 0,
+        'contract_amount' => 0,
+        'has_secondary_piping' => false,
+        'secondary_piping_amount' => 0,
+        'has_coating' => false,
+        'coating_amount' => 0,
+    ];
+
+    // =========================================================================
+    // 관계 정의
+    // =========================================================================
+
+    /**
+     * 연결된 계약
+     */
+    public function contract(): BelongsTo
+    {
+        return $this->belongsTo(Contract::class, 'contract_id');
+    }
+
+    /**
+     * 계약담당자
+     */
+    public function contractManager(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'contract_manager_id');
+    }
+
+    /**
+     * 공사PM
+     */
+    public function constructionPm(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'construction_pm_id');
+    }
+
+    /**
+     * 공사담당자 목록
+     */
+    public function managers(): HasMany
+    {
+        return $this->hasMany(HandoverReportManager::class, 'handover_report_id')
+            ->orderBy('sort_order');
+    }
+
+    /**
+     * 계약 ITEM 목록
+     */
+    public function items(): HasMany
+    {
+        return $this->hasMany(HandoverReportItem::class, 'handover_report_id')
+            ->orderBy('item_no');
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    /**
+     * 수정자
+     */
+    public function updater(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'updated_by');
+    }
+
+    // =========================================================================
+    // 스코프
+    // =========================================================================
+
+    /**
+     * 상태별 필터
+     */
+    public function scopeStatus($query, string $status)
+    {
+        return $query->where('status', $status);
+    }
+
+    /**
+     * 거래처별 필터
+     */
+    public function scopePartner($query, int $partnerId)
+    {
+        return $query->where('partner_id', $partnerId);
+    }
+
+    /**
+     * 계약별 필터
+     */
+    public function scopeContract($query, int $contractId)
+    {
+        return $query->where('contract_id', $contractId);
+    }
+
+    // =========================================================================
+    // 헬퍼 메서드
+    // =========================================================================
+
+    /**
+     * 상태 라벨 반환
+     */
+    public function getStatusLabelAttribute(): string
+    {
+        return match ($this->status) {
+            self::STATUS_PENDING => '인수인계대기',
+            self::STATUS_COMPLETED => '인수인계완료',
+            default => $this->status,
+        };
+    }
+
+    /**
+     * 진행중 여부
+     */
+    public function isPending(): bool
+    {
+        return $this->status === self::STATUS_PENDING;
+    }
+
+    /**
+     * 완료 여부
+     */
+    public function isCompleted(): bool
+    {
+        return $this->status === self::STATUS_COMPLETED;
+    }
+
+    /**
+     * 장비 외 실행금액 합계
+     */
+    public function getExternalEquipmentTotalAttribute(): float
+    {
+        if (! $this->external_equipment_cost) {
+            return 0;
+        }
+
+        return ($this->external_equipment_cost['shipping_cost'] ?? 0)
+            + ($this->external_equipment_cost['high_altitude_work'] ?? 0)
+            + ($this->external_equipment_cost['public_expense'] ?? 0);
+    }
+}

app/Models/Construction/HandoverReportItem.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace App\Models\Construction;
+
+use App\Models\Members\User;
+use App\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 인수인계보고서 계약 ITEM 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property int $handover_report_id
+ * @property int $item_no
+ * @property string $name
+ * @property string|null $product
+ * @property int $quantity
+ * @property string|null $remark
+ * @property int|null $created_by
+ * @property int|null $updated_by
+ * @property \Illuminate\Support\Carbon|null $created_at
+ * @property \Illuminate\Support\Carbon|null $updated_at
+ */
+class HandoverReportItem extends Model
+{
+    use BelongsToTenant;
+
+    protected $table = 'handover_report_items';
+
+    protected $fillable = [
+        'tenant_id',
+        'handover_report_id',
+        'item_no',
+        'name',
+        'product',
+        'quantity',
+        'remark',
+        'created_by',
+        'updated_by',
+    ];
+
+    protected $casts = [
+        'item_no' => 'integer',
+        'quantity' => 'integer',
+    ];
+
+    protected $attributes = [
+        'item_no' => 0,
+        'quantity' => 0,
+    ];
+
+    // =========================================================================
+    // 관계 정의
+    // =========================================================================
+
+    /**
+     * 인수인계보고서
+     */
+    public function handoverReport(): BelongsTo
+    {
+        return $this->belongsTo(HandoverReport::class, 'handover_report_id');
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    /**
+     * 수정자
+     */
+    public function updater(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'updated_by');
+    }
+}

app/Models/Construction/HandoverReportManager.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace App\Models\Construction;
+
+use App\Models\Members\User;
+use App\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 인수인계보고서 공사담당자 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property int $handover_report_id
+ * @property string $name
+ * @property string|null $non_performance_reason
+ * @property string|null $signature
+ * @property int $sort_order
+ * @property int|null $created_by
+ * @property int|null $updated_by
+ * @property \Illuminate\Support\Carbon|null $created_at
+ * @property \Illuminate\Support\Carbon|null $updated_at
+ */
+class HandoverReportManager extends Model
+{
+    use BelongsToTenant;
+
+    protected $table = 'handover_report_managers';
+
+    protected $fillable = [
+        'tenant_id',
+        'handover_report_id',
+        'name',
+        'non_performance_reason',
+        'signature',
+        'sort_order',
+        'created_by',
+        'updated_by',
+    ];
+
+    protected $casts = [
+        'sort_order' => 'integer',
+    ];
+
+    protected $attributes = [
+        'sort_order' => 0,
+    ];
+
+    // =========================================================================
+    // 관계 정의
+    // =========================================================================
+
+    /**
+     * 인수인계보고서
+     */
+    public function handoverReport(): BelongsTo
+    {
+        return $this->belongsTo(HandoverReport::class, 'handover_report_id');
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    /**
+     * 수정자
+     */
+    public function updater(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'updated_by');
+    }
+}

app/Models/Construction/StructureReview.php

@@ -167,4 +167,4 @@ public function isCompleted(): bool
     {
         return $this->status === self::STATUS_COMPLETED;
     }
-}
+}

app/Models/FcmSendLog.php

@@ -131,4 +131,4 @@ public function markAsFailed(string $errorMessage): void
             'completed_at' => now(),
         ]);
     }
-}
+}

app/Models/Orders/Order.php

@@ -2,7 +2,6 @@
 
 namespace App\Models\Orders;
 
-use App\Models\Clients\Client;
 use App\Models\Items\Item;
 use App\Models\Quote\Quote;
 use App\Traits\BelongsToTenant;

app/Models/Tenants/Position.php

@@ -74,4 +74,4 @@ public function scopeOrdered($query)
     {
         return $query->orderBy('sort_order');
     }
-}
+}

app/Models/Tenants/Salary.php

@@ -173,4 +173,4 @@ public function getPeriodLabel(): string
     {
         return sprintf('%d년 %d월', $this->year, $this->month);
     }
-}
+}

app/Models/Tenants/SiteBriefing.php

@@ -0,0 +1,304 @@
+<?php
+
+namespace App\Models\Tenants;
+
+use App\Models\Members\User;
+use App\Models\Orders\Client;
+use App\Models\Quote\Quote;
+use App\Traits\BelongsToTenant;
+use App\Traits\ModelTrait;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * 현장설명회 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property string|null $briefing_code 현설번호
+ * @property string $title 현장설명회명
+ * @property string|null $description 설명
+ * @property int|null $partner_id 거래처 ID
+ * @property int|null $site_id 현장 ID
+ * @property string $briefing_date 현장설명회 일자
+ * @property string|null $briefing_time 현장설명회 시간
+ * @property string $briefing_type 구분 (online|offline)
+ * @property string|null $location 장소
+ * @property string|null $address 주소
+ * @property string $status 상태
+ * @property string $bid_status 입찰상태
+ * @property string|null $bid_date 입찰일자
+ * @property array|null $attendees 참석자 목록 (JSON)
+ * @property string $attendance_status 참석상태
+ * @property int $attendee_count 총 참석자 수
+ * @property int $site_count 개소 수
+ * @property string|null $construction_start_date 공사기간 시작
+ * @property string|null $construction_end_date 공사기간 종료
+ * @property string $vat_type 부가세 타입
+ * @property int|null $created_by
+ * @property int|null $updated_by
+ * @property int|null $deleted_by
+ * @property-read Client|null $partner
+ * @property-read Site|null $site
+ */
+class SiteBriefing extends Model
+{
+    use BelongsToTenant, ModelTrait, SoftDeletes;
+
+    protected $table = 'site_briefings';
+
+    // 상태 상수
+    public const STATUS_SCHEDULED = 'scheduled';
+
+    public const STATUS_ONGOING = 'ongoing';
+
+    public const STATUS_COMPLETED = 'completed';
+
+    public const STATUS_CANCELLED = 'cancelled';
+
+    public const STATUS_POSTPONED = 'postponed';
+
+    public const STATUSES = [
+        self::STATUS_SCHEDULED,
+        self::STATUS_ONGOING,
+        self::STATUS_COMPLETED,
+        self::STATUS_CANCELLED,
+        self::STATUS_POSTPONED,
+    ];
+
+    // 입찰 상태 상수
+    public const BID_STATUS_PENDING = 'pending';
+
+    public const BID_STATUS_BIDDING = 'bidding';
+
+    public const BID_STATUS_CLOSED = 'closed';
+
+    public const BID_STATUS_FAILED = 'failed';
+
+    public const BID_STATUS_AWARDED = 'awarded';
+
+    public const BID_STATUSES = [
+        self::BID_STATUS_PENDING,
+        self::BID_STATUS_BIDDING,
+        self::BID_STATUS_CLOSED,
+        self::BID_STATUS_FAILED,
+        self::BID_STATUS_AWARDED,
+    ];
+
+    // 구분 상수
+    public const TYPE_ONLINE = 'online';
+
+    public const TYPE_OFFLINE = 'offline';
+
+    public const TYPES = [
+        self::TYPE_ONLINE,
+        self::TYPE_OFFLINE,
+    ];
+
+    // 참석 상태 상수
+    public const ATTENDANCE_SCHEDULED = 'scheduled';
+
+    public const ATTENDANCE_ATTENDED = 'attended';
+
+    public const ATTENDANCE_ABSENT = 'absent';
+
+    public const ATTENDANCE_STATUSES = [
+        self::ATTENDANCE_SCHEDULED,
+        self::ATTENDANCE_ATTENDED,
+        self::ATTENDANCE_ABSENT,
+    ];
+
+    // 부가세 상수
+    public const VAT_EXCLUDED = 'excluded';
+
+    public const VAT_INCLUDED = 'included';
+
+    public const VAT_TYPES = [
+        self::VAT_EXCLUDED,
+        self::VAT_INCLUDED,
+    ];
+
+    protected $fillable = [
+        'tenant_id',
+        'briefing_code',
+        'title',
+        'description',
+        'partner_id',
+        'site_id',
+        'briefing_date',
+        'briefing_time',
+        'briefing_type',
+        'location',
+        'address',
+        'status',
+        'bid_status',
+        'bid_date',
+        'attendees',
+        'attendance_status',
+        'attendee_count',
+        'site_count',
+        'construction_start_date',
+        'construction_end_date',
+        'vat_type',
+        'created_by',
+        'updated_by',
+        'deleted_by',
+    ];
+
+    protected $casts = [
+        'briefing_date' => 'date:Y-m-d',
+        'bid_date' => 'date:Y-m-d',
+        'construction_start_date' => 'date:Y-m-d',
+        'construction_end_date' => 'date:Y-m-d',
+        'attendees' => 'array',
+        'attendee_count' => 'integer',
+        'site_count' => 'integer',
+    ];
+
+    protected $attributes = [
+        'briefing_type' => self::TYPE_OFFLINE,
+        'status' => self::STATUS_SCHEDULED,
+        'bid_status' => self::BID_STATUS_PENDING,
+        'attendance_status' => self::ATTENDANCE_SCHEDULED,
+        'vat_type' => self::VAT_EXCLUDED,
+        'attendee_count' => 0,
+        'site_count' => 0,
+    ];
+
+    // =========================================================================
+    // 관계 정의
+    // =========================================================================
+
+    /**
+     * 거래처
+     */
+    public function partner(): BelongsTo
+    {
+        return $this->belongsTo(Client::class, 'partner_id');
+    }
+
+    /**
+     * 현장
+     */
+    public function site(): BelongsTo
+    {
+        return $this->belongsTo(Site::class);
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    /**
+     * 수정자
+     */
+    public function updater(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'updated_by');
+    }
+
+    /**
+     * 견적들 (현장설명회에서 자동생성된 견적)
+     */
+    public function quotes(): HasMany
+    {
+        return $this->hasMany(Quote::class);
+    }
+
+    // =========================================================================
+    // Accessors
+    // =========================================================================
+
+    /**
+     * 거래처명 (partner.name)
+     */
+    public function getPartnerNameAttribute(): ?string
+    {
+        return $this->partner?->name;
+    }
+
+    /**
+     * 현장명 (site.name)
+     */
+    public function getSiteNameAttribute(): ?string
+    {
+        return $this->site?->name;
+    }
+
+    /**
+     * API 응답에 자동 추가할 속성
+     */
+    protected $appends = ['partner_name', 'site_name'];
+
+    // =========================================================================
+    // 스코프
+    // =========================================================================
+
+    /**
+     * 상태별 필터
+     */
+    public function scopeStatus($query, string $status)
+    {
+        return $query->where('status', $status);
+    }
+
+    /**
+     * 입찰상태별 필터
+     */
+    public function scopeBidStatus($query, string $bidStatus)
+    {
+        return $query->where('bid_status', $bidStatus);
+    }
+
+    /**
+     * 날짜 범위 필터
+     */
+    public function scopeDateRange($query, ?string $startDate, ?string $endDate)
+    {
+        if ($startDate) {
+            $query->where('briefing_date', '>=', $startDate);
+        }
+        if ($endDate) {
+            $query->where('briefing_date', '<=', $endDate);
+        }
+
+        return $query;
+    }
+
+    // =========================================================================
+    // 헬퍼 메서드
+    // =========================================================================
+
+    /**
+     * 현설번호 생성
+     * 형식: SB-YYYYMM-XXXX (예: SB-202601-0001)
+     */
+    public static function generateBriefingCode(int $tenantId): string
+    {
+        $prefix = 'SB';
+        $yearMonth = now()->format('Ym');
+
+        // 해당 월의 마지막 번호 조회
+        $lastCode = self::withoutGlobalScopes()
+            ->where('tenant_id', $tenantId)
+            ->where('briefing_code', 'like', "{$prefix}-{$yearMonth}-%")
+            ->orderBy('briefing_code', 'desc')
+            ->value('briefing_code');
+
+        if ($lastCode) {
+            // 기존 번호에서 시퀀스 추출
+            $lastSequence = (int) substr($lastCode, -4);
+            $newSequence = $lastSequence + 1;
+        } else {
+            $newSequence = 1;
+        }
+
+        return sprintf('%s-%s-%04d', $prefix, $yearMonth, $newSequence);
+    }
+}