Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
54 lines (37 loc) · 2.29 KB

CONTRIBUTING.md

File metadata and controls

54 lines (37 loc) · 2.29 KB
Raw

贡献指南

感谢参与 QuantCockpit。Public Alpha 优先维护可验证的数据语义，而不是扩大交易功能范围。

开发环境

需要 Python 3.13、uv 和 Bun。请不要提交虚拟环境、node_modules、DuckDB 文件、报告、密钥或真实策略日志。

uv sync
cd frontend
bun install

变更流程

  1. 先写能准确失败的最小测试，再写实现。
  2. 事件、API 或错误语义变化时，同步更新 README 和架构文档。
  3. 示例必须完全合成，使用虚构策略名、工具名和标的、固定时间以及 paper 环境。
  4. 不新增交易执行、券商连接、收益承诺或自动调仓建议。
  5. 保持 API 对外错误为安全摘要，不回显坏行、绝对路径或密钥。

提交评审前运行：

uv run pytest -q
cd frontend
bun run test
bun run typecheck
bun run build
bun audit

建议把功能、修复和纯格式调整分开。提交说明应解释行为变化、失败模式、测试证据，以及是否改变 JSONL 或 API 契约。

契约变更

schema_version 和仓位映射的 profile_version 都是公共边界。新增必填字段、改变收益/敞口口径或改变幂等键都属于破坏性变更，必须提供迁移说明和旧数据测试。未知字段当前会被拒绝；不要用静默忽略来掩盖版本不匹配。

贡献仓位适配

优先贡献声明式映射示例，只有现有 CSV / JSON / JSONL 读取器无法表达时才新增代码适配器。每个新适配必须同时提供：

  • 完全合成且不含品牌、账户或真实标的的最小输入夹具；
  • 固定版本的映射配置，以及确定性的 mapping_profile_hash 测试；
  • preview 输出测试和正式导入测试，证明 preview 不写数据库；
  • 缺字段、坏数字、重复标的、半写尾行、超限输入和错误脱敏测试；
  • README 接入命令或独立文档入口，并说明数据来源的时间、方向和币种口径。

不要把特定券商 SDK、凭据读取或订单接口塞进通用导入器。适配器的职责是把已有导出文件变成规范 position_snapshot，不是控制交易账户。

报告问题

普通缺陷请提供最小合成 JSONL、执行命令、预期与实际结果。安全问题不要创建公开议题，请遵循 SECURITY.md。