feat(ccpm): 中金所成交持仓排名采集——CLI/API/WebUI 三端 + 新手科普

- 新增 easy_tdx.ccpm 模块（独立数据源，标准库 urllib 零依赖）：
  官网 /sj/ccpm/{YYYYMM}/{DD}/{品种}.xml，交易日约 16:15 发布，
  单文件含全部合约 × 三类排名（datatypeid 0=成交量/1=持买单/2=持卖单）× 前 20 名会员
- 协议要点：?id= 为 0~99 随机防缓存参数可省略；非交易日 302→error_404，
  禁用 urllib 自动重定向并翻译为 CcpmNoDataError（区别于网络错误 CcpmError）；
  仅 http 可用；历史可回溯至 2012 年
- 8 品种：IF/IH/IC/IM 股指 + TS/TF/T/TL 国债；latest_rank() 自动回溯最近交易日；
  按日不可变 → ~/.easy_tdx/cache/ccpm/ 落盘缓存，历史二次查询零网络
- CLI：easy-tdx ccpm IF [--date] [--table] [--refresh] [--no-cache]，all=全品种
- API：GET /ccpm/products（品种科普元数据）+ GET /ccpm/rank?product&date
  （404=非交易日/未发布，refresh 强制重抓）
- WebUI「期货持仓排名」页（行情组）：品种下拉+日期+自动回溯开关+一键采集，
  合约页签自动标注主力，前 20 合计多/空/净持仓概览，三组排名并排表格
- 三段新手科普：「这是什么数据」「品种一览」「多单空单加减仓怎么看」
  （强调排名看不出套保还是投机，空单多 ≠ 看空市场）
- 测试 20 例（mock HTTP 零网络）：解析/缓存/302 语义/回溯/路由/CLI

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 本文件记录 easy-tdx 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/)。
 
