Development and Testing

開發與測試

開發環境

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

專案支援 Python 3.10–3.13。fubon_neo 不是一般 PyPI 依賴來源時，需先安裝 wheels/ 中符合平台的官方 wheel。

目錄結構

fubon_api_mcp_server/   Python MCP runtime 與 services
tests/                  pytest、SDK mocks、MCP contract tests
examples/               需要人工執行的 API examples
vscode-extension/       VS Code Extension
scripts/                PowerShell 品質與 release tooling
specs/                  設計與實作規格
wheels/                 官方 fubon_neo 平台 wheels
data/                   runtime data，不應提交帳戶資料

新增 MCP tool

1. 選擇正確 service；不要把領域邏輯塞進 server.py。
2. 建立 Pydantic args model，明確區分必填、選填、範圍與 enum。
3. 需要帳戶時先呼叫 validate_and_get_account。
4. 使用 SDK 已有能力，並以 keyword arguments 呼叫。
5. 在 service _register_tools() 註冊 method。
6. 成功與錯誤使用 {status, data, message}。
7. 為成功、business failure、參數錯誤、未初始化與 account validation 加 regression tests。
8. 更新 Wiki、README 或 examples 中的公開介面。

交易 tool 需額外證明無效輸入不會到達 SDK write method。

設計原則

• 不維護已淘汰路徑；需求改變時移除舊路徑，不新增 compatibility layer。
• 選擇能完整達成當前需求的最簡單實作。
• 模組責任清楚，解析留在 service，共用 helper 留在 utils.py／enums.py。
• 先檢查現有依賴與 types，再決定是否新增套件或自行實作。
• 每一層都應維持可執行與可測試，不以未完成抽象取代已工作的產品路徑。

測試

完整離線測試：

python -m pytest

專項：

python -m pytest tests/test_account_service.py -v
python -m pytest tests/test_trading_service.py -v
python -m pytest tests/test_market_data_service.py -v
python -m pytest tests/test_analysis_service.py -v
python -m pytest tests/test_mcp_v2_protocol.py -v

覆蓋率：

python -m pytest --cov=fubon_api_mcp_server --cov-report=html --cov-report=term-missing

Markers：

Marker	用途
slow	慢速測試
integration	外部整合
live_readonly	真實憑證、禁止交易寫入
trading	交易相關且需特殊啟用

預設 tests 必須 mock SDK 與 server globals。真實交易不得出現在自動化測試。

格式、lint 與型別

python -m black --check fubon_api_mcp_server tests
python -m isort --check-only fubon_api_mcp_server tests
python -m flake8 fubon_api_mcp_server tests --select=E9,F63,F7,F82
python -m mypy fubon_api_mcp_server

• Black line length：127。
• isort profile：Black。
• 命名：modules/functions 用 snake_case，classes 用 PascalCase，constants 用 UPPER_SNAKE_CASE。
• type checking 為漸進式；不能因外部 SDK 缺少 stubs 而取消本專案邊界的型別。

快速檢查：

.\scripts\quick_check.ps1

此 script 在 Black／isort 不合格時會嘗試自動修正，並可能執行 Ruff fix；使用前先檢查 worktree，執行後再檢查 diff。

Package 驗證

python -m build
python -m twine check dist\*
python -m pip check

版本由 setuptools-scm 依 Git tags 產生。發布前還要檢查 wheel 內容，確認沒有包入 build/、dist/、.env、log、data 或憑證。

Git 與 PR

• 使用 Conventional Commits：feat:、fix:、refactor:、docs:、test:、chore:、ci:。
• PR 說明需包含變更、原因、開發者／使用者影響、驗證命令與介面文件更新。
• VS Code UI 變更需附畫面。
• 混合 worktree 只 stage 本次範圍；不得用廣泛 git add -A 吸收不相關變更。

測試實證層級

單元測試通過只證明 mock contract。發行宣稱應另外包含：

1. 格式與 hard-error lint。
2. 完整 pytest。
3. MCP discovery／structured output contract。
4. package build 與 Twine check。
5. 若介面涉及真實資料，另外執行明確授權的 read-only acceptance。