feat: Initial v0.9 release with API Key authentication

## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
2026-03-25 14:52:51 +08:00
parent 47e86b696f
commit 383201cacd
193 changed files with 40268 additions and 422 deletions
--- a/docs/BUILD_VERSION_RECORD.md
+++ b/docs/BUILD_VERSION_RECORD.md
@@ -0,0 +1,667 @@
+# 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')*
+\`\`\`
+
+```