+## [1.29.1] — 2026-09-02
+
+**中金所成交持仓排名采集（ccpm，独立数据源）**——散户能免费看到的**最接近"主力动向"的公开数据**：每个交易日收盘后约 16:15，中金所官网公布各期货品种「成交量 / 持买单量（多单）/ 持卖单量（空单）」各前 20 名期货公司会员排名。新增 `easy_tdx.ccpm` 模块并三端接入（CLI / Web API / WebUI），零第三方依赖（标准库 urllib）。
+
+### 新增
+
+- **核心模块 `easy_tdx.ccpm`**——抓取官网 `/sj/ccpm/{YYYYMM}/{DD}/{品种}.xml`（单文件含该品种全部合约 × 三类排名 × 各前 20 名会员）。协议逆向要点：官网 JS 的 `?id=` 仅为 0~99 随机防缓存参数可省略；非交易日返回 302→error_404，禁用 urllib 自动重定向并把 302/404 识别为「无数据」（`CcpmNoDataError`，区别于网络错误 `CcpmError`）；仅 http 可用（https 握手失败）；历史可回溯至 2012 年。`CcpmClient.get_rank()` 指定日期抓取、`latest_rank()` 自动回溯最近交易日（缺省最多回溯 15 天，覆盖春节长假）；每个交易日数据发布后不可变 → 按日落盘缓存 `~/.easy_tdx/cache/ccpm/{YYYYMMDD}/{品种}.json`（随 `EASY_TDX_CONFIG_DIR`），历史二次查询零网络，`refresh=True` 强制重抓。
+- **品种覆盖 8 个**：IF 沪深300 / IH 上证50 / IC 中证500 / IM 中证1000 股指期货 + TS/TF/T/TL 2/5/10/30 年期国债期货；品种元数据（标的 / 合约规模 / 一句话科普）集中在 `ccpm/models.py`，三端共用同一份文案。
+- **CLI `easy-tdx ccpm`**——`easy-tdx ccpm IF [--date YYYY-MM-DD] [--table] [--refresh] [--no-cache]`，品种参数支持 `all` 一次抓全部 8 个品种（实测 460 行）；`--table` 自动切换中文表头（JSON/CSV 保持英文机器友好列名）。
+- **Web API**——`GET /api/v1/ccpm/products`（品种科普元数据）+ `GET /api/v1/ccpm/rank?product=IF&date=2026-09-02`（`date` 缺省自动回溯；404=该日期非交易日或数据未发布，文案说明 16:15 发布时间；`refresh` 参数强制重抓）。
+- **WebUI「期货持仓排名」页**（行情组导航）——品种下拉（带中文名）+ 日期选择器 + 「自动取最近交易日」回溯开关 + 一键采集按钮；合约页签自动标注**主力**（=当日合计成交量最大的合约）；前 20 名合计概览 chips（多单/空单/净持仓·多−空/当日成交，红涨绿跌）；三组排名并排表格（与官网 CSV 同构），底部合计行；手动选非交易日给友好错误并可一键切回自动回溯。
+- **三段新手科普折叠帮助**（面向小白用户）：①「这是什么数据」——"(代客)"=期货公司经纪客户合计而非自营、只统计前 20 名（约占全市场六到八成）、「增减」=加仓/减仓语义；②「品种一览」——IF/IH/IC/IM 各跟踪哪个指数、国债期货=利率期货（价格与市场利率反向，期限越长越敏感）；③「多单、空单、加减仓怎么看」——多单=看涨或锁成本、空单=看跌**或**套保对冲，重点强调**排名表看不出套保还是投机，空单多 ≠ 看空市场**（股指期货空单大头常是机构套保盘），净持仓只是情绪参考，期货是零和合约全市场多空永远相等；另附页面级风险提示（期货带杠杆，亏损可超本金）。
+- **CLI/Web 测试 20 例**（`tests/unit/test_ccpm.py`，mock HTTP 零网络）：XML 长表→宽表对齐、缺单元格容错、302→无数据翻译、按日缓存命中/强制刷新、latest_rank 回溯与耗尽、品种元数据完整性、路由 200/404/422、CliRunner 三例。
+
 ## [1.29.0] — 2026-09-02
 
 **借鉴社区 Fork（[swimmingaaron/easy_tdx](https://github.com/swimmingaaron/easy_tdx)）的六项实用特性**——该 Fork 自 v1.20.12 分叉后独立演化出一批好想法，本轮逐项甄别后移植其精华（剥离其单文件前端/平行后端层/硬编码个人路径等不可维护部分）：ZIG 策略、交易时段感知刷新、120 分钟 K 线、逐 bar 衍生字段、159 只核心龙头池、多 Provider LLM 直连。
@@ -17,6 +31,7 @@
 - **AI 解读历史 + 龙头池页面（Web UI 导航新增「AI 解读历史」「龙头池」）**——每次成功的「直接解读」自动归档到 `~/.easy_tdx/llm_history.db`（SQLite，`llm_history_store`）：提问 Prompt、解读正文、模型/耗时与当时的策略上下文（策略/参数/标的/周期/日期区间）。历史页按时间倒序展开查看，每条带「→ 去回测（带参数）」一键跳回回测页复现场景（复用寻优页的 query 预填链路）、查看提问 Prompt、删除/清空；API 为 `GET/DELETE /llm/history`。「龙头池」页展示 159 只核心龙头（搜索过滤 + 点击进个股详情，即 `universe=core` 同一名单）。另为前端路由表加兜底重定向：未注册路径（如把 API 路径当页面访问）回看板而非渲染空白。
 - **多 Provider LLM 直连 + WebUI「AI 设置」页**——新增 `easy_tdx.ai` 模块与 `/llm/*` 路由。Provider 预设 9 家：DeepSeek / 通义千问 / 智谱 GLM（bigmodel.cn）/ Kimi / MiniMax / OpenAI / Claude（Anthropic 原生协议）/ Ollama（本地免 Key）/ 自定义（任意 OpenAI 兼容网关），base_url 与模型均可覆盖。配置落盘 `~/.easy_tdx/llm.json`（随 `EASY_TDX_CONFIG_DIR`），WebUI 表单与手工编辑同一份文件、双向兼容；字段级优先级 = 文件 > 环境变量（`LLM_PROVIDER`/`LLM_API_KEY`/`LLM_BASE_URL`/`LLM_MODEL`）> 预设默认。API：GET/PUT `/llm/config`（key 脱敏回显，回传脱敏串不覆盖真 key）、POST `/llm/test`（连通性+延迟）、POST `/llm/chat`。回测页「🤖 AI 解读」在模型已配置时新增「✨ 直接解读」——把组装好的报告 Prompt 提交为**后台任务**（接入与回测同一套 `task_runner`：4 线程池 + SQLite 持久化），前端短轮询 `GET /llm/chat/tasks/{task_id}` 取结果（`POST /llm/chat/async`，202），长耗时模型调用不占 HTTP 连接、断线重连后仍可查询，按钮实时显示已耗时；配置不完整在提交期即报 400，网络/鉴权/超时错误体现在任务态 `error`（读超时文案给出「调大超时」动作，默认超时 180s 可调至 600s）。未配置模型时保持导出 Prompt 手动路径。**思考型模型空白正文防御**（实测：GLM-5.x 的 `reasoning_content` 思考链计入 max_tokens，4000 预算被整份报告的思考耗尽后 `content` 为空白——truthy 但渲染为空，状态条报成功而正文空白）：解析层对空白正文显式拦截——有思考链时报「调大 Max Tokens」的可操作错误（含当前值与 finish_reason），无思考链按格式错误上报，绝不返回空串；max_tokens 默认 4000→16000（上限即目标，按实际生成计费），前端再拦一道纯空白。零第三方依赖（标准库 urllib + `asyncio.to_thread`）。
 
+
 ### 测试
 
 - 新增 6 个单测文件共 51 例：`test_mytt_zig.py`（ZIG 边界/单调/V 型/锯齿/阈值双写法）、`test_zig_strategy.py`（注册/参数校验/引擎成交/独立文件加载/预设网格）、`test_realtime_session.py`（窗口边界/午休/周末/session_info）、`test_bars_min120_derived.py`（重采样聚合/裁剪/缺列、衍生字段/兜底）、`test_screen_universe_core.py`（名单 159 只唯一性/已知龙头/core 过滤准确性）、`test_ai_llm.py`（配置文件↔环境变量优先级/脱敏/双协议请求组装/HTTP 错误包装，HTTP 层 monkeypatch 零真实网络）。