chinese-equity-quant/plugins/joinquant/README.md

JoinQuant Comparison Plugin

This plugin exports frozen targets from the internal A-share research pipeline, drives a standalone JoinQuant wrapper strategy, ingests JoinQuant output files, and reconciles them against the internal reference simulator.

The plugin validates system mechanics, not alpha quality:

• date alignment
• symbol mapping
• target position generation
• open execution timing
• lot rounding and filled shares
• position carry
• trading cost and PnL accounting
• blocked trades from suspension and price limits

Commands

uv run python cli.py joinquant export-targets \
  --positions-path portfolio/run1.pq \
  --portfolio-name run1 \
  --mode target_shares \
  --execution-calendar-path data/daily_bars/csi500 \
  --start-date 2026-07-01 \
  --end-date 2026-07-31 \
  --out-dir plugins_output/joinquant/targets

uv run python cli.py joinquant write-wrapper \
  --portfolio-name run1 \
  --mode target_shares \
  --out-path plugins_output/joinquant/wrapper_strategy_run1.py

uv run python cli.py joinquant ingest \
  --portfolio-name run1 \
  --fills-csv path/to/jq_fills.csv \
  --positions-csv path/to/jq_positions.csv \
  --pnl-csv path/to/jq_pnl.csv \
  --out-dir plugins_output/joinquant/ingested

uv run python cli.py joinquant reconcile \
  --portfolio-name run1 \
  --targets-dir plugins_output/joinquant/targets/run1 \
  --our-fills-path fills/run1.pq \
  --our-positions-path portfolio/run1.pq \
  --our-pnl-path pnl/run1.pq \
  --jq-fills-path plugins_output/joinquant/ingested/run1/fills.pq \
  --jq-positions-path plugins_output/joinquant/ingested/run1/positions.pq \
  --jq-pnl-path plugins_output/joinquant/ingested/run1/pnl.pq \
  --out-dir plugins_output/joinquant/reconcile

target_shares is the default and uses the built integer position_shares from portfolio build, matching what the internal simulator executes. For strict simulator-vs-JoinQuant comparison, pass --execution-calendar-path so position dates are shifted to the next session open, matching the internal simulator's next-open convention.