Merge pull request #53 from DamnDamnDamnM3/feature/mileage-tracking

feat: 新增行車里程追蹤功能

Author: JW-Albert

backend/src/main/java/com/vehicle/management/api/controller/BorrowingController.java

@@ -1,6 +1,7 @@
 package com.vehicle.management.api.controller;
 
 import com.vehicle.management.api.dto.BorrowingResponse;
+import com.vehicle.management.api.dto.CompleteBorrowingRequest;
 import com.vehicle.management.api.dto.ReviewBorrowingRequest;
 import com.vehicle.management.api.dto.SubmitBorrowingRequest;
 import com.vehicle.management.domain.model.User;
@@ -77,7 +78,8 @@ public BorrowingResponse startUse(@PathVariable UUID id) {
     }
 
     @PostMapping("/{id}/complete")
-    public BorrowingResponse complete(@PathVariable UUID id) {
-        return BorrowingResponse.from(borrowingService.completeUse(id));
+    public BorrowingResponse complete(@PathVariable UUID id,
+                                       @Valid @RequestBody CompleteBorrowingRequest req) {
+        return BorrowingResponse.from(borrowingService.completeUse(id, req.endMileage()));
     }
 }

backend/src/main/java/com/vehicle/management/api/dto/BorrowingResponse.java

@@ -15,13 +15,16 @@ public record BorrowingResponse(
         String state,
         String reviewNote,
         Instant createdAt,
-        Instant updatedAt
+        Instant updatedAt,
+        Integer startMileage,
+        Integer endMileage
 ) {
     public static BorrowingResponse from(BorrowingRequest r) {
         return new BorrowingResponse(
                 r.getId(), r.getUserId(), r.getVehicleId(),
                 r.getPeriodStart(), r.getPeriodEnd(), r.getPurpose(),
                 r.getStateName(), r.getReviewNote(),
-                r.getCreatedAt(), r.getUpdatedAt());
+                r.getCreatedAt(), r.getUpdatedAt(),
+                r.getStartMileage(), r.getEndMileage());
     }
 }

backend/src/main/java/com/vehicle/management/api/dto/CompleteBorrowingRequest.java

@@ -0,0 +1,9 @@
+package com.vehicle.management.api.dto;
+
+import jakarta.validation.constraints.Min;
+
+/** 還車請求 DTO，攜帶結束里程數。 */
+public record CompleteBorrowingRequest(
+        @Min(value = 0, message = "里程數不可為負數")
+        int endMileage
+) {}

backend/src/main/java/com/vehicle/management/api/dto/VehicleResponse.java

@@ -11,10 +11,11 @@ public record VehicleResponse(
         String model,
         int year,
         String status,
-        Instant createdAt
+        Instant createdAt,
+        int currentMileage
 ) {
     public static VehicleResponse from(Vehicle v) {
         return new VehicleResponse(v.getId(), v.getPlate(), v.getModel(),
-                v.getYear(), v.getStatus().name(), v.getCreatedAt());
+                v.getYear(), v.getStatus().name(), v.getCreatedAt(), v.getCurrentMileage());
     }
 }

backend/src/main/java/com/vehicle/management/domain/model/BorrowingRequest.java

