feat: Phase 6.1 악성채권 추심관리 API 구현

- 테이블 3개: bad_debts, bad_debt_documents, bad_debt_memos
- 모델 3개: BadDebt, BadDebtDocument, BadDebtMemo
- BadDebtService: CRUD, 요약 통계, 서류/메모 관리
- API 엔드포인트 11개 (목록, 등록, 상세, 수정, 삭제, 토글, 서류/메모 CRUD)
- Swagger 문서 작성 완료

app/Http/Controllers/Api/V1/BadDebtController.php

@@ -0,0 +1,142 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\V1\BadDebt\StoreBadDebtDocumentRequest;
+use App\Http\Requests\V1\BadDebt\StoreBadDebtMemoRequest;
+use App\Http\Requests\V1\BadDebt\StoreBadDebtRequest;
+use App\Http\Requests\V1\BadDebt\UpdateBadDebtRequest;
+use App\Services\BadDebtService;
+use Illuminate\Http\Request;
+
+class BadDebtController extends Controller
+{
+    public function __construct(
+        private readonly BadDebtService $service
+    ) {}
+
+    /**
+     * 악성채권 목록
+     */
+    public function index(Request $request)
+    {
+        $params = $request->only([
+            'client_id',
+            'status',
+            'is_active',
+            'search',
+            'sort_by',
+            'sort_dir',
+            'per_page',
+            'page',
+        ]);
+
+        $badDebts = $this->service->index($params);
+
+        return ApiResponse::success($badDebts, __('message.fetched'));
+    }
+
+    /**
+     * 악성채권 요약 통계
+     */
+    public function summary(Request $request)
+    {
+        $params = $request->only(['client_id']);
+
+        $summary = $this->service->summary($params);
+
+        return ApiResponse::success($summary, __('message.fetched'));
+    }
+
+    /**
+     * 악성채권 등록
+     */
+    public function store(StoreBadDebtRequest $request)
+    {
+        $badDebt = $this->service->store($request->validated());
+
+        return ApiResponse::success($badDebt, __('message.created'), [], 201);
+    }
+
+    /**
+     * 악성채권 상세
+     */
+    public function show(int $id)
+    {
+        $badDebt = $this->service->show($id);
+
+        return ApiResponse::success($badDebt, __('message.fetched'));
+    }
+
+    /**
+     * 악성채권 수정
+     */
+    public function update(int $id, UpdateBadDebtRequest $request)
+    {
+        $badDebt = $this->service->update($id, $request->validated());
+
+        return ApiResponse::success($badDebt, __('message.updated'));
+    }
+
+    /**
+     * 악성채권 삭제
+     */
+    public function destroy(int $id)
+    {
+        $this->service->destroy($id);
+
+        return ApiResponse::success(null, __('message.deleted'));
+    }
+
+    /**
+     * 설정 토글 (is_active)
+     */
+    public function toggle(int $id)
+    {
+        $badDebt = $this->service->toggle($id);
+
+        return ApiResponse::success($badDebt, __('message.updated'));
+    }
+
+    /**
+     * 서류 첨부
+     */
+    public function addDocument(int $id, StoreBadDebtDocumentRequest $request)
+    {
+        $document = $this->service->addDocument($id, $request->validated());
+
+        return ApiResponse::success($document, __('message.created'), [], 201);
+    }
+
+    /**
+     * 서류 삭제
+     */
+    public function removeDocument(int $id, int $documentId)
+    {
+        $this->service->removeDocument($id, $documentId);
+
+        return ApiResponse::success(null, __('message.deleted'));
+    }
+
+    /**
+     * 메모 추가
+     */
+    public function addMemo(int $id, StoreBadDebtMemoRequest $request)
+    {
+        $memo = $this->service->addMemo($id, $request->validated());
+
+        return ApiResponse::success($memo, __('message.created'), [], 201);
+    }
+
+    /**
+     * 메모 삭제
+     */
+    public function removeMemo(int $id, int $memoId)
+    {
+        $this->service->removeMemo($id, $memoId);
+
+        return ApiResponse::success(null, __('message.deleted'));
+    }
+}

