@catalyst-team/poly-sdk 0.1.0

package/docs/e2e/06-integration-scenarios.md

@@ -0,0 +1,481 @@
+# Integration Scenarios E2E Test
+
+> 完整用户场景集成测试
+
+---
+
+## 场景概览
+
+| 场景 | 描述 | 工具组合 | 认证需求 |
+|------|------|---------|---------|
+| Smart Money Analysis | 聪明钱分析 | Trader + Market | 无 |
+| Market Discovery | 市场发现 | Market + Order | 无 |
+| Copy Trading Setup | 跟单准备 | Trader + Market + Order | 无 |
+| Arbitrage Check | 套利检查 | Market + Order | 无 |
+| Trading Setup | 交易准备 | Wallet | 私钥 |
+| Full Trading Flow | 完整交易流 | All | API Key |
+
+---
+
+## Scenario 1: Smart Money Analysis (聪明钱分析)
+
+### 目标
+分析顶级交易者的策略和持仓，发现潜在的投资机会。
+
+### 流程
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 1: get_leaderboard(limit=10)                          │
+│  获取排行榜前 10 名                                           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Step 2: 对每个交易者调用 get_trader_profile                  │
+│  筛选: winRate > 60%, positionCount > 10                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Step 3: get_trader_positions(address)                      │
+│  收集所有优质交易者的当前持仓                                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Step 4: 分析持仓重叠                                         │
+│  找出 >= 3 个交易者共同持有的市场                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Step 5: get_market(conditionId) + get_orderbook            │
+│  深入分析这些共识市场                                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 测试用例
+```
+1. 调用 get_leaderboard(limit=10)
+   验证: 返回 10 个交易者
+
+2. 选择前 3 名，调用 get_trader_profile
+   记录: displayName, winRate, totalVolume
+
+3. 调用 get_trader_positions 获取持仓
+   记录: 每个交易者持有的市场 conditionId 列表
+
+4. 找出共同持仓
+   计算: 哪些 conditionId 出现次数 >= 2
+
+5. 获取共识市场详情
+   调用: get_market 和 get_orderbook
+   输出: 市场名称、当前价格、流动性
+```
+
+### 预期输出
+```
+Smart Money Consensus Report
+============================
+
+Top 3 Traders Analyzed:
+1. trader_a (Rank #1) - Win Rate: 72%, Volume: $1.2M
+2. trader_b (Rank #2) - Win Rate: 68%, Volume: $980K
+3. trader_c (Rank #3) - Win Rate: 65%, Volume: $850K
+
+Consensus Positions (2+ traders agree):
+┌────────────────────────────┬─────────┬───────────┬────────────┐
+│ Market                     │ Side    │ Avg Price │ Traders    │
+├────────────────────────────┼─────────┼───────────┼────────────┤
+│ Bitcoin above $100k        │ YES     │ $0.45     │ 3/3        │
+│ Fed rate cut Q1 2025       │ YES     │ $0.62     │ 2/3        │
+└────────────────────────────┴─────────┴───────────┴────────────┘
+```
+
+---
+
+## Scenario 2: Market Discovery (市场发现)
+
+### 目标
+发现高交易量、高流动性的投资机会。
+
+### 流程
+```
+1. get_trending_markets(sortBy="volume", limit=10)
+   ↓
+2. 对每个市场调用 get_market 获取详情
+   ↓
+3. 对每个市场调用 get_orderbook("Yes") 和 get_orderbook("No")
+   ↓
+4. 计算每个市场的:
+   - Spread (买卖差价)
+   - Depth (订单深度)
+   - Implied Probability
+   ↓
+5. 排序: 按 (低 Spread + 高 Depth) 综合评分
+   ↓
+6. 输出: Top 5 投资机会
+```
+
+### 测试用例
+```
+1. 获取趋势市场
+   调用: get_trending_markets(sortBy="volume", limit=10)
+   验证: 返回 10 个市场
+
+2. 获取订单簿
+   对每个市场调用:
+   - get_orderbook(conditionId, "Yes")
+   - get_orderbook(conditionId, "No")
+   记录: spread, bidDepth, askDepth
+
+3. 计算评分
+   score = (1 / spread) * (bidDepth + askDepth)
+
+4. 排序输出
+```
+
+### 预期输出
+```
+Market Discovery Report
+=======================
+
+Top 5 Markets by Quality Score:
+┌────────────────────────────┬─────────┬────────┬───────────┬───────┐
+│ Market                     │ Yes     │ Spread │ Depth     │ Score │
+├────────────────────────────┼─────────┼────────┼───────────┼───────┤
+│ Presidential Election 2024 │ $0.52   │ 0.01   │ $500K     │ 95    │
+│ Bitcoin EOY Price          │ $0.48   │ 0.02   │ $320K     │ 82    │
+│ Fed Decision Jan 2025      │ $0.35   │ 0.03   │ $180K     │ 65    │
+└────────────────────────────┴─────────┴────────┴───────────┴───────┘
+```
+
+---
+
+## Scenario 3: Copy Trading Setup (跟单准备)
+
+### 目标
+监控特定交易者的新交易，准备跟单。
+
+### 流程
+```
+1. get_trader_profile(address) - 确认目标交易者
+   ↓
+2. get_trader_trades(address, limit=20) - 获取最近交易
+   ↓
+3. 识别最新的交易
+   ↓
+4. get_market(conditionId) - 获取市场当前状态
+   ↓
+5. get_best_prices(conditionId) - 获取当前最优价格
+   ↓
+6. estimate_execution(amount) - 估算跟单成本
+   ↓
+7. 输出: 跟单建议
+```
+
+### 测试用例
+```
+1. 选择一个活跃交易者
+   调用: get_leaderboard(limit=1)
+   获取: 排名第一的地址
+
+2. 获取最近交易
+   调用: get_trader_trades(address, limit=10)
+   找出: 最近 1 小时内的交易
+
+3. 分析交易
+   对于每笔新交易:
+   - 市场是什么？
+   - 买入还是卖出？
+   - 价格是多少？
+
+4. 获取当前价格
+   调用: get_market + get_best_prices
+
+5. 估算跟单成本
+   调用: estimate_execution(amount=100)
+
+6. 输出建议
+```
+
+### 预期输出
+```
+Copy Trading Alert
+==================
+
+Target: whale_trader (Rank #1)
+Recent Activity: 3 new trades in last hour
+
+Trade #1 (5 mins ago):
+- Market: Bitcoin above $100k by EOY
+- Action: BUY YES
+- Their Price: $0.42
+- Current Price: $0.44
+- Price Changed: +4.8%
+- Recommendation: LATE (price moved)
+
+Trade #2 (15 mins ago):
+- Market: Fed rate cut Q1
+- Action: BUY YES
+- Their Price: $0.58
+- Current Price: $0.59
+- Price Changed: +1.7%
+- Estimated Cost for $500: 847 shares @ $0.59
+- Recommendation: CONSIDER
+```
+
+---
+
+## Scenario 4: Arbitrage Check (套利检查)
+
+### 目标
+检查市场是否存在套利机会。
+
+### 流程
+```
+1. get_trending_markets(limit=20)
+   ↓
+2. 对每个市场:
+   get_best_prices(conditionId)
+   ↓
+3. 检查套利条件:
+   - 买入套利: yes.bestAsk + no.bestAsk < 1.0
+   - 卖出套利: yes.bestBid + no.bestBid > 1.0
+   ↓
+4. 如果发现套利:
+   estimate_execution 估算实际成本
+   ↓
+5. 计算扣除费用后的实际收益
+```
+
+### 测试用例
+```
+1. 获取市场列表
+   调用: get_trending_markets(limit=20)
+
+2. 获取价格
+   对每个市场调用: get_best_prices
+
+3. 检查套利
+   对于每个市场:
+   if (yes.bestAsk + no.bestAsk < 0.99):
+     print("买入套利机会")
+   if (yes.bestBid + no.bestBid > 1.01):
+     print("卖出套利机会")
+
+4. 验证套利
+   调用 estimate_execution 确认实际成本
+
+5. 计算净收益
+   profit = 1.0 - (yes_cost + no_cost) - fees
+```
+
+### 预期输出
+```
+Arbitrage Scanner Report
+========================
+
+Scanned: 20 markets
+Found: 0 arbitrage opportunities
+
+Analysis:
+- Average Yes+No Ask Sum: 1.012
+- Average Yes+No Bid Sum: 0.988
+- Closest to Arbitrage: "Market XYZ" (sum: 1.003)
+
+Note: Polymarket is generally efficient.
+Arbitrage opportunities are rare and short-lived.
+```
+
+---
+
+## Scenario 5: Trading Setup (交易准备)
+
+### 目标
+准备钱包进行交易。
+
+### 前置条件
+- 配置了 POLY_PRIVATE_KEY
+
+### 流程
+```
+1. get_token_balances() - 检查余额
+   ↓
+2. check_allowances() - 检查授权
+   ↓
+3. 如果未授权:
+   approve_trading()
+   ↓
+4. 如果需要 USDC.e:
+   swap(MATIC/USDC -> USDC_E)
+   ↓
+5. 确认准备就绪
+```
+
+---
+
+## Scenario 6: Full Trading Flow (完整交易流)
+
+### 目标
+从发现市场到完成交易的完整流程。
+
+### 前置条件
+- 配置了 API Key
+- 完成了交易准备
+
+### 流程
+```
+1. Smart Money Analysis - 发现机会
+   ↓
+2. Market Discovery - 确认流动性
+   ↓
+3. estimate_execution - 预估成本
+   ↓
+4. place_limit_order - 下单
+   ↓
+5. get_my_orders - 监控订单
+   ↓
+6. (可选) cancel_order - 取消/调整
+```
+
+---
+
+## 执行记录
+
+### 2025-12-23 测试结果
+
+| Scenario | 状态 | 结果 | 备注 |
+|----------|------|------|------|
+| 1. Smart Money Analysis | ✅ PASS | 成功分析 Top 3 交易者 | 发现 Grizzlies/Pistons 共识 |
+| 2. Market Discovery | ✅ PASS | 发现热门市场 | 部分体育市场已结算 |
+| 3. Copy Trading Setup | ✅ PASS | 分析 #1 交易者交易 | 建议：当前不适合跟单（卖出模式） |
+| 4. Arbitrage Check | ✅ PASS | 扫描 20 市场 | 无套利机会（市场有效） |
+| 5. Trading Setup | ⚠️ PARTIAL | 4/5 步骤通过 | approve_trading 需要修复 provider |
+| 6. Full Trading Flow | ⚠️ BLOCKED | 需要 USDC | 钱包有 MATIC 但无 USDC |
+
+---
+
+### Scenario 1 详细结果: Smart Money Analysis
+
+**Top 3 Traders:**
+
+| Rank | Address | Display Name | Win Rate | Volume | PnL |
+|------|---------|--------------|----------|--------|-----|
+| 1 | 0x4259...936f | antman-batman-superman-lakers-in-5 | 50% | $135K | $175K |
+| 2 | 0xcd9b...414d | BITCOINTO500K | 44.4% | -$127K | $87K |
+| 3 | 0x4924...3782 | (unnamed) | 50% | $21K | $56K |
+
+**共识持仓**: Trader 2 和 3 对 Grizzlies vs. Thunder、Pistons 赛事有共同兴趣
+
+---
+
+### Scenario 2 详细结果: Market Discovery
+
+**Top Markets by Quality:**
+
+| Market | Yes Price | Spread | Total Depth |
+|--------|-----------|--------|-------------|
+| Fed Rate Increase Jan 2026 | 0.65c | 0.1c | $36.96M |
+| TikTok Sale 2025 | 99.45c | 0.1c | $720K |
+| China Invades Taiwan 2025 | 0.3c | 0.2c | $1.52M |
+
+---
+
+### Scenario 3 详细结果: Copy Trading Setup
+
+**目标交易者**: antman-batman-superman-lakers-in-5 (Rank #1)
+
+**最近活动**: 10 笔交易全部是 SELL（卖出）
+- 49ers Spread: 卖出 Colts @ $0.39-0.40
+- Utah State: 卖出 @ $0.001（清仓亏损持仓）
+
+**跟单建议**: ❌ 不建议此时跟单
+- 交易者处于退出模式
+- 建议等待 BUY 信号
+
+---
+
+### Scenario 4 详细结果: Arbitrage Check
+
+**扫描结果**:
+- 市场扫描: 20 个
+- 套利机会: 0 个
+- 最接近套利: Yes+No Ask = 1.001 (偏离 0.1%)
+
+**结论**: Polymarket 市场定价有效，无风险套利不可行
+
+---
+
+### Scenario 5 详细结果: Trading Setup
+
+**测试钱包**: `0xed1050F19F2D5890FF29c2f7416de97e68069171`
+
+**Step 1: Token Balances** ✅
+| Token | Balance |
+|-------|---------|
+| MATIC | 200.0 |
+| USDC | 0.0 |
+| USDC.e | 0.0 |
+
+**Step 2: Allowances Check** ✅
+
+Trading Ready: **No**
+
+缺失授权 (7 项):
+- ERC20: CTF Exchange, Neg Risk CTF Exchange, Neg Risk Adapter, Conditional Tokens
+- ERC1155: CTF Exchange, Neg Risk CTF Exchange, Neg Risk Adapter
+
+**Step 3: Approve Trading** ❌
+- 错误: `missing provider (operation="call")`
+- 原因: Provider/Signer 配置问题
+
+**Step 4: Deposit Addresses** ✅
+| Network | Address |
+|---------|---------|
+| EVM | 0x6c809Ad3fE0039Cb9E5bFC2b313854b59561909F |
+| Solana | BPQrhLN38pCqkv8HfdMEpjgy6ZqfKyZyn8BmfZGaZJUc |
+| Bitcoin | bc1qamd5v4djapa0a905aurcq9apc2nyjldmd8kzw6 |
+
+**Step 5: Supported Assets** ✅
+- 12 链
+- 207 种资产
+
+**结论**: 只读操作正常，写操作 (approve_trading, swap) 因 provider 配置问题失败
+
+---
+
+### Scenario 6: Full Trading Flow
+
+**状态**: BLOCKED
+
+**阻塞原因**:
+1. 钱包没有 USDC（只有 MATIC）
+2. 交易授权未设置
+3. Provider 配置问题导致无法执行 swap 和 approve
+
+**前置条件**:
+1. 修复 poly-sdk 的 provider 初始化问题
+2. 执行 `approve_trading()` 授权
+3. 执行 `swap(MATIC, USDC, amount)` 获取 USDC
+4. 然后才能执行完整交易流程
+
+---
+
+## 发现的问题
+
+| ID | 场景 | 问题描述 | 严重性 | 状态 |
+|----|------|---------|--------|------|
+| 1 | 2 | 已结算体育市场仍出现在 trending 结果中 | Medium | ✅ FIXED |
+| 2 | 2 | get_market 返回陈旧的 slug 数据 | Low | ✅ FIXED |
+| 3 | 1,4 | 11/20 市场查询 best_prices 返回 "Missing tokens" | Medium | Noted |
+| 4 | 1 | leaderboard PnL 与 profile PnL 不一致 | Low | ✅ FIXED |
+| 5 | 3 | 部分市场 tokenId 为空，无法查询价格 | Medium | Noted |
+| 6 | 5 | approve_trading/swap 失败: "missing provider" | High | 待修复 |
+| 7 | 5 | get_token_balances 失败: "Cannot read properties of null" | Medium | 待修复 |
+
+### 修复说明
+
+- **Issue #1**: `get_trending_markets` 现在添加了 `closed: false` 过滤和 `endDate < now` 检查
+- **Issue #2**: `getMarketByConditionId` 现在总是尝试获取 Gamma 数据，CLOB slug 不匹配时使用回退值
+- **Issue #4**: `get_trader_profile` 现在显示 `officialPnl`（来自 leaderboard）并添加差异说明