From 592db31ee7795a5458bc91d360cb8d270a884f5a Mon Sep 17 00:00:00 2001
From: "2569718930@qq.com" <2569718930@qq.com>
Date: Sat, 7 Feb 2026 00:48:16 +0800
Subject: [PATCH] docs: enhance READMEs with price source, strategy tips,
 project architecture, and data file descriptions.

---
 PAPER_TRADING_GUIDE.md | 42 ++++++++++++++++++++++++++++++++++++++++--
 README.md              | 20 ++++++++++++++++++++
 README_EN.md           | 20 ++++++++++++++++++++
 3 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/PAPER_TRADING_GUIDE.md b/PAPER_TRADING_GUIDE.md
index 1034f395..5363ef4b 100644
--- a/PAPER_TRADING_GUIDE.md
+++ b/PAPER_TRADING_GUIDE.md
@@ -7,13 +7,51 @@
 1.  **自动开仓**:
     - 监控引擎在扫描中，一旦发现任何档位的 **Buy Yes** 或 **Buy No** 价格处于 **85¢ - 95¢** 区间（与城市监控报告一致），即触发买入。
     - 初始本金: **$1000.00**
-    - 单笔投入: **$5.00**
+    - 单笔投入: **动态 $3-$10**（根据四层风控策略自动调整，见下文）
     - 资金检查: 余额不足时将停止开仓。
+    - **价格来源**: 使用真实 **Ask 价格**（实际可成交价格），而非中间价
 2.  **实时估值**:
     - 每轮扫描结束后，系统会根据最新盘口中间价更新持仓价值。
-3.  **数据持久化**:
+3.  **自动结项**:
+    - 当市场价格达到 0¢ 或 100¢（Polymarket 已结算），系统自动平仓并计算盈亏，资金回笼。
+4.  **数据持久化**:
     - 持仓与余额保存在 `data/paper_positions.json`。
 
+## 🎯 四层风控仓位策略
+
+系统结合 **Open-Meteo 天气预测**、**市场深度**、**结算时间** 和 **成交量** 自动决定仓位大小：
+
+| 条件组合 | 基础仓位 | 标签 | 说明 |
+|----------|----------|------|------|
+| 价格 ≥90¢ + 天气支持 + 高成交量 | **$10** | 🔥高置信 | 三重确认，重注 |
+| 价格 ≥90¢ + 天气支持 | **$7** | ⭐中置信 | 双重确认 |
+| 价格 ≥92¢ | **$5** | 📌价格锁定 | 纯价格锁定 |
+| 其他 85-91¢ | **$3** | 💡试探 | 最小仓位试探 |
+
+### 风控过滤规则
+
+1. **流动性过滤**: 市场深度 < $50 跳过；深度 < 5×仓位则按比例缩减
+2. **时间衰减**: 
+   - ≤1小时: 停止建仓 (0%)
+   - 1-4小时: 缩小至 40%
+   - 4-12小时: 缩小至 70%
+   - >12小时: 100%
+3. **预算上限**: 每日最高投入 $50
+4. **成交量加权**: 低活跃市场额外缩减 20%
+
+### 天气支持判断逻辑
+
+- **买 NO**: Open-Meteo 预测温度在选项区间 **之外** (±2° 容差)
+- **买 YES**: Open-Meteo 预测温度 **落入** 选项区间
+
+### 策略建议显示
+
+当推送包含交易信号时，会附带策略建议：
+```
+💡 策略建议:
+• 预测温度19.0°C落在21°C区间，市场与模型一致
+```
+
 ## 📊 盈亏计算公式
 
 - **持仓份额** = $5 / (买入价格 / 100)
diff --git a/README.md b/README.md
index 1689c5b1..d9f749a4 100644
--- a/README.md
+++ b/README.md
@@ -54,9 +54,13 @@ python run.py
 
 - **优化机制**: 同一轮扫描中，同一城市的所有异动将**合并为一条消息**发送，拒绝刷屏。
 - **触发内容**: 包含该城市下所有符合条件的"价格预警"与"市场异常"。
+- **价格来源**: 推送使用真实 **Ask 价格**（实际可成交价格），而非中间价
 - **推送格式**:
   ```
   ⚡ 40-41°F (2026-02-06): Buy No 87¢ | 预测:38°F [🛒 $10.0 🔥高置信]
+  
+  💡 策略建议:
+  • 预测温度38.0°C落在40-41°F区间，市场与模型一致
   ```
 
 ### 2. ⚡ 价格预警 (触发模拟买入)
@@ -147,6 +151,22 @@ HTTPS_PROXY=http://127.0.0.1:7890
 HTTP_PROXY=http://127.0.0.1:7890
 ```
 
+## 🏗️ 项目架构
+
+本项目完全基于 **py-clob-client** 官方客户端构建：
+- 所有与 Polymarket 的交互（市场数据、订单簿、下单等）均通过 `py-clob-client` 实现
+- 核心 API 封装在 `src/data_collection/polymarket_api.py`
+
+## 📂 数据文件说明
+
+| 文件 | 说明 |
+|------|------|
+| `data/paper_positions.json` | 模拟仓持仓、余额、交易历史 |
+| `data/pushed_signals.json` | 已推送信号记录（防刷屏） |
+| `data/active_signals.json` | 当前活跃交易信号 |
+| `data/all_markets.json` | 全量市场缓存 |
+| `data/price_history.json` | 价格历史（用于趋势计算） |
+
 ---
 
 ## 📋 核心功能特性
diff --git a/README_EN.md b/README_EN.md
index b2c5c703..d275e87f 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -53,9 +53,13 @@ The system automatically decides the position size based on **Open-Meteo Weather
 ### 1. 📂 City Alert Summaries (Push)
 
 - **Optimization**: All anomalies for the same city are merged into a **single report** per scan cycle to prevent spamming.
+- **Price Source**: Uses real **Ask price** (actual executable price), not mid price
 - **Push Format**:
   ```
   ⚡ 40-41°F (2026-02-06): Buy No 87¢ | Prediction:38°F [🛒 $10.0 🔥High Conf]
+
+  💡 Strategy Tips:
+  • Predicted temp 38.0°C falls within 40-41°F range, market aligns with model
   ```
 
 ### 2. ⚡ Price Alerts (Auto Paper Trade)
@@ -142,6 +146,22 @@ HTTPS_PROXY=http://127.0.0.1:7890
 HTTP_PROXY=http://127.0.0.1:7890
 ```
 
+## 🏗️ Project Architecture
+
+This project is built entirely on the official **py-clob-client**:
+- All interactions with Polymarket (market data, orderbook, trading) use `py-clob-client`
+- Core API wrapper: `src/data_collection/polymarket_api.py`
+
+## 📂 Data Files
+
+| File | Description |
+|------|-------------|
+| `data/paper_positions.json` | Paper trading positions, balance, trade history |
+| `data/pushed_signals.json` | Pushed signals record (anti-spam) |
+| `data/active_signals.json` | Currently active trading signals |
+| `data/all_markets.json` | Full market cache |
+| `data/price_history.json` | Price history for trend calculation |
+
 ---
 
 ## 📋 Core Features