app/Http/Requests/V1/BadDebt/StoreBadDebtDocumentRequest.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Http\Requests\V1\BadDebt;
+
+use App\Models\BadDebts\BadDebtDocument;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class StoreBadDebtDocumentRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'document_type' => ['required', 'string', Rule::in(array_keys(BadDebtDocument::DOCUMENT_TYPES))],
+            'file_id' => ['required', 'integer', 'exists:files,id'],
+        ];
+    }
+
+    /**
+     * Get custom messages for validator errors.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        return [
+            'document_type.required' => __('validation.required', ['attribute' => '서류유형']),
+            'document_type.in' => __('validation.in', ['attribute' => '서류유형']),
+            'file_id.required' => __('validation.required', ['attribute' => '파일']),
+            'file_id.exists' => __('validation.exists', ['attribute' => '파일']),
+        ];
+    }
+}

app/Http/Requests/V1/BadDebt/StoreBadDebtMemoRequest.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Requests\V1\BadDebt;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreBadDebtMemoRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'content' => ['required', 'string', 'max:5000'],
+        ];
+    }
+
+    /**
+     * Get custom messages for validator errors.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        return [
+            'content.required' => __('validation.required', ['attribute' => '메모 내용']),
+            'content.max' => __('validation.max.string', ['attribute' => '메모 내용', 'max' => 5000]),
+        ];
+    }
+}

app/Http/Requests/V1/BadDebt/StoreBadDebtRequest.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace App\Http\Requests\V1\BadDebt;
+
+use App\Models\BadDebts\BadDebt;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class StoreBadDebtRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'client_id' => ['required', 'integer', 'exists:clients,id'],
+            'debt_amount' => ['required', 'numeric', 'min:0'],
+            'status' => ['nullable', 'string', Rule::in(array_keys(BadDebt::STATUSES))],
+            'overdue_days' => ['nullable', 'integer', 'min:0'],
+            'assigned_user_id' => ['nullable', 'integer', 'exists:users,id'],
+            'occurred_at' => ['nullable', 'date'],
+            'closed_at' => ['nullable', 'date', 'after_or_equal:occurred_at'],
+            'is_active' => ['nullable', 'boolean'],
+            'options' => ['nullable', 'array'],
+        ];
+    }
+
+    /**
+     * Get custom messages for validator errors.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        return [
+            'client_id.required' => __('validation.required', ['attribute' => '거래처']),
+            'client_id.exists' => __('validation.exists', ['attribute' => '거래처']),
+            'debt_amount.required' => __('validation.required', ['attribute' => '채권금액']),
+            'debt_amount.numeric' => __('validation.numeric', ['attribute' => '채권금액']),
+            'status.in' => __('validation.in', ['attribute' => '상태']),
+            'closed_at.after_or_equal' => __('validation.after_or_equal', ['attribute' => '종료일', 'date' => '발생일']),
+        ];
+    }
+}

app/Http/Requests/V1/BadDebt/UpdateBadDebtRequest.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Http\Requests\V1\BadDebt;
+
+use App\Models\BadDebts\BadDebt;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class UpdateBadDebtRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'client_id' => ['sometimes', 'integer', 'exists:clients,id'],
+            'debt_amount' => ['sometimes', 'numeric', 'min:0'],
+            'status' => ['sometimes', 'string', Rule::in(array_keys(BadDebt::STATUSES))],
+            'overdue_days' => ['sometimes', 'integer', 'min:0'],
+            'assigned_user_id' => ['nullable', 'integer', 'exists:users,id'],
+            'occurred_at' => ['nullable', 'date'],
+            'closed_at' => ['nullable', 'date', 'after_or_equal:occurred_at'],
+            'is_active' => ['sometimes', 'boolean'],
+            'options' => ['nullable', 'array'],
+        ];
+    }
+
+    /**
+     * Get custom messages for validator errors.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        return [
+            'client_id.exists' => __('validation.exists', ['attribute' => '거래처']),
+            'debt_amount.numeric' => __('validation.numeric', ['attribute' => '채권금액']),
+            'status.in' => __('validation.in', ['attribute' => '상태']),
+            'closed_at.after_or_equal' => __('validation.after_or_equal', ['attribute' => '종료일', 'date' => '발생일']),
+        ];
+    }
+}