A_Share_DP/CLAUDE.md

CLAUDE.md — A-Share Data Platform (Trading OS)

Project Overview

A-share trading operating system built on Parquet + DuckDB with REST/WebSocket APIs. Architecture follows a 5-subsystem design: Data Platform → Market Intelligence → Signal Intelligence → Execution Intelligence → Presentation. Dashboard at /dashboard renders a Trading Command Center.

Tech Stack

• Data: akshare (East Money / Sina), Parquet (Zstd), DuckDB (analytics)
• API: FastAPI + uvicorn, single /api/v1/dashboard/state endpoint + K-line/stock/calendar REST
• CLI: Typer (ashare-dp backfill daily|minute|industry|signals ...)
• Scheduler: APScheduler (EOD 15:05, EMA52 15:10)
• Config: pydantic-settings (.env)

Project Structure (v10 — 5 Subsystems)

src/ashare_dp/
├── config.py           # Settings
├── core/               # Shared kernel
│   ├── models.py       # Freq enum, INDEX_CODES, INDEX_SINA_SYMBOLS
│   ├── codes.py        # ★ Single ts_code conversion module (IDEMPOTENT)
│   ├── calendar.py     # Trading calendar, market state, Beijing TZ
│   └── exceptions.py
├── domain/             # Ontology — shared contracts
│   ├── state.py        # MarketState (7-dim continuous vector)
│   ├── context.py      # TradingContext, Playbook, Expectancy, Opportunity
│   ├── events.py       # RiskEvent
│   ├── features.py     # FeatureDefinition
│   ├── leadership.py   # LeaderState enum
│   └── signal.py       # SignalType, SignalInstance
├── data/               # ═══ DATA PLATFORM ═══
│   ├── sources/        # akshare_client, index, industry
│   ├── pipelines/      # backfill, eod, realtime
│   └── store/          # database (get_db, analytics_conn, kline_glob), repository, partitioning, schema
├── features/           # Feature Store (6 registered features, all use analytics_conn + kline_glob)
├── market/             # ═══ MARKET INTELLIGENCE ═══
│   ├── state.py        # infer_market_state
│   ├── leadership.py   # assess_leaders (lifecycle per industry)
│   ├── opportunity.py  # rank_opportunities
│   ├── flow.py         # compute_flow (money flow graph)
│   ├── sentiment.py    # Phase 2 placeholder
│   └── memory.py       # StateStore (state_snapshot table)
├── signals/            # ═══ SIGNAL INTELLIGENCE ═══ (the moat)
│   ├── detectors.py    # EMA52 cross detection + shared screening logic
│   ├── store.py        # signal_instance CRUD (to be extracted from detectors)
│   └── expectancy.py   # get_expectancy(state) — single entry, fallback chain internal
├── execution/          # ═══ EXECUTION INTELLIGENCE ═══
│   ├── playbook.py     # build_playbook (State → strategies/bias/holding)
│   ├── risk.py         # RiskRule engine + evaluate_risks
│   └── brief.py        # build_brief + brief_to_api_dict (single serialization point)
└── apps/               # ═══ PRESENTATION ═══
    ├── api/            # app.py, routers/, websocket/, dashboard/
    ├── cli/            # main.py + backfill/serve/query/eod/screening commands
    └── scheduler/      # scheduler.py, jobs.py

Key Conventions

ts_code conversion (CRITICAL)

Always use from ashare_dp.core.codes import to_ts_code — the single idempotent implementation. Never write local _code_to_ts_code() copies. to_ts_code() is safe to call on any format: bare codes, already-formatted ts_codes, Sina symbols, even legacy corrupted .SZ.SZ values.

Database connections

• DuckDB tables (stock_info, trading_calendar, signal_instance): use get_db() context manager from data.store.database
• Analytics queries (features, engines): use analytics_conn() for raw DuckDB connection — the single sanctioned way. Never hardcode "data/duckdb/ashare.db"
• Parquet globs: use kline_glob() or partition_glob(freq) — never hardcode paths

Architecture boundaries

• data/ knows nothing about trading
• features/ computes features, never classifies regimes
• market/ infers state, knows nothing about signals
• signals/ queries historical expectancy, knows nothing about execution
• execution/ maps state to strategies, assembles TradingBrief
• apps/ only renders, never reasons

MarketState is a continuous vector (not enum)

7 dimensions: trend, fear, liquidity, rotation, participation, volatility, breadth. Each 0.0–1.0. Display labels derived downstream only.

API Response

Single endpoint produces all dashboard data: GET /api/v1/dashboard/state. Response versioned ("version": "1.0"). Serialization in execution/brief.py::brief_to_api_dict() — the single serialization point. Router only orchestrates engine calls.

Running

pip install -e ".[dev]"
ashare-dp backfill init        # Schema + stock list + trading calendar
ashare-dp backfill daily       # Daily/weekly/monthly + indices
ashare-dp backfill industry    # Industry classifications
ashare-dp backfill signals     # EMA52 signal detection + store
ashare-dp serve start          # API + scheduler + realtime
open http://localhost:8000/dashboard