feat: [시공관리] 계약관리 API 구현

- Contract 모델, 마이그레이션 추가 - ContractController CRUD 엔드포인트 구현 - ContractService 비즈니스 로직 구현 - ContractStoreRequest, ContractUpdateRequest 검증 추가 - Swagger API 문서 작성 - 라우트 등록 (GET/POST/PUT/DELETE) - 통계 및 단계별 건수 조회 API 추가 Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-09 10:18:43 +09:00
parent 349917f019
commit 3a8af2d7ee
9 changed files with 1188 additions and 0 deletions
--- a/app/Http/Controllers/Api/V1/Construction/ContractController.php
+++ b/app/Http/Controllers/Api/V1/Construction/ContractController.php
@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Construction;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Construction\ContractStoreRequest;
+use App\Http\Requests\Construction\ContractUpdateRequest;
+use App\Services\Construction\ContractService;
+use Illuminate\Http\Request;
+
+class ContractController extends Controller
+{
+    public function __construct(private ContractService $service) {}
+
+    /**
+     * 계약 목록 조회
+     */
+    public function index(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->index($request->all());
+        }, __('message.contract.fetched'));
+    }
+
+    /**
+     * 계약 상세 조회
+     */
+    public function show(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->show($id);
+        }, __('message.contract.fetched'));
+    }
+
+    /**
+     * 계약 등록
+     */
+    public function store(ContractStoreRequest $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->store($request->validated());
+        }, __('message.contract.created'));
+    }
+
+    /**
+     * 계약 수정
+     */
+    public function update(ContractUpdateRequest $request, int $id)
+    {
+        return ApiResponse::handle(function () use ($request, $id) {
+            return $this->service->update($id, $request->validated());
+        }, __('message.contract.updated'));
+    }
+
+    /**
+     * 계약 삭제
+     */
+    public function destroy(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $this->service->destroy($id);
+
+            return 'success';
+        }, __('message.contract.deleted'));
+    }
+
+    /**
+     * 계약 일괄 삭제
+     */
+    public function bulkDestroy(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $this->service->bulkDestroy($request->input('ids', []));
+
+            return 'success';
+        }, __('message.contract.deleted'));
+    }
+
+    /**
+     * 계약 통계 조회
+     */
+    public function stats(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->stats($request->all());
+        }, __('message.contract.fetched'));
+    }
+
+    /**
+     * 계약 단계별 카운트 조회
+     */
+    public function stageCounts(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->stageCounts($request->all());
+        }, __('message.contract.fetched'));
+    }
+}
--- a/app/Http/Requests/Construction/ContractStoreRequest.php
+++ b/app/Http/Requests/Construction/ContractStoreRequest.php
@@ -0,0 +1,75 @@
+<?php
+
+namespace App\Http\Requests\Construction;
+
+use App\Models\Construction\Contract;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class ContractStoreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            // 기본 정보
+            'contract_code' => 'required|string|max:50',
+            'project_name' => 'required|string|max:255',
+
+            // 거래처 정보
+            'partner_id' => 'nullable|integer',
+            'partner_name' => 'nullable|string|max:255',
+
+            // 담당자 정보
+            'contract_manager_id' => 'nullable|integer',
+            'contract_manager_name' => 'nullable|string|max:100',
+            'construction_pm_id' => 'nullable|integer',
+            'construction_pm_name' => 'nullable|string|max:100',
+
+            // 계약 상세
+            'total_locations' => 'nullable|integer|min:0',
+            'contract_amount' => 'nullable|numeric|min:0',
+            'contract_start_date' => 'nullable|date',
+            'contract_end_date' => 'nullable|date|after_or_equal:contract_start_date',
+
+            // 상태 정보
+            'status' => [
+                'nullable',
+                Rule::in([Contract::STATUS_PENDING, Contract::STATUS_COMPLETED]),
+            ],
+            'stage' => [
+                'nullable',
+                Rule::in([
+                    Contract::STAGE_ESTIMATE_SELECTED,
+                    Contract::STAGE_ESTIMATE_PROGRESS,
+                    Contract::STAGE_DELIVERY,
+                    Contract::STAGE_INSTALLATION,
+                    Contract::STAGE_INSPECTION,
+                    Contract::STAGE_OTHER,
+                ]),
+            ],
+
+            // 연결 정보
+            'bidding_id' => 'nullable|integer',
+            'bidding_code' => 'nullable|string|max:50',
+
+            // 기타
+            'remarks' => 'nullable|string',
+            'is_active' => 'nullable|boolean',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'contract_code.required' => __('validation.required', ['attribute' => '계약번호']),
+            'contract_code.max' => __('validation.max.string', ['attribute' => '계약번호', 'max' => 50]),
+            'project_name.required' => __('validation.required', ['attribute' => '현장명']),
+            'contract_end_date.after_or_equal' => __('validation.after_or_equal', ['attribute' => '계약종료일', 'date' => '계약시작일']),
+        ];
+    }
+}
--- a/app/Http/Requests/Construction/ContractUpdateRequest.php
+++ b/app/Http/Requests/Construction/ContractUpdateRequest.php
@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Http\Requests\Construction;
+
+use App\Models\Construction\Contract;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class ContractUpdateRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            // 기본 정보
+            'contract_code' => 'sometimes|string|max:50',
+            'project_name' => 'sometimes|string|max:255',
+
+            // 거래처 정보
+            'partner_id' => 'nullable|integer',
+            'partner_name' => 'nullable|string|max:255',
+
+            // 담당자 정보
+            'contract_manager_id' => 'nullable|integer',
+            'contract_manager_name' => 'nullable|string|max:100',
+            'construction_pm_id' => 'nullable|integer',
+            'construction_pm_name' => 'nullable|string|max:100',
+
+            // 계약 상세
+            'total_locations' => 'nullable|integer|min:0',
+            'contract_amount' => 'nullable|numeric|min:0',
+            'contract_start_date' => 'nullable|date',
+            'contract_end_date' => 'nullable|date|after_or_equal:contract_start_date',
+
+            // 상태 정보
+            'status' => [
+                'nullable',
+                Rule::in([Contract::STATUS_PENDING, Contract::STATUS_COMPLETED]),
+            ],
+            'stage' => [
+                'nullable',
+                Rule::in([
+                    Contract::STAGE_ESTIMATE_SELECTED,
+                    Contract::STAGE_ESTIMATE_PROGRESS,
+                    Contract::STAGE_DELIVERY,
+                    Contract::STAGE_INSTALLATION,
+                    Contract::STAGE_INSPECTION,
+                    Contract::STAGE_OTHER,
+                ]),
+            ],
+
+            // 연결 정보
+            'bidding_id' => 'nullable|integer',
+            'bidding_code' => 'nullable|string|max:50',
+
+            // 기타
+            'remarks' => 'nullable|string',
+            'is_active' => 'nullable|boolean',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'contract_code.max' => __('validation.max.string', ['attribute' => '계약번호', 'max' => 50]),
+            'contract_end_date.after_or_equal' => __('validation.after_or_equal', ['attribute' => '계약종료일', 'date' => '계약시작일']),
+        ];
+    }
+}
--- a/app/Models/Construction/Contract.php
+++ b/app/Models/Construction/Contract.php
@@ -0,0 +1,218 @@
+<?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\SoftDeletes;
+
+/**
+ * 계약 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property string $contract_code
+ * @property string $project_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_locations
+ * @property float $contract_amount
+ * @property string|null $contract_start_date
+ * @property string|null $contract_end_date
+ * @property string $status
+ * @property string $stage
+ * @property int|null $bidding_id
+ * @property string|null $bidding_code
+ * @property string|null $remarks
+ * @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 Contract extends Model
+{
+    use BelongsToTenant, ModelTrait, SoftDeletes;
+
+    protected $table = 'contracts';
+
+    // 상태 상수
+    public const STATUS_PENDING = 'pending';
+
+    public const STATUS_COMPLETED = 'completed';
+
+    // 단계 상수
+    public const STAGE_ESTIMATE_SELECTED = 'estimate_selected';
+
+    public const STAGE_ESTIMATE_PROGRESS = 'estimate_progress';
+
+    public const STAGE_DELIVERY = 'delivery';
+
+    public const STAGE_INSTALLATION = 'installation';
+
+    public const STAGE_INSPECTION = 'inspection';
+
+    public const STAGE_OTHER = 'other';
+
+    protected $fillable = [
+        'tenant_id',
+        'contract_code',
+        'project_name',
+        'partner_id',
+        'partner_name',
+        'contract_manager_id',
+        'contract_manager_name',
+        'construction_pm_id',
+        'construction_pm_name',
+        'total_locations',
+        'contract_amount',
+        'contract_start_date',
+        'contract_end_date',
+        'status',
+        'stage',
+        'bidding_id',
+        'bidding_code',
+        'remarks',
+        'is_active',
+        'created_by',
+        'updated_by',
+        'deleted_by',
+    ];
+
+    protected $casts = [
+        'total_locations' => 'integer',
+        'contract_amount' => 'decimal:2',
+        'contract_start_date' => 'date:Y-m-d',
+        'contract_end_date' => 'date:Y-m-d',
+        'is_active' => 'boolean',
+    ];
+
+    protected $attributes = [
+        'is_active' => true,
+        'status' => self::STATUS_PENDING,
+        'stage' => self::STAGE_ESTIMATE_SELECTED,
+        'total_locations' => 0,
+        'contract_amount' => 0,
+    ];
+
+    // =========================================================================
+    // 관계 정의
+    // =========================================================================
+
+    /**
+     * 계약담당자
+     */
+    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 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 scopeStage($query, string $stage)
+    {
+        return $query->where('stage', $stage);
+    }
+
+    /**
+     * 거래처별 필터
+     */
+    public function scopePartner($query, int $partnerId)
+    {
+        return $query->where('partner_id', $partnerId);
+    }
+
+    // =========================================================================
+    // 헬퍼 메서드
+    // =========================================================================
+
+    /**
+     * 상태 라벨 반환
+     */
+    public function getStatusLabelAttribute(): string
+    {
+        return match ($this->status) {
+            self::STATUS_PENDING => '계약대기',
+            self::STATUS_COMPLETED => '계약완료',
+            default => $this->status,
+        };
+    }
+
+    /**
+     * 단계 라벨 반환
+     */
+    public function getStageLabelAttribute(): string
+    {
+        return match ($this->stage) {
+            self::STAGE_ESTIMATE_SELECTED => '견적선정',
+            self::STAGE_ESTIMATE_PROGRESS => '견적진행',
+            self::STAGE_DELIVERY => '납품',
+            self::STAGE_INSTALLATION => '설치중',
+            self::STAGE_INSPECTION => '검수',
+            self::STAGE_OTHER => '기타',
+            default => $this->stage,
+        };
+    }
+
+    /**
+     * 진행중 여부
+     */
+    public function isPending(): bool
+    {
+        return $this->status === self::STATUS_PENDING;
+    }
+
+    /**
+     * 완료 여부
+     */
+    public function isCompleted(): bool
+    {
+        return $this->status === self::STATUS_COMPLETED;
+    }
+}
--- a/app/Services/Construction/ContractService.php
+++ b/app/Services/Construction/ContractService.php
@@ -0,0 +1,283 @@
+<?php
+
+namespace App\Services\Construction;
+
+use App\Models\Construction\Contract;
+use App\Services\Service;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Facades\DB;
+
+class ContractService extends Service
+{
+    /**
+     * 계약 목록 조회
+     */
+    public function index(array $params): LengthAwarePaginator
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Contract::query()
+            ->where('tenant_id', $tenantId);
+
+        // 검색 필터
+        if (! empty($params['search'])) {
+            $search = $params['search'];
+            $query->where(function ($q) use ($search) {
+                $q->where('contract_code', 'like', "%{$search}%")
+                    ->orWhere('project_name', 'like', "%{$search}%")
+                    ->orWhere('partner_name', 'like', "%{$search}%");
+            });
+        }
+
+        // 상태 필터
+        if (! empty($params['status'])) {
+            $query->where('status', $params['status']);
+        }
+
+        // 단계 필터
+        if (! empty($params['stage'])) {
+            $query->where('stage', $params['stage']);
+        }
+
+        // 거래처 필터
+        if (! empty($params['partner_id'])) {
+            $query->where('partner_id', $params['partner_id']);
+        }
+
+        // 계약담당자 필터
+        if (! empty($params['contract_manager_id'])) {
+            $query->where('contract_manager_id', $params['contract_manager_id']);
+        }
+
+        // 공사PM 필터
+        if (! empty($params['construction_pm_id'])) {
+            $query->where('construction_pm_id', $params['construction_pm_id']);
+        }
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('contract_start_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('contract_end_date', '<=', $params['end_date']);
+        }
+
+        // 활성화 상태 필터
+        if (isset($params['is_active'])) {
+            $query->where('is_active', $params['is_active']);
+        }
+
+        // 정렬
+        $sortBy = $params['sort_by'] ?? 'created_at';
+        $sortDir = $params['sort_dir'] ?? 'desc';
+        $query->orderBy($sortBy, $sortDir);
+
+        // 페이지네이션
+        $perPage = $params['per_page'] ?? 20;
+
+        return $query->paginate($perPage);
+    }
+
+    /**
+     * 계약 상세 조회
+     */
+    public function show(int $id): Contract
+    {
+        $tenantId = $this->tenantId();
+
+        return Contract::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['contractManager', 'constructionPm', 'creator', 'updater'])
+            ->findOrFail($id);
+    }
+
+    /**
+     * 계약 등록
+     */
+    public function store(array $data): Contract
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($data, $tenantId, $userId) {
+            $contract = Contract::create([
+                'tenant_id' => $tenantId,
+                'contract_code' => $data['contract_code'],
+                'project_name' => $data['project_name'],
+                'partner_id' => $data['partner_id'] ?? null,
+                'partner_name' => $data['partner_name'] ?? null,
+                'contract_manager_id' => $data['contract_manager_id'] ?? null,
+                'contract_manager_name' => $data['contract_manager_name'] ?? null,
+                'construction_pm_id' => $data['construction_pm_id'] ?? null,
+                'construction_pm_name' => $data['construction_pm_name'] ?? null,
+                'total_locations' => $data['total_locations'] ?? 0,
+                'contract_amount' => $data['contract_amount'] ?? 0,
+                'contract_start_date' => $data['contract_start_date'] ?? null,
+                'contract_end_date' => $data['contract_end_date'] ?? null,
+                'status' => $data['status'] ?? Contract::STATUS_PENDING,
+                'stage' => $data['stage'] ?? Contract::STAGE_ESTIMATE_SELECTED,
+                'bidding_id' => $data['bidding_id'] ?? null,
+                'bidding_code' => $data['bidding_code'] ?? null,
+                'remarks' => $data['remarks'] ?? null,
+                'is_active' => $data['is_active'] ?? true,
+                'created_by' => $userId,
+                'updated_by' => $userId,
+            ]);
+
+            return $contract;
+        });
+    }
+
+    /**
+     * 계약 수정
+     */
+    public function update(int $id, array $data): Contract
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($id, $data, $tenantId, $userId) {
+            $contract = Contract::query()
+                ->where('tenant_id', $tenantId)
+                ->findOrFail($id);
+
+            $contract->fill([
+                'contract_code' => $data['contract_code'] ?? $contract->contract_code,
+                'project_name' => $data['project_name'] ?? $contract->project_name,
+                'partner_id' => $data['partner_id'] ?? $contract->partner_id,
+                'partner_name' => $data['partner_name'] ?? $contract->partner_name,
+                'contract_manager_id' => $data['contract_manager_id'] ?? $contract->contract_manager_id,
+                'contract_manager_name' => $data['contract_manager_name'] ?? $contract->contract_manager_name,
+                'construction_pm_id' => $data['construction_pm_id'] ?? $contract->construction_pm_id,
+                'construction_pm_name' => $data['construction_pm_name'] ?? $contract->construction_pm_name,
+                'total_locations' => $data['total_locations'] ?? $contract->total_locations,
+                'contract_amount' => $data['contract_amount'] ?? $contract->contract_amount,
+                'contract_start_date' => $data['contract_start_date'] ?? $contract->contract_start_date,
+                'contract_end_date' => $data['contract_end_date'] ?? $contract->contract_end_date,
+                'status' => $data['status'] ?? $contract->status,
+                'stage' => $data['stage'] ?? $contract->stage,
+                'bidding_id' => $data['bidding_id'] ?? $contract->bidding_id,
+                'bidding_code' => $data['bidding_code'] ?? $contract->bidding_code,
+                'remarks' => $data['remarks'] ?? $contract->remarks,
+                'is_active' => $data['is_active'] ?? $contract->is_active,
+                'updated_by' => $userId,
+            ]);
+
+            $contract->save();
+
+            return $contract->fresh();
+        });
+    }
+
+    /**
+     * 계약 삭제
+     */
+    public function destroy(int $id): bool
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($id, $tenantId, $userId) {
+            $contract = Contract::query()
+                ->where('tenant_id', $tenantId)
+                ->findOrFail($id);
+
+            $contract->deleted_by = $userId;
+            $contract->save();
+            $contract->delete();
+
+            return true;
+        });
+    }
+
+    /**
+     * 계약 일괄 삭제
+     */
+    public function bulkDestroy(array $ids): bool
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($ids, $tenantId, $userId) {
+            $contracts = Contract::query()
+                ->where('tenant_id', $tenantId)
+                ->whereIn('id', $ids)
+                ->get();
+
+            foreach ($contracts as $contract) {
+                $contract->deleted_by = $userId;
+                $contract->save();
+                $contract->delete();
+            }
+
+            return true;
+        });
+    }
+
+    /**
+     * 계약 통계 조회
+     */
+    public function stats(array $params): array
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Contract::query()
+            ->where('tenant_id', $tenantId);
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('contract_start_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('contract_end_date', '<=', $params['end_date']);
+        }
+
+        $totalCount = (clone $query)->count();
+        $pendingCount = (clone $query)->where('status', Contract::STATUS_PENDING)->count();
+        $completedCount = (clone $query)->where('status', Contract::STATUS_COMPLETED)->count();
+        $totalAmount = (clone $query)->sum('contract_amount');
+        $totalLocations = (clone $query)->sum('total_locations');
+
+        return [
+            'total_count' => $totalCount,
+            'pending_count' => $pendingCount,
+            'completed_count' => $completedCount,
+            'total_amount' => (float) $totalAmount,
+            'total_locations' => (int) $totalLocations,
+        ];
+    }
+
+    /**
+     * 계약 단계별 카운트 조회
+     */
+    public function stageCounts(array $params): array
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Contract::query()
+            ->where('tenant_id', $tenantId);
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('contract_start_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('contract_end_date', '<=', $params['end_date']);
+        }
+
+        $stageCounts = (clone $query)
+            ->select('stage', DB::raw('COUNT(*) as count'))
+            ->groupBy('stage')
+            ->pluck('count', 'stage')
+            ->toArray();
+
+        return [
+            'estimate_selected' => $stageCounts[Contract::STAGE_ESTIMATE_SELECTED] ?? 0,
+            'estimate_progress' => $stageCounts[Contract::STAGE_ESTIMATE_PROGRESS] ?? 0,
+            'delivery' => $stageCounts[Contract::STAGE_DELIVERY] ?? 0,
+            'installation' => $stageCounts[Contract::STAGE_INSTALLATION] ?? 0,
+            'inspection' => $stageCounts[Contract::STAGE_INSPECTION] ?? 0,
+            'other' => $stageCounts[Contract::STAGE_OTHER] ?? 0,
+        ];
+    }
+}
--- a/app/Swagger/v1/ContractApi.php
+++ b/app/Swagger/v1/ContractApi.php
@@ -0,0 +1,339 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="Contract", description="시공관리 - 계약관리")
+ *
+ * @OA\Schema(
+ *   schema="Contract",
+ *   type="object",
+ *   required={"id","contract_code","project_name"},
+ *
+ *   @OA\Property(property="id", type="integer", example=1),
+ *   @OA\Property(property="tenant_id", type="integer", example=1),
+ *   @OA\Property(property="contract_code", type="string", maxLength=50, example="CT-2026-001", description="계약번호"),
+ *   @OA\Property(property="project_name", type="string", maxLength=255, example="서울 A타워 시공", description="현장명"),
+ *   @OA\Property(property="partner_id", type="integer", nullable=true, example=1, description="거래처 ID"),
+ *   @OA\Property(property="partner_name", type="string", nullable=true, maxLength=255, example="ABC건설", description="거래처명"),
+ *   @OA\Property(property="contract_manager_id", type="integer", nullable=true, example=1, description="계약담당자 ID"),
+ *   @OA\Property(property="contract_manager_name", type="string", nullable=true, maxLength=100, example="홍길동", description="계약담당자명"),
+ *   @OA\Property(property="construction_pm_id", type="integer", nullable=true, example=2, description="공사PM ID"),
+ *   @OA\Property(property="construction_pm_name", type="string", nullable=true, maxLength=100, example="김철수", description="공사PM명"),
+ *   @OA\Property(property="total_locations", type="integer", example=15, description="총 개소수"),
+ *   @OA\Property(property="contract_amount", type="number", format="float", example=150000000, description="계약금액"),
+ *   @OA\Property(property="contract_start_date", type="string", format="date", nullable=true, example="2026-01-01", description="계약시작일"),
+ *   @OA\Property(property="contract_end_date", type="string", format="date", nullable=true, example="2026-12-31", description="계약종료일"),
+ *   @OA\Property(property="status", type="string", enum={"pending", "completed"}, example="pending", description="상태 (pending: 계약대기, completed: 계약완료)"),
+ *   @OA\Property(property="stage", type="string", enum={"estimate_selected", "estimate_progress", "delivery", "installation", "inspection", "other"}, example="estimate_selected", description="단계 (estimate_selected: 견적선정, estimate_progress: 견적진행, delivery: 납품, installation: 설치중, inspection: 검수, other: 기타)"),
+ *   @OA\Property(property="bidding_id", type="integer", nullable=true, example=1, description="입찰 ID"),
+ *   @OA\Property(property="bidding_code", type="string", nullable=true, maxLength=50, example="BID-2025-001", description="입찰번호"),
+ *   @OA\Property(property="remarks", type="string", nullable=true, example="특이사항 없음", description="비고"),
+ *   @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부"),
+ *   @OA\Property(property="created_by", type="integer", nullable=true, example=1),
+ *   @OA\Property(property="updated_by", type="integer", nullable=true, example=1),
+ *   @OA\Property(property="created_at", type="string", example="2026-01-08 12:00:00"),
+ *   @OA\Property(property="updated_at", type="string", example="2026-01-08 12:00:00")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ContractPagination",
+ *   type="object",
+ *
+ *   @OA\Property(property="current_page", type="integer", example=1),
+ *   @OA\Property(
+ *     property="data",
+ *     type="array",
+ *
+ *     @OA\Items(ref="#/components/schemas/Contract")
+ *   ),
+ *
+ *   @OA\Property(property="first_page_url", type="string", example="/api/v1/construction/contracts?page=1"),
+ *   @OA\Property(property="from", type="integer", example=1),
+ *   @OA\Property(property="last_page", type="integer", example=3),
+ *   @OA\Property(property="last_page_url", type="string", example="/api/v1/construction/contracts?page=3"),
+ *   @OA\Property(
+ *     property="links",
+ *     type="array",
+ *
+ *     @OA\Items(type="object",
+ *
+ *       @OA\Property(property="url", type="string", nullable=true, example=null),
+ *       @OA\Property(property="label", type="string", example="&laquo; Previous"),
+ *       @OA\Property(property="active", type="boolean", example=false)
+ *     )
+ *   ),
+ *   @OA\Property(property="next_page_url", type="string", nullable=true, example="/api/v1/construction/contracts?page=2"),
+ *   @OA\Property(property="path", type="string", example="/api/v1/construction/contracts"),
+ *   @OA\Property(property="per_page", type="integer", example=20),
+ *   @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
+ *   @OA\Property(property="to", type="integer", example=20),
+ *   @OA\Property(property="total", type="integer", example=50)
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ContractCreateRequest",
+ *   type="object",
+ *   required={"contract_code","project_name"},
+ *
+ *   @OA\Property(property="contract_code", type="string", maxLength=50, example="CT-2026-001", description="계약번호"),
+ *   @OA\Property(property="project_name", type="string", maxLength=255, example="서울 A타워 시공", description="현장명"),
+ *   @OA\Property(property="partner_id", type="integer", nullable=true, example=1, description="거래처 ID"),
+ *   @OA\Property(property="partner_name", type="string", nullable=true, maxLength=255, example="ABC건설", description="거래처명"),
+ *   @OA\Property(property="contract_manager_id", type="integer", nullable=true, example=1, description="계약담당자 ID"),
+ *   @OA\Property(property="contract_manager_name", type="string", nullable=true, maxLength=100, example="홍길동", description="계약담당자명"),
+ *   @OA\Property(property="construction_pm_id", type="integer", nullable=true, example=2, description="공사PM ID"),
+ *   @OA\Property(property="construction_pm_name", type="string", nullable=true, maxLength=100, example="김철수", description="공사PM명"),
+ *   @OA\Property(property="total_locations", type="integer", nullable=true, example=15, description="총 개소수"),
+ *   @OA\Property(property="contract_amount", type="number", format="float", nullable=true, example=150000000, description="계약금액"),
+ *   @OA\Property(property="contract_start_date", type="string", format="date", nullable=true, example="2026-01-01", description="계약시작일"),
+ *   @OA\Property(property="contract_end_date", type="string", format="date", nullable=true, example="2026-12-31", description="계약종료일"),
+ *   @OA\Property(property="status", type="string", enum={"pending", "completed"}, nullable=true, example="pending", description="상태"),
+ *   @OA\Property(property="stage", type="string", enum={"estimate_selected", "estimate_progress", "delivery", "installation", "inspection", "other"}, nullable=true, example="estimate_selected", description="단계"),
+ *   @OA\Property(property="bidding_id", type="integer", nullable=true, example=1, description="입찰 ID"),
+ *   @OA\Property(property="bidding_code", type="string", nullable=true, maxLength=50, example="BID-2025-001", description="입찰번호"),
+ *   @OA\Property(property="remarks", type="string", nullable=true, example="특이사항 없음", description="비고"),
+ *   @OA\Property(property="is_active", type="boolean", nullable=true, example=true, description="활성 여부")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ContractUpdateRequest",
+ *   type="object",
+ *
+ *   @OA\Property(property="contract_code", type="string", maxLength=50, description="계약번호"),
+ *   @OA\Property(property="project_name", type="string", maxLength=255, description="현장명"),
+ *   @OA\Property(property="partner_id", type="integer", nullable=true, description="거래처 ID"),
+ *   @OA\Property(property="partner_name", type="string", nullable=true, maxLength=255, description="거래처명"),
+ *   @OA\Property(property="contract_manager_id", type="integer", nullable=true, description="계약담당자 ID"),
+ *   @OA\Property(property="contract_manager_name", type="string", nullable=true, maxLength=100, description="계약담당자명"),
+ *   @OA\Property(property="construction_pm_id", type="integer", nullable=true, description="공사PM ID"),
+ *   @OA\Property(property="construction_pm_name", type="string", nullable=true, maxLength=100, description="공사PM명"),
+ *   @OA\Property(property="total_locations", type="integer", nullable=true, description="총 개소수"),
+ *   @OA\Property(property="contract_amount", type="number", format="float", nullable=true, description="계약금액"),
+ *   @OA\Property(property="contract_start_date", type="string", format="date", nullable=true, description="계약시작일"),
+ *   @OA\Property(property="contract_end_date", type="string", format="date", nullable=true, description="계약종료일"),
+ *   @OA\Property(property="status", type="string", enum={"pending", "completed"}, nullable=true, description="상태"),
+ *   @OA\Property(property="stage", type="string", enum={"estimate_selected", "estimate_progress", "delivery", "installation", "inspection", "other"}, nullable=true, description="단계"),
+ *   @OA\Property(property="bidding_id", type="integer", nullable=true, description="입찰 ID"),
+ *   @OA\Property(property="bidding_code", type="string", nullable=true, maxLength=50, description="입찰번호"),
+ *   @OA\Property(property="remarks", type="string", nullable=true, description="비고"),
+ *   @OA\Property(property="is_active", type="boolean", nullable=true, description="활성 여부")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ContractStats",
+ *   type="object",
+ *
+ *   @OA\Property(property="total_count", type="integer", example=50, description="전체 계약 수"),
+ *   @OA\Property(property="pending_count", type="integer", example=30, description="계약대기 수"),
+ *   @OA\Property(property="completed_count", type="integer", example=20, description="계약완료 수"),
+ *   @OA\Property(property="total_amount", type="number", format="float", example=5000000000, description="총 계약금액"),
+ *   @OA\Property(property="total_locations", type="integer", example=500, description="총 개소수")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ContractStageCounts",
+ *   type="object",
+ *
+ *   @OA\Property(property="estimate_selected", type="integer", example=10, description="견적선정 수"),
+ *   @OA\Property(property="estimate_progress", type="integer", example=15, description="견적진행 수"),
+ *   @OA\Property(property="delivery", type="integer", example=8, description="납품 수"),
+ *   @OA\Property(property="installation", type="integer", example=12, description="설치중 수"),
+ *   @OA\Property(property="inspection", type="integer", example=3, description="검수 수"),
+ *   @OA\Property(property="other", type="integer", example=2, description="기타 수")
+ * )
+ */
+class ContractApi
+{
+    /**
+     * @OA\Get(
+     *   path="/api/v1/construction/contracts",
+     *   tags={"Contract"},
+     *   summary="계약 목록 조회",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", example=1)),
+     *   @OA\Parameter(name="per_page", in="query", @OA\Schema(type="integer", example=20)),
+     *   @OA\Parameter(name="search", in="query", description="계약번호/현장명/거래처명 검색", @OA\Schema(type="string")),
+     *   @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"pending", "completed"})),
+     *   @OA\Parameter(name="stage", in="query", description="단계 필터", @OA\Schema(type="string", enum={"estimate_selected", "estimate_progress", "delivery", "installation", "inspection", "other"})),
+     *   @OA\Parameter(name="partner_id", in="query", description="거래처 ID 필터", @OA\Schema(type="integer")),
+     *   @OA\Parameter(name="contract_manager_id", in="query", description="계약담당자 ID 필터", @OA\Schema(type="integer")),
+     *   @OA\Parameter(name="construction_pm_id", in="query", description="공사PM ID 필터", @OA\Schema(type="integer")),
+     *   @OA\Parameter(name="start_date", in="query", description="시작일 필터 (계약시작일 기준)", @OA\Schema(type="string", format="date")),
+     *   @OA\Parameter(name="end_date", in="query", description="종료일 필터 (계약종료일 기준)", @OA\Schema(type="string", format="date")),
+     *   @OA\Parameter(name="is_active", in="query", description="활성화 상태 필터", @OA\Schema(type="boolean")),
+     *   @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", example="created_at")),
+     *   @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc", "desc"}, example="desc")),
+     *
+     *   @OA\Response(response=200, description="조회 성공",
+     *
+     *     @OA\JsonContent(allOf={
+     *
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ContractPagination"))
+     *     })
+     *   ),
+     *
+     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Get(
+     *   path="/api/v1/construction/contracts/{id}",
+     *   tags={"Contract"},
+     *   summary="계약 상세 조회",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *
+     *   @OA\Response(response=200, description="조회 성공",
+     *
+     *     @OA\JsonContent(allOf={
+     *
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Contract"))
+     *     })
+     *   ),
+     *
+     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function show() {}
+
+    /**
+     * @OA\Post(
+     *   path="/api/v1/construction/contracts",
+     *   tags={"Contract"},
+     *   summary="계약 등록",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ContractCreateRequest")),
+     *
+     *   @OA\Response(response=200, description="등록 성공",
+     *
+     *     @OA\JsonContent(allOf={
+     *
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Contract"))
+     *     })
+     *   ),
+     *
+     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function store() {}
+
+    /**
+     * @OA\Put(
+     *   path="/api/v1/construction/contracts/{id}",
+     *   tags={"Contract"},
+     *   summary="계약 수정",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *
+     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ContractUpdateRequest")),
+     *
+     *   @OA\Response(response=200, description="수정 성공",
+     *
+     *     @OA\JsonContent(allOf={
+     *
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Contract"))
+     *     })
+     *   ),
+     *
+     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function update() {}
+
+    /**
+     * @OA\Delete(
+     *   path="/api/v1/construction/contracts/{id}",
+     *   tags={"Contract"},
+     *   summary="계약 삭제",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *
+     *   @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
+     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function destroy() {}
+
+    /**
+     * @OA\Delete(
+     *   path="/api/v1/construction/contracts/bulk",
+     *   tags={"Contract"},
+     *   summary="계약 일괄 삭제",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\RequestBody(required=true,
+     *
+     *     @OA\JsonContent(
+     *
+     *       @OA\Property(property="ids", type="array", @OA\Items(type="integer"), example={1, 2, 3}, description="삭제할 계약 ID 목록")
+     *     )
+     *   ),
+     *
+     *   @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
+     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function bulkDestroy() {}
+
+    /**
+     * @OA\Get(
+     *   path="/api/v1/construction/contracts/stats",
+     *   tags={"Contract"},
+     *   summary="계약 통계 조회",
+     *   description="전체 계약 수, 상태별 수, 총 계약금액, 총 개소수 등의 통계 정보를 반환합니다.",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\Parameter(name="start_date", in="query", description="시작일 필터", @OA\Schema(type="string", format="date")),
+     *   @OA\Parameter(name="end_date", in="query", description="종료일 필터", @OA\Schema(type="string", format="date")),
+     *
+     *   @OA\Response(response=200, description="조회 성공",
+     *
+     *     @OA\JsonContent(allOf={
+     *
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ContractStats"))
+     *     })
+     *   ),
+     *
+     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function stats() {}
+
+    /**
+     * @OA\Get(
+     *   path="/api/v1/construction/contracts/stage-counts",
+     *   tags={"Contract"},
+     *   summary="계약 단계별 카운트 조회",
+     *   description="각 단계별 계약 수를 반환합니다.",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *   @OA\Parameter(name="start_date", in="query", description="시작일 필터", @OA\Schema(type="string", format="date")),
+     *   @OA\Parameter(name="end_date", in="query", description="종료일 필터", @OA\Schema(type="string", format="date")),
+     *
+     *   @OA\Response(response=200, description="조회 성공",
+     *
+     *     @OA\JsonContent(allOf={
+     *
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ContractStageCounts"))
+     *     })
+     *   ),
+     *
+     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function stageCounts() {}
+}
--- a/database/migrations/2026_01_08_000001_create_contracts_table.php
+++ b/database/migrations/2026_01_08_000001_create_contracts_table.php
@@ -0,0 +1,77 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('contracts', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('tenant_id')->comment('테넌트 ID');
+
+            // 계약 기본 정보
+            $table->string('contract_code', 50)->comment('계약번호');
+            $table->string('project_name')->comment('현장명');
+
+            // 거래처 정보
+            $table->unsignedBigInteger('partner_id')->nullable()->comment('거래처 ID');
+            $table->string('partner_name')->nullable()->comment('거래처명');
+
+            // 담당자 정보
+            $table->unsignedBigInteger('contract_manager_id')->nullable()->comment('계약담당자 ID');
+            $table->string('contract_manager_name')->nullable()->comment('계약담당자명');
+            $table->unsignedBigInteger('construction_pm_id')->nullable()->comment('공사PM ID');
+            $table->string('construction_pm_name')->nullable()->comment('공사PM명');
+
+            // 계약 상세
+            $table->integer('total_locations')->default(0)->comment('총 개소');
+            $table->decimal('contract_amount', 15, 2)->default(0)->comment('계약금액');
+            $table->date('contract_start_date')->nullable()->comment('계약시작일');
+            $table->date('contract_end_date')->nullable()->comment('계약종료일');
+
+            // 상태 정보
+            $table->string('status', 20)->default('pending')->comment('계약상태: pending, completed');
+            $table->string('stage', 30)->default('estimate_selected')->comment('계약단계: estimate_selected, estimate_progress, delivery, installation, inspection, other');
+
+            // 연결 정보
+            $table->unsignedBigInteger('bidding_id')->nullable()->comment('입찰 ID');
+            $table->string('bidding_code', 50)->nullable()->comment('입찰번호');
+
+            // 비고
+            $table->text('remarks')->nullable()->comment('비고');
+
+            // 활성화 상태
+            $table->boolean('is_active')->default(true)->comment('활성화 여부');
+
+            // 감사 컬럼
+            $table->unsignedBigInteger('created_by')->nullable()->comment('생성자 ID');
+            $table->unsignedBigInteger('updated_by')->nullable()->comment('수정자 ID');
+            $table->unsignedBigInteger('deleted_by')->nullable()->comment('삭제자 ID');
+
+            // 타임스탬프
+            $table->timestamps();
+            $table->softDeletes();
+
+            // 인덱스
+            $table->index('tenant_id');
+            $table->index('partner_id');
+            $table->index('status');
+            $table->index('stage');
+            $table->unique(['tenant_id', 'contract_code']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('contracts');
+    }
+};
--- a/lang/ko/message.php
+++ b/lang/ko/message.php
@@ -274,6 +274,14 @@
        'active_fetched' => '활성화된 현장 목록을 조회했습니다.',
    ],

+    // 계약 관리 (시공관리)
+    'contract' => [
+        'fetched' => '계약을 조회했습니다.',
+        'created' => '계약이 등록되었습니다.',
+        'updated' => '계약이 수정되었습니다.',
+        'deleted' => '계약이 삭제되었습니다.',
+    ],
+
    // 보고서 관리
    'report' => [
        'fetched' => '보고서를 조회했습니다.',
--- a/routes/api.php
+++ b/routes/api.php
@@ -25,6 +25,7 @@
 use App\Http\Controllers\Api\V1\ClassificationController;
 use App\Http\Controllers\Api\V1\ClientController;
 use App\Http\Controllers\Api\V1\ClientGroupController;
+use App\Http\Controllers\Api\V1\Construction\ContractController;
 use App\Http\Controllers\Api\V1\CommonController;
 use App\Http\Controllers\Api\V1\CompanyController;
 use App\Http\Controllers\Api\V1\DashboardController;
@@ -419,6 +420,21 @@
            Route::delete('/{id}', [SiteController::class, 'destroy'])->whereNumber('id')->name('v1.sites.destroy');
        });

+        // Construction API (시공관리)
+        Route::prefix('construction')->group(function () {
+            // Contract API (계약관리)
+            Route::prefix('contracts')->group(function () {
+                Route::get('', [ContractController::class, 'index'])->name('v1.construction.contracts.index');
+                Route::post('', [ContractController::class, 'store'])->name('v1.construction.contracts.store');
+                Route::get('/stats', [ContractController::class, 'stats'])->name('v1.construction.contracts.stats');
+                Route::get('/stage-counts', [ContractController::class, 'stageCounts'])->name('v1.construction.contracts.stage-counts');
+                Route::delete('/bulk', [ContractController::class, 'bulkDestroy'])->name('v1.construction.contracts.bulk-destroy');
+                Route::get('/{id}', [ContractController::class, 'show'])->whereNumber('id')->name('v1.construction.contracts.show');
+                Route::put('/{id}', [ContractController::class, 'update'])->whereNumber('id')->name('v1.construction.contracts.update');
+                Route::delete('/{id}', [ContractController::class, 'destroy'])->whereNumber('id')->name('v1.construction.contracts.destroy');
+            });
+        });
+
        // Card API (카드 관리)
        Route::prefix('cards')->group(function () {
            Route::get('', [CardController::class, 'index'])->name('v1.cards.index');