feat(API): Inspection API 구현

- InspectionController 생성 (CRUD + stats + complete)
- InspectionService 생성 (비즈니스 로직)
- FormRequest 생성 (Store/Update/Complete)
- 라우트 등록 (7개 엔드포인트)
- i18n 메시지 추가 (message.php, error.php)

기존 inspections 테이블 및 Inspection 모델 활용

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

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

@@ -0,0 +1,88 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Inspection\InspectionCompleteRequest;
+use App\Http\Requests\Inspection\InspectionStoreRequest;
+use App\Http\Requests\Inspection\InspectionUpdateRequest;
+use App\Services\InspectionService;
+use Illuminate\Http\Request;
+
+class InspectionController extends Controller
+{
+    public function __construct(private InspectionService $service) {}
+
+    /**
+     * 목록 조회
+     */
+    public function index(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->index($request->all());
+        }, __('message.inspection.fetched'));
+    }
+
+    /**
+     * 통계 조회
+     */
+    public function stats(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->stats($request->all());
+        }, __('message.inspection.fetched'));
+    }
+
+    /**
+     * 단건 조회
+     */
+    public function show(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->show($id);
+        }, __('message.inspection.fetched'));
+    }
+
+    /**
+     * 생성
+     */
+    public function store(InspectionStoreRequest $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->store($request->validated());
+        }, __('message.inspection.created'));
+    }
+
+    /**
+     * 수정
+     */
+    public function update(InspectionUpdateRequest $request, int $id)
+    {
+        return ApiResponse::handle(function () use ($request, $id) {
+            return $this->service->update($id, $request->validated());
+        }, __('message.inspection.updated'));
+    }
+
+    /**
+     * 삭제
+     */
+    public function destroy(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $this->service->destroy($id);
+
+            return 'success';
+        }, __('message.inspection.deleted'));
+    }
+
+    /**
+     * 검사 완료 처리
+     */
+    public function complete(InspectionCompleteRequest $request, int $id)
+    {
+        return ApiResponse::handle(function () use ($request, $id) {
+            return $this->service->complete($id, $request->validated());
+        }, __('message.inspection.completed'));
+    }
+}

app/Http/Requests/Inspection/InspectionCompleteRequest.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Http\Requests\Inspection;
+
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class InspectionCompleteRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'result' => ['required', Rule::in(['pass', 'fail'])],
+            'opinion' => ['nullable', 'string', 'max:2000'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'result.required' => __('validation.required', ['attribute' => '검사결과']),
+            'result.in' => __('validation.in', ['attribute' => '검사결과']),
+        ];
+    }
+}

app/Http/Requests/Inspection/InspectionStoreRequest.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace App\Http\Requests\Inspection;
+
+use App\Models\Qualitys\Inspection;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class InspectionStoreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'inspection_type' => ['required', Rule::in([
+                Inspection::TYPE_IQC,
+                Inspection::TYPE_PQC,
+                Inspection::TYPE_FQC,
+            ])],
+            'lot_no' => ['required', 'string', 'max:50'],
+            'item_name' => ['nullable', 'string', 'max:200'],
+            'process_name' => ['nullable', 'string', 'max:100'],
+            'quantity' => ['nullable', 'numeric', 'min:0'],
+            'unit' => ['nullable', 'string', 'max:20'],
+            'inspector_id' => ['nullable', 'integer', 'exists:users,id'],
+            'remarks' => ['nullable', 'string', 'max:1000'],
+            'items' => ['nullable', 'array'],
+            'items.*.name' => ['required_with:items', 'string', 'max:200'],
+            'items.*.type' => ['required_with:items', Rule::in(['quality', 'measurement'])],
+            'items.*.spec' => ['required_with:items', 'string', 'max:200'],
+            'items.*.unit' => ['nullable', 'string', 'max:20'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'inspection_type.required' => __('validation.required', ['attribute' => '검사유형']),
+            'inspection_type.in' => __('validation.in', ['attribute' => '검사유형']),
+            'lot_no.required' => __('validation.required', ['attribute' => 'LOT번호']),
+        ];
+    }
+}

