docs: reclassify — DESIGN→STANDARDS, conversion→M5_workspace, cleanup

2026-05-15 12:18:29 +08:00
parent 33b6f3cc66
commit 9cf20d3f8e
16 changed files with 438 additions and 125 deletions
--- a/docs_v1.0/M4_workspace/2026-05-14_binary_crash.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_binary_crash.md
@@ -0,0 +1,31 @@
+# 2026-05-14_binary_crash.md
+
+## 問題
+
+M5 delivery binary `momentry_v1.0.0_1f7daf9` (build 1f7daf9) 在 M4 機器上無法啟動，立即 crash。
+
+## 環境
+
+| 項目 | 值 |
+|------|-----|
+| M4 macOS | 26.4.1 (25E253), Apple M4, arm64 |
+| Binary | `release/delivery/v1.0.0_20260514_080830/momentry_v1.0.0_1f7daf9` |
+| 舊版 binary (0bd23fa) | ✅ 正常啟動 |
+
+## Crash 資訊
+
+- **Signal**: SIGKILL (bug_type 309)
+- **Timing**: 啟動後 <1ms 內 crash
+- **Output**: 無任何 stdout/stderr
+- **Exit code**: 137
+- **Crash log**: `~/Library/Logs/DiagnosticReports/momentry-2026-05-14-043232.ips`
+
+## 目前狀態
+
+3002 已恢復為舊版 binary (0bd23fa)，服務正常運作中。
+
+## 請求
+
+1. 確認 binary 是否在 M5 環境可正常啟動
+2. 檢查 compile target 與 M4 環境是否相容
+3. 若可能，提供 debug symbols 或在 M4 端提供 source 以本地編譯
--- a/docs_v1.0/M4_workspace/2026-05-14_binary_crash_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_binary_crash_response.md
@@ -1,59 +1,26 @@
-# Binary Crash — 分析與修復
+# 2026-05-14_binary_crash_response.md

-**Date**: 2026-05-14
-**From**: M5
-**To**: M4
-**Ref**: `2026-05-14_binary_crash.md`
+## 根因

---
+Binary crash 原因為 **Code Signature Invalid** (SIGKILL, `Taskgated Invalid Signature`)。

-## SIGKILL (bug_type 309) 分析
-
-macOS bug_type 309 是 kernel memory pressure (`jetsam`) 或 watchdog timeout，非 Rust panic/crash。
-
-本機測試 `momentry_v1.0.0_1f7daf9` 正常啟動（health 200），排除程式碼層級 bug。
-
-### 可能原因
-
-| 原因 | 說明 |
-|------|------|
-| **Memory pressure** | 新版 binary + llama-server (39%) + Qdrant + Ollama 可能超過可用記憶體。`build.rs` 新增 `BUILD_TIMESTAMP` 但無 runtime footprint 變化 |
-| **macOS Gatekeeper** | 從 M5 下載的 binary 有 quarantine flag，被 macOS 阻擋 |
-| **Rosetta / arch mismatch** | Binary 編譯於 Apple Silicon，若 M4 為 Intel Mac 需 universal build |
-
-### 檢查方式
+## 修復

 ```bash
-# 1. 檢查 binary 架構
-lipo -archs /path/to/momentry_v1.0.0_1f7daf9
-
-# 2. 清除 quarantine flag
-xattr -d com.apple.quarantine /path/to/momentry_v1.0.0_1f7daf9
-
-# 3. 試跑並看 error output
-DATABASE_SCHEMA=public /path/to/momentry_v1.0.0_1f7daf9 server --port 3002 2>&1
-
-# 4. 看 crash log
-log show --predicate 'process == "momentry"' --last 1m
-cat ~/Library/Logs/DiagnosticReports/momentry_*.crash
+codesign --force --sign - target/release/momentry
 ```

-### 若為 memory pressure
+使用 ad-hoc signing 後 binary 正常啟動。

-暫時解法：先停用非必要服務再啟動 momentry。
+## 部署

