1.0.0-alpha        # 早期開發，API 可能大幅變動
1.0.0-beta.1       # 功能完整，還在測試
1.0.0-rc.1         # Release Candidate，準備正式發布
1.0.0              # 正式版
1.0.0+build.20260608  # 加上 build metadata（不影響版本比較）

1.2.0-SNAPSHOT

1.2.0

feature/xxx → develop → 1.2.0-SNAPSHOT（CI build）
develop → release/1.2.0 → 測試通過 → 移除 SNAPSHOT → 1.2.0（RELEASE tag）
release/1.2.0 → main → 部署 production

main          ──────●──────────────────────●──── (production)
                   ↑                       ↑
release/1.2.0  ────┤───fix───────────tag──┤
                   ↑
develop       ─────●──────●──────●──────────── (integration)
                   ↑      ↑      ↑
feature/A    ──────┘   feature/B feature/C

main      ──────●──────●──────●──── (隨時可部署)
                ↑      ↑      ↑
feature/A ──────┘  feature/B  feature/C

# 範例：GitHub Actions trigger 規則
on:
  push:
    branches:
      - develop          # 推送到 develop → 觸發 SNAPSHOT build + Dev 部署
      - 'release/**'     # 推送到 release/* → 觸發 RC build + Staging 部署
      - main             # 推送到 main → 觸發 Production 部署
  pull_request:
    branches:
      - develop
      - main             # PR 時跑完整測試但不部署
  workflow_dispatch:     # 手動觸發（緊急修補）

# 從最近的 tag 推導版本號
VERSION=$(git describe --tags --abbrev=0)
# 如果 HEAD 不在 tag 上，加上 commit hash
VERSION=$(git describe --tags)
# 輸出：1.2.0-3-g1a2b3c4（距離 tag 3 個 commit）

<!-- pom.xml -->
<version>1.2.0-SNAPSHOT</version>

<!-- 加入 plugin -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-release-plugin</artifactId>
</plugin>

# 執行 release（會自動改版本、tag、推進 SNAPSHOT）
mvn release:prepare release:perform

# 安裝 standard-version（Angular 專案常用）
npm install -D standard-version

# 根據 commit message 自動決定版本號升級幅度
npx standard-version
# 等效操作：
#   1. 更新 package.json 的 version
#   2. 更新 CHANGELOG.md
#   3. 打 Git tag

# semantic-release（更自動化，常用於 CI 環境）
npx semantic-release
# 從 commit message 判斷要 bump MAJOR / MINOR / PATCH
# feat: → MINOR bump（1.1.0 → 1.2.0）
# fix:  → PATCH bump（1.2.0 → 1.2.1）
# BREAKING CHANGE: → MAJOR bump（1.2.1 → 2.0.0）

【開發階段】
開發者 push feature/PROJ-123-xxx
  └─ PR → Code Review → Merge to develop
            ↓
  後端 CI（Spring Boot）：
    mvn test                      # Unit + Integration Test
    mvn package -DSNAPSHOT        # build: backend-1.2.0-SNAPSHOT.jar
    docker build → 推送 ECR/GHCR  # image tag: 1.2.0-SNAPSHOT
            ↓
  前端 CI（Angular）：
    npm test                      # Jest / Karma unit test
    npm run build -- --configuration=dev
    # 產出 dist/，artifact 版本：package.json 的 "1.2.0-dev"
            ↓
  Deploy to Dev Environment
    後端：deploy backend-1.2.0-SNAPSHOT
    前端：deploy Angular dist 1.2.0-dev

【Release 準備階段】（QA 通過 Dev，準備進 Staging）
  切出 release/1.2.0 分支：
    git checkout develop
    git checkout -b release/1.2.0
            ↓
  後端：移除 SNAPSHOT
    pom.xml: 1.2.0-SNAPSHOT → 1.2.0-RC.1
    或直接用 Maven Release Plugin: mvn release:prepare
            ↓
  前端：更新版本號
    package.json: "version": "1.2.0-rc.1"
    npx standard-version --prerelease rc
            ↓
  Build & Deploy to Staging:
    後端：backend-1.2.0-RC.1.jar → deploy to staging
    前端：npm run build -- --configuration=staging → deploy to staging

【UAT + 驗收階段】
  Staging 上跑 E2E 測試（Cypress / Playwright）
  PM / Client 做 UAT
  Performance Test（JMeter / k6）

