# CSP-002　專案骨架與模組結構（Project Skeleton & Module Structure）

| 項目 | 內容 |
|---|---|
| 文件編號 | CSP-002 |
| 版本 | 1.1 |
| 狀態 | 已核定 |
| 撰寫者 | SA / Tech Lead |
| 審查者 | PMO |
| 對應需求 | BRD-001 §5 系統邊界；SAD-002 微服務劃分 |

---

## 1. 目的

定義微服務程式碼倉（repository）的**標準骨架**：目錄布局、建置設定、共用程式庫、跨服務契約，
使 17 個服務（SAD-002）具備**一致、可獨立建置、可獨立部署**的結構。
骨架**僅提供結構與必要基礎設施接線**（如配置類、健康檢查端點），**不含任何業務邏輯空殼**（見 §6 禁止事項）。

---

## 2. 倉庫策略

建議採 **「一個服務一個倉庫」（one-service-one-repo）**，便於獨立 CI/CD 與權限隔離；
共用程式庫獨立為 `cardcore-common` 系列模組，經套件管理發佈。

```
cardcore/
├── backend/
│   ├── services/
│   │   ├── authorization-service/    授權（iECS 授權引擎）
│   │   ├── card-service/             卡片生命週期
│   │   ├── limit-service/            額度管理
│   │   ├── party-service/            歸戶／卡人（多層次帳戶歸戶層）
│   │   ├── product-service/          產品參數化（P0–P3）
│   │   ├── pricing-service/          費率／利息
│   │   ├── posting-service/          入帳／分戶（CQRS 寫側）
│   │   ├── payment-service/          繳款／約定扣款
│   │   ├── installment-service/      分期
│   │   ├── rewards-service/          點數累積／兌換
│   │   ├── statement-service/        帳單
│   │   ├── dispute-service/          爭議帳款
│   │   ├── clearing-service/          清算結算
│   │   ├── merchant-service/         特約商店／收單
│   │   ├── migration-service/        遷移波次（W0–W4）與回退
│   │   ├── notification-service/     通知
│   │   └── report-service/           報表
│   └── platform/
│       ├── api-gateway/              統一入口、路由、限流
│       ├── bff-web/                  Web 聚合層（前端 BFF）
│       ├── common-spring/            跨服務 Spring 基礎（例外、攔截器、追蹤）
│       ├── common-security/          鑑權、加解密、個資遮蔽
│       ├── common-event/             Kafka 事件基底、Outbox 工具
│       └── common-domain/            共用值物件（Money、CardNumber…）
└── frontend/
    └── cardcore-web/                 React 18 + Vite + TypeScript 單體前端
```

---

## 3. 單一服務骨架（Gradle 基線）

> 語言為 **Java 21**（見 `CSP-006 §2.1`）。原 1.0 版誤植為 Kotlin，已更正。

```
authorization-service/
├── build.gradle.kts                 依賴與外掛（Spring Boot、Jacoco、SpotBugs）
├── settings.gradle.kts
├── Dockerfile                       多階段建置（JRE 執行期）
├── src/main/
│   ├── java/com/beam/cardcore/auth/
│   │   ├── interfaces/rest/         AuthorizationController + DTO
│   │   ├── application/command/     AuthorizeTransactionHandler
│   │   ├── application/query/       GetAuthorizationHandler
│   │   ├── application/port/        AuthorizationRepositoryPort
│   │   ├── domain/model/            Authorization（聚合根）
│   │   ├── domain/service/          LimitCheckService
│   │   └── infrastructure/persistence/ OracleAuthorizationAdapter
│   └── resources/
│       ├── application.yml          連線、逾時、開關（來自 Config Server）
│       └── db/migration/            Flyway：V1__init.sql 等（Oracle 方言）
└── src/test/java/...                單元／整合測試（CSP-005）
```

**骨架約定**：每個服務暴露 `GET /actuator/health`（liveness/readiness）、
`GET /actuator/info`（版本、commit）、`GET /actuator/prometheus`（指標）。

**骨架產生**：17 個服務之骨架由 `tools/gen_service_skeleton.py` 依 `CSP-007` 產生，
不得手工複製貼上（避免骨架漂移）。

---

## 4. 共用程式庫職責

