Skip to content

Commit 770dd04

Browse files
JW-Albertclaude
JW-Albert
and
claude
committed
docs: 校對 README / CLAUDE.md 與專案實況一致
- 設計模式 6 → 10 個：總覽表補 Builder/Chain/Decorator/Command， 修正後 4 個模式標題編號（原本重複編號 6） - README 核心功能表補：通知收件夾、稽核日誌、帳號安全、資料治理、申請維護 - 技術選型補：springdoc-openapi 2.6.0、Spring Boot Actuator - 專案結構補：domain/chain、domain/command、infrastructure/config、 新增 service、Email/InboxNotificationObserver、前端 api/views（notifications/audit/system、InboxView/AdminAuditView） - CLAUDE.md：Flyway migration V1–V5 → V1–V8、依賴與套件清單更新、 Project Overview 模式列表、補 Swagger UI / Actuator 端點說明 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 333456b commit 770dd04

2 files changed

Lines changed: 45 additions & 27 deletions

File tree

‎CLAUDE.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Project Overview
44

55
Project: 114-2 逢甲大學軟體框架設計期末專題 — 公司車輛管理系統
6-
Purpose: 企業內部車輛借用管理平台，提供借車申請、審核、出車、還車完整工作流程，並展示 OOD 原則（SOLID、LoD）與 GoF 設計模式（State、Observer、Strategy、Factory Method、Adapter）的實際應用。
6+
Purpose: 企業內部車輛借用管理平台，提供借車申請、審核、出車、還車完整工作流程，並涵蓋站內通知收件夾、稽核日誌、帳號安全（密碼政策 + 登入鎖定）、車輛軟刪除等企業化功能；展示 OOD 原則（SOLID、LoD）與 10 個 GoF 設計模式（State、Observer、Strategy、Template Method、Factory Method、Adapter、Builder、Chain of Responsibility、Decorator、Command）的實際應用。
77
Owner: DamnDamnDamnM3（王建葦 D1210799、陳稚翔 D1249623）
88
Demo: https://demo.jw-albert.dev
99

@@ -12,7 +12,7 @@ Demo: https://demo.jw-albert.dev
1212
**Backend**
1313
- Language: Java 21
1414
- Framework: Spring Boot 3.3.4
15-
- Key dependencies: Spring Security + JJWT 0.12.6、Spring Data JPA、Flyway、Apache POI 5.3.0（Excel 匯出）、H2（dev profile）、PostgreSQL（prod profile）
15+
- Key dependencies: Spring Security + JJWT 0.12.6、Spring Data JPA、Flyway、Apache POI 5.3.0（Excel 匯出）、springdoc-openapi 2.6.0（Swagger UI）、Spring Boot Actuator（健康監控）、H2（dev profile）、PostgreSQL（prod profile）
1616
- Build tool: Maven 3.9+（含 Maven Wrapper，無需全域安裝）
1717

