markbase/examples/developer_quickstart.md

開發者快速展示指南

##目的

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

---

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

1.1啟動伺服器

cargo run -- display

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

1.2顯示範例文件

cargo run -- display examples/demo_features.md

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

---

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

2.1查看 Demo資料

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

預期結果： -返回 JSON格式的檔案樹結構

• 50個節點（5 Folder + 45 File）

2.2不同顯示模式

#列表模式
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建立新節點

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列出音訊裝置

curl http://localhost:11438/devices

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

3.2語音測試

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

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

---

##四、渲染功能展示

4.1渲染 Markdown檔案

cargo run -- render examples/demo_features.md

預期結果： -輸出 HTML到 stdout

4.2輸出到檔案

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

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

---

##五、測試展示

5.1執行所有測試

cargo test --all

預期結果：

• 62個測試全部通過 -執行時間 ~1秒

5.2特定模組測試

cargo test filetree
cargo test modes
cargo test api_logic

---

##六、代碼品質展示

6.1格式化檢查

cargo fmt -- --check

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

6.2 Clippy檢查

cargo clippy --all-targets

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

---

##七、 Runner展示

7.1啟動 Runner

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

預期結果：

• Runner連接遠端 Gitea -日誌輸出到/tmp/gitea-runner.log

7.2驗證 Runner狀態

./scripts/verify_runner.sh

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

---

##八、展示腳本整合

###完整展示流程

# 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）

---

展示指南完成！