doc: update readme doc

README.md

@@ -1,10 +1,102 @@
-# real_trader
+# Real Trader - 量化交易执行平台
-real trader 服务器, 基于easytrader
 
-python 版本： 3.8.10-win32
+Real Trader是一个量化交易执行平台，专为中国A股市场设计，提供接近实时的交易执行、模拟交易与实盘交易无缝切换、多策略管理等功能。
 
-## 依赖安装
+## 功能特点
-pip install -r requirements.txt
 
-## 运行准备
+- **实盘与模拟交易无缝切换**：根据当前交易时段和配置自动切换模拟/实盘模式
-在环境变量中设置ACCOUNT和PASSWORD
+- **多策略持仓管理**：支持多个策略并行运行，独立管理各策略持仓
+- **实盘交易管理**：自动处理部分成交、超时等异常情况
+- **RESTful API接口**：提供完整的HTTP API，便于各类策略接入
+- **自动交易时段判断**：基于中国A股交易时间，自动判断当前是否在交易时间内
+- **丰富的配置选项**：可通过环境变量或配置文件灵活配置
+- **完善的日志系统**：详细记录交易过程和异常情况
+- **定时任务调度**：支持每日定时执行任务，如保存策略数据、清理超时委托等
+
+## 系统架构
+
+- **trade_server.py**：RESTful API服务器，处理交易请求
+- **real_trader_manager.py**：实盘交易管理器，处理实盘交易异常情况
+- **strategy_position_manager.py**：策略持仓管理器，管理各策略持仓情况
+- **xt_trader.py**：交易接口封装，基于XtQuant接口
+- **simulation_trader.py**：模拟交易实现
+- **logger_config.py**：日志系统配置
+- **config.py**：系统配置管理
+
+## API接口
+
+系统提供以下RESTful API接口：
+
+- 健康检查: `GET /yu/healthcheck`
+- 买入: `POST /yu/buy`
+- 卖出: `POST /yu/sell`
+- 撤单: `DELETE /yu/cancel/<entrust_no>`
+- 查询余额: `GET /yu/balance`
+- 查询持仓: `GET /yu/positions`
+- 查询今日成交: `GET /yu/todaytrades`
+- 查询今日委托: `GET /yu/todayentrust`
+- 清空策略持仓: `DELETE /yu/clear/<strategy_name>`
+- 查询订单状态: `GET /yu/order_status`
+- 查询策略目标持仓: `GET /yu/strategy_targets`
+
+## 环境要求
+
+- Python 3.12.8+
+- 依赖库：
+  - chinese-calendar
+  - flask
+  - flask-limiter
+  - requests
+  - schedule
+  - XtQuant交易接口（实盘环境需要）
+
+## 配置项
+
+主要配置项可通过环境变量设置：
+
+- **PORT**：服务端口（默认：9527）
+- **HOST**：服务监听地址（默认：0.0.0.0）
+- **DEBUG**：调试模式（默认：False）
+- **SIMULATION_ONLY**：是否仅使用模拟交易（默认：False）
+- **XT_ACCOUNT**：XtQuant账号
+- **XT_PATH**：XtQuant路径
+
+更多配置项请参考`config.py`文件。
+
+## 使用示例
+
+1. 设置环境变量（可选）
+```bash
+export XT_ACCOUNT=你的账号
+export XT_PATH=XtQuant安装路径
+```
+
+2. 启动服务
+```bash
+python main.py
+```
+
+3. API调用示例
+```python
+import requests
+
+# 买入示例
+response = requests.post('http://localhost:9527/yu/buy', json={
+    'strategy_name': '策略名称',
+    'code': '600000',
+    'price': 10.5,
+    'amount': 100
+})
+print(response.json())
+
+# 查询持仓
+response = requests.get('http://localhost:9527/yu/positions')
+print(response.json())
+```
+
+## 注意事项
+
+- 实盘交易需要配置XtQuant交易接口
+- 系统默认会根据交易时间自动判断是否使用模拟交易
+- 交易日判断基于chinese-calendar库
+- 请确保配置正确的交易账号和路径