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

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. 共用程式庫職責

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。

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. 修訂記錄