# 開發者快速展示指南

##目的

本文件提供MarkBase核心功能的快速展示範例。

---

##一、基礎展示（3分鐘）

### 1.1啟動伺服器

```bash
cargo run -- display
```

**預期結果：**
-伺服器啟動在 http://localhost:11438
-瀏覽器自動開啟
-顯示 MarkBase主頁

### 1.2顯示範例文件

```bash
cargo run -- display examples/demo_features.md
```

**預期結果：**
-顯示完整功能展示文檔
-支援表格、列表、代碼區塊

---

##二、檔案樹展示（5分鐘）

### 2.1查看 Demo資料

```bash
curl http://localhost:11438/api/v2/tree/demo?mode=tree
```

**預期結果：**
-返回 JSON格式的檔案樹結構
- 50個節點（5 Folder + 45 File）

### 2.2不同顯示模式

```bash
#列表模式
curl http://localhost:11438/api/v2/tree/demo?mode=list

#小格狀模式
curl http://localhost:11438/api/v2/tree/demo?mode=grid_sm

#大格狀模式
curl http://localhost:11438/api/v2/tree/demo?mode=grid_lg
```

### 2.3建立新節點

```bash
curl -X POST http://localhost:11438/api/v2/tree/demo/node \
  -H "Content-Type: application/json" \
  -d '{"label":"展示資料夾", "node_type":"folder"}'
```

**預期結果：**
-返回 node_id
-狀態碼 201（CREATED）

---

##三、音訊功能展示（macOS）

### 3.1列出音訊裝置

```bash
curl http://localhost:11438/devices
```

**預期結果：**
-列出所有輸出裝置
-列出所有輸入裝置
-顯示當前選用裝置

### 3.2語音測試

```bash
curl -X POST http://localhost:11438/command \
  -H "Content-Type: application/json" \
  -d '{"cmd":"test_voice", "val":"zh_TW"}'
```

**預期結果：**
-播放中文語音「語音測試一二三」

---

##四、渲染功能展示

### 4.1渲染 Markdown檔案

```bash
cargo run -- render examples/demo_features.md
```

**預期結果：**
-輸出 HTML到 stdout

### 4.2輸出到檔案

```bash
cargo run -- render examples/demo_features.md -o demo_output.html
```

**預期結果：**
-生成 demo_output.html檔案

---

##五、測試展示

### 5.1執行所有測試

```bash
cargo test --all
```

**預期結果：**
- 62個測試全部通過
-執行時間 ~1秒

### 5.2特定模組測試

```bash
cargo test filetree
cargo test modes
cargo test api_logic
```

---

##六、代碼品質展示

### 6.1格式化檢查

```bash
cargo fmt -- --check
```

**預期結果：**
-無差異（代碼已格式化）

### 6.2 Clippy檢查

```bash
cargo clippy --all-targets
```

**預期結果：**
-少數次要警告（可忽略）
-主要警告已修復

---

##七、 Runner展示

### 7.1啟動 Runner

```bash
cd /Users/accusys/markbase
./scripts/start_runner.sh
```

**預期結果：**
- Runner連接遠端 Gitea
-日誌輸出到/tmp/gitea-runner.log

### 7.2驗證 Runner狀態

```bash
./scripts/verify_runner.sh
```

**預期結果：**
-顯示 Runner配置狀態
-顯示環境準備度

---

##八、展示腳本整合

###完整展示流程

```bash
# 1.建構專案
cargo build

# 2.啟動伺服器
cargo run -- display examples/demo_features.md

# 3.測試檔案樹API
curl http://localhost:11438/api/v2/tree/demo

# 4.測試音訊功能
curl http://localhost:11438/devices

# 5.執行測試
cargo test --all

# 6.代碼品質檢查
cargo clippy

# 7. Runner驗證
./scripts/verify_runner.sh
```

---

##九、展示檔案位置

```
examples/
├── demo_features.md         # 功能展示文檔
├── developer_quickstart.md  #開發者快速指南
├── sample.md                #基本範例
├── sample.json              # JSON範例
└── files/
    ├── example_video.mp4    #影片範例（待補充）
    ├── example_audio.mp3    #音訊範例（待補充）
    └── example_image.jpg    #圖片範例（待補充）
```

---

##十、展示檢查清單

展示前確認：

- [ ] cargo build成功
- [ ] cargo test全部通過
- [ ] SwitchAudioSource已安裝（macOS）
- [ ] demo.sqlite資料完整（50節點）
- [ ] Runner已啟動（若展示 CI/CD）

---

**展示指南完成！**