# Momentry Core 版本紀錄

## 版本命名規則

### Main Version (主版本)
```
v{major}.{minor}
例: v0.1, v0.2, v1.0
```

### Build Version (建置版本)
```
v{major}.{minor}.{YYYYMMDD_HHMMSS}
例: v0.1.20260325_143000
```

---

## 版本紀錄存放位置

```
/Users/accusys/momentry/versions/
├── current/                    # 目前使用版本
│   ├── binary                 # 當前 binary
│   └── version.json           # 版本資訊
│
├── releases/                  # Release 版本存放
│   ├── v0.1/
│   │   ├── v0.1.20260325_143000/
│   │   │   ├── binary
│   │   │   └── version.json
│   │   ├── v0.1.20260324_100000/
│   │   │   └── ...
│   │   └── release.json      # v0.1 版本總覽
│   │
│   └── v0.2/
│       └── ...
│
└── changelog.json             # 全域版本變更記錄
```

---

## version.json 格式

```json
{
  "version": "v0.1.20260325_143000",
  "main_version": "v0.1",
  "build_timestamp": "2026-03-25T14:30:00+08:00",
  "git_commit": "83ae050",
  "git_branch": "main",
  "git_message": "fix: save probe.json to OUTPUT_DIR instead of current directory",
  "features": [
    "API Key Authentication",
    "Job Worker System"
  ],
  "fixes": [
    "get_processor_results_by_job column mapping"
  ],
  "deployed_at": "2026-03-25T15:00:00+08:00",
  "deployed_by": "opencode",
  "status": "production"
}
```

---

## release.json 格式 (主版本總覽)

```json
{
  "version": "v0.1",
  "status": "production",
  "created_at": "2026-03-14T10:00:00+08:00",
  "current_build": "v0.1.20260325_143000",
  "builds": [
    {
      "build": "v0.1.20260325_143000",
      "date": "2026-03-25",
      "commits": ["83ae050", "171c36a"],
      "summary": "fix: save probe.json, add v2 backup versioning"
    },
    {
      "build": "v0.1.20260324_100000",
      "date": "2026-03-24",
      "commits": ["89fbfd6", "3edaf01"],
      "summary": "feat: add POST /api/v1/probe endpoint"
    }
  ],
  "changelog": [
    "## v0.1.20260325_143000",
    "- 修復 processor_results 欄位映射錯誤",
    "- 添加 API Key 認證",
    "",
    "## v0.1.20260324_100000",
    "- 新增 Probe API"
  ]
}
```

---

## changelog.json 格式 (全域變更記錄)

```json
{
  "updated_at": "2026-03-25T14:30:00+08:00",
  "versions": {
    "v0.1": {
      "status": "production",
      "current_build": "v0.1.20260325_143000",
      "build_count": 12
    },
    "v0.0": {
      "status": "deprecated",
      "final_build": "v0.0.20260310_090000"
    }
  },
  "recent_changes": [
    {
      "version": "v0.1.20260325_143000",
      "date": "2026-03-25",
      "changes": [
        {"type": "fix", "description": "get_processor_results_by_job column mapping"},
        {"type": "feat", "description": "API Key Authentication"}
      ]
    }
  ]
}
```

---

## Release Script

### /Users/accusys/momentry/scripts/release.sh

