From 74facf050a6e2cb312dd80f4d6a91662d59eb385 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Thu, 12 Mar 2026 21:56:36 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[card-vehicle]=20=EC=B0=A8=EB=9F=89?= =?UTF-8?q?=EA=B4=80=EB=A6=AC=203=EA=B0=9C=20=EB=A9=94=EB=89=B4=20?= =?UTF-8?q?=EC=9D=B4=EA=B4=80=20=EB=AC=B8=EC=84=9C=20=EC=B5=9C=EC=8B=A0?= =?UTF-8?q?=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: 기술 스택 버전 수정 (Laravel 12, PHP 8.4), 이관 현황 테이블 추가 - corporate-vehicles.md: 이관 현황 + API 이관 스펙 (엔드포인트, 필터, 고려사항) - vehicle-logs.md: 이관 현황 + API 이관 스펙 (summary 응답 구조 포함) - vehicle-maintenance.md: 이관 현황 + API 이관 스펙 (주행거리 갱신 로직 포함) --- features/card-vehicle/README.md | 24 +++++++- features/card-vehicle/corporate-vehicles.md | 44 +++++++++++++++ features/card-vehicle/vehicle-logs.md | 59 ++++++++++++++++++++ features/card-vehicle/vehicle-maintenance.md | 45 +++++++++++++++ 4 files changed, 171 insertions(+), 1 deletion(-) diff --git a/features/card-vehicle/README.md b/features/card-vehicle/README.md index 064692d..36bce2d 100644 --- 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`는 출하 배차 기능이며, 차량관리와 별도이다. diff --git a/features/card-vehicle/corporate-vehicles.md b/features/card-vehicle/corporate-vehicles.md index 9b5eef5..fdc9d6a 100644 --- 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` 분리 diff --git a/features/card-vehicle/vehicle-logs.md b/features/card-vehicle/vehicle-logs.md index a0ab543..9af875e 100644 --- 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` 분리 diff --git a/features/card-vehicle/vehicle-maintenance.md b/features/card-vehicle/vehicle-maintenance.md index 2930cf6..b0a412b 100644 --- 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` 분리