DDDD Trade API

概述

使用该技能构建或改进一个面向东方财富网页交易（Eastmoney web trading）的、经过安全净化的 Python 封装库。优先保障安全性、可复现性及面向公开发布的工程规范：凭证必须来自环境变量；订单提交默认应为试运行（dry-run）模式；日志与文档中严禁暴露账户 ID、Cookie、validatekey 或密码等敏感信息。

默认工作流程

1. 编辑前先审查现有项目结构与代码。
2. 坚持“试运行优先”设计原则：绝不能将真实下单设为默认行为。
3. 保持公共 API 精简且类型明确：仅包含 client、models、settings、CLI 及可选的 strategy 辅助模块。
4. 将策略生成逻辑与订单提交逻辑分离。策略函数应返回订单载荷（order payload）或 Order 对象；是否提交由调用方显式决定。
5. 更新 README 中的使用示例、安全警告及发布检查清单。
6. 在宣告项目就绪前，执行完整密钥扫描（secret scan）。

推荐的包结构

采用以下结构以确保项目清晰、适合公开发布：

dddd-trade-api/
├── .env.example
├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml
├── examples/
│   └── basic_usage.py
├── src/
│   └── eastmoney_trade_api/
│       ├── __init__.py
│       ├── cli.py
│       ├── client.py
│       ├── models.py
│       ├── settings.py
│       └── strategy.py
└── tests/
    └── test_models.py

即使仓库名或分发包名为 dddd-trade-api，Python 导入包名仍应统一为 eastmoney_trade_api；该命名对用户更清晰、更符合惯例。

安全规范

• 账户 ID、密码及可选的第三方凭证，仅允许从 .env 文件或环境变量中读取。
• 将 .env、日志文件、导出的持仓数据、Excel/CSV 文件、浏览器配置文件等加入 .gitignore。
• 禁止打印完整的 Cookie、validatekey、Token、账户 ID、密码或订单会话相关材料。
• 在诊断输出中使用 mask_secret()、mask_cookie_header() 等辅助函数对敏感值进行掩码处理。
• 所有构造器、CLI 示例、测试用例及 README 片段中，默认均需设置 dry_run=True。
• 调用真实接口 Trade/SubmitTradeV2 前，必须显式传入类似 --live-trade 的标志位。
• 须包含金融风险免责声明。不得将策略截图或历史胜率表述为对未来业绩的保证。

东方财富客户端实现模式

基于 DrissionPage 实现浏览器登录，随后从持仓查询请求中捕获 validatekey 与 Cookie，并仅限于当前运行时会话内使用。

核心方法：

• start() 打开 https://jywg.18.cn/。
• login() 自动填充账号/密码，处理验证码，并检测登录是否成功。
• query_positions() 监听 Com/queryAssetAndPositionV1?validatekey 请求，返回 DataFrame 并保存 AuthSession 实例。
• submit_order(order) 在启用 dry-run 模式时仅返回请求载荷；否则向 Trade/SubmitTradeV2?validatekey=... 发起 POST 请求。

使用东方财富接口所需的载荷字段如下：

{
    "stockCode": "510300",
    "price": "3.5",
    "amount": "100",
    "tradeType": "B",
    "zqmc": "沪深300ETF",
    "market": "HA",
}

策略开发指引

将私有交易策略迁移至本项目时，请遵循：

• 将券商连接与会话管理逻辑移入 client.py。
• 将订单载荷模型定义移入 models.py。
• 将策略专属的订单生成逻辑放入 strategy.py。
• 市场数据获取功能设为可选依赖（例如通过 .[strategy] 安装）。
• 示例脚本应聚焦于载荷生成或 dry-run 演示，而非实盘交易脚本。

针对可转债或 ETF 策略，建议先对东方财富原始持仓行进行标准化处理，再依据证券代码前缀分类证券类型，最终生成 Order 对象。

README 编写指引

README 应包含以下内容：

• 一句简明扼要的项目定位说明（中英文皆可）。
• 默认启用 dry-run 行为的说明。
• 安装命令。
• .env.example 的使用方式。
• CLI 查询持仓与 dry-run 下单的示例。
• Python API 调用示例。
• 安全检查清单。
• 后续功能路线图，如撤单、批量下单、成交回报、账户资产查询等接口。
• 公开使用风险免责声明。

若需附带验证截图，请确保所有金额、账户名、ID 及个人身份信息均已完全遮蔽。

密钥扫描检查清单

发布或推送前请执行：

rg -n --hidden -g '!.git' 'password|passwd|cookie|token|secret|validatekey|资金账号|交易密码|手机号|用户名|密码' .
rg -n --hidden -g '!.git' '[0-9]{11,}|[0-9]{6}' .
git grep -n -I -E 'password|cookie|token|secret|validatekey|资金账号|交易密码' HEAD

人工逐条核查所有匹配结果。字段名与占位符（placeholder）可接受；实际敏感值绝对不可出现。

参考文档

准备将仓库发布至 GitHub 公共仓库或上传至 SkillHub 前，请阅读 references/release-checklist.md。