1818
**Frontend**
@@ -25,31 +25,34 @@ Demo: https://demo.jw-albert.dev
2525
```
2626
backend/
2727
src/main/java/com/vehicle/management/
28-
api/controller/ - REST Controllers（BorrowingController、VehicleController 等）
28+
api/controller/ - REST Controllers（Borrowing、Vehicle、Notification、Audit、Violation 等）
2929
api/dto/ - Request / Response records
30-
domain/model/ - 領域模型（BorrowingRequest、Vehicle、User）
30+
domain/model/ - 領域模型（BorrowingRequest、Vehicle、User、Notification、AuditLog）
3131
domain/state/ - State Pattern（PendingState、ApprovedState、InUseState 等）
3232
domain/role/ - Role / Permission、RoleFactory（Factory Method）
33-
domain/observer/ - BorrowingEventPublisher、EmailNotificationObserver
34-
domain/strategy/ - ConflictCheckStrategy、StrictOverlapStrategy
35-
service/ - BorrowingService、VehicleService、ViolationService 等
36-
repository/ - 介面定義（IBorrowingRepository 等）+ InMemory 實作（測試用）
33+
domain/observer/ - BorrowingEventPublisher、Email/InboxNotificationObserver（Observer）
34+
domain/strategy/ - ConflictCheckStrategy、StrictOverlapStrategy、BufferedOverlapDecorator（Decorator）
35+
domain/chain/ - BorrowingValidator 責任鏈（Chain of Responsibility）
36+
domain/command/ - BorrowingCommand、ApproveCommand 等 + BorrowingCommandBus（Command）
37+
service/ - BorrowingService、NotificationService、AuditService、LoginAttemptService、PasswordPolicy 等
38+
repository/ - 介面定義（IBorrowingRepository、INotificationRepository 等）+ InMemory 實作（測試用）
3739
infrastructure/
3840
persistence/ - JPA Entities + Repository Adapters（Adapter Pattern）
3941
security/ - JwtUtil、JwtAuthFilter、SecurityConfig
42+
config/ - OpenApiConfig（Swagger UI 設定）
4043
src/main/resources/
4144
application.yml - 預設設定（PostgreSQL prod）
4245
application-dev.yml - dev profile（H2 記憶體 DB，自動建測試帳號）
43-
db/migration/ - Flyway SQL 遷移腳本（V1__init.sql … V5__violations.sql）
46+
db/migration/ - Flyway SQL 遷移腳本（V1__initial_schema.sql … V8__soft_delete_vehicles.sql）
4447
4548
frontend/
4649
src/
47-
api/ - auth.ts / vehicles.ts / borrowings.ts / maintenance.ts / reports.ts
50+
api/ - auth / vehicles / borrowings / maintenance / reports / notifications / audit / system
4851
stores/ - auth.ts（Pinia，存 JWT token 與使用者資訊）
4952
router/ - index.ts（路由守衛：adminOnly / approverOnly / requiresAuth）
50-
views/ - LoginView / EmployeeBorrowView / AdminReviewView / AdminVehiclesView
53+
views/ - LoginView / EmployeeBorrowView / InboxView / AdminReviewView / AdminVehiclesView
5154
AdminMaintenanceView / AdminUserManagementView / AdminViolationsView
52-
CalendarView / AdminDashboardView
55+
AdminAuditView / CalendarView / AdminDashboardView
5356
5457
.github/workflows/
5558
deploy.yml - GitHub Actions CI/CD（tag-based，建置 JAR + SSH 部署至 VPS）
@@ -101,6 +104,7 @@ npx vue-tsc --build --noEmit
101104
- **PM2 on VPS**：VPS 使用者無 sudo 權限，PM2 安裝於 `$HOME/.npm-global`。SSH session 不讀 `~/.profile`，因此 `java` 必須用絕對路徑啟動（`which java` 動態取得）。
102105
- **Vite allowedHosts**：`vite.config.ts` 中已設定 `allowedHosts: ['demo.jw-albert.dev']`，讓 Cloudflare Tunnel 可以正常存取 Vite dev server。
103106
- **`frontend/tsconfig.node.json`**：需包含 `"types": ["node"]` 與 `"skipLibCheck": true`，否則 CI `vue-tsc --build` 會失敗。
107+
- **API 文件與健康檢查**：後端啟動後可瀏覽 `http://localhost:8080/swagger-ui.html`（互動式 API 文件，可用 JWT 授權測試）與 `http://localhost:8080/actuator/health`（健康狀態）。前端 Vite proxy 已涵蓋 `/api` 與 `/actuator`。
104108

105109
## Workflow Rules
106110

‎README.md‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@
2626
| 審核工作流 | 管理員核准 / 拒絕、備注填寫、全部記錄查詢 |
2727
| 保養管理 | 保養紀錄新增 / 查詢、到期日提醒 |
2828
| 違規管理 | 還車超時自動登錄、管理員 / 主管手動登錄（車損、違停、交通違規等） |
29+
| 通知收件夾 | 站內訊息中心 + 未讀狀態燈，借車事件自動通知相關人（Observer Pattern） |
30+
| 稽核日誌 | 借車狀態操作自動記錄並持久化，管理員可查詢（Command Pattern） |
31+
| 帳號安全 | 密碼強度政策、連續登入失敗帳號鎖定 |
32+
| 資料治理 | 車輛軟刪除與還原，保留資料可追溯 |
33+
| 申請維護 | 管理員 / 主管撤銷已核准申請、更改申請內容 |
2934

