開發慣例 (Development Conventions)

這份文件記錄了開發此應用程式時應遵循的慣例和最佳實踐。

1. JPA 實體 (JPA Entities)

為了程式碼的可讀性、避免與 SQL 保留字衝突，並與 Spring Security 框架術語保持一致，我們遵循以下命名規則：

核心認證實體:
- 使用者實體應命名為 Account (對應資料表 accounts)。
- 角色/權限實體應命名為 Authority (對應資料表 authorities)。
- 未來若有更細粒度的權限，應命名為 Privilege。
通用規則:
- 當實體名稱與 SQL 保留字（如 USER, ORDER）衝突時，應使用語意清晰的替代名稱（如 Account, ProductOrder），並將其資料表名稱設定為複數形式。
- 對於沒有衝突的實體（如 Product），則無需特別指定 @Table 名稱，使用 JPA 預設的類別名稱即可。
- 不使用統一的資料表前綴（如 app_）。

所有 JPA 實體應遵循以下結構：

繼承: 繼承 AuditableBase 基底類別，以獲得標準的審計欄位 (如 createdBy, createdDate)。
Lombok: 使用 @Getter, @Setter, @NoArgsConstructor 來簡化程式碼。
主鍵:
- 主鍵欄位應命名為 uuid。
- 型別為 String，長度 36。
- 使用 @GeneratedValue(strategy = GenerationType.UUID) 自動生成。
註解:
- 使用 jakarta.persistence.* 進行 ORM 映射。
- 使用 jakarta.validation.constraints.* 進行欄位驗證。

本專案採用多模組架構，各模組職責分明，以提高程式碼的重用性與維護性。

appfuse-server:
- 定位: 核心公用函式庫 (Shared Library)。
- 職責: 封裝了應用程式的核心業務邏輯、資料存取、安全框架等通用功能。它被設計為可重用的元件，並會發佈至 Maven 倉庫。
- 特徵: 在 build.gradle.kts 中使用 java-library 插件，且不打包為可執行的 bootJar。
app-server:
- 定位: 參考實作應用程式 (Reference Implementation)。
- 職責: 作為一個完整的 Web 應用程式，展示如何使用 appfuse-server 函式庫來建構一個功能齊全的系統。它提供了前端 UI、API 端點，並作為各種安全機制的具體實作範例。
- 特徵: 在 build.gradle.kts 中依賴 appfuse-server 模組。

本應用程式使用非對稱式 RSA 金鑰來簽發與驗證本地 JWT。為了讓應用程式能正常啟動與運作，您需要在本地開發環境中產生一組金鑰，並將其設定在 application.yaml 中。

請在您的終端機中執行以下 openssl 指令來產生一個 2048 位元的 RSA 金鑰對。

產生私鑰 (PEM 格式):

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

從私鑰中提取公鑰 (PEM 格式):

openssl rsa -pubout -in private_key.pem -out public_key.pem

應用程式設定檔需要 Base64 編碼格式的金鑰。

轉換並編碼私鑰:

openssl pkcs8 -topk8 -inform PEM -outform DER -in private_key.pem -nocrypt | base64

轉換並編碼公鑰:
```
openssl rsa -in public_key.pem -pubin -outform DER | base64
```
執行完上述指令後，請複製終端機輸出的兩段長字串。

開啟位於 app-server/src/main/resources/ 的 application.yaml 檔案，找到 app.jwt 區塊，並將您在上一步複製的 Base64 字串貼入對應的欄位。

app:
  jwt:
    private-key: "貼上你的私鑰 Base64 字串"
    public-key: "貼上你的公鑰 Base64 字串"
    expiration: 86400000 # 24 hours

完成以上步驟後，您的 app-server 應用程式便已具備簽發與驗證 JWT 的能力。