docs: [card-vehicle] 차량관리 3개 메뉴 이관 문서 최신화

- README.md: 기술 스택 버전 수정 (Laravel 12, PHP 8.4), 이관 현황 테이블 추가 - corporate-vehicles.md: 이관 현황 + API 이관 스펙 (엔드포인트, 필터, 고려사항) - vehicle-logs.md: 이관 현황 + API 이관 스펙 (summary 응답 구조 포함) - vehicle-maintenance.md: 이관 현황 + API 이관 스펙 (주행거리 갱신 로직 포함)
2026-03-12 21:56:36 +09:00
parent af20f974f7
commit 74facf050a
4 changed files with 171 additions and 1 deletions
--- a/features/card-vehicle/README.md
+++ b/features/card-vehicle/README.md
@@ -47,7 +47,7 @@ SAM 프로젝트의 카드/차량관리 모듈은 법인카드 관리, 카드

 | 기술 | 용도 |
 |------|------|
-| Laravel 11 (PHP 8.3) | 백엔드 프레임워크 |
+| Laravel 12 (PHP 8.4) | 백엔드 프레임워크 |
 | React 18 + Babel | 클라이언트 렌더링 UI (전 페이지) |
 | Tailwind CSS + Lucide | 스타일링 및 아이콘 |
 | Barobill SOAP API | 카드거래 실시간 연동 |
@@ -115,3 +115,25 @@ corporate_cards.card_number  ←매칭→  barobill_card_transactions.card_num
 | `corporate_vehicles` | 법인/렌트/리스 차량 정보 |
 | `vehicle_logs` | 차량 운행기록 (출발/도착, 거리, 용도) |
 | `vehicle_maintenances` | 정비/주유/보험 등 비용 기록 |
+
+---
+
+## 이관 현황 (2026-03-12 기준)
+
+### 차량 관리 영역
+
+| 기능 | MNG (현재) | DB 마이그레이션 | API REST | React UI |
+|------|:--------:|:----------:|:------:|:------:|
+| 차량목록 | ✅ 운영중 | ✅ API 관리 | ❌ 미이관 | ❌ 미이관 |
+| 차량일지 | ✅ 운영중 | ✅ API 관리 | ❌ 미이관 | ❌ 미이관 |
+| 정비이력 | ✅ 운영중 | ✅ API 관리 | ❌ 미이관 | ❌ 미이관 |
+
+### 카드 관리 영역
+
+| 기능 | MNG (현재) | DB 마이그레이션 | API REST | React UI |
+|------|:--------:|:----------:|:------:|:------:|
+| 법인카드관리 | ✅ 운영중 | — | ❌ 미이관 | ❌ 미이관 |
+| 카드사용내역 | ✅ 운영중 | — | ❌ 미이관 | ❌ 미이관 |
+
+> **참고**: 차량 관련 3개 테이블의 마이그레이션은 이미 API(`sam/api/database/migrations/`)에서 관리한다.
+> API의 `VehicleDispatchController`는 출하 배차 기능이며, 차량관리와 별도이다.
--- a/features/card-vehicle/corporate-vehicles.md
+++ b/features/card-vehicle/corporate-vehicles.md
@@ -161,3 +161,47 @@ CorporateVehicle (1) ← (N) VehicleLog (총 주행거리 합산)

 - React 기반 페이지이므로 **HX-Redirect 필요**
 - `@push('scripts')` 블록에 React/Babel 스크립트 포함
+
+---
+
+## 이관 현황 (2026-03-12 기준)
+
+| 항목 | 상태 | 비고 |
+|------|:----:|------|
+| DB 마이그레이션 | ✅ | `api/database/migrations/2026_02_02_220000_create_corporate_vehicles_table.php` |
+| MNG UI (Blade+React) | ✅ | 운영중 |
+| API REST 엔드포인트 | ❌ | 미이관 |
+| API Service/Model | ❌ | 미이관 |
+| React UI | ❌ | 미이관 |
+
+---
+
+## API 이관 스펙
+
+### 제안 엔드포인트
+
+```
+GET    /api/v1/corporate-vehicles          차량 목록 (페이지네이션 + 필터)
+GET    /api/v1/corporate-vehicles/{id}     차량 상세 (총 주행거리 포함)
+POST   /api/v1/corporate-vehicles          차량 등록
+PUT    /api/v1/corporate-vehicles/{id}     차량 수정
+DELETE /api/v1/corporate-vehicles/{id}     차량 삭제 (SoftDelete)
+GET    /api/v1/corporate-vehicles/dropdown 차량 드롭다운 목록 (id, plate_number, model)
+```
+
+### 필터 파라미터
+
+| 파라미터 | 타입 | 설명 |
+|---------|------|------|
+| `ownership_type` | string | corporate / rent / lease |
+| `vehicle_type` | string | 승용차 / 승합차 / 화물차 / SUV |
+| `status` | string | active / maintenance / disposed |
+| `search` | string | 차량번호, 모델, 운전자 검색 |
+
+### 이관 시 고려사항
+
+1. **멀티테넌트**: `BelongsToTenant` trait + `tenant_id` 자동 필터
+2. **총 주행거리 계산**: `mileage + SUM(vehicle_logs.distance_km)` — API에서 계산 후 응답에 포함
+3. **options 컬럼**: 현재 미적용. 이관 시 렌트/리스 전용 필드를 options JSON으로 통합 검토
+4. **Auditable**: API 모델에 `Auditable` trait 적용
+5. **FormRequest**: `StoreCorporateVehicleRequest`, `UpdateCorporateVehicleRequest` 분리
--- a/features/card-vehicle/vehicle-logs.md
+++ b/features/card-vehicle/vehicle-logs.md
@@ -177,3 +177,62 @@ VehicleLog::getNoteOptions()    // 미리 정의된 비고 옵션

 - React 기반 페이지이므로 **HX-Redirect 필요**
 - `@push('scripts')` 블록에 React/Babel 스크립트 포함
