全系统 Key 配对维度升级 — 缺陷与不足分析

结论概览

核心改造（strategy / position_manager / trade_repository / protocols / orchestrator）已正确按 PairKey = (symbol, base_symbol) 落地，历史 z4h 灌入、退场/平仓、sync、cleanup 等均已按配对维度传递。仍存在 1 处明确缺陷（风控重复仓位检查）、2 处语义/边界问题（服务层持仓判断、孤儿恢复），以及若干可改进点。

1. 明确缺陷：风控重复仓位检查未按配对维度

位置：src/trading/risk_manager.py 第 72–75 行

现状：在 allow_duplicate_position=False 时，仅用 pos.symbol == signal.symbol 判断“重复仓位”，因此同一 symbol 只允许一个仓位。与本次升级的“按配对隔离”语义不一致。

影响：当同一 symbol 对多个 base 交易时（如 PURR/HYPE 与 PURR/BTC），第二个配对的开仓请求会被风控错误拒绝（“已有 PURR 的活跃仓位”），即便 PM 与策略层已支持多配对并存。

设计文档依据：设计文档第 8 节明确要求：“若存在按 pos.symbol == signal.symbol 的判断，改为同时比较 base_symbol”。

建议修改：将“重复仓位”定义为同一配对的重复，即同时比较 symbol 与 base_symbol：

# 当前
if pos.symbol == signal.symbol:
    return False, f"已有 {signal.symbol} 的活跃仓位: ..."

# 建议
key_signal = (signal.symbol, signal.base_symbol or "")
if (pos.symbol, pos.base_symbol or "") == key_signal:
    return False, f"已有 {signal.symbol}|{signal.base_symbol or ''} 的活跃仓位: ..."

这样在关闭“允许重复仓位”时，仍可禁止同一配对的重复开仓，但允许同一 symbol 下不同 base 各一个仓位。

2. 语义/边界问题

2.1 服务层 _has_open_position(symbol) 仅按 symbol 维度

位置：src/services/realtime_kline_service_base.py 第 1547 行及调用处（黑名单豁免、Gate 未通过时 exit_only 分支等）。

现状：
_has_open_position(symbol: str) 只判断“该 symbol 是否有任意持仓”，不区分 base。

设计文档：第 6 节建议 _has_open_position(symbol, base_symbol=None)，若传入 base_symbol 则按配对查。

影响分析：

• 黑名单豁免：当前语义是“只要该 symbol 有任意持仓就不拉黑”。比“仅对 (symbol, base_symbol) 有仓的配对豁免”更保守，对风控更安全，可保留。
• Gate 未通过但有持仓（约 1521 行）：当前是“该 symbol 有任意持仓 → 对该 pair 做 exit_only 分析”。若 PURR/HYPE 有仓而 PURR/BTC 无仓，对 PURR/BTC 也会走 exit_only，可能多做一次退场检查；若业务希望“仅对本配对有仓时再做 exit_only”，则这里应按配对查。

建议：

• 短期：在文档中明确当前语义（symbol 维度“任意持仓”），并说明黑名单与 Gate 的取舍。
• 可选增强：实现 _has_open_position(symbol, base_symbol=None)，base_symbol is None 时保持现有“任意持仓”语义，传入时按 (symbol, base_symbol) 查；在 Gate 未通过分支改为传入当前 base_symbol，实现“仅本配对有仓才 exit_only”。

2.2 孤儿恢复 _restore_orphans_from_db 在多 base 下可能匹配错误

位置：src/trading/position_manager.py 第 1023–1055 行。

现状：
用 get_positions_by_symbols(symbols) 按 symbol 拉取 DB 仓位得到 dict[PairKey, dict]，再对每个候选 symbol 用：

db_row = next((v for (sym, _), v in db_positions_map.items() if sym == symbol), None)

当同一 symbol 在 DB 中有多条（不同 base）时，会取第一个匹配的 row，可能与交易所孤儿实际对应的 base 不一致。

影响：

