diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..18b63be --- /dev/null +++ b/docs/README.md @@ -0,0 +1,109 @@ +# Sanguo VeighNa 文档中心 + +本目录包含项目的完整文档体系。 + +## 📚 文档目录 + +### 1. 需求文档 (`requirements/`) +业务需求、功能需求和非功能需求的存放位置。 + +- **business/** - 业务需求文档 (BRD) +- **functional/** - 功能需求文档和用户故事 +- **non_functional/** - 非功能需求（性能、安全等） + +**查看详情**: [requirements/README.md](requirements/README.md) + +--- + +### 2. 设计文档 (`design/`) +技术架构和详细设计文档。 + +- **architecture/** - 系统架构设计 +- **database/** - 数据库设计 +- **ui/** - 界面设计和原型 +- **integration/** - 接口和集成设计 + +**查看详情**: [design/README.md](design/README.md) + +--- + +### 3. API 文档 (`api/`) +接口定义和 API 规范。 + +- **rest/** - REST API 文档 +- **event/** - 事件定义和说明 +- **internal/** - 内部接口定义 + +**查看详情**: [api/README.md](api/README.md) + +--- + +### 4. 用户指南 (`user_guide/`) +面向终端用户的使用文档。 + +- **quick_start/** - 快速开始指南 +- **tutorials/** - 详细教程 +- **faq/** - 常见问题 + +**查看详情**: [user_guide/README.md](user_guide/README.md) + +--- + +### 5. 运维文档 (`operations/`) +系统部署、监控和故障排查。 + +- **deployment/** - 部署文档 +- **monitoring/** - 监控指标和告警 +- **troubleshooting/** - 故障排查手册 + +**查看详情**: [operations/README.md](operations/README.md) + +--- + +### 6. 量化研究 (`research/`) +因子、策略和回测报告。 + +- **factors/** - 因子研究文档 +- **strategies/** - 策略说明文档 +- **backtests/** - 回测报告 + +**查看详情**: [research/README.md](research/README.md) + +--- + +## 📝 文档规范 + +### 命名规范 + +| 类型 | 格式 | 示例 | +|-----|------|------| +| 业务需求 | `brd-XXX.md` | `brd-001-平台概述.md` | +| 功能需求 | `feature-XXX-模块-功能.md` | `feature-001-gateway-ctp.md` | +| 设计文档 | `system-名称.md` | `system-交易核心.md` | +| API 文档 | `gateway-接口名.md` | `gateway-ctp-api.md` | +| 用户文档 | `主题.md` | `installation.md` | + +### 编写规范 + +1. 使用 Markdown 格式 +2. 代码块指定语言 +3. 添加必要的图表和示例 +4. 保持与代码同步更新 +5. 使用中文编写，技术术语保留英文 + +--- + +## 🔗 快速链接 + +- [开发指南](development.md) +- [项目 README](../README.md) +- [变更日志](../CHANGELOG.md) +- [Gitea 仓库](http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2) + +--- + +## 📋 文档更新记录 + +| 日期 | 文档 | 变更说明 | +|-----|------|---------| +| 2025-07-01 | 全部 | 初始化文档体系 | diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 0000000..4a21796 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,188 @@ +# API 文档目录 + +本目录用于存放项目的 API 设计文档。 + +## 目录结构 + +``` +api/ +├── rest/ # REST API +│ ├── v1/ # API版本 +│ │ ├── trading.md +│ │ └── data.md +│ └── openapi.json # OpenAPI规范 +├── event/ # 事件定义 +│ ├── trading_events.md +│ └── data_events.md +└── internal/ # 内部接口 + ├── gateway_interface.md + └── engine_interface.md +``` + +## 事件定义模板 + +### trading_events.md + +```markdown +# 交易事件定义 + +基于 VeighNa 事件系统，扩展自定义事件。 + +## 标准事件（来自 VeighNa） + +| 事件名 | 类型 | 数据对象 | 触发时机 | +|-------|------|---------|---------| +| EVENT_TICK | eTick | TickData | 行情更新 | +| EVENT_ORDER | eOrder | OrderData | 委托状态变化 | +| EVENT_TRADE | eTrade | TradeData | 成交回报 | +| EVENT_POSITION | ePosition | PositionData | 持仓变化 | +| EVENT_ACCOUNT | eAccount | AccountData | 账户变化 | +| EVENT_CONTRACT | eContract | ContractData | 合约信息 | +| EVENT_LOG | eLog | LogData | 日志输出 | + +## 自定义事件 + +### EVENT_RISK_ALERT + +风险预警事件 + +```python +from vnpy.event import Event + +EVENT_RISK_ALERT = "eRiskAlert" + +class RiskAlertData: + """风险预警数据""" + def __init__( + self, + alert_type: str, + level: str, + message: str, + vt_symbol: str = "", + ) -> None: + self.alert_type = alert_type # 预警类型 + self.level = level # 预警级别 + self.message = message # 预警信息 + self.vt_symbol = vt_symbol # 合约标识 +``` + +## 事件处理示例 + +```python +from vnpy.event import EventEngine +from vnpy.trader.engine import MainEngine + +def on_tick(event: Event) -> None: + """处理行情事件""" + tick: TickData = event.data + # 处理逻辑 + pass + +event_engine: EventEngine = ... +event_engine.register(EVENT_TICK, on_tick) +``` +``` + +## REST API 模板 + +### trading.md + +```markdown +# 交易 REST API + +## 基础信息 + +- Base URL: `http://localhost:8000/api/v1` +- 认证方式: Bearer Token +- 数据格式: JSON + +## 接口列表 + +### 1. 发单 + +**POST** `/orders` + +```json +{ + "symbol": "IF2412", + "exchange": "CFFEX", + "direction": "LONG", + "offset": "OPEN", + "price": 3500.0, + "volume": 1, + "price_type": "LIMIT" +} +``` + +**响应** +```json +{ + "status": "success", + "data": { + "order_id": "ORDER123456", + "vt_orderid": "CTP.ORDER123456" + } +} +``` + +### 2. 撤单 + +**DELETE** `/orders/{order_id}` + +### 3. 查询持仓 + +**GET** `/positions` + +## 错误码 + +| 错误码 | 说明 | +|-------|------| +| 400 | 参数错误 | +| 401 | 未授权 | +| 500 | 服务器错误 | +``` + +## 内部接口模板 + +### gateway_interface.md + +```markdown +# Gateway 接口定义 + +自定义交易接口需要实现的标准接口。 + +## 必须实现的方法 + +```python +from abc import ABC, abstractmethod +from vnpy.trader.gateway import BaseGateway +from vnpy.trader.object import ( + OrderRequest, + CancelRequest, + SubscribeRequest, +) + +class CustomGateway(BaseGateway): + default_name: str = "CUSTOM" + + def connect(self, setting: dict) -> None: + """连接接口""" + pass + + def close(self) -> None: + """关闭连接""" + pass + + def subscribe(self, req: SubscribeRequest) -> None: + """订阅行情""" + pass + + def send_order(self, req: OrderRequest) -> str: + """发单""" + pass + + def cancel_order(self, req: CancelRequest) -> None: + """撤单""" + pass +``` +``` diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 0000000..bb0b86f --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,145 @@ +# 设计文档目录 + +本目录用于存放项目的技术设计文档。 + +## 目录结构 + +``` +design/ +├── architecture/ # 架构设计 +│ ├── system-*.md # 系统架构 +│ ├── module-*.md # 模块设计 +│ └── sequence-*.md # 时序图 +├── database/ # 数据库设计 +│ ├── schema-*.md # 数据表结构 +│ └── erd-*.md # ER图 +├── ui/ # 界面设计 +│ ├── mockup-*.md # 界面原型 +│ └── workflow-*.md # 交互流程 +└── integration/ # 集成设计 + ├── gateway-*.md # 接口集成 + └── protocol-*.md # 协议定义 +``` + +## 文档命名规范 + +| 类型 | 命名格式 | 示例 | +|-----|---------|------| +| 系统架构 | `system-名称.md` | `system-交易核心.md` | +| 模块设计 | `module-模块名.md` | `module-order-engine.md` | +| 数据表 | `schema-表名.md` | `schema-orders.md` | +| 原型设计 | `mockup-页面名.md` | `mockup-交易面板.md` | +| 接口设计 | `gateway-接口名.md` | `gateway-ctp-api.md` | + +## 设计文档模板 + +### 系统架构设计模板 + +```markdown +# [系统名称] 架构设计 + +## 1. 概述 + + +## 2. 架构原则 + + +## 3. 分层架构 +```mermaid +graph TB + A[表现层] --> B[业务层] + B --> C[数据层] +``` + +## 4. 核心组件 +### 4.1 组件A +- 职责 +- 接口 +- 依赖 + +## 5. 数据流 +```mermaid +sequenceDiagram + A->>B: 请求 + B->>C: 处理 +``` + +## 6. 扩展点 + + +## 7. 技术选型 +| 技术 | 用途 | 理由 | +|-----|------|------| +| Python | 核心语言 | VeighNa基础 | +``` + +### 模块设计模板 + +```markdown +# [模块名称] 模块设计 + +## 1. 模块职责 + + +## 2. 类设计 +### 2.1 ClassA +```python +class ClassA: + """类说明""" + def method1(self) -> None: + """方法说明""" + pass +``` + +## 3. 状态机 +```mermaid +stateDiagram-v2 + [*] --> Created + Created --> Active + Active --> Closed +``` + +## 4. 接口定义 +```python +from abc import ABC, abstractmethod + +class InterfaceA(ABC): + @abstractmethod + def method(self) -> None: + pass +``` + +## 5. 异常处理 +| 异常 | 触发条件 | 处理方式 | +|-----|---------|---------| +| ExceptionA | 条件A | 方式A | + +## 6. 性能考虑 + +``` + +## 设计评审流程 + +```mermaid +graph LR + A[设计草稿] --> B[团队评审] + B --> C{通过?} + C -->|否| A + C -->|是| D[设计定稿] + D --> E[开发实施] +``` + +## 设计原则 + +1. **SOLID 原则** + - 单一职责 + - 开闭原则 + - 里氏替换 + - 接口隔离 + - 依赖倒置 + +2. **量化平台特有原则** + - 数据一致性优先 + - 低延迟要求 + - 高可用保障 + - 风险控制内置 diff --git a/docs/operations/README.md b/docs/operations/README.md new file mode 100644 index 0000000..bb36b17 --- /dev/null +++ b/docs/operations/README.md @@ -0,0 +1,204 @@ +# 运维文档目录 + +本目录用于存放系统运维相关的文档。 + +## 目录结构 + +``` +operations/ +├── deployment/ # 部署文档 +│ ├── local.md +│ ├── server.md +│ └── docker.md +├── monitoring/ # 监控文档 +│ ├── metrics.md +│ ├── alerts.md +│ └── logging.md +└── troubleshooting/ # 故障排查 + ├── common.md + ├── critical.md + └── recovery.md +``` + +## 文档命名规范 + +| 类型 | 命名格式 | 示例 | +|-----|---------|------| +| 部署文档 | `deployment/环境.md` | `deployment/server.md` | +| 监控文档 | `monitoring/类型.md` | `monitoring/metrics.md` | +| 故障排查 | `troubleshooting/级别-主题.md` | `troubleshooting/critical-order.md` | + +## 部署文档模板 + +### deployment/server.md + +```markdown +# 服务器部署指南 + +## 环境准备 + +### 硬件要求 +- CPU: 4核+ +- 内存: 8GB+ +- 磁盘: 100GB+ + +### 软件要求 +- OS: Ubuntu 22.04 LTS+ +- Python: 3.10+ +- 数据库: PostgreSQL 14+ + +## 部署步骤 + +### 1. 安装依赖 + +\`\`\`bash +sudo apt update +sudo apt install python3.11 python3.11-venv postgresql +\`\`\` + +### 2. 配置数据库 + +\`\`\`bash +sudo -u postgres createdb sanguo_trading +sudo -u postgres psql -c "CREATE USER sanguo WITH PASSWORD 'xxx';" +sudo -u postgres psql -c "GRANT ALL ON DATABASE sanguo_trading TO sanguo;" +\`\`\` + +### 3. 部署应用 + +\`\`\`bash +git clone http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2 +cd sanguo_vnpy_v2 +python3.11 -m venv venv +source venv/bin/activate +pip install -r requirements/base.txt +\`\`\` + +### 4. 配置服务 + +创建 systemd 服务文件... + +### 5. 启动服务 + +\`\`\`bash +sudo systemctl start sanguo-trader +sudo systemctl enable sanguo-trader +\`\`\` + +## 验证部署 + +\`\`\`bash +curl http://localhost:8000/health +\`\`\` +``` + +## 监控文档模板 + +### monitoring/metrics.md + +```markdown +# 系统监控指标 + +## 核心指标 + +### 交易相关 +| 指标 | 说明 | 告警阈值 | +|-----|------|---------| +| order_latency | 订单延迟 | >100ms | +| order_success_rate | 订单成功率 | <99% | +| position_sync_rate | 持仓同步率 | <95% | +| tick_delay | 行情延迟 | >500ms | + +### 系统相关 +| 指标 | 说明 | 告警阈值 | +|-----|------|---------| +| cpu_usage | CPU使用率 | >80% | +| memory_usage | 内存使用率 | >85% | +| disk_io | 磁盘IO | >90% | + +## 告警规则 + +\`\`\`yaml +alerts: + - name: OrderDelay + condition: order_latency > 100 + action: send_alert + severity: warning +\`\`\` + +## 监控工具 + +- Prometheus + Grafana +- 日志分析 +``` + +## 故障排查模板 + +### troubleshooting/critical.md + +```markdown +# 紧急故障处理手册 + +## 故障分级 + +| 级别 | 描述 | 响应时间 | +|-----|------|---------| +| P0 | 系统不可用 | 15分钟 | +| P1 | 核心功能异常 | 1小时 | +| P2 | 部分功能异常 | 4小时 | +| P3 | 轻微问题 | 1个工作日 | + +## 常见紧急场景 + +### 场景1: 订单无法下发 + +**症状** +- 订单一直处于提交中状态 +- 日志显示连接超时 + +**排查步骤** +1. 检查网络连接 +2. 检查接口状态 +3. 查看错误日志 + +**解决方案** +\`\`\`bash +# 重启接口连接 +systemctl restart sanguo-gateway +\`\`\` + +### 场景2: 行情中断 + +**症状** +- K线图不再更新 +- Tick 数据停止 + +**排查步骤** +... + +## 紧急联系人 + +| 角色 | 姓名 | 电话 | +|-----|------|------| +| 开发负责人 | xxx | xxx | +| 运维负责人 | xxx | xxx | +| 业务负责人 | xxx | xxx | +``` + +## 运维检查清单 + +### 日常检查（每日） +- [ ] 系统运行状态 +- [ ] 接口连接状态 +- [ ] 错误日志检查 +- [ ] 数据备份确认 + +### 周期检查（每周） +- [ ] 磁盘空间检查 +- [ ] 性能指标分析 +- [ ] 安全补丁更新 + +### 月度检查（每月） +- [ ] 备份恢复测试 +- [ ] 灾备演练 +- [ ] 容量规划评估 diff --git a/docs/requirements/README.md b/docs/requirements/README.md new file mode 100644 index 0000000..90fa49f --- /dev/null +++ b/docs/requirements/README.md @@ -0,0 +1,99 @@ +# 需求文档目录 + +本目录用于存放项目各阶段的需求文档。 + +## 目录结构 + +``` +requirements/ +├── business/ # 业务需求 +│ ├── brd-001.md # 业务需求文档 +│ └── market-*.md # 市场调研文档 +├── functional/ # 功能需求 +│ ├── epic-*.md # 史诗级需求 +│ ├── feature-*.md # 功能需求 +│ └── story-*.md # 用户故事 +└── non_functional/ # 非功能需求 + ├── performance.md # 性能需求 + ├── security.md # 安全需求 + └── reliability.md # 可靠性需求 +``` + +## 文档命名规范 + +| 类型 | 命名格式 | 示例 | +|-----|---------|------| +| 业务需求 | `brd-XXX.md` | `brd-001-平台概述.md` | +| 功能史诗 | `epic-XXX.md` | `epic-001-交易模块.md` | +| 功能需求 | `feature-XXX-模块-功能.md` | `feature-001-gateway-ctp.md` | +| 用户故事 | `story-XXX.md` | `story-001-订单撤单.md` | +| 接口需求 | `api-XXX.md` | `api-001-行情接口.md` | + +## 文档模板 + +### 业务需求文档 (BRD) 模板 + +创建 `business/brd-template.md`： + +```markdown +# [项目名称] 业务需求文档 + +## 1. 项目背景 + + +## 2. 业务目标 + + +## 3. 目标用户 + + +## 4. 业务范围 + + +## 5. 竞争分析 + + +## 6. 成功指标 + +``` + +### 功能需求文档模板 + +创建 `functional/feature-template.md`： + +```markdown +# [功能名称] 需求文档 + +## 需求概述 + + +## 用户角色 + + +## 功能描述 + + +## 验收标准 +- [ ] 标准1 +- [ ] 标准2 + +## 优先级 +P0 / P1 / P2 / P3 + +## 依赖关系 + + +## 相关链接 +- Issue: #xxx +- 设计文档: ../design/xxx.md +``` + +## 工作流程 + +```mermaid +graph LR + A[业务需求] --> B[功能分解] + B --> C[技术评审] + C --> D[排期开发] + D --> E[验收测试] +``` diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 0000000..b087b2d --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,233 @@ +# 量化研究目录 + +本目录用于存放量化投研相关的文档和成果。 + +## 目录结构 + +``` +research/ +├── factors/ # 因子研究 +│ ├── alpha/ # Alpha因子 +│ ├── technical/ # 技术因子 +│ ├── fundamental/# 基本面因子 +│ └── risk/ # 风险因子 +├── strategies/ # 策略研究 +│ ├── cta/ # CTA策略 +│ ├── alpha/ # Alpha策略 +│ ├── arbitrage/ # 套利策略 +│ └── option/ # 期权策略 +└── backtests/ # 回测报告 + ├── summary/ # 回测汇总 + ├── detail/ # 详细报告 + └── analysis/ # 分析报告 +``` + +## 文档命名规范 + +| 类型 | 命名格式 | 示例 | +|-----|---------|------| +| 因子文档 | `factors/分类/因子名.md` | `factors/alpha/momentum.md` | +| 策略文档 | `strategies/分类/策略名.md` | `strategies/cta/dual-thrust.md` | +| 回测报告 | `backtests/detail/策略_日期.md` | `backtests/detail/dual-thrust_20240101.md` | + +## 因子研究模板 + +### factors/alpha/momentum.md + +```markdown +# 动量因子研究 + +## 因子描述 + +动量因子捕捉价格趋势延续性。 + +## 计算公式 + +\`\`\`python +def calculate_momentum(close_prices: pd.Series, period: int = 20) -> pd.Series: + \"\"\" + 计算动量因子 + + Parameters + ---------- + close_prices : pd.Series + 收盘价序列 + period : int + 计算周期 + + Returns + ------- + pd.Series + 动量因子值 + \"\"\" + return close_prices / close_prices.shift(period) - 1 +\`\`\` + +## 参数设置 + +| 参数 | 默认值 | 说明 | +|-----|-------|------| +| period | 20 | 计算周期 | + +## 回测结果 + +| 指标 | 数值 | +|-----|------| +| 年化收益 | 8.5% | +| 夏普比率 | 1.2 | +| 最大回撤 | -12% | + +## 分析结论 + +... + +## 参考文献 + +- Jegadeesh, N., & Titman, S. (1993). Returns to Buying Winners and Selling Losers +``` + +## 策略研究模板 + +### strategies/cta/dual-thrust.md + +```markdown +# Dual Thrust 策略 + +## 策略概述 + +Dual Thrust 是一种突破类策略，基于开盘价波动范围确定上下轨。 + +## 策略逻辑 + +\`\`\`python +class DualThrustStrategy(CtaStrategyTemplate): + \"\"\"Dual Thrust 策略\"\"\" + + def __init__(self, cta_engine, strategy_name, vt_symbol, setting): + super().__init__(cta_engine, strategy_name, vt_symbol, setting) + + # 参数 + self.k1 = setting.get("k1", 0.5) # 上轨系数 + self.k2 = setting.get("k2", 0.5) # 下轨系数 + + def on_bar(self, bar): + \"\"\"K线回调\"\"\" + # 计算上下轨 + # 判断突破 + # 下单逻辑 + pass +\`\`\` + +## 参数优化 + +| 参数 | 范围 | 步长 | +|-----|------|------| +| k1 | 0.3-0.7 | 0.05 | +| k2 | 0.3-0.7 | 0.05 | + +## 回测表现 + +### 股指期货 + +| 品种 | 年化收益 | 夏普比率 | 最大回撤 | +|-----|---------|---------|---------| +| IF | 12% | 1.5 | -15% | +| IH | 8% | 1.2 | -12% | +| IC | 10% | 1.3 | -14% | + +## 风险提示 + +- 趋势市场表现好，震荡市场亏损 +- 需要做好止损设置 +``` + +## 回测报告模板 + +### backtests/detail/report_template.md + +```markdown +# 策略回测报告 + +## 基本信息 + +| 项目 | 数值 | +|-----|------| +| 策略名称 | xxx | +| 回测区间 | 2020-01-01 至 2023-12-31 | +| 交易品种 | IF2412 | +| 初始资金 | 100万 | + +## 绩效指标 + +### 收益指标 + +| 指标 | 数值 | +|-----|------| +| 总收益率 | 50% | +| 年化收益率 | 12.5% | +| 基准收益率 | 8% | +| 超额收益率 | 4.5% | + +### 风险指标 + +| 指标 | 数值 | +|-----|------| +| 波动率 | 15% | +| 夏普比率 | 1.25 | +| 卡玛比率 | 0.83 | +| 最大回撤 | -15% | + +### 交易统计 + +| 指标 | 数值 | +|-----|------| +| 总交易次数 | 500 | +| 盈利次数 | 280 | +| 亏损次数 | 220 | +| 胜率 | 56% | +| 盈亏比 | 1.8 | + +## 分析图表 + +### 资金曲线 +\`\`\` +[图表] +\`\`\` + +### 回撤曲线 +\`\`\` +[图表] +\`\`\` + +## 结论与建议 + +... +``` + +## 研究工作流 + +```mermaid +graph LR + A[因子发现] --> B[因子验证] + B --> C[策略构建] + C --> D[历史回测] + D --> E{通过?} + E -->|否| A + E -->|是| F[模拟测试] + F --> G{通过?} + G -->|否| A + G -->|是| H[实盘上线] +``` + +## 数据管理 + +### 数据源 +- 历史行情: 数据库存储 +- 实时行情: 接口订阅 +- 基本面: 第三方数据源 + +### 数据更新 +- 日线数据: 每日盘后更新 +- 分钟数据: 实时更新 +- 财务数据: 每季度更新 +``` diff --git a/docs/user_guide/README.md b/docs/user_guide/README.md new file mode 100644 index 0000000..ed8be43 --- /dev/null +++ b/docs/user_guide/README.md @@ -0,0 +1,149 @@ +# 用户指南目录 + +本目录用于存放面向终端用户的文档。 + +## 目录结构 + +``` +user_guide/ +├── quick_start/ # 快速开始 +│ ├── installation.md +│ ├── first_trade.md +│ └── first_strategy.md +├── tutorials/ # 教程 +│ ├── basic/ # 基础教程 +│ ├── advanced/ # 高级教程 +│ └── examples/ # 示例代码 +└── faq/ # 常见问题 + ├── general.md + ├── trading.md + └── strategy.md +``` + +## 文档命名规范 + +| 类型 | 命名格式 | 示例 | +|-----|---------|------| +| 快速开始 | `quick_start/主题.md` | `quick_start/installation.md` | +| 教程 | `tutorials/分类/主题.md` | `tutorials/basic/cta_strategy.md` | +| FAQ | `faq/分类.md` | `faq/trading.md` | + +## 快速开始模板 + +### installation.md + +```markdown +# 安装指南 + +## 环境要求 + +- Python 3.10+ +- 推荐使用 Python 3.13 + +## 安装步骤 + +### Windows + +\`\`\`bash +# 1. 下载安装包 +# 2. 运行安装程序 +# 3. 验证安装 +python -c "import sanguo_trader; print(sanguo_trader.__version__)" +\`\`\` + +### Linux/Mac + +\`\`\`bash +# 1. 克隆仓库 +git clone http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2 + +# 2. 安装依赖 +cd sanguo_vnpy_v2 +pip install -r requirements/base.txt + +# 3. 验证安装 +python -c "import sanguo_trader; print('OK')" +\`\`\` + +## 常见问题 + +### Q: 安装失败怎么办？ +A: 检查 Python 版本，使用虚拟环境 +``` + +## 教程模板 + +### tutorials/basic/cta_strategy.md + +```markdown +# CTA 策略开发教程 + +## 概述 + +本教程将带你创建一个简单的 CTA 策略。 + +## 前置知识 + +- Python 基础 +- 量化交易基本概念 + +## 步骤 1: 创建策略类 + +\`\`\`python +from sanguo_trader.strategy import CtaStrategyTemplate + +class MyStrategy(CtaStrategyTemplate): + """我的第一个策略""" + + def __init__(self, cta_engine, strategy_name, vt_symbol, setting): + super().__init__(cta_engine, strategy_name, vt_symbol, setting) + + def on_tick(self, tick): + """行情回调""" + pass + + def on_order(self, order): + """委托回调""" + pass +\`\`\` + +## 步骤 2: 编写交易逻辑 + +... + +## 步骤 3: 回测验证 + +... + +## 下一步 + +- 查看[高级教程](../advanced/) +- 查看[策略库](../../research/strategies/) +``` + +## FAQ 模板 + +### faq/trading.md + +```markdown +# 交易相关常见问题 + +## 委托问题 + +### Q: 为什么委托没有成交？ +A: 可能原因： +1. 价格偏离市场价太远 +2. 市场流动性不足 +3. 触发了风控规则 + +### Q: 如何修改委托价格？ +A: ... +``` + +## 文档风格指南 + +1. 使用清晰简洁的语言 +2. 提供可运行的代码示例 +3. 使用截图说明界面操作 +4. 保持文档与代码同步更新 +5. 添加必要的警告和注意事项