| 模組 | 職責 | 禁止放入 |
|---|---|---|
| `common-spring` | 全域例外攔截器、相關性 ID（correlation-id）過濾器、統一回應封套 | 業務規則 |
| `common-security` | JWT 驗證、欄位級加解密、個資遮蔽工具（對應 SAD-005） | 特定服務邏輯 |
| `common-event` | 事件基類、Outbox 表 DDL、發布器 | 領域事件內容 |
| `common-domain` | `Money`、`CardNumber`、`LimitAmount`、`Currency` 等值物件 | 可變狀態 |

---

## 5. 跨服務契約綁定

- **API 契約**：每個服務的 REST 介面必須與 `cardcore/contracts/openapi/<service>.yaml`（SDD-006）一致；
  CI 以 `openapi-diff` 比對實作與契約，不允許「實作漂移」。
- **事件契約**：領域事件結構定義於 `common-event`，版本以 `schema_version` 欄位向後相容演進。
- **DB 遷移**：Flyway 腳本須可重跑（冪等）；禁止在生產腳本使用 `DROP TABLE` 或 `DELETE` 全表。

---

## 6. 禁止事項（對應 CSP-001 §8）

1. **禁止空殼骨架**：`interfaces/`、`domain/`、`application/` 下不得出現「只有 `class` 宣告、方法本體空白」的檔案；
   骨架只包含 §3 所列之**基礎設施接線**（配置、健康端點、攔截器），不含業務類別佔位。
2. **禁止 `@SpringBootTest` 當單元測試**：單元測試不得啟動整個 Spring 容器（見 CSP-005）。
3. **禁止跨層依賴反轉**：`domain/` 不得依賴 `infrastructure/`；依賴方向必須為
   `interfaces → application → domain ← infrastructure`（依賴反轉原則）。
4. **禁止共用資料庫**：各服務自有 schema（SAD-003），禁止跨服務直連他庫。
   權威 OLTP schema 位於 **Oracle**（`CC_<SERVICE>`）；CQRS 讀模型／事件流存檔／報表位於
   **PostgreSQL**（`proj`／`evt`／`rpt`），詳見 `CSP-006 §2.4`。

```mermaid
flowchart TD
    A[interfaces] --> B[application]
    B --> C[domain]
    D[infrastructure] -.implements port.-> B
    D -.reads/writes.-> E[(schema: auth)]
    C -.defines port.-> B
    style C fill:#EEF3F8,stroke:#0B2E59
    style E fill:#FFF6E0,stroke:#C8A45C
```

---

## 7. 前端骨架（React 18 + Vite）

```
cardcore-web/
├── package.json                    React 18 / Vite / TypeScript / ESLint
├── src/
│   ├── app/                       路由、佈局、Provider
│   ├── features/                  依業務功能切分（auth, card, limit, party…）
│   │   └── <feature>/             components / hooks / api / types
│   ├── shared/                    UI 元件庫、HTTP client、錯誤處理
│   └── mocks/                     開發期假資料（**僅 dev 模式載入，不進 production bundle**）
└── vite.config.ts                 proxy 指向 api-gateway / bff-web
```

> **關鍵**：客戶認可之 `bank-core-react-standalone 1.html` 為**設計參考**（選單、版面、元件），
> 前端須依 SDD-007 重構為接真 API 的 React 元件；`src/mocks/` 僅於 `import.meta.env.DEV` 啟用，
> **正式建置不得包含任何 mock 資料路徑**（CI 以 `grep` 確認 production bundle 無 `mock` 引用）。

---

## 8. 修訂記錄

| 版本 | 日期 | 修訂者 | 說明 |
|---|---|---|---|
| 1.0 | 2026-09-17 | SA / Tech Lead | 初版 |
| 1.1 | 2026-09-18 | SA / Tech Lead | ①§3 骨架路徑 `src/main/kotlin/`、`src/test/kotlin/` 更正為 `src/main/java/`、`src/test/java/`——原路徑與 `CSP-001 §5` 指定之 Java 工具鏈（Checkstyle／SpotBugs／PMD）矛盾，經決議採 **Java 21**（`CSP-006 §2.1`）；②§3 持久化實作 `PostgresAuthorizationAdapter` 更名為 `OracleAuthorizationAdapter`——權威 OLTP 已改為 Oracle（`CSP-006 §2.4`）；③§3 增列骨架產生器 `tools/gen_service_skeleton.py` 與規範 `CSP-007`；④§6.4 補充 Oracle／PostgreSQL 之 schema 落點 |