app/Http/Requests/Inspection/InspectionUpdateRequest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Http\Requests\Inspection;
+
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class InspectionUpdateRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'items' => ['nullable', 'array'],
+            'items.*.id' => ['required_with:items', 'string'],
+            'items.*.result' => ['nullable', 'string', 'max:20'],
+            'items.*.measured_value' => ['nullable', 'numeric'],
+            'items.*.judgment' => ['nullable', Rule::in(['pass', 'fail'])],
+            'result' => ['nullable', Rule::in(['pass', 'fail'])],
+            'remarks' => ['nullable', 'string', 'max:1000'],
+            'opinion' => ['nullable', 'string', 'max:2000'],
+        ];
+    }
+}

app/Services/InspectionService.php

@@ -0,0 +1,401 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Qualitys\Inspection;
+use App\Services\Audit\AuditLogger;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class InspectionService extends Service
+{
+    private const AUDIT_TARGET = 'inspection';
+
+    public function __construct(
+        private readonly AuditLogger $auditLogger
+    ) {}
+
+    /**
+     * 목록 조회 (검색/필터링/페이징)
+     */
+    public function index(array $params)
+    {
+        $tenantId = $this->tenantId();
+
+        $page = (int) ($params['page'] ?? 1);
+        $perPage = (int) ($params['per_page'] ?? 20);
+        $q = trim((string) ($params['q'] ?? ''));
+        $status = $params['status'] ?? null;
+        $inspectionType = $params['inspection_type'] ?? null;
+        $dateFrom = $params['date_from'] ?? null;
+        $dateTo = $params['date_to'] ?? null;
+
+        $query = Inspection::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['inspector:id,name', 'item:id,item_name']);
+
+        // 검색어 (검사번호, LOT번호)
+        if ($q !== '') {
+            $query->where(function ($qq) use ($q) {
+                $qq->where('inspection_no', 'like', "%{$q}%")
+                    ->orWhere('lot_no', 'like', "%{$q}%");
+            });
+        }
+
+        // 상태 필터
+        if ($status !== null) {
+            $query->where('status', $status);
+        }
+
+        // 검사유형 필터
+        if ($inspectionType !== null) {
+            $query->where('inspection_type', $inspectionType);
+        }
+
+        // 요청일 범위 필터
+        if ($dateFrom !== null) {
+            $query->where('request_date', '>=', $dateFrom);
+        }
+        if ($dateTo !== null) {
+            $query->where('request_date', '<=', $dateTo);
+        }
+
+        $query->orderByDesc('created_at');
+
+        $paginated = $query->paginate($perPage, ['*'], 'page', $page);
+
+        // 프론트엔드 형식에 맞게 데이터 변환
+        $transformedData = $paginated->getCollection()->map(fn ($item) => $this->transformToFrontend($item));
+
+        return [
+            'data' => $transformedData,
+            'current_page' => $paginated->currentPage(),
+            'last_page' => $paginated->lastPage(),
+            'per_page' => $paginated->perPage(),
+            'total' => $paginated->total(),
+        ];
+    }
+
+    /**
+     * 통계 조회
+     */
+    public function stats(array $params = []): array
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Inspection::where('tenant_id', $tenantId);
+
+        // 필터 적용
+        if (! empty($params['date_from'])) {
+            $query->where('request_date', '>=', $params['date_from']);
+        }
+        if (! empty($params['date_to'])) {
+            $query->where('request_date', '<=', $params['date_to']);
+        }
+        if (! empty($params['inspection_type'])) {
+            $query->where('inspection_type', $params['inspection_type']);
+        }
+
+        // 상태별 카운트
+        $counts = (clone $query)
+            ->select('status', DB::raw('count(*) as count'))
+            ->groupBy('status')
+            ->pluck('count', 'status')
+            ->toArray();
+
+        // 불량률 계산 (완료된 검사 중 불합격 비율)
+        $completedQuery = (clone $query)->where('status', Inspection::STATUS_COMPLETED);
+        $completedCount = $completedQuery->count();
+        $failCount = (clone $completedQuery)->where('result', Inspection::RESULT_FAIL)->count();
+        $defectRate = $completedCount > 0 ? round(($failCount / $completedCount) * 100, 2) : 0;
+
+        return [
+            'waiting_count' => $counts[Inspection::STATUS_WAITING] ?? 0,
+            'in_progress_count' => $counts[Inspection::STATUS_IN_PROGRESS] ?? 0,
+            'completed_count' => $counts[Inspection::STATUS_COMPLETED] ?? 0,
+            'defect_rate' => $defectRate,
+        ];
+    }
+
+    /**
+     * 단건 조회
+     */
+    public function show(int $id)
+    {
+        $tenantId = $this->tenantId();
+
+        $inspection = Inspection::where('tenant_id', $tenantId)
+            ->with(['inspector:id,name', 'item:id,item_name'])
+            ->find($id);
+
+        if (! $inspection) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        return $this->transformToFrontend($inspection);
+    }
+
+    /**
+     * 생성
+     */
+    public function store(array $data)
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($data, $tenantId, $userId) {
+            // 검사번호 자동 생성
+            $inspectionNo = Inspection::generateInspectionNo($tenantId, $data['inspection_type']);
+
+            // meta JSON 구성
+            $meta = [
+                'process_name' => $data['process_name'] ?? null,
+                'quantity' => $data['quantity'] ?? null,
+                'unit' => $data['unit'] ?? null,
+            ];
+
+            // extra JSON 구성
+            $extra = [
+                'remarks' => $data['remarks'] ?? null,
+            ];
+
+            // items JSON 구성
+            $items = [];
+            if (! empty($data['items'])) {
+                foreach ($data['items'] as $index => $item) {
+                    $items[] = [
+                        'id' => uniqid('item_'),
+                        'name' => $item['name'],
+                        'type' => $item['type'],
+                        'spec' => $item['spec'],
+                        'unit' => $item['unit'] ?? null,
+                        'result' => null,
+                        'measured_value' => null,
+                        'judgment' => null,
+                    ];
+                }
+            }
+
+            $inspection = Inspection::create([
+                'tenant_id' => $tenantId,
+                'inspection_no' => $inspectionNo,
+                'inspection_type' => $data['inspection_type'],
+                'request_date' => $data['request_date'] ?? now()->toDateString(),
+                'lot_no' => $data['lot_no'],
+                'inspector_id' => $data['inspector_id'] ?? null,
+                'meta' => $meta,
+                'items' => $items,
+                'extra' => $extra,
+                'created_by' => $userId,
+            ]);
+
+            // 감사 로그
+            $this->auditLogger->log(
+                $tenantId,
+                self::AUDIT_TARGET,
+                $inspection->id,
+                'created',
+                null,
+                $inspection->toArray()
+            );
+
+            return $this->transformToFrontend($inspection->load(['inspector:id,name']));
+        });
+    }
+
+    /**
+     * 수정
+     */
+    public function update(int $id, array $data)
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        $inspection = Inspection::where('tenant_id', $tenantId)->find($id);
+        if (! $inspection) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        $beforeData = $inspection->toArray();
+
+        return DB::transaction(function () use ($inspection, $data, $userId, $beforeData) {
+            $updateData = ['updated_by' => $userId];
+
+            // items 업데이트
+            if (isset($data['items'])) {
+                $existingItems = $inspection->items ?? [];
+                $updatedItems = [];
+
+                foreach ($data['items'] as $inputItem) {
+                    // 기존 항목 찾기
+                    $found = false;
+                    foreach ($existingItems as $existing) {
+                        if ($existing['id'] === $inputItem['id']) {
+                            $existing['result'] = $inputItem['result'] ?? $existing['result'];
+                            $existing['measured_value'] = $inputItem['measured_value'] ?? $existing['measured_value'];
+                            $existing['judgment'] = $inputItem['judgment'] ?? $existing['judgment'];
+                            $updatedItems[] = $existing;
+                            $found = true;
+                            break;
+                        }
+                    }
+                    if (! $found) {
+                        $updatedItems[] = $inputItem;
+                    }
+                }
+
+                $updateData['items'] = $updatedItems;
+            }
+
+            // result 업데이트
+            if (isset($data['result'])) {
+                $updateData['result'] = $data['result'];
+            }
+
+            // extra JSON 업데이트
+            $extra = $inspection->extra ?? [];
+            if (isset($data['remarks'])) {
+                $extra['remarks'] = $data['remarks'];
+            }
+            if (isset($data['opinion'])) {
+                $extra['opinion'] = $data['opinion'];
+            }
+            if (! empty($extra)) {
+                $updateData['extra'] = $extra;
+            }
+
+            $inspection->update($updateData);
+
+            // 감사 로그
+            $this->auditLogger->log(
+                $inspection->tenant_id,
+                self::AUDIT_TARGET,
+                $inspection->id,
+                'updated',
+                $beforeData,
+                $inspection->fresh()->toArray()
+            );
+
+            return $this->transformToFrontend($inspection->load(['inspector:id,name']));
+        });
+    }
+
+    /**
+     * 삭제
+     */
+    public function destroy(int $id)
+    {
+        $tenantId = $this->tenantId();
+
+        $inspection = Inspection::where('tenant_id', $tenantId)->find($id);
+        if (! $inspection) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        // 완료된 검사는 삭제 불가
+        if ($inspection->status === Inspection::STATUS_COMPLETED) {
+            throw new BadRequestHttpException(__('error.inspection.cannot_delete_completed'));
+        }
+
+        $beforeData = $inspection->toArray();
+        $inspection->deleted_by = $this->apiUserId();
+        $inspection->save();
+        $inspection->delete();
+
+        // 감사 로그
+        $this->auditLogger->log(
+            $tenantId,
+            self::AUDIT_TARGET,
+            $inspection->id,
+            'deleted',
+            $beforeData,
+            null
+        );
+
+        return 'success';
+    }
+
+    /**
+     * 검사 완료 처리
+     */
+    public function complete(int $id, array $data)
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        $inspection = Inspection::where('tenant_id', $tenantId)->find($id);
+        if (! $inspection) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        // 이미 완료된 경우
+        if ($inspection->status === Inspection::STATUS_COMPLETED) {
+            throw new BadRequestHttpException(__('error.inspection.already_completed'));
+        }
+
+        $beforeData = $inspection->toArray();
+
+        return DB::transaction(function () use ($inspection, $data, $userId, $beforeData) {
+            $extra = $inspection->extra ?? [];
+            if (isset($data['opinion'])) {
+                $extra['opinion'] = $data['opinion'];
+            }
+
+            $inspection->update([
+                'status' => Inspection::STATUS_COMPLETED,
+                'result' => $data['result'],
+                'inspection_date' => now()->toDateString(),
+                'extra' => $extra,
+                'updated_by' => $userId,
+            ]);
+
+            // 감사 로그
+            $this->auditLogger->log(
+                $inspection->tenant_id,
+                self::AUDIT_TARGET,
+                $inspection->id,
+                'completed',
+                $beforeData,
+                $inspection->fresh()->toArray()
+            );
+
+            return $this->transformToFrontend($inspection->load(['inspector:id,name']));
+        });
+    }
+
+    /**
+     * DB 데이터를 프론트엔드 형식으로 변환
+     */
+    private function transformToFrontend(Inspection $inspection): array
+    {
+        $meta = $inspection->meta ?? [];
+        $extra = $inspection->extra ?? [];
+
+        return [
+            'id' => $inspection->id,
+            'inspection_no' => $inspection->inspection_no,
+            'inspection_type' => $inspection->inspection_type,
+            'request_date' => $inspection->request_date?->format('Y-m-d'),
+            'inspection_date' => $inspection->inspection_date?->format('Y-m-d'),
+            'item_name' => $inspection->item?->item_name ?? ($meta['item_name'] ?? null),
+            'lot_no' => $inspection->lot_no,
+            'process_name' => $meta['process_name'] ?? null,
+            'quantity' => $meta['quantity'] ?? null,
+            'unit' => $meta['unit'] ?? null,
+            'status' => $inspection->status,
+            'result' => $inspection->result,
+            'inspector_id' => $inspection->inspector_id,
+            'inspector' => $inspection->inspector ? [
+                'id' => $inspection->inspector->id,
+                'name' => $inspection->inspector->name,
+            ] : null,
+            'items' => $inspection->items ?? [],
+            'remarks' => $extra['remarks'] ?? null,
+            'opinion' => $extra['opinion'] ?? null,
+            'attachments' => $inspection->attachments ?? [],
+            'created_at' => $inspection->created_at?->toIso8601String(),
+            'updated_at' => $inspection->updated_at?->toIso8601String(),
+        ];
+    }
+}