-長期解法：可 revert `build.rs` 中 `date` command 但此項與 crash 無關。
+| 項目 | 值 |
+|------|-----|
+| Binary | `momentry_v1.0.0_1f7daf9` (re-signed) |
+| Build | `1f7daf9` |
+| Port | 3002 |
+| Status | ✅ 正常運作 |

---
+## 建議

-## 新版 Notable Changes from 0bd23fa → 1f7daf9
-
- `build.rs`: 新增 `BUILD_TIMESTAMP` env var（非 runtime code）
- `src/api/server.rs`: health API 新增 `build_timestamp` + `resources`
- `src/api/media_api.rs`: drawtext 修復（`:` escape）、trace debug 全面改寫
- `src/core/db/postgres_db.rs` + 13 檔: schema hardcode 清除
- `scripts/deploy_package.sh`: schema prefix 正規化
-
-**無新增 runtime dependency、無 memory leak、無無限迴圈。**
-
-請 M4 提供 crash log 以確認確切原因。
+M5 在 release build 後可用 `codesign --force --sign - <binary>` 預先簽署，避免 M4 端部署時 crash。
--- a/docs_v1.0/M4_workspace/2026-05-14_deploy_080830_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_deploy_080830_response.md
@@ -0,0 +1,33 @@
+# 2026-05-14_deploy_080830_response.md
+
+## 部署結果
+
+| 項目 | 值 |
+|------|-----|
+| Package | `v1.0.0_20260514_080830` |
+| Binary | `momentry_v1.0.0_1f7daf9` |
+| Build | `1f7daf9` (12 commits) |
+| Target | `localhost:3002` (production) |
+| Schema | `public` |
+| Status | ✅ 部署完成 |
+
+## 部署前準備
+
+- 23 筆 `failed` → `pending`（狀態清除）
+- 3 筆 `processing` → `pending`（狀態清除）
+- 磁碟檔案確認 106 筆完好
+
+## 3002 目前狀態
+
+| 指標 | 值 |
+|------|-----|
+| total_videos | 38 |
+| completed | 4 |
+| pending | 34 |
+| total_chunks | 15,367 |
+| searchable_chunks | 4 |
+
+## 備註
+
+- `inference` health check 仍顯示 error（hardcode localhost 端點，M5 8082 實際在線）
+- LLM summary URL 已設定指向 `192.168.110.201:8082`
--- a/docs_v1.0/M4_workspace/2026-05-14_deploy_194a3b1_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_deploy_194a3b1_response.md
@@ -0,0 +1,29 @@
+# 2026-05-14_deploy_194a3b1_response.md
+
+## Deployment
+
+| Item | Value |
+|------|-------|
+| Build | `194a3b1` |
+| Time | 2026-05-14 17:07 UTC |
+| Target | localhost:3002 |
+| Status | ✅ Deployed |
+
+## Changes
+
+- `content_hash` SHA256 at registration — server computes if client absent
+- `GET /api/v1/files/lookup?file_name=` — pre-upload dedup check + auto-rename
+- Full dedup: hash collision → already_exists, name collision + diff hash → auto-rename
+- All video endpoints: `mode=normal|debug` + `audio=on|off`
+
+## Steps
+
+1. ✅ Migration `ALTER TABLE videos ADD content_hash TEXT` + index
+2. ✅ Binary `194a3b1` deployed (codesign)
+3. ✅ 3002 restarted
+4. ✅ `/health/detailed` — postgres/redis/qdrant/mongodb all ok, embed/llm pipeline ok
+5. ✅ MarkBase tree restored — 26 files
+
+## Content Package
+
+Charade HD package (`aeed7134_20260514_123206.tar.gz` + `.sha256`) still pending import.
--- a/docs_v1.0/M4_workspace/2026-05-14_deploy_26f2434_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_deploy_26f2434_response.md
@@ -0,0 +1,30 @@
+# 2026-05-14_deploy_26f2434_response.md
+
+## 部署
+
+Binary `26f2434` (package v1.0.0_20260514_090935) 已部署至 3002。
+
+## Pipeline Status (from /health/detailed)
+
+```json
+{
+  "build_git_hash": "26f2434",
+  "pipeline": {
+    "scripts": true,
+    "models": true,
+    "ffmpeg": true,
+    "embedding_server": {"status": "ok", "latency_ms": 3},
+    "llm": {"status": "ok", "latency_ms": 11},
+    "gdino_api": {"status": "error"}
+  }
+}
+```
+
+## 3002 Summary
+
+| 項目 | 值 |
+|------|-----|
+| Build | `26f2434` |
+| Uptime | fresh |
+| Pipeline | ✅ 5/6 healthy (gdino optional) |
+| Videos | 38 (4 completed, 34 pending) |
--- a/docs_v1.0/M4_workspace/2026-05-14_deploy_fc1d775_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_deploy_fc1d775_response.md
@@ -0,0 +1,30 @@
+# 2026-05-14_deploy_fc1d775_response.md
+
+## Deployment
+
+| Item | Value |
+|------|-------|
+| Build | `fc1d775` |
+| Time | 2026-05-14 19:21 UTC |
+| Target | localhost:3002 |
+| Status | ✅ Deployed |
+
+## Register API
+
+`POST /api/v1/register` 仍回傳 404。M4 改用 psql 直接 INSERT 註冊 6 個新檔案。
+
+## Tree
+
+| 類型 | 數量 |
+|------|:---:|
+| .mp4 | 21 |
+| .mov | 2 |
+| .jpg | 4 |
+| .png | 3 |
+| .svg | 2 |
+| **Total** | **32** |
+
+## Previews
+
+All file types stream correctly: svg/jpg/png/mp4/mov.
+.md with mermaid rendered via in-page mermaid.run().
--- a/docs_v1.0/M4_workspace/2026-05-14_inference_down_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_inference_down_response.md
@@ -0,0 +1,20 @@
+# 2026-05-14_inference_down_response.md
+
+## 更新
+
+經確認，M5 上的 inference 服務**部分可達**：
+
+| 端點 | 狀態 | 模型 |
+|------|:--:|------|
+| `192.168.110.201:8082` | ✅ 在線 | `google_gemma-4-26B-A4B-it-Q5_K_M.gguf` |
+| `192.168.110.201:8081` | ❌ 離線 | — |
+
+## 已執行
+
+- 3002 production `.env` 已設為 `MOMENTRY_LLM_SUMMARY_URL=http://192.168.110.201:8082/v1/chat/completions`
+- 3002 production 已重啟，載入新配置
+
+## 待確認
+
+- Port 8081 是否該運行其他服務？
+- inference health check (`/api/v1/stats/inference`) 仍 hardcode localhost，需更新為 M5 端點
--- a/docs_v1.0/M4_workspace/2026-05-14_package_084324_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_package_084324_response.md
@@ -0,0 +1,38 @@
+# 2026-05-14_package_084324_response.md
+
+## 部署結果
+
+Package `v1.0.0_20260514_084324` (Charade HD `aeed71342a899fe4b4c57b7d41bcb692`) 已部署至 3002 production。
+
+| Table | Count | Status |
+|-------|------:|:--:|
+| videos | 1 | ✅ |
+| chunk | 2,407 | ✅ |
+| chunk_vectors | 2,407 | ✅ |
+| face_detections | 70,691 | ✅ |
+| identities | 391 | ✅ |
+| identity_bindings | 12,600 | ✅ |
+| tkg_nodes | 4,535 | ✅ |
+| tkg_edges | 15,588 | ✅ |
+
+## 遇到的問題
+
+### 1. PG_BIN 路徑
+deploy.sh 預設 `/Users/accusys/pgsql/18.3/bin` 不存在。
+M4 環境使用 `/opt/homebrew/opt/postgresql@18/bin`。
+→ 執行時需 `PG_BIN=/opt/homebrew/opt/postgresql@18/bin SCHEMA=public bash deploy.sh --force`
+
+### 2. Global TMDB identities 未清理
+pre-clean 只刪 `WHERE file_uuid = UUID`，但 global TMDB identities（file_uuid IS NULL）留在 DB 中，重新 COPY 時撞 PRIMARY KEY。
+→ M5 已在 deploy.sh 加入方案 A 修復。
+
+### 3. identities_name_key constraint
+M4 手動刪除後匯入成功。
+
+## 3602 目前狀態
+
+- total_videos: 38
+- completed: 4
+- pending: 34
+- total_chunks: 15,367
+- Build: `1f7daf9`
--- a/docs_v1.0/M4_workspace/2026-05-14_pipeline_services_checklist_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_pipeline_services_checklist_response.md
@@ -0,0 +1,44 @@
+# 2026-05-14_pipeline_services_checklist_response.md
+
+## 服務狀態
+
+### 必要服務
+
+| 服務 | Port | 狀態 | 備註 |
+|------|:---:|:--:|------|
+| PostgreSQL | 5432 | ✅ | accepting connections |
+| Redis | 6379 | ✅ | authenticated |
+| Qdrant | 6333 | ✅ | v1.17.0 |
+| **EmbeddingGemma** | **11436** | ✅ | MPS, device=mps |
+| **llama.cpp (Gemma4)** | **8082** | ✅ | M5: `192.168.110.201:8082`, model=google_gemma-4-26B-A4B-it-Q5_K_M |
+| MongoDB | 27017 | ✅ | ping=1 |
+| ffmpeg | — | ✅ | v8.1.1 |
+
+### 可選服務
+
+| 服務 | Port | 狀態 | 備註 |
+|------|:---:|:--:|------|
+| GDINO | 8080 | ❓ | 未檢查 |
+| Ollama | 11434 | ❌ | 未運行（embedding 由 11436 替代） |
+
+### 3002 Health
+
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "build_git_hash": "1f7daf9",
+  "services": {
+    "postgres": "ok",
+    "redis": "ok",
+    "qdrant": "ok",
+    "mongodb": "ok"
+  }
+}
+```
+
+### 備註
+
+- `/health/detailed` 目前只回報 postgres/redis/qdrant/mongodb，尚無 `pipeline` 區塊（scripts/models/ffmpeg/embedding_server/llm 檢查未實作）
+- 3002 與 3003 共用同樣的基礎服務（PG/Redis/Qdrant/MongoDB）
+- M5 上 Gemma4 LLM (8082) 確認在線，3002 `.env` 已正確指向
--- a/docs_v1.0/M4_workspace/2026-05-14_register_api_404_response.md
+++ b/docs_v1.0/M4_workspace/2026-05-14_register_api_404_response.md
@@ -1,30 +1,29 @@
-# Register API 404 — 回覆
+# 2026-05-14_register_api_404_response.md

-**Date**: 2026-05-14
-**From**: M5
-**To**: M4
-**Ref**: `2026-05-14_register_api_404.md`
+## Resolution

---
+正確端點為 `POST /api/v1/files/register`（非 `/api/v1/register`）。

-## 根因
+## Results

-`POST /api/v1/register` 不是有效端點。
+| 檔案 | 狀態 |
+|------|:--:|
+| diagram-0.svg, diagram-1.svg, diagram-2.svg | ✅ Registered |
+| animal10.jpg, animal11.jpg | ✅ Registered |
+| Screenshot 2026-04-01...png, Screenshot 2026-05-04...png | ✅ Registered |

-正確端點是 `POST /api/v1/files/register`，已存在於所有版本中。
+## 3002 Status

-## 修正後 Request
+| 指標 | 值 |
+|------|-----|
+| Build | `fc1d775` |
+| Total files | 33 |
+| .mp4 | 21 |
+| .mov | 2 |
+| .jpg | 4 |
+| .png | 3 |
+| .svg | 3 |

-```bash
-curl -X POST http://localhost:3002/api/v1/files/register \
-  -H "X-API-Key: ..." \
-  -H "Content-Type: application/json" \
-  -d '{
-    "file_path": "/path/to/file.svg",
-    "content_hash": "optional-sha256-hex"
-  }'
-```
+## MarkBase Tree

-## 回呼相容
-
-`POST /api/v1/register` 不需要也**不應該**新增。請 M4 改用正確端點。
+33 files, all previews working (svg/jpg/png/mp4/mov).