trade-journal

# Trade Journal Analysis

## Purpose

Users upload broker exports (交割单) and get an honest, data-grounded portrait
of their own trading. Two layers are live:

- **Profile** — holding days, frequency, win rate, PnL ratio, cumulative PnL,
  max drawdown, top symbols, market/hourly distribution.
- **Behavior diagnostics** — 4 biases, each with severity (low/medium/high)
  and numeric evidence: disposition effect, overtrading, chasing momentum,
  anchoring.

Strategy extraction → backtest bridge lands in Phase 4c.

Supported formats (auto-detected):
- **同花顺** (Tonghuashun) — A-share CSV, typically GBK-encoded
- **东方财富** (Eastmoney) — A-share CSV, typically GBK-encoded
- **富途** (Futu) — HK/US CSV, UTF-8
- **Generic** — any CSV with columns like `datetime/symbol/side/qty/price`

## Usage

**Call the `analyze_trade_journal` tool directly. Never run Python from bash.**

```
analyze_trade_journal(file_path="uploads/xxx.csv")
analyze_trade_journal(file_path="uploads/xxx.csv", analysis_type="profile")
analyze_trade_journal(file_path="uploads/xxx.csv", filter_expr="2026-01 to 2026-03")
analyze_trade_journal(file_path="uploads/xxx.csv", filter_expr="symbol=600519.SH")
analyze_trade_journal(file_path="uploads/xxx.csv", filter_expr="market=china_a")
```

`analysis_type`:
- `full` (default) — profile + behavior (strategy still placeholder)
- `profile` — profile metrics only (fastest)
- `behavior` — 4 behavior diagnostics only
- `strategy` — Phase 4c placeholder

`filter_expr` (optional):
- Date range: `"YYYY-MM to YYYY-MM"` or `"YYYY-MM-DD to YYYY-MM-DD"`
- Symbol: `"symbol=600519.SH"` (exact match on qualified symbol)
- Market: `"market=china_a|us|hk|crypto"`

## Return shape (profile subset)

```json
{
  "status": "ok",
  "file": "xxx.csv",
  "format_detected": "tonghuashun",
  "total_records": 326,
  "date_range": "2026-01-06 ~ 2026-03-28",
  "symbols_count": 42,
  "market": "china_a",
  "profile": {
    "total_trades": 326,
    "total_roundtrips": 118,
    "avg_holding_days": 3.2,
    "trade_frequency_per_week": 4.1,
    "win_rate": 0.48,
    "profit_loss_ratio": 1.35,
    "total_pnl": 18240.55,
    "max_drawdown": -9820.10,
    "top_symbols": [{"symbol": "600519.SH", "trades": 14, "total_amount": 1.02e6}, ...],
    "market_distribution": {"china_a": 326},
    "hourly_distribution": {9: 52, 10: 84, ...},
    "roundtrips_sample": [{"symbol": "600519.SH", "buy_dt": "...", "sell_dt": "...", "pnl": 3400.1, "pnl_pct": 0.021, "hold_days": 2.5}, ...]
  }
}
```

Note: PnL uses FIFO lot matching; unmatched open positions are excluded from
win rate / PnL ratio (only closed round-trips count).

## Presenting results to the user

Produce a **single markdown report** in the user's language. Lead with the
top-line numbers, then section-by-section. Keep it dense — this is retail
readers skimming on a phone.

### Report template

```
## 你的交易画像 — {date_range}

**总体**
- 交易笔数：{total_trades}（完整来回 {total_roundtrips} 次）
- 平均持仓：{avg_holding_days} 天
- 交易频率：{trade_frequency_per_week} 次/周
- 胜率：{win_rate:.0%}
- 盈亏比：{profit_loss_ratio}
- 累计盈亏：{total_pnl}
- 最大回撤：{max_drawdown}

**最常交易的标的**（前 5 名）
| 标的 | 笔数 | 成交额 |
|------|------|--------|
| ... | ... | ... |

**市场分布**
{market_distribution}

**交易时段**
{hourly_distribution — highlight peak hours}

**一句话观察**
（根据数据写 1-2 句：过度交易？只做窄范围标的？集中在某时段？）
```

Guidance:
- If `win_rate < 0.4` AND `profit_loss_ratio < 1.0` → explicit warning: losing
  on both win rate and payoff. Ask whether they want behavior diagnostics
  (Phase 4b) or a cooling-off reality check.
- If `avg_holding_days < 1` AND `trade_frequency_per_week > 15` → flag
  intraday-heavy pattern, note that minute-level backtest would be better.
- If `symbols_count <= 3` → concentration risk; ask if they want a sector-
  diversification check.

## Follow-up dialogue

After the initial report, users typically ask:
- **Time-slice**: "3 月份表现怎么样" → re-call with `filter_expr="2026-03-01 to 2026-03-31"`.
- **Symbol deep-dive**: "茅台这只赚了多少" → `filter_expr="symbol=600519.SH"`.
- **Market split**: "港股和美股分开看" → two calls, `market=hk` and `market=us`.
- **Hypothetical** ("如果我严格止损 -5%") → Phase 4b feature; for now tell the
  user this is on the roadmap.

Do NOT re-upload — the file path is still valid for subsequent tool calls
in the same session.

## Error handling

- `File not found` / `Unsupported extension` — ask user to re-upload.
- `Unrecognized trade journal format` — share the detected columns back to
  the user and ask them to rename the key columns to: `datetime, symbol,
  side, quantity, price, amount, fee` (generic fallback).
- `No trade records parsed` — likely empty file or header-only; ask user to
  confirm the export contains actual fills.

## Behavior diagnostics (shape)

Under `result["behavior"]`:

```json
{
  "disposition_effect": {
    "severity": "high",
    "ratio_loss_to_win_hold": 1.69,
    "avg_winner_hold_days": 7.4,
    "avg_loser_hold_days": 12.5,
    "evidence": "Losing roundtrips held 12.5d vs winning 7.4d (ratio 1.69). Classic disposition pattern."
  },
  "overtrading": {
    "severity": "high",
    "busy_day_avg_pnl": -2632,
    "quiet_day_avg_pnl": 759,
    "evidence": "On busy days (≥3 trades) avg PnL -2632; on quiet days (≤1) avg PnL +759. High activity hurts returns."
  },
  "chasing_momentum": {
    "severity": "medium",
    "chase_ratio": 0.5,
    "buys_evaluated": 4,
    "evidence": "2/4 buys (50%) came after a >3% price run-up in the same symbol. Some chasing tendency."
  },
  "anchoring": {
    "severity": "high",
    "anchored_symbol_ratio": 0.83,
    "symbols_evaluated": 6,
    "anchored_symbols": [...],
    "evidence": "5/6 frequently-traded symbols stayed in a narrow price band (CV<5%). Strong anchoring."
  }
}
```

### Detection logic (for user-facing explanation)

| Bias | Metric | Medium | High |
|------|--------|--------|------|
| **Disposition effect** | avg_loser_hold / avg_winner_hold | ≥ 1.2 | ≥ 1.5 |
| **Overtrading** | (quiet − busy) / \|quiet\| day-PnL gap | ≥ 0.3 | ≥ 1.0 |
| **Chasing** |