# ENGINEERING_SPEC — ECR-003

**Status:** Approved  
**Date:** 2026-08-06  

## Package

`chanlun/analysis/wyckoff/`：

- `engine.py` — `analyze_wyckoff(df) -> dict`
- `range.py` — 交易区间检测（ATR 容差震荡箱）
- `phases.py` — A–E 状态机
- `events.py` — Spring/SOS/LPS/UTAD（及 distribution 对称）
- `volume_profile.py` — 区间内分桶 VP
- `__init__.py` — 导出 `analyze_wyckoff`

## API

`GET /api/analyze?include_wyckoff=1` → `result["wyckoff"]`：

```json
{
  "trading_range": {"start_time","end_time","high","low","mid","active"},
  "bias": "accumulation|distribution|unknown",
  "phases": [{"phase","label","start_time","end_time"}],
  "events": [{"type","time","price","note","volume_ratio","volume_ok"}],
  "volume_profile": {"bins":[{"price","volume"}],"poc","vah","val","bin_count"},
  "volume_confirm": {"avg_volume","event_checks":{}}
}
```

默认 `include_wyckoff` 假：可不返回或返回 `null`（实现选：不返回键以减负）。

## Detection heuristics

1. ATR(14) 容差；扫描最近窗口找高低点接近的连续段作为 TR。
2. 阶段：价格在 TR 内相对位置 + 假破/真破时间序。
3. Spring：下破 TR.low 后收回且收盘回到区间内；量能相对均量判断。
4. SOS：收盘站上 TR.high 且放量。
5. LPS：SOS 后回踩不破 mid/high 带且缩量。
6. UTAD：上破后跌回区间内（派发）。
7. VP：typical=(H+L+C)/3，volume 加权分桶，VA≈70% 围绕 POC。

## Frontend

主站 checkbox + `chart_view` 传参；`chart_tv.js` 绘制。