campaigns bidding strategies: TextCampaign search branch

[axisrow]

Parent: #346
Grandparent: #290

Scope

Patch-sized child issue for canonical typed CLI support for TextCampaign.BiddingStrategy.Search rows in direct campaigns add/update.

WSDL audit routing

• Current audit route: missing_followup under campaigns add/update: shared bidding-strategy builder foundation #290.
• Row count at split time: 253.
• Operations: campaigns.add/campaigns.update.
• Exact path prefixes: TextCampaign.BiddingStrategy.Search, TextCampaign.BiddingStrategy.Search.*.
• Strategy families in scope: WbMaximumClicks, WbMaximumConversionRate, AverageCpc, AverageCpa, PayForConversion, AverageRoi, AverageCrr, MaxProfit, AverageCpaMultipleGoals, PayForConversionMultipleGoals, WeeklyClickPackage, PlacementTypes.

CLI contract

• Typed flags only; no public --json or blob payload forwarding.
• Preserve canonical command shape: direct campaigns <add|update> [flags].
• Keep examples single-line if docs/help examples are added.
• Validate only documented local constraints unless official Yandex API docs require stricter behavior.

Acceptance criteria

• Focused dry-run tests prove the exact Yandex Direct payload shape for add and update where both operations are in scope.
• tests/test_wsdl_parity_gate.py routes this scope to this issue or marks the implemented rows supported.
• tests/WSDL_OPTIONAL_FIELD_AUDIT.md is regenerated consistently.
• Relevant CLI/help/docs tests pass.
• Official Yandex API docs are checked for field placement/types before implementation.

Out of scope

• TextCampaign.Network, DynamicTextCampaign, UnifiedCampaign, Smart/MobileApp/CPM branches.
• Live API write tests.
• Broad all-optional-fields parity outside this child issue.

[axisrow]

Implementation plan for #361 (TextCampaign.BiddingStrategy.Search only):

Scope:

• Parent campaigns bidding strategies: text/dynamic/unified search branches #346 / grandparent campaigns add/update: shared bidding-strategy builder foundation #290.
• Implement only TextCampaign.BiddingStrategy.Search for direct campaigns add/update.
• Keep TextCampaign.Network, DynamicTextCampaign, UnifiedCampaign, SmartCampaign, MobileAppCampaign, and CPM branches out of this PR.

CLI contract:

• Keep canonical direct campaigns <add|update> [typed flags]. No public --json.
• Existing --search-strategy selects TextCampaign.Search.BiddingStrategyType.
• Add typed Text search flags: --search-goal-id, --search-weekly-spend-limit, --search-bid-ceiling, --search-custom-period-spend-limit, --search-custom-period-start-date, --search-custom-period-end-date, --search-custom-period-auto-continue, --search-average-cpc, --search-average-cpa, --search-cpa, --search-clicks-per-week, --search-crr, --search-roi-coef, --search-reserve-return, --search-profitability, --search-exploration-minimum-budget, --search-exploration-custom, --search-placement-search-results, --search-placement-product-gallery, --search-placement-dynamic-places.
• Add update-only --search-budget-type.
• New money flags accept rubles and convert to API micro-ruble long values. Existing legacy add-only --average-cpa / --bid-ceiling remain accepted for current tests/backward compatibility, but the new audit route uses --search-* flags.

Wire shape:

• TextCampaign.BiddingStrategy.Search = { BiddingStrategyType, PlacementTypes?, ? }.
• Strategy enum to WSDL subtype: WB_MAXIMUM_CLICKS -> WbMaximumClicks; WB_MAXIMUM_CONVERSION_RATE -> WbMaximumConversionRate; AVERAGE_CPC -> AverageCpc; AVERAGE_CPA -> AverageCpa; PAY_FOR_CONVERSION -> PayForConversion; WEEKLY_CLICK_PACKAGE -> WeeklyClickPackage; AVERAGE_ROI -> AverageRoi; AVERAGE_CRR -> AverageCrr; PAY_FOR_CONVERSION_CRR -> PayForConversionCrr; AVERAGE_CPA_MULTIPLE_GOALS -> AverageCpaMultipleGoals; PAY_FOR_CONVERSION_MULTIPLE_GOALS -> PayForConversionMultipleGoals; MAX_PROFIT -> MaxProfit.
• CustomPeriodBudget requires all four custom-period flags; ExplorationBudget requires both minimum budget and custom YES/NO flag; BudgetType is update-only and follows the cached WSDL update shape.

Tests/audit:

• Add focused dry-run tests for representative add/update payloads, required-field failures, placement types, budget switching, and incompatible type guards.
• Update tests/test_wsdl_parity_gate.py so TextCampaign.Search rows are supported and TextCampaign.Network remains routed to campaigns add/update: shared bidding-strategy builder foundation #290.
• Regenerate tests/WSDL_OPTIONAL_FIELD_AUDIT.md via scripts/build_wsdl_optional_field_audit.py --write, then verify with --check.
• Run focused pytest plus the repo gate lane before PR.

Official docs checked:

• Yandex Direct Campaigns add/update TextCampaign parameter docs and cached campaigns WSDL are the contract sources for field placement and names.

[axisrow]

#361 is being split before continuing implementation.

Current child/PR map:

