Dev yuan 1203

Dockerfile

@@ -1,22 +1,23 @@
-# Build stage
-FROM eclipse-temurin:17-jdk-alpine AS build
-WORKDIR /workspace/app
+FROM eclipse-temurin:17-jdk-alpine
+WORKDIR /app
+
+# 安裝 Maven
+RUN apk add --no-cache maven
 
+# 複製 Maven wrapper 和 pom.xml
 COPY mvnw .
 COPY .mvn .mvn
 COPY pom.xml .
-COPY src src
 
-# Grant execution rights on the mvnw wrapper
+# 下載依賴（這層會被快取）
 RUN chmod +x mvnw
-RUN ./mvnw install -DskipTests
-RUN mkdir -p target/dependency && (cd target/dependency; jar -xf ../*.jar)
+RUN ./mvnw dependency:go-offline -B
 
-# Run stage
-FROM eclipse-temurin:17-jdk-alpine
-VOLUME /tmp
-ARG DEPENDENCY=/workspace/app/target/dependency
-COPY --from=build ${DEPENDENCY}/BOOT-INF/lib /app/lib
-COPY --from=build ${DEPENDENCY}/META-INF /app/META-INF
-COPY --from=build ${DEPENDENCY}/BOOT-INF/classes /app
-ENTRYPOINT ["java","-cp","app:app/lib/*","com.example.ride_hailing.RideHailingApplication"]
+# 複製源碼
+COPY src src
+
+# 暴露端口
+EXPOSE 8080 5005
+
+# 使用 spring-boot:run 啟動，支援 devtools hot-reload
+CMD ["./mvnw", "spring-boot:run", "-Dspring-boot.run.jvmArguments=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"]

README.md

@@ -1,29 +1,114 @@
-# 白癡 SA 作業
+# 系統分析與設計作業--簡易乘車配對系統 (Ride-Hailing System)
 
-## 專案更新 (2025-11-28)
-- **架構重整**：已將專案結構調整為標準 Maven 目錄結構 (`src/main/java/...`)。
-- **容器化**：新增 `Dockerfile` 與 `docker-compose.yml`，支援一鍵啟動。
-- **依賴修正**：修復 `pom.xml` 依賴與 Plugin 設定，解決編譯錯誤。
-- **功能修復**：修正 Model 缺漏與語法錯誤，Web 服務已可正常存取。
+- 這是一個基於 Java Spring Boot 開發的簡易乘車配對平台，模擬了乘客發送乘車請求、司機報價以及乘客選擇司機進行配對的完整流程。
 
-## 啟動方式 (推薦)
-本專案已支援 Docker Compose，無需手動安裝 Java 或 Maven 環境。
+## 👥 組員資訊
+- 資管三 112403531 汪筠涵
+- 資管三 112403026 魏仁祥
+- 資管三 112403523 傅聖祐
+- 資管三 112403525 黃媺涵
+- 資管三 112403543 王暐元
 
-1. 確保已安裝 **Docker** 與 **Docker Compose**。
-2. 在專案根目錄執行：
+
+## 系統簡介
+
+系統架構前後端分離，旨在展示一個簡易的叫車服務架構 (前端為 GenAI 生成之單一 HTML 檔案)。
+- **乘客**：可以輸入上車地點、目的地與時間，發送請求，並查看司機的即時報價。
+- **司機**：可以查看線上的乘車請求並提交報價。
+- **配對**：乘客從報價列表中選擇心儀的司機，完成配對並交換聯絡資訊。
+
+---
+
+## 安裝與啟動教學
+
+### 環境需求
+- **Docker**
+- **Java JDK 17+** 與 **Maven**
+
+### 方法一：Docker
+
+1. 開啟終端機 (Terminal/PowerShell)。
+2. 進入專案根目錄。
+3. 執行以下指令：
    ```bash
-   docker-compose up --build
+   docker compose up --build
    ```
-3. 等待啟動完成後，開啟瀏覽器存取：
-   - 首頁：http://localhost:8080
-
-## 傳統啟動方式 (不推薦)
-若仍需使用本機 Maven 啟動：
-1. `java -version` (需 JDK 17+)
-2. `mvn -v`
-3. `mvn spring-boot:run`
-
-## 專案結構
-- `src/main/java`: 後端原始碼 (Controller, Model, Service)
-- `src/main/resources`: 設定檔與靜態資源 (HTML)
-- `docker-compose.yml`: 容器編排設定
+4. 等待看到 `Started RideHailingApplication` 字樣。
+5. 開啟瀏覽器訪問：[http://localhost:8080](http://localhost:8080)
+
+---
+
+### 方法二：使用 Maven 本機執行
+
+1. 確保已安裝 JDK 17 或以上版本。
+2. 在專案根目錄執行：
+   - **Windows**:
+     ```powershell
+     .\mvnw spring-boot:run
+     ```
+   - **Mac/Linux**:
+     ```bash
+     ./mvnw spring-boot:run
+     ```
+3. 啟動後訪問：[http://localhost:8080](http://localhost:8080)
+
+## 專案結構說明
+
+採用標準的 MVC 分層架構，主要程式碼位於 `src/main/java/com/example/ride_hailing/` 下。
+
+### 1. Controller 層 (`controller/`)
+負責接收前端的 HTTP 請求，並將請求轉發給 Service 層處理。
+- **`RideController.java`**: 
+  - 定義了所有的 API 端點 (Endpoints)，如 `/api/rides/request` (建立請求), `/api/rides/bids` (取得報價)。
+  - 作為前端與後端邏輯的入口點。
+
+### 2. Service 層 (`service/`)
+負責業務邏輯的處理與狀態管理。
+- **`RideService.java`**: 
+  - 系統的核心服務類別。
+  - 管理司機列表 (`drivers`)、當前的乘客 (`currentPassenger`) 與乘車請求 (`currentRideRequest`)。
+  - 協調 Model 層的物件進行運算（例如呼叫 `Passenger` 物件來獲取報價列表）。
+
+### 3. Model 層 (`model/`)
+定義系統的資料結構與核心商業邏輯。
+- **`Passenger.java`**: 
+  - 代表乘客實體。
+  - **關鍵邏輯**：包含 `updateBideList` 方法，負責決定乘客能看到哪些報價（這是系統設計的一個特點，報價列表是由乘客物件視角提供的）。
+- **`Driver.java`**: 代表司機實體，包含車輛資訊與狀態。
+- **`RideRequest.java`**: 代表一筆乘車請求，包含起訖點、狀態 (`INITIATE`, `MATCHED`) 與收到的報價列表。
+- **`Bid.java`**: 代表司機對某一請求的報價。
+- **`MatchService.java`**: 處理具體的配對邏輯，如建立請求、新增報價、執行配對等。
+
+### 4. 前端資源 (`src/main/resources/static/`)
+- **`index.html`**: 使用者介面，包含乘客端與司機端的模擬畫面。
+- **`script.js`**: 前端邏輯，負責透過 `fetch` API 與後端 Controller 溝通，並動態更新頁面 DOM 元素。
+
+---
+
+## 系統交互流程
+
+以下說明一個完整的叫車流程是如何在各個檔案間交互運作的：
+
+1.  **發送請求**：
+    - **前端** (`script.js`) 呼叫 `POST /api/rides/request`。
+    - **Controller** (`RideController`) 接收請求並呼叫 `RideService.createRideRequest`。
+    - **Service** 透過 `MatchService` 建立一個新的 `RideRequest` 物件。
+
+2.  **司機報價**：
+    - **前端** (司機介面) 呼叫 `POST /api/rides/bids/submit`。
+    - **Controller** 接收並轉發給 `RideService`。
+    - **Service** 將報價 (`Bid`) 加入到該 `RideRequest` 的報價列表中。
+
+3.  **顯示報價列表 (關鍵交互)**：
+    - **前端** 定時輪詢 `GET /api/rides/bids`。
+    - **Controller** 呼叫 `RideService.getAllBids()`。
+    - **Service** 呼叫 `currentPassenger.updateBideList(currentRideRequest)`。
+    - **Model** (`Passenger`) 執行邏輯並回傳報價列表給 Service -> Controller -> 前端。
+    - *這確保了資料是經過乘客物件的邏輯過濾或處理的。*
+
+4.  **選擇配對**：
+    - **前端** (乘客介面) 呼叫 `POST /api/rides/bids/select`。
+    - **Service** 更新請求狀態為 `MATCHED`。
+    - **前端** 顯示配對成功資訊。
+
+---

docker-compose.yml

@@ -4,5 +4,17 @@ services:
     build: .
     ports:
       - "8080:8080"
+      - "5005:5005"  # Debug port
     environment:
-      - SPRING_PROFILES_ACTIVE=docker
+      - SPRING_PROFILES_ACTIVE=dev
+      - SPRING_DEVTOOLS_RESTART_ENABLED=true
+      - SPRING_DEVTOOLS_LIVERELOAD_ENABLED=true
+    volumes:
+      # 掛載源碼目錄實現 hot-reload
+      - ./src:/app/src:delegated
+      # 掛載 Maven 本地倉庫以加速構建
+      - ~/.m2:/root/.m2:cached
+      # 避免掛載 target 目錄
+      - /app/target
+    stdin_open: true
+    tty: true

docs/intro-mvn.md

@@ -0,0 +1,55 @@
+# Maven 與 .mvn 資料夾介紹
+
+## 什麼是 Maven？
+
+**Apache Maven** 是一個主要用於 Java 專案的**專案管理與自動化建置工具**。它基於專案物件模型（Project Object Model，簡稱 POM）的概念，透過一個核心的設定檔 `pom.xml` 來管理專案的建置、報告和文件。
+
+### Maven 的核心功能：
+
+1.  **依賴管理 (Dependency Management)**：
+    這是 Maven 最強大的功能之一。您只需要在 `pom.xml` 中宣告您需要的函式庫（例如 Spring Boot, JUnit），Maven 就會自動從中央儲存庫（Maven Central Repository）下載這些 jar 檔及其依賴的其他 jar 檔，免去了手動管理 classpath 的痛苦。
+
+2.  **標準化的目錄結構**：
+    Maven 提倡 "Convention over Configuration"（慣例優於配置）。它定義了一套標準的專案結構（如 `src/main/java` 放原始碼，`src/test/java` 放測試碼），讓任何熟悉 Maven 的開發者都能快速看懂您的專案結構。
+
+3.  **建置生命週期 (Build Lifecycle)**：
+    Maven 定義了標準的建置階段，例如：
+    - `clean`: 清除上次建置產生的檔案。
+    - `compile`: 編譯原始碼。
+    - `test`: 執行單元測試。
+    - `package`: 將編譯後的程式碼打包成可發布的格式（如 JAR 或 WAR）。
+    - `install`: 將打包好的檔案安裝到本地儲存庫，供其他本地專案使用。
+
+---
+
+## 什麼是 .mvn 資料夾？
+
+`.mvn` 資料夾是 **Maven Wrapper** 機制的配置目錄。它的主要目的是確保專案可以在任何環境下（開發者的電腦、CI/CD 伺服器等）使用**特定版本**的 Maven 進行建置，而不需要預先手動安裝 Maven。
+
+## 資料夾結構與內容
+
+在 `.mvn` 資料夾中，通常包含以下內容：
+
+- **wrapper/**
+  - `maven-wrapper.properties`: 這是核心設定檔。它指定了該專案所需的 Maven 版本（例如 3.8.6）以及下載 Maven 的 URL。
+  - `maven-wrapper.jar` (有時會存在，或由 script 下載): 負責實際下載並執行 Maven 的 Java 程式庫。
+
+## 它是如何運作的？
+
+當您在專案根目錄看到 `mvnw` (Linux/macOS) 和 `mvnw.cmd` (Windows) 這兩個腳本時，它們就是搭配 `.mvn` 資料夾運作的。
+
+1. 當您執行 `./mvnw clean install` 時，腳本會讀取 `.mvn/wrapper/maven-wrapper.properties`。
+2. 它會檢查您的電腦是否已經下載了指定版本的 Maven。
+3. 如果沒有，它會自動下載該版本的 Maven 到使用者的家目錄 (`~/.m2/wrapper/`)。
+4. 最後，它會使用這個下載的 Maven 來執行您的建置命令。
+
+## 為什麼要保留它？
+
+保留 `.mvn` 資料夾與 `mvnw` 腳本有以下好處：
+
+1. **環境一致性**：確保所有開發者和 CI 伺服器都使用完全相同的 Maven 版本，避免因為版本差異導致的建置錯誤 ("It works on my machine" 問題)。
+2. **快速上手**：新加入的開發者不需要安裝 Maven，只要有 Java 環境，拉下程式碼後直接執行 `./mvnw` 即可開始工作。
+
+## 總結
+
+`.mvn` 資料夾是專案建置工具鏈的重要組成部分，**不建議刪除**。它讓您的專案更加獨立且易於移植。

pom.xml

@@ -52,6 +52,18 @@
 		</dependency>
 	</dependencies>
 
+	<profiles>
+		<profile>
+			<id>dev</id>
+			<activation>
+				<activeByDefault>true</activeByDefault>
+			</activation>
+			<properties>
+				<spring-boot.run.fork>false</spring-boot.run.fork>
+			</properties>
+		</profile>
+	</profiles>
+
 	<build>
 		<plugins>
 			<plugin>