【正式發布】（UAT 通過）
  後端：
    pom.xml: 1.2.0-RC.1 → 1.2.0（移除 RC）
    mvn release:perform（自動打 tag v1.2.0，版本推進 1.2.1-SNAPSHOT）
            ↓
  前端：
    package.json: "version": "1.2.0"
    npx standard-version（更新 CHANGELOG，打 tag v1.2.0）
            ↓
  merge release/1.2.0 → main
  merge release/1.2.0 → develop（帶回 release 期間的 bug fix）
            ↓
  Build RELEASE artifact:
    後端：backend-1.2.0.jar / docker image:1.2.0
    前端：npm run build -- --configuration=production
            ↓
  Deploy to Production（Blue/Green 或 Canary）
            ↓
  Smoke Test on Production
            ↓
  🎉 Release 1.2.0 complete

## Migration Guide: v1.x → v2.0

### Breaking Changes

#### 1. UserController API 路徑變更
- 舊：POST /api/user/create
- 新：POST /api/v2/users
- 說明：統一改為 RESTful 命名規範

#### 2. JWT Token 格式變更
- 舊：token payload 包含 userId（int）
- 新：token payload 包含 userId（UUID 字串）
- 影響：所有呼叫方需重新登入取得新 token

### Migration Steps
1. 執行資料庫腳本：`db/migrations/v2.0.0__user_id_to_uuid.sql`
2. 更新前端 API 呼叫路徑（見下方前端 Migration Guide）
3. 清除所有現有 session / token，要求使用者重新登入

## Migration Guide: v1.x → v2.0

### 1. UserService API 呼叫路徑更新
舊：
  this.userService.createUser(data)  // POST /api/user/create
新：
  this.userService.createUser(data)  // POST /api/v2/users（Service 內部已更新）

### 2. User Model 型別變更
舊：interface User { id: number }
新：interface User { id: string }  // UUID

需全域搜尋 userId 型別宣告並更新。

## 分支命名規則
- feature/[ticket-id]-short-description  （例：feature/PROJ-123-add-login）
- bugfix/[ticket-id]-short-description
- hotfix/x.y.z
- release/x.y.z

## 版本號規則
- develop 分支永遠是 x.y.z-SNAPSHOT
- release 分支完成後移除 SNAPSHOT
- 每次 MAJOR bump 要寫 Migration Guide
- Hotfix 只改 PATCH 號

## PR 規則
- 每個 PR 至少 1 個 reviewer approve
- 必須通過所有 CI check 才能 merge
- squash merge 到 develop；merge commit 到 main
  # squash merge：把整個 feature branch 的多個 commit 壓成一個 commit 再 merge
  # 好處：develop 的 git log 整潔，每個 feature 是一條記錄
  # merge commit：保留所有 commit 歷史，並加一個「Merge branch xxx」commit
  # main 用 merge commit 是為了保留完整的 release 歷史軌跡

## Commit Message 規範（Conventional Commits）
feat: 新功能
fix: Bug 修正
docs: 只改文件
chore: 建構流程、依賴更新
BREAKING CHANGE: footer 寫 breaking change 說明

## Release Checklist v{VERSION}

### 準備階段
- [ ] 從 develop 切出 release/{VERSION} 分支
- [ ] 更新 CHANGELOG.md
- [ ] 移除版本號中的 SNAPSHOT
- [ ] 確認所有 ticket 都已關閉或移至下一 sprint

### 測試階段
- [ ] CI 全部 green（Unit / Integration / E2E）
- [ ] Staging 部署完成
- [ ] UAT 簽核
- [ ] Performance Baseline 未退化

### 發布階段
- [ ] merge release/{VERSION} → main
- [ ] 打 tag v{VERSION}
- [ ] merge release/{VERSION} → develop（帶回 bug fix）
- [ ] 刪除 release branch

### 發布後
- [ ] Production Smoke Test
- [ ] 通知 Stakeholders
- [ ] 更新 develop 版本號至下一個 SNAPSHOT

# 1. 從 main 切出
git checkout main
git checkout -b hotfix/2.3.1

# 2. 修 bug，版本號從 2.3.0 → 2.3.1

# 3. 跑測試，CI green

# 4. merge 回 main 並 tag
git checkout main
git merge --no-ff hotfix/2.3.1
git tag -a v2.3.1 -m "Hotfix: fix critical payment bug"

# 5. 同步回 develop（確保 fix 不被下次 release 遺漏）
git checkout develop
git merge --no-ff hotfix/2.3.1

# 6. 刪分支
git branch -d hotfix/2.3.1

# 衝突情境（不好的做法）
feature/A：pom.xml version = 1.2.0-SNAPSHOT  ← 改過
feature/B：pom.xml version = 1.3.0-SNAPSHOT  ← 也改過
merge 時就衝突了

