測試指南
概述
本測試指南旨在幫助開發者和 QA 團隊在受控環境中測試 Stock Protocol Maker API。本指南說明如何使用預定義的數量規則來模擬不同的訂單狀態和生命週期場景。
模擬撮合引擎根據您提交的訂單數量值返回一致的響應。這使您能夠驗證各種訂單狀態行為，而無需實際的區塊鏈交易或真實市場條件。
目的
- 驗證訂單創建和生命週期管理
- 測試訂單狀態轉換（待成交、部分成交、完全成交、拒單、撤銷）
- 驗證不同場景下的 API 響應
- 確保正確的錯誤處理和邊界情況
- 為生產部署做好準備
測試環境
基礎 URL: 使用 {API_BASE_URL} 佔位符表示您的測試環境
認證: 必需 - 使用從認證授權 API 獲取的 JWT 令牌
區塊鏈: BSC 測試網（鏈 ID: 97）或配置的測試網絡
獲取測試代幣
在測試環境中創建訂單前，您需要獲取 MOCK_USDT 或 MOCK_USDC 測試代幣。測試代幣合約部署在 BSC 測試網上，提供了 faucet 函數供用戶免費獲取測試代幣。
測試代幣合約地址
- MOCK_USDT:
0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91 - MOCK_USDC:
0x5f3733f382ab5d464D39742Bb3840898cD24E6a0 - 精度: 18 位小數
- 網絡: BSC 測試網（Chain ID: 97）
方法 1: 使用 Web3 庫調用 faucet 函數
import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider('https://data-seed-prebsc-1-s1.binance.org:8545/');
const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);
const MOCK_USDT_ADDRESS = '{MOCK_USDT_ADDRESS}';
const mockERC20ABI = [
'function faucet(uint256 amount) external',
'function balanceOf(address account) view returns (uint256)'
];
const mockUSDT = new ethers.Contract(MOCK_USDT_ADDRESS, mockERC20ABI, wallet);
const amount = ethers.parseUnits('1000', 18);
const tx = await mockUSDT.faucet(amount);
await tx.wait();
console.log('成功獲取 1000 MOCK_USDT');方法 2: 使用智能合約瀏覽器
- 訪問 BSC 測試網瀏覽器：https://testnet.bscscan.com/
- 搜索 MOCK_USDT 合約地址：
0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91 - 進入「Contract」標籤頁，點擊「Write Contract」
- 連接您的 MetaMask 錢包（確保已切換到 BSC 測試網）
- 找到
faucet函數 - 輸入金額（注意：需要輸入帶 18 位小數的數值，例如
1000000000000000000000表示 1000 USDT） - 點擊「Write」按鈕並確認交易
注意事項
- 每次調用
faucet函數沒有數量限制，但建議根據測試需求合理獲取 - 確保您的錢包有足夠的 BNB 測試幣支付 gas 費用
- BNB 測試幣可從 BSC 測試網水龍頭獲取：https://testnet.bnbchain.org/faucet-smart
- MOCK_USDC 的獲取方式與 MOCK_USDT 完全相同，只需替換合約地址即可
訂單數量規則
為了模擬不同的訂單狀態，在創建訂單時使用以下數量模式：
市場特定規則
- 美股無最小數量限制
- 可使用任何遵循以下模式的數量
數量模式
1. 待成交訂單（等待成交）
模式: 以 1 結尾的數量（例如：1, 10, 100, 1000, 10000）
預期行為:
- 訂單創建並保持在
pending狀態 - 不執行任何成交
- 訂單留在訂單簿上等待接單方
使用場景: 測試訂單創建和訂單簿列表
示例數量:
1, 10, 100, 1000, 100002. 部分成交訂單
模式: 以 2 結尾的數量（例如：2, 20, 200, 2000, 20000）
預期行為:
- 訂單創建並立即部分成交
- 訂單狀態變為
partially_filled - 剩餘數量留在訂單簿上
- 生成成交記錄
使用場景: 測試部分執行和剩餘數量追蹤
示例數量:
2, 20, 200, 2000, 200003. 拒單訂單
模式: 以 3 結尾的數量（例如：3, 30, 300, 3000, 30000）
預期行為:
- 訂單被系統拒絕
- 訂單狀態變為
rejected - 不執行任何成交
- 返回錯誤消息
使用場景: 測試錯誤處理和拒單場景
示例數量:
3, 30, 300, 3000, 300004. 部分撤銷訂單
模式: 以 4 結尾的數量（例如：4, 40, 400, 4000, 40000）
預期行為:
- 訂單創建並部分成交
- 剩餘數量自動撤銷
- 訂單狀態變為
cancelled - 成交記錄顯示撤銷前的部分執行
使用場景: 測試帶有部分成交的撤銷
示例數量:
4, 40, 400, 4000, 400005. 完全撤銷訂單
模式: 以 5 結尾的數量（例如：5, 50, 500, 5000, 50000）
預期行為:
- 訂單創建但沒有任何成交
- 訂單立即被撤銷
- 訂單狀態變為
cancelled - 不生成成交記錄
使用場景: 測試無執行的完全撤銷
示例數量:
5, 50, 500, 5000, 500006. 完全成交訂單
模式: 以 6 結尾的數量（例如：6, 60, 600, 6000, 60000）
預期行為:
- 訂單創建並立即完全成交
- 訂單狀態變為
filled - 生成完整的成交記錄
- 訂單簿上無剩餘數量
使用場景: 測試完整訂單執行
示例數量:
6, 60, 600, 6000, 60000測試矩陣
| 數量 | 尾數 | 預期狀態 | 成交數量 | 剩餘數量 | 說明 |
|---|---|---|---|---|---|
| 1 | 1 | pending | 0 | 1 | 訂單等待成交 |
| 2 | 2 | partially_filled | ~1 | ~1 | 部分執行 |
| 3 | 3 | rejected | 0 | 0 | 訂單被拒絕 |
| 4 | 4 | cancelled | ~2 | 0 | 部分成交後撤銷 |
| 5 | 5 | cancelled | 0 | 0 | 完全撤銷 |
| 6 | 6 | filled | 6 | 0 | 完全執行 |
查詢訂單狀態
創建訂單後，使用以下方式查詢其狀態：
curl -X GET "{API_BASE_URL}/api/v1/orders/{order_id}" \
-H "Authorization: Bearer {JWT_TOKEN}"或列出所有訂單：
curl -X GET "{API_BASE_URL}/api/v1/orders?status=pending" \
-H "Authorization: Bearer {JWT_TOKEN}"最佳實踐
1. 測試所有狀態
創建涵蓋所有數量模式的綜合測試套件：
- 每個模式 1 個訂單（1, 2, 3, 4, 5, 6）
- 每個模式多個數量（10, 100, 1000）
- 不同的股票代碼和方向（買/賣）
2. 驗證狀態轉換
監控訂單狀態變化：
- 檢查創建後的初始狀態
- 在預期轉換後查詢狀態
- 驗證成交記錄符合預期行為
3. 測試錯誤場景
- 無效數量（負數、零）
- 無效價格
- 過期訂單
- 餘額不足（如適用）
4. 清理測試數據
測試後，撤銷待成交訂單：
curl -X DELETE "{API_BASE_URL}/api/v1/orders/{order_id}" \
-H "Authorization: Bearer {JWT_TOKEN}"訂單狀態參考
| 狀態 | 說明 | 可撤銷 | 有成交 |
|---|---|---|---|
pending | 訂單在簿上，等待成交 | 是 | 否 |
partially_filled | 訂單部分執行 | 是 | 是 |
filled | 訂單完全執行 | 否 | 是 |
cancelled | 訂單被用戶/系統撤銷 | 否 | 可能 |
rejected | 訂單被系統拒絕 | 否 | 否 |
expired | 訂單過期（超過到期時間） | 否 | 可能 |
故障排除
問題: 訂單未創建
解決方案: 檢查認證令牌，驗證所有必填字段，確保數量遵循有效模式
問題: 訂單狀態不符預期
解決方案: 驗證數量尾數與預期模式匹配，檢查訂單查詢時機
問題: 無法查詢訂單
解決方案: 確保 order_id 正確，驗證認證，檢查訂單是否已過期
問題: 成交記錄缺失
解決方案: 在測試環境中，只有數量以 2、4 或 6 結尾的訂單才有成交
其他資源
支持
如有測試環境問題或疑問：
- 檢查 API 響應錯誤消息
- 查閱本測試指南
- 聯繫開發團隊並提供訂單 ID 和時間戳
注意: 本測試指南僅適用於測試/沙盒環境。生產環境使用真實的區塊鏈交易和市場條件。