lang/ko/error.php

@@ -379,4 +379,11 @@
         'not_bending_process' => '벤딩 공정이 아닙니다.',
         'invalid_transition' => "상태를 ':from'에서 ':to'(으)로 변경할 수 없습니다. 허용된 상태: :allowed",
     ],
+
+    // 검사 관련
+    'inspection' => [
+        'not_found' => '검사를 찾을 수 없습니다.',
+        'cannot_delete_completed' => '완료된 검사는 삭제할 수 없습니다.',
+        'already_completed' => '이미 완료된 검사입니다.',
+    ],
 ];

lang/ko/message.php

@@ -428,6 +428,15 @@
         'issue_resolved' => '이슈가 해결되었습니다.',
     ],
 
+    // 검사 관리
+    'inspection' => [
+        'fetched' => '검사를 조회했습니다.',
+        'created' => '검사가 등록되었습니다.',
+        'updated' => '검사가 수정되었습니다.',
+        'deleted' => '검사가 삭제되었습니다.',
+        'completed' => '검사가 완료되었습니다.',
+    ],
+
     // 작업실적 관리
     'work_result' => [
         'fetched' => '작업실적을 조회했습니다.',

routes/api.php

@@ -44,6 +44,7 @@
 use App\Http\Controllers\Api\V1\ExpectedExpenseController;
 use App\Http\Controllers\Api\V1\FileStorageController;
 use App\Http\Controllers\Api\V1\FolderController;
+use App\Http\Controllers\Api\V1\InspectionController;
 use App\Http\Controllers\Api\V1\InternalController;
 use App\Http\Controllers\Api\V1\ItemMaster\CustomTabController;
 use App\Http\Controllers\Api\V1\ItemMaster\EntityRelationshipController;
@@ -1203,6 +1204,17 @@
             Route::patch('/{id}/packaging', [WorkResultController::class, 'togglePackaging'])->whereNumber('id')->name('v1.work-results.packaging');        // 포장 상태 토글
         });
 
+        // 검사 관리 API (Quality)
+        Route::prefix('inspections')->group(function () {
+            Route::get('', [InspectionController::class, 'index'])->name('v1.inspections.index');                                              // 목록
+            Route::get('/stats', [InspectionController::class, 'stats'])->name('v1.inspections.stats');                                        // 통계
+            Route::post('', [InspectionController::class, 'store'])->name('v1.inspections.store');                                             // 생성
+            Route::get('/{id}', [InspectionController::class, 'show'])->whereNumber('id')->name('v1.inspections.show');                        // 상세
+            Route::put('/{id}', [InspectionController::class, 'update'])->whereNumber('id')->name('v1.inspections.update');                    // 수정
+            Route::delete('/{id}', [InspectionController::class, 'destroy'])->whereNumber('id')->name('v1.inspections.destroy');               // 삭제
+            Route::patch('/{id}/complete', [InspectionController::class, 'complete'])->whereNumber('id')->name('v1.inspections.complete');     // 완료 처리
+        });
+
         // 파일 저장소 API
         Route::prefix('files')->group(function () {
             Route::post('/upload', [FileStorageController::class, 'upload'])->name('v1.files.upload');                           // 파일 업로드 (임시)