誰負責改版本號？

分支             誰改               改成什麼
feature/*       不改               （維持 develop 的版本）
develop         Team Lead 設定     x.y.z-SNAPSHOT
release/x.y.z   Release Manager    x.y.z-RC.n → x.y.z
main            自動（CI/CD）       打 tag x.y.z

┌─────────────────────────────────────────────────────────┐
│                    GitLab Group                         │
│                                                         │
│  platform/          feature-auth/     feature-payment/  │
│  ├─ backend/        ├─ backend/       ├─ backend/       │
│  │  pom.xml         │  pom.xml        │  pom.xml        │
│  └─ frontend/       └─ frontend/      └─ frontend/      │
│     package.json       package.json     package.json    │
└─────────────────────────────────────────────────────────┘
                              │
                              │ publish artifact
                              ▼
┌─────────────────────────────────────────────────────────┐
│                        Nexus                            │
│                                                         │
│  maven-snapshots/    maven-releases/                    │
│  ├─ feature-auth-1.2.0-SNAPSHOT.jar                     │
│  └─ ...              ├─ feature-auth-1.1.0.jar          │
│                      └─ feature-payment-2.0.0.jar       │
│                                                         │
│  npm-snapshots/      npm-releases/                      │
│  ├─ @feature/auth-1.2.0-snapshot.tgz                    │
│  └─ ...              └─ @feature/auth-1.1.0.tgz         │
└─────────────────────────────────────────────────────────┘
                              │
                              │ resolve dependency
                              ▼
┌─────────────────────────────────────────────────────────┐
│                     platform repo                       │
│  backend/pom.xml:                                       │
│    <dependency>                                         │
│      <artifactId>feature-auth</artifactId>              │
│      <version>1.2.0-SNAPSHOT</version>  ← dev 用 SNAPSHOT│
│    </dependency>                                        │
│                                                         │
│  frontend/package.json:                                 │
│    "@feature/auth": "1.2.0-snapshot"    ← dev 用 snapshot│
└─────────────────────────────────────────────────────────┘

feature/xxx → develop → release/1.2.0 → main

stages:
  - test
  - build
  - publish

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
  NEXUS_URL: "https://nexus.your-company.com"

# ─────────────────────────────────────
# 後端（Spring Boot）
# ─────────────────────────────────────
backend:test:
  stage: test
  script:
    - cd backend
    - mvn test
  only:
    - merge_requests
    - develop
    - /^release\/.*/

backend:publish-snapshot:
  stage: publish
  script:
    - cd backend
    - mvn deploy -DskipTests
      -DaltDeploymentRepository=snapshots::default::${NEXUS_URL}/repository/maven-snapshots/
  only:
    - develop   # develop push → 自動發布 SNAPSHOT 到 Nexus

backend:publish-release:
  stage: publish
  script:
    - cd backend
    # 移除 SNAPSHOT，打 tag，發布 RELEASE 到 Nexus
    - mvn release:prepare release:perform
      -DreleaseVersion=${RELEASE_VERSION}
      -DdevelopmentVersion=${NEXT_SNAPSHOT_VERSION}
      -DaltReleaseDeploymentRepository=releases::default::${NEXUS_URL}/repository/maven-releases/
  only:
    - /^release\/.*/   # release branch push → 手動或 trigger 發布 RELEASE
  when: manual         # 避免意外觸發，需手動確認

# ─────────────────────────────────────
# 前端（Angular）
# ─────────────────────────────────────
frontend:test:
  stage: test
  script:
    - cd frontend
    - npm ci
    - npm test -- --watch=false --browsers=ChromeHeadless
  only:
    - merge_requests
    - develop
    - /^release\/.*/

frontend:publish-snapshot:
  stage: publish
  script:
    - cd frontend
    - npm ci
    - npm run build -- --configuration=production
    # 設定 snapshot 版本號（從 package.json 取版本再加 -snapshot）
    - VERSION=$(node -p "require('./package.json').version")
    - npm version ${VERSION}-snapshot.$(date +%Y%m%d%H%M%S) --no-git-tag-version
    - npm publish --registry ${NEXUS_URL}/repository/npm-snapshots/
  only:
    - develop

frontend:publish-release:
  stage: publish
  script:
    - cd frontend
    - npm ci
    - npm run build -- --configuration=production
    - npm publish --registry ${NEXUS_URL}/repository/npm-releases/
  only:
    - /^release\/.*/
  when: manual