• 单 base 或 single 模式：无影响。
• 多 base：例如 DB 中有 PURR/HYPE 与 PURR/BTC，交易所孤儿仅为“PURR”一侧时，可能错误地用 PURR/HYPE 的 DB 记录恢复，导致 base 腿不一致、对账/风控偏差。

建议：

• 若交易所接口能提供 pair 信息（symbol + base_symbol），应改为按 (symbol, base_symbol) 精确匹配再恢复。
• 若当前无法获得 base：在文档中注明“多 base 场景下，仅按 symbol 恢复的孤儿可能与 DB 中某一条 base 随机对应，建议以单 base 或配对明确的场景使用”；或限制为仅对 single 模式做 DB 恢复，pair 模式仅依赖 _adopt_paired_orphans。

3. 可改进点（非缺陷）

3.1 统一 pair_key 辅助函数

设计文档：第 1 节建议在 models.py 或 utils 中提供 pair_key(symbol, base_symbol) -> (symbol, base_symbol or "")。
现状：仅在 position_manager 中有 _pair_key(pos: PairPosition)，其余地方多处内联 (symbol, base_symbol or "")。
建议：在 src/trading/models.py 中增加模块级函数，例如：

def pair_key(symbol: str, base_symbol: str | None) -> PairKey:
    return (symbol, base_symbol or "")

并在 strategy、orchestrator、position_manager 等处逐步改为调用该函数，减少重复与拼写错误。

3.2 仓储接口命名与入参

现状：get_positions_by_symbols(symbols: list[str]) 返回 dict[PairKey, dict]，名称仍为“by_symbols”，入参为 symbol 列表。
建议：若后续需要“按配对列表查询”，可新增 get_positions_by_pairs(pairs: list[PairKey]) 或保留现接口并在 docstring 中明确“按 symbol 列表查询，返回所有匹配的配对维度结果”。当前调用方（如孤儿恢复）仅需按 symbol 查，无需强制改名。

3.3 测试与文档

• 测试：实施报告未提及配对维度的单测/集成测试。建议补充：
  • 同一 symbol 多 base（如 PURR/HYPE、PURR/BTC）下，基线与仓位互不覆盖；
  • 平仓、止损、sync、cleanup 仅影响对应配对；
  • 风控在“不允许重复仓位”下允许不同 base、拒绝同一配对重复开仓。
• 文档：在实施报告或运维文档中补充：
  • “多 base 下孤儿恢复”的已知限制；
  • 服务层 _has_open_position 当前为 symbol 维度的说明及可选增强方式。

4. 已确认无误的部分

• 策略层：9 个字典/集合均为 PairKey；process_tick / prime_buffer / sync_position / on_position_opened / cleanup_pair / cleanup_symbol 等均已按配对传参；信号去重 key 含 base_symbol。
• 仓位管理层：_positions、_opening_pairs 为 PairKey；开仓/平仓/恢复/sync_with_exchange/孤儿收纳均按 pair。
• 仓储层：get_positions_by_symbols 返回 dict[PairKey, dict]；get_known_pair_relations 返回 list[PairKey]。
• 编排器：历史 z4h 按 (symbol, base_symbol) 查询并灌入；退场/平仓/策略回调均传 base_symbol。
• 数据库与表结构：pair_positions、analysis_results 已有 symbol/base_symbol，无需迁移；灌 buffer 的 SQL 已按配对过滤。

5. 建议实施优先级

6. 架构与数据流确认（简要）

flowchart LR
  subgraph inputs [输入]
    Kline[K线/分析]
    DB[DB 仓位/分析结果]
  end
  subgraph core [核心状态均按 PairKey]
    S[Strategy 基线/仓位/冷却]
    PM[PositionManager 仓位/开平]
    Repo[TradeRepo 查询返回 PairKey]
  end
  subgraph risk [待修复]
    RM[RiskManager 重复检查]
  end
  Kline --> S
  DB --> Repo
  Repo --> PM
  S --> PM
  PM --> RM
  RM -->|"当前仅 symbol"| PM

当前除风控重复检查外，从分析结果 → 策略 → 仓位管理 → 仓储的 key 已统一为配对维度；修复 risk_manager 后，整条链路在“同一 symbol 多 base”场景下行为与设计一致。