```bash
#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="/Users/accusys/momentry_core_0.1"
VERSIONS_DIR="/Users/accusys/momentry/versions"
BACKUP_DIR="/Users/accusys/momentry/backup/bin"
CURRENT_BIN="/Users/accusys/momentry/bin/momentry"

# 顏色輸出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# 解析命令列參數
MAIN_VERSION=""
while [[ $# -gt 0 ]]; do
  case $1 in
    -v|--version)
      MAIN_VERSION="$2"
      shift 2
      ;;
    *)
      log_error "Unknown option: $1"
      exit 1
      ;;
  esac
done

if [ -z "$MAIN_VERSION" ]; then
  log_error "請指定主版本: ./release.sh -v v0.1"
  exit 1
fi

log_info "開始 Release ${MAIN_VERSION}..."

# 1. 取得 Git 資訊
GIT_COMMIT=$(git -C "$PROJECT_DIR" rev-parse --short HEAD)
GIT_BRANCH=$(git -C "$PROJECT_DIR" rev-parse --abbrev-ref HEAD)
GIT_MESSAGE=$(git -C "$PROJECT_DIR" log -1 --pretty=%s)
BUILD_TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BUILD_VERSION="${MAIN_VERSION}.${BUILD_TIMESTAMP}"

log_info "Build Version: ${BUILD_VERSION}"
log_info "Git Commit: ${GIT_COMMIT}"

# 2. 創建版本目錄
BUILD_DIR="${VERSIONS_DIR}/releases/${MAIN_VERSION}/${BUILD_VERSION}"
mkdir -p "$BUILD_DIR"
mkdir -p "${VERSIONS_DIR}/current"
mkdir -p "$BACKUP_DIR"

# 3. 停止 Production Service
log_info "停止 Production Service..."
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist 2>/dev/null || true

# 4. 備份當前 Binary
if [ -f "$CURRENT_BIN" ]; then
  OLD_VERSION=$(cat "${VERSIONS_DIR}/current/version.json" 2>/dev/null | jq -r '.version // "unknown"')
  log_info "備份當前版本: $OLD_VERSION"
  cp "$CURRENT_BIN" "${BACKUP_DIR}/momentry_${OLD_VERSION}_$(date +%Y%m%d_%H%M%S)"
fi

# 5. 編譯 Release 版本
log_info "編譯 Release 版本..."
cd "$PROJECT_DIR"
cargo build --release --bin momentry

# 6. 複製到版本目錄
log_info "複製到版本目錄..."
cp target/release/momentry "${BUILD_DIR}/binary"
cp target/release/momentry "$CURRENT_BIN"

# 7. 生成 version.json
cat > "${BUILD_DIR}/version.json" << EOF
{
  "version": "${BUILD_VERSION}",
  "main_version": "${MAIN_VERSION}",
  "build_timestamp": "$(date -Iseconds)",
  "git_commit": "${GIT_COMMIT}",
  "git_branch": "${GIT_BRANCH}",
  "git_message": "${GIT_MESSAGE}",
  "features": [],
  "fixes": [],
  "deployed_at": null,
  "deployed_by": null,
  "status": "built"
}
EOF

# 8. 更新 current
cp "${BUILD_DIR}/version.json" "${VERSIONS_DIR}/current/version.json"

# 9. 更新 changelog.json
UPDATE_CHANGELOG="
import json
from datetime import datetime

changelog_path = '${VERSIONS_DIR}/changelog.json'
build_info = {
    'version': '${BUILD_VERSION}',
    'date': datetime.now().strftime('%Y-%m-%d'),
    'commit': '${GIT_COMMIT}',
    'message': '${GIT_MESSAGE}'
}

try:
    with open(changelog_path, 'r') as f:
        changelog = json.load(f)
except FileNotFoundError:
    changelog = {'updated_at': '', 'versions': {}, 'recent_changes': []}

changelog['updated_at'] = datetime.now().isoformat()
if '${MAIN_VERSION}' not in changelog['versions']:
    changelog['versions']['${MAIN_VERSION}'] = {'status': 'building', 'build_count': 0}

changelog['versions']['${MAIN_VERSION}']['build_count'] += 1
changelog['versions']['${MAIN_VERSION}']['current_build'] = '${BUILD_VERSION}'
changelog['recent_changes'].insert(0, build_info)

with open(changelog_path, 'w') as f:
    json.dump(changelog, f, indent=2, ensure_ascii=False)
"
python3 -c "$UPDATE_CHANGELOG"

# 10. 啟動 Production Service
log_info "啟動 Production Service..."
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 11. 驗證
sleep 3
if curl -s http://localhost:3002/health > /dev/null; then
  log_info "✓ Release 成功！"
  log_info "版本: ${BUILD_VERSION}"
  log_info "目錄: ${BUILD_DIR}"
else
  log_error "✗ Release 失敗！請檢查服務狀態。"
  exit 1
fi
```

---

## 查詢版本指令

### 查詢目前版本
```bash
cat /Users/accusys/momentry/versions/current/version.json
```

### 查詢所有 Release
```bash
ls -la /Users/accusys/momentry/versions/releases/
```

### 查詢版本歷史
```bash
cat /Users/accusys/momentry/versions/changelog.json | python3 -m json.tool
```

### 查詢特定主版本
```bash
ls /Users/accusys/momentry/versions/releases/v0.1/
```

---

## 版本狀態

