# Engineering Spec: ECR-001 引擎 + Web 重构

## Related

| Doc | Link |
|-----|------|
| ECR | `docs/ECR/ECR-001-chan-web-restructure.md` |
| PRODUCT_SPEC | `docs/PRODUCT_SPEC/ECR-001-restructure.md` |
| ADR | `docs/ADR/ADR-001-package-layout.md` |

## Module Design

### `chanlun/core/*`

| 项 | 值 |
|----|-----|
| Responsibility | K 线单元、合并 K、笔/段/中枢/买卖点数据结构与枚举 |
| Can | 表达缠论基础对象 |
| Cannot | 拉行情、写 Flask 路由 |
| Layer | domain |

### `chanlun/pipeline/*`

| 项 | 值 |
|----|-----|
| Responsibility | `ChanLun` 编排、`TF_DF` 门面、builders |
| Can | 从 DataFrame 构建结构 |
| Cannot | 改公开方法语义 |
| Layer | application |

### `chanlun/indicators/*` / `chanlun/analysis/*`

| 项 | 值 |
|----|-----|
| Responsibility | MACD 状态、Zone/Classifier/Trend 等分析 |
| Layer | domain / application |

### Root shims (`ChanLun.py`, `ChanEnum.py`, …)

| 项 | 值 |
|----|-----|
| Responsibility | 转发到 `chanlun.*`，兼容 strategies |
| Cannot | 含业务逻辑 |

### `web/config.py` + `web/services/*` + `web/api/*`

| 项 | 值 |
|----|-----|
| Responsibility | 配置、行情、分析、序列化、HTTP |
| Cannot | 修改缠论算法 |

### `web/static/js/app/*`

| 项 | 值 |
|----|-----|
| Responsibility | 图表、overlay、UI、API 客户端 |
| Cannot | 本轮引入 React 构建 |

## Interfaces

```python
class TF_DF:
    # 公开方法签名保持与重构前一致
    def get_kl_data(self, dataframe): ...
    def get_bi_list(self, dataframe): ...
    # ... 门面委托 builders

class ChanLun:
    def init_dataframes(...): ...
```

`/api/analyze`：查询参数与 JSON 顶层字段兼容。

## Algorithm Sketch

1. 物理迁移模块到 `chanlun/`，修正 import
2. 根 shim 再导出
3. `TF_DF` 方法体迁移到 builders，门面调用
4. Web 按职责拆文件，路由注册不变
5. HTML 抽 JS；未接线 TS 入 `_unused`

## Error Handling

| Case | Behavior |
|------|----------|
| 行情失败 | 保持现有 JSON error |
| 分析异常 | 保持现有日志与错误返回 |

## Config / Constants

| Name | Source |
|------|--------|
| DATA_SERVICE_URL | env / config |
| HTTP(S)_PROXY | env / config（替代硬编码 7897） |
| MACD periods | config |

## Test Plan Pointer

- `tests/test_golden_pipeline.py` + `tests/fixtures/golden_*`
- `web/tests/` analyze 契约冒烟
- `python -c "from ChanLun import ChanLun"`

## Migration / API Impact

无破坏性 API 变更；仅内部路径变化。