<project>
  <groupId>com.company</groupId>
  <artifactId>platform</artifactId>
  <version>3.0.0-SNAPSHOT</version>  <!-- platform 自己的版本 -->

  <properties>
    <!-- 在這裡統一管理各 feature 的版本號 -->
    <feature-auth.version>1.2.0-SNAPSHOT</feature-auth.version>
    <feature-payment.version>2.1.0-SNAPSHOT</feature-payment.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.company</groupId>
      <artifactId>feature-auth-backend</artifactId>
      <version>${feature-auth.version}</version>
    </dependency>
    <dependency>
      <groupId>com.company</groupId>
      <artifactId>feature-payment-backend</artifactId>
      <version>${feature-payment.version}</version>
    </dependency>
  </dependencies>

  <repositories>
    <!-- 從 Nexus group 取得依賴（含 SNAPSHOT + RELEASE + proxy） -->
    <repository>
      <id>nexus-group</id>
      <url>https://nexus.your-company.com/repository/maven-group/</url>
      <snapshots><enabled>true</enabled></snapshots>
      <releases><enabled>true</enabled></releases>
    </repository>
  </repositories>
</project>

{
  "name": "@company/platform-frontend",
  "version": "3.0.0-snapshot",
  "dependencies": {
    "@feature/auth-frontend": "1.2.0-snapshot.20260608120000",
    "@feature/payment-frontend": "2.1.0-snapshot.20260607090000"
  }
}

【Sprint 結束，準備 Release】

Step 1：各 Feature Repo 各自 release
  ┌──────────────────────────────────────────┐
  │ feature-auth: develop → release/1.2.0    │
  │   ├─ pom.xml: 1.2.0-SNAPSHOT → 1.2.0    │
  │   ├─ package.json: 1.2.0-snapshot → 1.2.0│
  │   ├─ CI 跑測試                           │
  │   ├─ 發布 1.2.0 到 Nexus maven-releases  │
  │   ├─ 發布 1.2.0 到 Nexus npm-releases    │
  │   └─ merge to main, tag v1.2.0           │
  │                                          │
  │ feature-payment: 同上流程 → v2.1.0       │
  └──────────────────────────────────────────┘
              ↓
Step 2：Platform Repo 更新依賴版本，進行 Release
  ┌──────────────────────────────────────────┐
  │ platform: develop → release/3.0.0        │
  │   ├─ pom.xml: feature-auth 改為 1.2.0    │
  │   │  （從 SNAPSHOT 改為 RELEASE）         │
  │   ├─ package.json: @feature/auth 改為 1.2.0│
  │   ├─ CI 重跑完整整合測試                  │
  │   ├─ Deploy to Staging                   │
  │   ├─ UAT 通過後，platform 版本改 3.0.0   │
  │   ├─ 發布 platform 3.0.0 artifacts       │
  │   └─ merge to main, tag v3.0.0           │
  └──────────────────────────────────────────┘
              ↓
Step 3：Deploy to Production
  platform 3.0.0 → Production

<!-- 在 CI pipeline 加一個驗證 job，發現 SNAPSHOT 依賴就 fail -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <executions>
    <execution>
      <id>no-snapshots-in-release</id>
      <goals><goal>enforce</goal></goals>
      <configuration>
        <rules>
          <requireReleaseDeps>
            <onlyWhenRelease>true</onlyWhenRelease>
            <message>Release build 不允許 SNAPSHOT 依賴！</message>
          </requireReleaseDeps>
        </rules>
      </configuration>
    </execution>
  </executions>
</plugin>

feature-auth repo
  develop push
    → CI: test + build
    → publish feature-auth-1.2.0-SNAPSHOT.jar to Nexus
    → trigger platform repo pipeline（可選）

feature-auth repo
  release/1.2.0 merge to main
    → CI: test + build
    → publish feature-auth-1.2.0.jar to Nexus
    → 自動開 GitLab Issue / 通知 platform team：「auth 1.2.0 已 release，請更新依賴」

platform repo
  develop push（開發者手動更新依賴版本後）
    → CI: mvn dependency:resolve（確認 Nexus 上的依賴存在）
    → 整合測試
    → Deploy to Dev

platform repo
  release/3.0.0（所有 feature 都 release 後）
    → 驗證無 SNAPSHOT 依賴（enforcer plugin）
    → CI: 完整測試
    → Deploy to Staging → UAT → Deploy to Production

# feature-auth/.gitlab-ci.yml
notify-platform:
  stage: notify
  trigger:
    project: company/platform
    branch: develop
    strategy: depend   # 等待 downstream pipeline 完成
  only:
    - develop