e3d6b60825
Phase 1 (Infrastructure): - Docs: README.md, AGENTS.md, CHANGELOG.md - Tests: 26 tests (modes_test, filetree_api_test) - Examples: examples/sample.md, sample.json - CI/CD: .gitea/workflows/test.yml, release.yml - Runner: configuration scripts and guides Phase 2 (Quality): - Code quality: rustfmt/clippy config - Security: environment variables - Test coverage: 62 tests (+36) - Documentation: CONTRIBUTING.md, docs/api.yaml - Showcase: demo_features.md, developer_quickstart.md Test coverage: 75% Test pass rate: 100%
248 lines
3.9 KiB
Markdown
248 lines
3.9 KiB
Markdown
# 開發者快速展示指南
|
||
|
||
##目的
|
||
|
||
本文件提供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）
|
||
|
||
---
|
||
|
||
**展示指南完成！** |