# ECR-001

**Title:** 缠论引擎包化 + Web 分层重构（行为冻结）  
**Status:** Approved  
**Date:** 2026-08-05  
**Change Level:** L3  

## Change

将根目录扁平 `Chan*.py` / `TF_DF.py` 包化为 `chanlun/`，拆分 `web/app.py` 与巨型 `index.html` inline JS；算法与 `/api/analyze` 契约冻结；`config/` / `strategies/` 不动。

## Motivation

根目录与 Web 单体过大、职责混杂，难以维护与测试；需在不影响 Freqtrade 策略导入的前提下重整结构。

## Scope

### Allowed

- 创建 `chanlun/`（core / pipeline / indicators / analysis）与根目录兼容 shim
- 拆分 `TF_DF` 为 builders + 门面（公开方法签名不变）
- Web：`config` + `services` + `api` blueprints；配置外置（proxy / DATA_SERVICE）
- 前端：`index.html` 业务 JS 外置到 `static/js/app/`；隔离未接线 TS/TSX
- 示例与笔记迁入 `examples/` / `docs/notes/`
- Golden / 契约回归测试

### Forbidden

- 修改笔 / 线段 / 中枢 / 买卖点算法语义
- 破坏 `/api/analyze` JSON 字段（可增不可删）
- 修改 `config/`；修改 `strategies/` 交易逻辑或参数（import/`sys.path` 迁移除外，见 CODE_REVIEW）
- 引入 Vite/React/TS 构建
- 重做 UI 视觉或更换 TradingView

## Risk

| Risk | Mitigation |
|------|------------|
| 策略 import 断裂 | 根 shim + 冒烟导入 |
| 拆文件改算法 | 仅搬移；golden fixture |
| 前端事件遗漏 | 按块抽取 + 手工/冒烟 |
| API 字段漂移 | analyze 契约测试 |

## Acceptance Criteria

- [x] `from ChanLun import ChanLun` / `from ChanEnum import ...` 仍可用
- [x] Golden：同一 fixture 下 bi/seg/zs/bsp 序列化结果与基线一致
- [x] `/api/analyze` 关键字段集合兼容（契约冒烟）
- [x] `web/app.py` 瘦身为 factory；业务在 services/api
- [x] `index.html` 不再含大体量业务 inline JS
- [x] ESS docs 齐全；TEST_REPORT / IMPLEMENTATION_REPORT / CHANGELOG
- [x] `config/` 无内容变更；`strategies/` 仅允许 import/`sys.path` 迁移（Human 增补，无交易逻辑变更）

**Status:** Done (Released as `v1.0.0`)

## Rollback

单分支 / 单 PR 回滚；shim 期可整体 `git revert`。

## Risk Review

- Path: `docs/RISK_REVIEW/ECR-001.md` — N/A（不改交易语义）

## Linked

- PRD / PRODUCT_SPEC: `docs/PRODUCT_SPEC/ECR-001-restructure.md`
- ENGINEERING_SPEC: `docs/ENGINEERING_SPEC/ECR-001-restructure.md`
- ADR: `docs/ADR/ADR-001-package-layout.md`
- EXPERIMENT: N/A
- TRACEABILITY: Yes