+
+---
+
+## 이관 현황 (2026-03-12 기준)
+
+| 항목 | 상태 | 비고 |
+|------|:----:|------|
+| DB 마이그레이션 | ✅ | `api/database/migrations/2026_02_03_100000_create_vehicle_logs_table.php` |
+| trip_type ENUM 수정 | ✅ | `api/database/migrations/2026_02_03_133000_modify_vehicle_logs_trip_type_enum.php` |
+| MNG UI (Blade+React) | ✅ | 운영중 |
+| API REST 엔드포인트 | ❌ | 미이관 |
+| API Service/Model | ❌ | 미이관 |
+| React UI | ❌ | 미이관 |
+
+---
+
+## API 이관 스펙
+
+### 제안 엔드포인트
+
+```
+GET    /api/v1/vehicle-logs              운행기록 목록 (페이지네이션 + 필터)
+GET    /api/v1/vehicle-logs/{id}         운행기록 상세
+POST   /api/v1/vehicle-logs              운행기록 등록
+PUT    /api/v1/vehicle-logs/{id}         운행기록 수정
+DELETE /api/v1/vehicle-logs/{id}         운행기록 삭제 (SoftDelete)
+GET    /api/v1/vehicle-logs/summary      월별 용도별 통계 (건수, 거리)
+```
+
+### 필터 파라미터
+
+| 파라미터 | 타입 | 설명 |
+|---------|------|------|
+| `vehicle_id` | int | 차량 ID |
+| `year` | int | 연도 |
+| `month` | int | 월 |
+| `trip_type` | string | commute_to / commute_from / business / personal 등 |
+| `search` | string | 운전자, 부서, 출발지, 도착지, 비고 검색 |
+
+### summary 응답 구조 (참고)
+
+```json
+{
+  "byType": {
+    "commute_to": { "label": "출근용", "count": 5, "distance": 125 },
+    "business": { "label": "업무용", "count": 10, "distance": 280 }
+  },
+  "total": { "count": 22, "distance": 580 }
+}
+```
+
+### 이관 시 고려사항
+
+1. **멀티테넌트**: `BelongsToTenant` trait + `tenant_id` 자동 필터
+2. **차량 관계**: `vehicle_id` → `corporate_vehicles` FK, 응답에 차량번호/모델 포함
+3. **trip_type ENUM**: 7가지 — commute_to, commute_from, business, personal + 왕복 3종
+4. **복사 기능**: 클라이언트(React)에서 처리, API는 일반 store로 충분
+5. **Auditable**: API 모델에 `Auditable` trait 적용
+6. **FormRequest**: `StoreVehicleLogRequest`, `UpdateVehicleLogRequest` 분리
--- a/features/card-vehicle/vehicle-maintenance.md
+++ b/features/card-vehicle/vehicle-maintenance.md
@@ -201,3 +201,48 @@ CREATE TABLE vehicle_maintenances (

 - React 기반 페이지이므로 **HX-Redirect 필요**
 - `@push('scripts')` 블록에 React/Babel 스크립트 포함
+
+---
+
+## 이관 현황 (2026-03-12 기준)
+
+| 항목 | 상태 | 비고 |
+|------|:----:|------|
+| DB 마이그레이션 | ✅ | `api/database/migrations/2026_02_03_195000_create_vehicle_maintenances_table.php` |
+| MNG UI (Blade+React) | ✅ | 운영중 |
+| API REST 엔드포인트 | ❌ | 미이관 |
+| API Service/Model | ❌ | 미이관 |
+| React UI | ❌ | 미이관 |
+
+---
+
+## API 이관 스펙
+
+### 제안 엔드포인트
+
+```
+GET    /api/v1/vehicle-maintenances              정비이력 목록 (페이지네이션 + 필터)
+GET    /api/v1/vehicle-maintenances/{id}         정비이력 상세
+POST   /api/v1/vehicle-maintenances              정비이력 등록 + 차량 주행거리 갱신
+PUT    /api/v1/vehicle-maintenances/{id}         정비이력 수정 + 차량 주행거리 갱신
+DELETE /api/v1/vehicle-maintenances/{id}         정비이력 삭제 (SoftDelete)
+```
+
+### 필터 파라미터
+
+| 파라미터 | 타입 | 설명 |
+|---------|------|------|
+| `vehicle_id` | int | 차량 ID |
+| `category` | string | 주유 / 정비 / 보험 / 세차 / 주차 / 통행료 / 검사 / 기타 |
+| `start_date` | date | 시작일 |
+| `end_date` | date | 종료일 (기본: 최근 3개월) |
+| `search` | string | 설명, 업체명, 메모 검색 |
+
+### 이관 시 고려사항
+
+1. **멀티테넌트**: `BelongsToTenant` trait + `tenant_id` 자동 필터
+2. **주행거리 자동 갱신**: store/update 시 `mileage` 값이 있으면 `corporate_vehicles.mileage` 갱신 — Service 레이어에서 트랜잭션 처리
+3. **비용 집계**: 목록 API 응답에 총 정비비용, 주유비, 정비비, 기타 합계 포함
+4. **카테고리**: 8종 — 주유, 정비, 보험, 세차, 주차, 통행료, 검사, 기타
+5. **Auditable**: API 모델에 `Auditable` trait 적용
+6. **FormRequest**: `StoreVehicleMaintenanceRequest`, `UpdateVehicleMaintenanceRequest` 분리