# Momentry Core 版本管理規範

## 1. 版本與通訊埠對照表

| 版本 | Binary | Port | Redis Prefix | 用途 |
|------|--------|------|--------------|------|
| **Production** | `momentry` | **3002** | `momentry:` | 正式環境 |
| **Development** | `momentry_playground` | **3003** | `momentry_dev:` | 開發測試 |

### 通訊埠嚴禁事項
- ❌ 開發版嚴禁使用 3002
- ❌ 任何 `cargo run` 直接啟動的 server 嚴禁綁定 3002
- ❌ Debug build 嚴禁部署到 3002

---

## 2. 開發環境隔離原則

### 2.1 開發流程
```bash
# 永遠在 3003 開發測試
cd /Users/accusys/momentry_core_0.1

# 開發版啟動 (3003)
cargo run --bin momentry_playground -- server
# 或
cargo run --bin momentry -- server --port 3003
```

### 2.2 測試完成後
1. 確認所有功能在 3003 正常運作
2. 進行 `cargo clippy --lib` 檢查
3. 進行 `cargo test --lib` 測試
4. 確認後才能進行 release

### 2.3 環境變數隔離
```bash
# Development
export MOMENTRY_SERVER_PORT=3003
export MOMENTRY_REDIS_PREFIX=momentry_dev:

# Production (launchd 管理，勿手動設定)
# MOMENTRY_SERVER_PORT=3002
# MOMENTRY_REDIS_PREFIX=momentry:
```

---

## 3. Release 版本管理

### 3.1 Release 前檢查清單

```
□ 開發版 (3003) 功能測試完成
□ cargo clippy --lib 通過
□ cargo test --lib 通過
□ cargo fmt -- --check 通過
□ 所有修改已 commit 到 Gitea
```

### 3.2 Release 流程

```bash
# 1. 確保目前是乾淨的工作目錄
git status

# 2. 備份當前 production binary
BACKUP_DIR="/Users/accusys/momentry/backup/bin"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp /Users/accusys/momentry/bin/momentry "${BACKUP_DIR}/momentry_${TIMESTAMP}"

# 3. 停止 production server
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
# 或
pkill -f "target/release/momentry server"

# 4. 編譯 release 版本
cargo build --release --bin momentry

# 5. 部署到正式位置
cp target/release/momentry /Users/accusys/momentry/bin/momentry

# 6. 啟動 production server
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 7. 驗證
curl http://localhost:3002/health
```

### 3.3 Backup 存放位置
```
/Users/accusys/momentry/backup/bin/
├── momentry_20260325_143000  (backup)
├── momentry_20260324_100000
├── momentry_20260323_090000
└── ...
```

---

## 4. Gitea 版本控制

### 4.1 Commit 規範
```
feat:     新功能
fix:      錯誤修復
refactor: 重構
docs:     文件更新
chore:    杂项
test:     测试
```

### 4.2 Release Tag 規範
```bash
# 建立 release tag
git tag -a v0.1.1 -m "Release v0.1.1 - API Key Authentication"
git push origin v0.1.1
```

### 4.3 版本號命名
```
v{major}.{minor}.{patch}
  │      │      └── Patch version (bug fix)
  │      └───────── Minor version (新功能)
  └──────────────── Major version (破壞性變更)
```

### 4.4 Gitea Release 建立
1. 在 Gitea Repo > Releases > New Release
2. 選擇對應的 Tag
3. 填寫 Release Notes
4. 上傳 compiled binary（如需要）

---

## 5. 服務管理

### 5.1 Production Service (launchd)
```bash
# Plist 位置
/Library/LaunchDaemons/com.momentry.api.plist

# 管理指令
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist   # 啟動
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist # 停止
sudo launchctl list | grep momentry                                 # 狀態
```

### 5.2 緊急回滾
```bash
# 1. 停止當前服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist

# 2. 恢復上一個 backup
BACKUP_FILE=$(ls -t /Users/accusys/momentry/backup/bin/ | head -1)
cp "/Users/accusys/momentry/backup/bin/${BACKUP_FILE}" /Users/accusys/momentry/bin/momentry

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

# 4. 驗證
curl http://localhost:3002/health
```

---

## 6. 快速參考卡片

### Development
```bash
# 啟動開發版
cd /Users/accusys/momentry_core_0.1
cargo run --bin momentry_playground -- server

# 或手動指定 port
cargo run --bin momentry -- server --port 3003

# 測試端點
curl -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  http://localhost:3003/api/v1/jobs
```

### Production
```bash
# 查看狀態
sudo launchctl list | grep momentry

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

# 查看日誌
tail -f /Users/accusys/momentry/log/momentry_release.log
```

### 常用指令
```bash
# 檢查 port 使用
lsof -i :3002  # Production
lsof -i :3003  # Development

# 檢查 process
ps aux | grep momentry | grep server

# 停止所有 momentry server
pkill -9 -f "momentry.*server"
```

---

## 7. 禁止事項

| 項目 | 說明 |
|------|------|
| ❌ 禁止在 3002 測試 | 3002 是 Production，嚴禁用於測試 |
| ❌ 禁止覆蓋 production binary | 使用 backup + deploy 流程 |
| ❌ 禁止跳過測試直接 release | 必須完成檢查清單 |
| ❌ 禁止在未備份的情況下部署 | 每次部署前必須備份 |

---

## 8. 疑難排解

### Q: 3002 無法綁定怎麼辦？
```bash
# 檢查誰在使用
lsof -i :3002

# 停止舊的 server
pkill -9 -f "momentry.*server"
```

### Q: 如何確認使用的是哪個版本？
```bash
# 檢查 binary 位置和版本
file $(which momentry)
./target/release/momentry --version 2>/dev/null || echo "No version flag"
```

### Q: 如何確認有沒有 API Key 驗證？
```bash
# 沒有 API Key 應該返回 401
curl -s http://localhost:3002/api/v1/jobs
# HTTP/1.1 401 Unauthorized
```