3035
---
3136

@@ -37,6 +42,8 @@
3742
| 安全認證 | Spring Security + JJWT | 0.12.6 |
3843
| 資料庫 | PostgreSQL + Spring Data JPA | — |
3944
| DB 遷移 | Flyway | — |
45+
| API 文件 | springdoc-openapi（Swagger UI） | 2.6.0 |
46+
| 健康監控 | Spring Boot Actuator | — |
4047
| 前端框架 | Vue 3 + TypeScript | — |
4148
| 狀態管理 | Pinia | 2.x |
4249
| HTTP 客戶端 | Axios | 1.x |
@@ -81,42 +88,49 @@
8188
│ │ │ ├── controller/ # REST Controllers + GlobalExceptionHandler
8289
│ │ │ └── dto/ # Request / Response records
8390
│ │ ├── domain/
84-
│ │ │ ├── model/ # BorrowingRequest, Vehicle, User, MaintenanceRecord
91+
│ │ │ ├── model/ # BorrowingRequest, Vehicle, User, Notification, AuditLog…
8592
│ │ │ ├── state/ # State Pattern: BorrowingState, PendingState, …
86-
│ │ │ ├── role/ # Role, AdminRole, EmployeeRole, RoleFactory, Permission
87-
│ │ │ ├── observer/ # BorrowingEventPublisher, EmailNotificationObserver
88-
│ │ │ └── strategy/ # ConflictCheckStrategy, StrictOverlapStrategy
89-
│ │ ├── service/ # BorrowingService, VehicleService, …
90-
│ │ ├── repository/ # IVehicleRepository, IBorrowingRepository, …
93+
│ │ │ ├── role/ # Role, AdminRole, EmployeeRole, ManagerRole, RoleFactory
94+
│ │ │ ├── observer/ # BorrowingEventPublisher, Email/InboxNotificationObserver
95+
│ │ │ ├── strategy/ # ConflictCheckStrategy, StrictOverlapStrategy, BufferedOverlapDecorator
96+
│ │ │ ├── chain/ # Chain of Responsibility: BorrowingValidator 責任鏈
97+
│ │ │ └── command/ # Command Pattern: ApproveCommand, RejectCommand, …
98+
│ │ ├── service/ # BorrowingService, NotificationService, AuditService, LoginAttemptService…
99+
│ │ ├── repository/ # IVehicleRepository, IBorrowingRepository, INotificationRepository…
91100
│ │ │ └── inmemory/ # InMemory 實作（單元測試用）
92101
│ │ └── infrastructure/
93102
│ │ ├── persistence/ # JPA Entities + Repository Adapters
94-
│ │ └── security/ # JwtUtil, JwtAuthFilter, SecurityConfig
103+
│ │ ├── security/ # JwtUtil, JwtAuthFilter, SecurityConfig
104+
│ │ └── config/ # OpenApiConfig（Swagger UI）
95105
│ └── test/java/com/vehicle/management/
96106
│ ├── unit/ # BorrowingServiceTest, VehicleServiceTest, …
97107
│ └── integration/ # BorrowingControllerTest (WebMvcTest)
98108
└── frontend/
99109
└── src/
100-
├── api/ # auth.ts / vehicles.ts / borrowings.ts / maintenance.ts
110+
├── api/ # auth / vehicles / borrowings / notifications / audit / system…
101111
├── stores/ # auth.ts (Pinia)
102112
├── router/ # index.ts
103-
└── views/ # LoginView / EmployeeBorrowView / Admin views
113+
└── views/ # LoginView / EmployeeBorrowView / InboxView / AdminAuditView / …
104114
```
105115

106116
---
107117

108118
## 設計模式應用
109119

110-
本專案實作了 **6 個 GoF 設計模式**，涵蓋 Behavioral、Structural、Creational 三大分類。
120+
本專案實作了 **10 個 GoF 設計模式**，涵蓋 Behavioral、Structural、Creational 三大分類，其中後 4 個（Builder、Chain of Responsibility、Decorator、Command）用於重構既有設計、消除擴充痛點。
111121

112122
| # | 模式 | 分類 | 主要類別 |
113123
|---|------|------|---------|
114124
| 1 | [State](#1-state-pattern--借車申請生命週期) | Behavioral | `BorrowingRequest`, `BorrowingState`, `PendingState`… |
115-
| 2 | [Observer](#2-observer-pattern--借車事件通知) | Behavioral | `BorrowingEventPublisher`, `EmailNotificationObserver` |
125+
| 2 | [Observer](#2-observer-pattern--借車事件通知) | Behavioral | `BorrowingEventPublisher`, `EmailNotificationObserver`, `InboxNotificationObserver` |
116126
| 3 | [Strategy](#3-strategy-pattern--時段衝突檢查) | Behavioral | `ConflictCheckStrategy`, `StrictOverlapStrategy` |
117127
| 4 | [Template Method](#4-template-method-pattern--服務層權限守衛) | Behavioral | `AbstractProtectedService`, `VehicleService`, `MaintenanceService` |
118128
| 5 | [Factory Method](#5-factory-method-pattern--角色建立) | Creational | `RoleFactory`, `AdminRole`, `EmployeeRole`, `ManagerRole` |
119129
| 6 | [Adapter](#6-adapter-pattern--repository-橋接) | Structural | `*RepositoryAdapter`, `Jpa*Repo` |
130+
| 7 | [Builder](#7-builder-pattern--借車申請物件建構63) | Creational | `BorrowingRequest.Builder` |
131+
| 8 | [Chain of Responsibility](#8-chain-of-responsibility-pattern--借車申請多步驟驗證64) | Behavioral | `BorrowingValidator`, `PermissionValidator`, `TimeConflictValidator` |
132+
| 9 | [Decorator](#9-decorator-pattern--可疊加的衝突緩衝策略65) | Structural | `BufferedOverlapDecorator` |
133+
| 10 | [Command](#10-command-pattern--借車狀態操作稽核66) | Behavioral | `BorrowingCommand`, `BorrowingCommandBus`, `ApproveCommand` |
120134

121135
---
122136

@@ -399,7 +413,7 @@ classDiagram
399413

400414
---
401415

402-
### 6. Builder Pattern — 借車申請物件建構（[#63](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/63)）
416+
### 7. Builder Pattern — 借車申請物件建構（[#63](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/63)）
403417

404418
**問題**：`BorrowingRepositoryAdapter.toDomain()` 從資料庫還原物件時，需呼叫 `r.approve(null); r.startUse();` 等副作用方法重播 State transition，會觸發 Observer 通知且邏輯脆弱。
405419

@@ -436,7 +450,7 @@ classDiagram
436450
437451
---
438452

439-
### 7. Chain of Responsibility Pattern — 借車申請多步驟驗證（[#64](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/64)）
453+
### 8. Chain of Responsibility Pattern — 借車申請多步驟驗證（[#64](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/64)）
440454

441455
**問題**：`BorrowingService.submitRequest()` 依序進行「權限檢查 → 車輛存在 → 時段衝突」三步驗證，邏輯全寫在一個方法中，新增驗證規則需修改 Service 本身（違反 OCP）。
442456

@@ -482,7 +496,7 @@ classDiagram
482496
483497
---
484498

485-
### 8. Decorator Pattern — 可疊加的衝突緩衝策略（[#65](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/65)）
499+
### 9. Decorator Pattern — 可疊加的衝突緩衝策略（[#65](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/65)）
486500

487501
**問題**：若需在現有嚴格重疊策略上加入「借車前後保留 30 分鐘緩衝時間」的規則，直接修改 `StrictOverlapStrategy` 會使其邏輯複雜，且難以在不同情境下選擇是否啟用緩衝。
488502

@@ -512,7 +526,7 @@ classDiagram
512526
513527
---
514528

515-
### 9. Command Pattern — 借車狀態操作稽核（[#66](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/66)）
529+
### 10. Command Pattern — 借車狀態操作稽核（[#66](https://github.com/DamnDamnDamnM3/114-2_FCU_Framework-Design-Final/issues/66)）
516530

517531
**問題**：`BorrowingController` 直接呼叫 `borrowingService.approveRequest(...)` 等方法，各操作的稽核日誌、非同步處理等橫切關注點分散在各 endpoint，無法統一管理。
518532

0 commit comments

Comments
 (0)