@@ -37,6 +37,10 @@ public class BorrowingRequest {
     private String reviewNote;
     private final Instant createdAt;
     private Instant updatedAt;
+    /** 出車時記錄的起始里程（可為 null）。 */
+    private Integer startMileage;
+    /** 還車時記錄的結束里程（可為 null）。 */
+    private Integer endMileage;
 
     /**
      * 建構新的借車申請，初始狀態為 {@link PendingState}（待審核）。
@@ -102,14 +106,16 @@ public void startUse() {
     }
 
     /**
-     * 完成用車並還車。
+     * 完成用車並還車，記錄結束里程。
      * 委派給目前的 {@link BorrowingState#complete} 執行狀態轉換。
      *
+     * @param endMileage 還車時的里程數
      * @throws com.vehicle.management.domain.state.InvalidStateTransitionException
      *         若目前狀態不是 IN_USE
      */
-    public void complete() {
+    public void complete(int endMileage) {
         state.complete(this);
+        this.endMileage = endMileage;
         this.updatedAt = Instant.now();
     }
 
@@ -160,4 +166,21 @@ public void transitionState(BorrowingState newState, String note) {
 
     /** @return 最後更新時間 */
     public Instant getUpdatedAt() { return updatedAt; }
+
+    /** @return 出車時的起始里程（可能為 {@code null}） */
+    public Integer getStartMileage() { return startMileage; }
+
+    /** @return 還車時的結束里程（可能為 {@code null}） */
+    public Integer getEndMileage() { return endMileage; }
+
+    /**
+     * 由 Adapter 呼叫，從資料庫還原里程資料。
+     *
+     * @param startMileage 起始里程
+     * @param endMileage   結束里程
+     */
+    public void restoreMileage(Integer startMileage, Integer endMileage) {
+        this.startMileage = startMileage;
+        this.endMileage = endMileage;
+    }
 }

backend/src/main/java/com/vehicle/management/domain/model/Vehicle.java

@@ -32,6 +32,8 @@ public class Vehicle {
     /** 可變狀態欄位，僅透過狀態守衛方法修改。 */
     private VehicleStatus status;
     private final Instant createdAt;
+    /** 車輛目前累積里程（公里），預設為 0。 */
+    private int currentMileage;
 
     /**
      * 建構車輛物件。
@@ -45,12 +47,29 @@ public class Vehicle {
      */
     public Vehicle(UUID id, String plate, String model, int year,
                    VehicleStatus status, Instant createdAt) {
+        this(id, plate, model, year, status, createdAt, 0);
+    }
+
+    /**
+     * 建構車輛物件（含里程）。
+     *
+     * @param id             車輛唯一識別碼
+     * @param plate          車牌號碼
+     * @param model          車款名稱
+     * @param year           出廠年份
+     * @param status         初始狀態
+     * @param createdAt      建立時間
+     * @param currentMileage 目前累積里程
+     */
+    public Vehicle(UUID id, String plate, String model, int year,
+                   VehicleStatus status, Instant createdAt, int currentMileage) {
         this.id = id;
         this.plate = plate;
         this.model = model;
         this.year = year;
         this.status = status;
         this.createdAt = createdAt;
+        this.currentMileage = currentMileage;
     }
 
     /**
@@ -109,4 +128,21 @@ public void markMaintenance() {
 
     /** @return 車輛資料建立時間 */
     public Instant getCreatedAt() { return createdAt; }
+
+    /** @return 車輛目前累積里程（公里） */
+    public int getCurrentMileage() { return currentMileage; }
+
+    /**
+     * 更新車輛累積里程。
+     *
+     * @param km 新的里程數（必須 >= 目前里程）
+     * @throws IllegalArgumentException 若 km 小於目前里程（里程不可倒退）
+     */
+    public void updateMileage(int km) {
+        if (km < currentMileage) {
+            throw new IllegalArgumentException(
+                    "New mileage " + km + " is less than current mileage " + currentMileage);
+        }
+        this.currentMileage = km;
+    }
 }

backend/src/main/java/com/vehicle/management/infrastructure/persistence/BorrowingRepositoryAdapter.java

@@ -56,13 +56,15 @@ private BorrowingRequest toDomain(BorrowingRequestEntity e) {
                 e.getId(), e.getUserId(), e.getVehicleId(),
                 e.getPeriodStart(), e.getPeriodEnd(), e.getPurpose(), e.getCreatedAt());
         // Restore state by replaying transitions
+        int endMil = e.getEndMileage() != null ? e.getEndMileage() : 0;
         switch (e.getState()) {
             case "APPROVED" -> r.approve(e.getReviewNote());
             case "REJECTED" -> r.reject(e.getReviewNote());
             case "IN_USE"   -> { r.approve(null); r.startUse(); }
-            case "RETURNED" -> { r.approve(null); r.startUse(); r.complete(); }
+            case "RETURNED" -> { r.approve(null); r.startUse(); r.complete(endMil); }
             // PENDING: no replay needed
         }
+        r.restoreMileage(e.getStartMileage(), e.getEndMileage());
         return r;
     }
 
@@ -78,6 +80,8 @@ private BorrowingRequestEntity toEntity(BorrowingRequest r) {
         e.setReviewNote(r.getReviewNote());
         e.setCreatedAt(r.getCreatedAt());
         e.setUpdatedAt(r.getUpdatedAt());
+        e.setStartMileage(r.getStartMileage());
+        e.setEndMileage(r.getEndMileage());
         return e;
     }
 }