• campaigns bidding strategies: TextCampaign search base and placement types #380 / PR Add TextCampaign search placement flags #381: base TextCampaign.BiddingStrategy.Search container, BiddingStrategyType, and PlacementTypes flags only.
• Remaining TextCampaign Search strategy subtype fields stay out of PR Add TextCampaign search placement flags #381 and will continue in follow-up PR(s) from the scratch implementation.
• TextCampaign Network rows remain routed to campaigns bidding strategies: TextCampaign network branch #364.

The broad local implementation was kept only as scratch/reference; it is not being pushed as a single epic PR.

[axisrow]

План реализации (агент Claude Code)

Реализую типизированные CLI-флаги для всех 12 strategy families в TextCampaign.BiddingStrategy.Search (direct campaigns add/update), используя зарегистрированный в foundation builder через register_bidding_strategy_builder("TEXT_CAMPAIGN", "add"|"update", "search").

Strategy families (полный scope из issue)

WbMaximumClicks, WbMaximumConversionRate, AverageCpc, AverageCpa, PayForConversion, AverageRoi, AverageCrr, MaxProfit, AverageCpaMultipleGoals, PayForConversionMultipleGoals, WeeklyClickPackage, PayForConversionCrr (плюс HIGHEST_POSITION / IMPRESSIONS_BELOW_SEARCH / SERVING_OFF — без subtype block), плюс PlacementTypes.

Files

• direct_cli/_bidding_strategy.py — новый build_text_campaign_search_strategy(...), обогащающий build_text_campaign_search_base детальными flag-based subtype blocks; регистрация под branch="search" (existing "search_base" оставлен для backward-compat: новый builder продолжает строить контейнер BiddingStrategy.Search через base).
• direct_cli/commands/campaigns.py — добавляю флаги --text-search-* (12 шт.); переключаю TextCampaign-add/update на новый builder; расширяю валидаторы (поле принадлежит strategy, required-fields per minOccurs=1).
• tests/test_dry_run.py — отдельный focused dry-run на каждую strategy + негативные кейсы (silent data loss, missing required, conflicting flags).
• tests/test_wsdl_parity_gate.py — OPTIONAL_FIELD_CLI_OPTIONS для всех supported путей TextCampaign.BiddingStrategy.Search.<Subtype>.<Field>; перевод OPTIONAL_FIELD_CHILD_PREFIX_FOLLOWUPS[#361] строк в supported.

Новые CLI flags

• --text-search-weekly-spend-limit (RUBLES_TO_MICRO_RUBLES)
• --text-search-custom-period-spend-limit/-start-date/-end-date/-auto-continue (CustomPeriodBudget)
• --text-search-budget-type (WEEKLY_BUDGET|CUSTOM_PERIOD_BUDGET, update-only)
• --text-search-average-cpc (RUBLES, для AVERAGE_CPC / WEEKLY_CLICK_PACKAGE.AverageCpc)
• --text-search-pay-cpa (RUBLES, StrategyPayForConversionAdd.Cpa)
• --text-search-clicks-per-week (int, WEEKLY_CLICK_PACKAGE)
• --text-search-reserve-return (int %, AverageRoi)
• --text-search-roi-coef (long, AverageRoi)
• --text-search-profitability (long, AverageRoi)
• --text-search-exploration-min-budget (RUBLES, ExplorationBudget.MinimumExplorationBudget)
• --text-search-exploration-is-custom (YES/NO)
  Также расширяю scope существующих flags --goal-id, --average-cpa, --crr, --bid-ceiling на все новые strategy subtypes согласно WSDL.

Source-of-truth

• Локальный WSDL: tests/wsdl_cache/campaigns.xml — авторитетный (типы Strategy*Add 1363-1509, базы StrategyWeeklyBudgetAddBase 1333-1338, CustomPeriodBudget 1965-1972, ExplorationBudget 1973-1978, контейнер TextCampaignSearchStrategyAdd 1621-1630, container base TextCampaignStrategyAddBase 1581-1608).
• Yandex docs: https://yandex.com/dev/direct/doc/en/campaigns/get-text-campaign — структура TextCampaignSearchStrategy со всеми 12 subtypes; типы (long/int) и optional/required матчат WSDL (с поправкой: WSDL minOccurs=1 для Add — единый источник истины для required-валидации).

LoC estimate

~700-900 lines (флаги + builder + тесты + parity map). Если превысит 1000 — сабскоупим первые 6-8 families, остальные follow-up.

Acceptance check (mapping to issue criteria)

1. Focused dry-run tests prove the exact Yandex Direct payload shape for add and update → добавлены test_campaigns_<add|update>_text_search_<strategy>_payload для каждого из 12 subtypes.
2. tests/test_wsdl_parity_gate.py routes this scope to this issue or marks the implemented rows supported → добавлены явные OPTIONAL_FIELD_CLI_OPTIONS для каждого WSDL path TextCampaign.BiddingStrategy.Search.<Subtype>.<Field> → перейдут в supported.
3. tests/WSDL_OPTIONAL_FIELD_AUDIT.md is regenerated consistently → НЕ перегенерирую (per CLAUDE.md/instruction — handled by final consolidation PR); regenerate guard в parity gate подтвердит классификацию.
4. Relevant CLI/help/docs tests pass → запускаю test_dry_run, test_wsdl_parity_gate, test_cli, test_comprehensive после каждой правки.
5. Official Yandex API docs are checked for field placement/types → проверил https://yandex.com/dev/direct/doc/en/campaigns/get-text-campaign + локальный WSDL.