| 狀態 | 說明 |
|------|------|
| `building` | 建置中 |
| `built` | 已建置，未部署 |
| `testing` | 測試中 |
| `production` | 正式環境使用中 |
| `deprecated` | 已棄用 |
| `archived` | 已封存 |

---

## 版本流程圖

```
develop (git branch)
    │
    ▼
feature/bugfix commit
    │
    ▼
develop ──────────────────┐
    │                    │
    │ (merge to main)   │
    ▼                    │
main (git)               │
    │                    │
    ▼                    │
Build v0.1.20260325_143000
    │                    │
    ├──► testing (3003) │
    │                    │
    │ (approve)          │
    ▼                    ▼
v0.1 ───────────────────┘
    │
    ├──► releases/v0.1/v0.1.20260325_143000/
    │
    ├──► current/ (production)
    │
    ▼
changelog.json (update)
```

---

## Release Note (版本發布說明)

### Release Note 存放位置

```
/Users/accusys/momentry/versions/releases/{主版本}/{建置版本}/
├── binary
├── version.json
└── RELEASE_NOTE.md    # 發布說明 (Markdown)
```

### Release Note 範本

```markdown
# Momentry Core v0.1.20260325_143000 Release Note

## 版本資訊
- **Build Version**: v0.1.20260325_143000
- **Main Version**: v0.1
- **Build Date**: 2026-03-25 14:30:00
- **Git Commit**: 83ae050

## 新功能 (Features)

### API Key 認證系統
- 添加 API Key 認證中介層
- 所有 `/api/v1/*` 端點需要 `X-API-Key` header
- 支援 API Key 使用追蹤和審計日誌

### Job Worker 系統
- 新增 Job Worker 二進位檔
- 支援最多 2 個並發處理器
- 新增 `/api/v1/jobs/:uuid` 端點查詢任務詳情

## 錯誤修復 (Bug Fixes)

| Issue | 描述 |
|-------|------|
| #001 | 修復 `get_processor_results_by_job` 欄位映射錯誤 |
| #002 | 修復 API Key 驗證時區處理問題 |

## API 變更 (API Changes)

### 新增端點
| Method | Endpoint | 說明 |
|--------|----------|------|
| GET | `/api/v1/jobs` | 取得所有任務列表 |
| GET | `/api/v1/jobs/:uuid` | 取得特定任務詳情 |

### 認證變更
| 端點 | 舊版 | 新版 |
|------|------|------|
| `/api/v1/*` | 公開 | 需要 API Key |

## 升級指南

### 從舊版升級
1. 備份當前版本
2. 停止服務
3. 替換 binary
4. 重啟服務
5. 更新 API Key 配置

### API Key 配置
```bash
# 請求範例
curl -H "X-API-Key: your_api_key" \
  "http://localhost:3002/api/v1/videos"
```

## 已知問題 (Known Issues)

- 暫無

## 相關文檔

- [API 文檔](../docs/API_INDEX.md)
- [版本管理規範](../docs/VERSION_MANAGEMENT.md)

---

## Release Note 自動生成 Script

### /Users/accusys/momentry/scripts/generate_release_note.sh

```bash
#!/bin/bash
set -e

BUILD_VERSION=$1
MAIN_VERSION=$2
BUILD_DIR="/Users/accusys/momentry/versions/releases/${MAIN_VERSION}/${BUILD_VERSION}"

# 取得 Git 資訊
GIT_COMMITS=$(git log --oneline -10)
GIT_CHANGES=$(git diff --stat HEAD~5..HEAD)

cat > "${BUILD_DIR}/RELEASE_NOTE.md" << EOF
# Momentry Core ${BUILD_VERSION} Release Note

## 版本資訊
- **Build Version**: ${BUILD_VERSION}
- **Main Version**: ${MAIN_VERSION}
- **Build Date**: $(date '+%Y-%m-%d %H:%M:%S')
- **Git Commit**: $(git rev-parse --short HEAD)

## 變更內容

### Commit 記錄
\`\`\`
${GIT_COMMITS}
\`\`\`

### 變更統計
\`\`\`
${GIT_CHANGES}
\`\`\`

## 新功能

## 錯誤修復

## API 變更

## 升級指南

## 已知問題

EOF

echo "Release Note 生成完成: ${BUILD_DIR}/RELEASE_NOTE.md"
```

---

## Release Note 查詢

### 查詢所有 Release Note
```bash
find /Users/accusys/momentry/versions/releases -name "RELEASE_NOTE.md"
```

### 查看特定版本 Release Note
```bash
cat /Users/accusys/momentry/versions/releases/v0.1/v0.1.20260325_143000/RELEASE_NOTE.md
```

### 查詢最新版本 Release Note
```bash
cat /Users/accusys/momentry/versions/current/RELEASE_NOTE.md
```

---

## Release Note 範例

### 完整 Release Note 範例

\`\`\`markdown
# Momentry Core v0.1.20260325_143000 Release Note

## 版本資訊
| 項目 | 內容 |
|------|------|
| Build Version | v0.1.20260325_143000 |
| Main Version | v0.1 |
| Build Date | 2026-03-25 14:30:00 |
| Git Commit | 83ae050 |
| Status | ✅ Production |

## 新功能 (Features)

### 1. API Key 認證系統
添加完整的 API Key 認證系統，保護所有 API 端點。

**功能:**
- SHA256 key hash 驗證
- 使用統計追蹤
- 審計日誌記錄
- 異常檢測

**API 使用方式:**
\`\`\`bash
curl -H "X-API-Key: your_key" \\
  "http://localhost:3002/api/v1/videos"
\`\`\`

### 2. Job Worker 系統
新增獨立的 Job Worker 處理影片處理任務。

**特性:**
- 最多 2 個並發處理器
- Polling-based 任務獲取
- 自動進度追蹤

## 錯誤修復 (Bug Fixes)

| Issue | 描述 | 嚴重性 |
|-------|------|--------|
| #001 | 修復 `get_processor_results_by_job` TIMESTAMP 欄位映射 | 🔴 高 |
| #002 | 修復 3002 port 衝突問題 | 🟡 中 |

## API 變更

### 新增端點
| Method | Endpoint | 說明 |
|--------|----------|------|
| GET | `/api/v1/jobs` | 取得任務列表 |
| GET | `/api/v1/jobs/:uuid` | 取得任務詳情 |

### 端點認證狀態
| 端點 | 認證需求 |
|------|----------|
| `/health` | ❌ 不需要 |
| `/api/v1/*` | ✅ 需要 `X-API-Key` |

## 升級指南

### 前置需求
- PostgreSQL 資料庫
- Redis 伺服器
- MongoDB 快取

### 升級步驟
1. **備份當前版本**
   \`\`\`bash
   cp /Users/accusys/momentry/bin/momentry \\
     /Users/accusys/momentry/backup/bin/momentry_$(date +%Y%m%d)
   \`\`\`

2. **停止服務**
   \`\`\`bash
   sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
   \`\`\`

3. **替換 Binary**
   \`\`\`bash
   cp v0.1.20260325_143000/binary /Users/accusys/momentry/bin/momentry
   \`\`\`

4. **重啟服務**
   \`\`\`bash
   sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
   \`\`\`

5. **驗證**
   \`\`\`bash
   curl http://localhost:3002/health
   \`\`\`

## 已知問題 (Known Issues)

- 暫無

## 技術細節

### 認證流程
\`\`\`
Client Request
     │
     ▼
[X-API-Key Header] ──► Middleware
     │                        │
     │                        ▼
     │                   Hash Key (SHA256)
     │                        │
     │                        ▼
     │                   DB Lookup
     │                        │
     │                        ▼
     │                   Validate Status
     │                        │
     ▼                        ▼
Handler ◄────────────────────┘
\`\`\`

### 資料庫變更
\`\`\`sql
-- 新增 duration_secs 欄位
ALTER TABLE processor_results 
ADD COLUMN IF NOT EXISTS duration_secs DOUBLE PRECISION;
\`\`\`

## 回滾指南

如需回滾到上一版本：
\`\`\`bash
# 1. 停止服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist

# 2. 恢復舊版
cp /Users/accusys/momentry/backup/bin/momentry_v0.1.20260324_100000 \\
   /Users/accusys/momentry/bin/momentry

# 3. 重啟服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
\`\`\`

## 聯繫與支援

- **Issue Tracker**: https://gitea.momentry.ddns.net/momentry/momentry_core/issues
- **文檔**: https://docs.momentry.ddns.net

---

*Generated: $(date '+%Y-%m-%d %H:%M:%S')*
\`\`\`

```