backend/src/main/java/com/vehicle/management/infrastructure/persistence/VehicleRepositoryAdapter.java

@@ -53,7 +53,7 @@ public void delete(UUID id) {
 
     private Vehicle toDomain(VehicleEntity e) {
         return new Vehicle(e.getId(), e.getPlate(), e.getModel(), e.getYear(),
-                VehicleStatus.valueOf(e.getStatus()), e.getCreatedAt());
+                VehicleStatus.valueOf(e.getStatus()), e.getCreatedAt(), e.getCurrentMileage());
     }
 
     private VehicleEntity toEntity(Vehicle v) {
@@ -64,6 +64,7 @@ private VehicleEntity toEntity(Vehicle v) {
         e.setYear(v.getYear());
         e.setStatus(v.getStatus().name());
         e.setCreatedAt(v.getCreatedAt());
+        e.setCurrentMileage(v.getCurrentMileage());
         return e;
     }
 }

backend/src/main/java/com/vehicle/management/infrastructure/persistence/entity/BorrowingRequestEntity.java

@@ -39,6 +39,12 @@ public class BorrowingRequestEntity {
     @Column(name = "updated_at", nullable = false)
     private Instant updatedAt = Instant.now();
 
+    @Column(name = "start_mileage")
+    private Integer startMileage;
+
+    @Column(name = "end_mileage")
+    private Integer endMileage;
+
     public BorrowingRequestEntity() {}
 
     public UUID getId() { return id; }
@@ -61,4 +67,8 @@ public BorrowingRequestEntity() {}
     public void setCreatedAt(Instant createdAt) { this.createdAt = createdAt; }
     public Instant getUpdatedAt() { return updatedAt; }
     public void setUpdatedAt(Instant updatedAt) { this.updatedAt = updatedAt; }
+    public Integer getStartMileage() { return startMileage; }
+    public void setStartMileage(Integer startMileage) { this.startMileage = startMileage; }
+    public Integer getEndMileage() { return endMileage; }
+    public void setEndMileage(Integer endMileage) { this.endMileage = endMileage; }
 }

backend/src/main/java/com/vehicle/management/infrastructure/persistence/entity/VehicleEntity.java

@@ -27,6 +27,9 @@ public class VehicleEntity {
     @Column(name = "created_at", nullable = false, updatable = false)
     private Instant createdAt = Instant.now();
 
+    @Column(name = "current_mileage", nullable = false)
+    private int currentMileage = 0;
+
     public VehicleEntity() {}
 
     public UUID getId() { return id; }
@@ -41,4 +44,6 @@ public VehicleEntity() {}
     public void setStatus(String status) { this.status = status; }
     public Instant getCreatedAt() { return createdAt; }
     public void setCreatedAt(Instant createdAt) { this.createdAt = createdAt; }
+    public int getCurrentMileage() { return currentMileage; }
+    public void setCurrentMileage(int currentMileage) { this.currentMileage = currentMileage; }
 }