快速開始

這一頁只回答兩件事：

1. 怎麼把系統跑起來
2. 你跑起來之後會看到什麼

執行環境

根據 pyproject.toml，本專案目前要求：

• Python >= 3.13

主要依賴包含：

• fastapi
• uvicorn
• pandas
• numpy
• sqlalchemy
• shioaji
• databento

安裝依賴

如果你使用 uv：

uv sync

啟動 API

uv run python app.py

啟動後預設會開在：

• http://127.0.0.1:8000

可直接使用：

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

啟動時會發生什麼

app.py 在模組載入時就會做幾件事：

1. load_dotenv()
2. 初始化 quote adapter
3. 建立資料庫連線與資料表
4. 印出 startup config
5. 直接跑一次初始回測

這代表：

• 啟動不是完全無副作用
• 若外部資料源或金鑰有問題，服務可能在啟動階段就失敗

這一點在部署時非常重要，詳見 部署指南。

最低必要環境變數

實際使用時，至少可能需要：

SHIOAJI_API_KEY=...
SHIOAJI_SECRET_KEY=...

DB_TYPE=sqlite
SQLITE_PATH=./training_params.db

# 若使用 PostgreSQL
# DB_TYPE=postgresql
# DATABASE_URL=postgresql+psycopg2://USER:PASSWORD@HOST:PORT/DBNAME

STRATEGY_NAME=BollingerATRStrategy
OPTIMIZATION_WORKERS=4

驗證系統是否正常

建議依序檢查：

1. GET /strategy_list
2. GET /ticker_list
3. GET /get_strategy
4. GET /get_timeframe
5. GET /get_params
6. GET /state

若以上可正常回應，代表：

• API 已啟動
• 全域狀態已初始化
• 策略系統可用
• 參數系統可用
• 回測主流程至少能產出 state

本機文件站

若要把本專案文件變成網站：

uv add --dev mkdocs mkdocs-material
uv run mkdocs serve

建置靜態網站：

uv run mkdocs build

輸出目錄：

• site/