Chan/docs/ECR/ECR-001-chan-web-restructure.md

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

• from ChanLun import ChanLun / from ChanEnum import ... 仍可用
• Golden：同一 fixture 下 bi/seg/zs/bsp 序列化结果与基线一致
• /api/analyze 关键字段集合兼容（契约冒烟）
• web/app.py 瘦身为 factory；业务在 services/api
• index.html 不再含大体量业务 inline JS
• ESS docs 齐全；TEST_REPORT / IMPLEMENTATION_REPORT / CHANGELOG
• 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