From 4a9751725f16d0dd41775f5b171111d06dc6ea73 Mon Sep 17 00:00:00 2001 From: Pigbibi Date: Fri, 9 Oct 2026 18:15:02 +0800 Subject: [PATCH] docs(b12): consumer adoption matrix; prefer semantics+display in tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Record remaining LongBridge/Firstrade production callers (out of scope). Keep runtime_plan facade; contracts test asserts modern≡legacy payloads. --- ...b06_execution_presentation_facade.zh-CN.md | 3 ++ docs/b12_consumer_adoption.zh-CN.md | 38 +++++++++++++++++ tests/test_strategy_contracts.py | 42 +++++++++++++++---- 3 files changed, 76 insertions(+), 7 deletions(-) create mode 100644 docs/b12_consumer_adoption.zh-CN.md diff --git a/docs/b06_execution_presentation_facade.zh-CN.md b/docs/b06_execution_presentation_facade.zh-CN.md index 9a48bdb8..9dabf2e2 100644 --- a/docs/b06_execution_presentation_facade.zh-CN.md +++ b/docs/b06_execution_presentation_facade.zh-CN.md @@ -24,3 +24,6 @@ ## 验证 `pytest tests/test_strategy_contracts.py tests/test_value_target_presentation_facade.py` + +## B12 +见 `docs/b12_consumer_adoption.zh-CN.md`（消费者采用矩阵；LB/Firstrade 剩余）。 diff --git a/docs/b12_consumer_adoption.zh-CN.md b/docs/b12_consumer_adoption.zh-CN.md new file mode 100644 index 00000000..a34a53f9 --- /dev/null +++ b/docs/b12_consumer_adoption.zh-CN.md @@ -0,0 +1,38 @@ +# B12：value-target 消费者采用矩阵（2026-10-09） + +依据：本地 clone `rg`（gh code search 本会话 rate-limit；Alpaca 等未 clone 仓标 incomplete）。 +策略：batch-upgrade-then-remove-compat；**保留** `build_value_target_runtime_plan` 与混合 `ValueTargetExecutionAnnotations` facade，直至剩余生产消费者清零。 + +## 1. 已迁到 `semantics` + `display` / execution API + +| 仓 | 路径 | 证据 | +| --- | --- | --- | +| CharlesSchwabPlatform | `decision_mapper.py` | [#501](https://github.com/QuantStrategyLab/CharlesSchwabPlatform/pull/501) → `build_value_target_execution_runtime_plan` + `ValueTargetPlanPresentation`；[#504](https://github.com/QuantStrategyLab/CharlesSchwabPlatform/pull/504) → `semantics=` + `display=`（pin QPK #655） | +| QuantPlatformKit | `tests/test_value_target_presentation_facade.py` + `tests/test_strategy_contracts.py` | #654/#655；本 PR 将 contracts 单测改为 modern 优先 + legacy 等价 | + +## 2. 无 `ValueTargetExecutionAnnotations` / `build_value_target_runtime_plan` 生产调用（本批本地） + +| 仓 | 说明 | +| --- | --- | +| InteractiveBrokersPlatform | `decision_mapper` 用 `translate_decision_to_target_mode`；annotations 为 dict metadata，非 ValueTarget 类型 | +| BinancePlatform | `decision_mapper` 无 value-target plan builder | +| QmtPlatform（本地） | 无上述符号 | +| UsEquityStrategies | 无上述符号（dashboard 走 diagnostics dict） | +| QuantRuntimeSettings | JS Worker；不消费该 Python API | + +## 3. 剩余生产消费者（**本侧不迁**） + +| 仓 | 符号 | 原因 | +| --- | --- | --- | +| LongBridgePlatform | `build_value_target_runtime_plan` + `ValueTargetExecutionAnnotations(...)` | LB-HK 禁区；归 quant | +| FirstradePlatform | 同上 | Firstrade Environment/ingress 禁区；归 quant | + +## 4. Facade 保留条件 + +- 新代码：`build_value_target_execution_runtime_plan(semantics=, display=, presentation=)` +- 旧代码：`build_value_target_runtime_plan` / `annotations=ValueTargetExecutionAnnotations(...)` +- **删除混合字段 / 撤 facade**：仅当 §3 清零且 B12 矩阵绿灯（N14） + +## 5. incomplete + +- gh `search/code` org 查询本会话 **0 / rate-limit**；未对 AlpacaPlatform / 未 clone 仓做全文确认。限流恢复后补扫：`org:QuantStrategyLab build_value_target_runtime_plan`。 diff --git a/tests/test_strategy_contracts.py b/tests/test_strategy_contracts.py index c17f5160..4e6ae821 100644 --- a/tests/test_strategy_contracts.py +++ b/tests/test_strategy_contracts.py @@ -21,6 +21,7 @@ ) from quant_platform_kit.common.execution_translation import ( ValueTargetPortfolioInputs, + build_value_target_execution_runtime_plan, build_value_target_portfolio_inputs_from_account_state, build_value_target_portfolio_inputs_from_snapshot, build_value_target_runtime_plan, @@ -29,6 +30,12 @@ translate_value_decision_to_weight_targets, translate_weight_decision_to_value_targets, ) +from quant_platform_kit.common.presentation import ( + ValueTargetDisplayAnnotations, + ValueTargetExecutionSemantics, + ValueTargetPlanPresentation, + split_value_target_annotation_parts, +) from quant_platform_kit.common.runtime_inputs import ( build_account_state_from_portfolio_snapshot, build_portfolio_snapshot_from_account_state, @@ -973,7 +980,25 @@ def test_build_value_target_runtime_plan_translates_decision_with_shared_helper( } ) - payload = build_value_target_runtime_plan( + semantics, display = split_value_target_annotation_parts(decision) + modern = build_value_target_execution_runtime_plan( + decision, + strategy_profile="soxl_soxx_trend_income", + portfolio_inputs=inputs, + semantics=semantics, + display=display, + presentation=ValueTargetPlanPresentation( + portfolio_rows_layout=("risk", "safe"), + execution_fields=( + "trade_threshold_value", + "signal_display", + "investable_cash", + ), + execution_defaults={"investable_cash": 12000.0}, + ), + ) + # Compat facade must remain behavior-equivalent (B12 keeps facade). + legacy = build_value_target_runtime_plan( decision, strategy_profile="soxl_soxx_trend_income", portfolio_inputs=inputs, @@ -986,9 +1011,12 @@ def test_build_value_target_runtime_plan_translates_decision_with_shared_helper( execution_defaults={"investable_cash": 12000.0}, ) - self.assertEqual(payload["allocation"]["target_mode"], "value") - self.assertEqual(payload["allocation"]["targets"]["SOXL"], 30000.0) - self.assertEqual(payload["portfolio"]["sellable_quantities"]["BOXX"], 5) - self.assertEqual(payload["execution"]["trade_threshold_value"], 250.0) - self.assertEqual(payload["execution"]["signal_display"], "risk-on") - self.assertEqual(payload["execution"]["investable_cash"], 12000.0) + self.assertEqual(modern, legacy) + self.assertEqual(modern["allocation"]["target_mode"], "value") + self.assertEqual(modern["allocation"]["targets"]["SOXL"], 30000.0) + self.assertEqual(modern["portfolio"]["sellable_quantities"]["BOXX"], 5) + self.assertEqual(modern["execution"]["trade_threshold_value"], 250.0) + self.assertEqual(modern["execution"]["signal_display"], "risk-on") + self.assertEqual(modern["execution"]["investable_cash"], 12000.0) + self.assertIsInstance(semantics, ValueTargetExecutionSemantics) + self.assertIsInstance(display, ValueTargetDisplayAnnotations)