@bluevs/vhcli 0.5.9 → 0.5.10

package/skill/docs/tiktok.md

@@ -1,749 +0,0 @@
-# TikTok 广告创编模块 (tiktok)
-
-项目级 TikTok 广告创编流水线，使用 `--project-id`（`po_xxx`）+ api-key 鉴权，与 `vhcli media tiktok`（基于 `--auth-id`）不是同一条链路。
-
-覆盖：创编任务提交/查询、表单下拉元数据、兴趣定向树、优化事件、`dark_post_status` 校验、Spark Ads 帖子批量授权。
-
----
-
-## 1. 架构总览
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  Agent / 用户                                                        │
-└────────────────────────────┬────────────────────────────────────────┘
-                             │ vhcli tiktok ...
-                             ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  vhcli (本仓 vision_hub_cli)                                         │
-│  - cmd/vhcli/tiktok_creative.go      （cobra 子命令）                 │
-│  - internal/client/tiktok_creative.go（HTTP 客户端）                  │
-│  - internal/types/tiktok_creative.go （请求/响应类型）                │
-└────────────────────────────┬────────────────────────────────────────┘
-                             │ HTTPS  /open_api/v2/tiktok/*
-                             │ Header: Authorization: Bearer vhk_xxx
-                             ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  vision_hub OpenAPI                                                  │
-│  - api/open_api/v1/open_api.proto                                    │
-│  - internal/service/http/open_api/open_api_ads_creative.go           │
-│    (反查 po_xxx → int32 customer_project_id 后委托给 biz)            │
-└────────────────────────────┬────────────────────────────────────────┘
-                             ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  vision_hub biz: AdsCreativeCase                                     │
-│  - 元数据查询：直接代理 TikTok Marketing API + Redis 缓存            │
-│  - 提交：幂等(SetNX 10min) + 落 4 张表 + 起 VHM 调度任务              │
-└────────────────────────────┬────────────────────────────────────────┘
-                             ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  Docker 镜像 ads-creative-tiktok-dev (独立仓)                         │
-│  真正调 TikTok Marketing API 创建 campaign/adgroup/ad、上传素材      │
-│  执行结果回写 ads_tiktok_creative.task_status / fail_reason          │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**关键点**：
-
-- vhcli 提交 ≠ 立即创建广告。`submit` 只是"落库 + 入队"，TikTok 那边是否真的创建成功，需要后续 `task list` 轮询 `task_status`。
-- 元数据查询（语言/地域/账号 等）走 vision_hub 服务端 Redis 缓存（list 30min，token 5min），不会每次都打 TikTok。
-- 同一个 `request_id` **10 分钟**内重复 submit 会被拒。
-
----
-
-## 2. 鉴权与全局参数
-
-### 鉴权
-所有 `vhcli tiktok ...` 命令必须先鉴权：
-
-```bash
-vhcli auth login              # Device Flow
-# 或
-export VHCLI_TOKEN="vhk_xxx"  # 直接给 token
-```
-
-### 项目入口
-- **`--project-id`**：必传，格式 `po_xxxxxxxx`（公网项目编号，对应 vision_hub `customer_project.project_id` 字段）。OpenAPI 会反查为内部 int32 ID 后再调 biz。
-- **`--resource-id`**：广告账户 ID（TikTok advertiser_id），多数命令需要。token 通过 `(project_id, resource_id)` 在内部查 `customer_project_resource` + `sys_user_authorization` 解析。
-
-### 全局可选 flag
-
-| Flag | 说明 |
-|---|---|
-| `--format json\|table\|csv` | 输出格式，默认 json |
-| `--server` | vision_hub 地址，默认线上 |
-| `--dry-run` | 仅打印 payload 不发请求（仅 submit/spark-ads 等写操作有效） |
-| `--yes -y` | 跳过写操作的二次确认 |
-
----
-
-## 3. 命令清单
-
-```
-vhcli tiktok
-├── task
-│   ├── list                  查询创编任务列表（含 status / fail_reason）
-│   └── submit                提交创编任务（10min 幂等）
-├── options                   表单下拉（6 type 合一）
-├── dark-post-status          dark_post_status 允许取值
-├── optimization-event        优化事件列表（仅 READY）
-├── targeting-search          兴趣定向树
-└── spark-ads
-    └── authorize             Spark Ads 帖子批量授权
-```
-
-每条命令的完整 spec 见 §5。
-
----
-
-## 4. 三层配置模型（核心）
-
-### 4.1 数据层：4 张表
-
-| 表 | 用途 | 主键 |
-|---|---|---|
-| `ads_tiktok_creative` | 任务主表（status/fail_reason 在这） | `id` |
-| `project_tiktok_campaign_config` | Campaign 层级参数 | `task_id` |
-| `project_tiktok_adgroup_config` | Adgroup 层级参数 | `task_id` |
-| `project_tiktok_ad_config` | Ad 层级参数 | `task_id` |
-
-submit 是**单事务**写入这 4 张表，全部成功或全部回滚。
-
-### 4.2 三个动态对象
-
-`vhcli tiktok task submit --config-file <file.json>` 的 JSON 必须长这样：
-
-```json
-{
-  "campaign_config": { ... },
-  "adgroup_config":  { ... },
-  "ad_config":       { ... }
-}
-```
-
-每一层都是 `map[string]interface{}` —— **任意字段都可以传**，服务端的处理规则：
-
-1. 通过反射看 model struct 的 gorm column tag，判断字段是否是"已知字段"
-2. **已知字段** → 写入对应表的独立列（e.g. `campaign_name` 写入 `project_tiktok_campaign_config.campaign_name`）
-3. **未知字段** → 全部塞进同表的 `extra_params` JSON 列（不会丢，下游 docker 镜像会读出来透传给 TikTok Marketing API）
-
-> 这意味着：Agent 可以放心把 TikTok Marketing API 文档里的任何字段（如 `bid_price`、`schedule_type`、`pacing`、`interest_keyword_ids` 等）放到对应层的 config 里，**不需要等待 vhcli/服务端发版**。只要字段名一致，下游会自动透传。
-
-### 4.3 已知字段表（哪些字段是"独立列"）
-
-来源：`internal/data/media_ad/model/project_tiktok_*_config.gen.go`
-
-#### campaign_config 已知字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `campaign_name` | string | 推广系列名（必填） |
-| `budget` | float | 预算（CBO 时在 campaign 层；ABO 时移到 adgroup 层） |
-| `budget_mode` | string | 预算类型 |
-| `objective_type` | string | 推广目标 |
-| `app_promotion_type` | string | `APP_INSTALL` 或 `MINIS` |
-| `campaign_id` | string | 创建成功后回写，submit 时不传 |
-| `campaign_count` | int | 一次提交创建几个 campaign（默认 1） |
-
-#### adgroup_config 已知字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `adgroup_name` | string | 广告组名 |
-| `location_ids` | string | 地域 ID 列表，逗号分隔 |
-| `languages` | string | 语言 code 列表，逗号分隔 |
-| `app_id` | string | 应用 ID（注意：MINIS 推广类型时这里放 minis_id，**前端字段 `minis_id` 会被自动别名为 `app_id`**） |
-| `gender` | string | 性别定向 |
-| `adgroup_id` | string | 创建成功后回写，submit 时不传 |
-
-> **字段别名**：仅 `minis_id → app_id` 一条（见 `repo/ads_creative.go:fieldAliases`）。其他字段名如实写入 extra_params，不要自创别名。
-
-#### ad_config 已知字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `ad_name` | string | 广告名 |
-| `user_material` | string | 素材组 ID（注意：CLI/服务端里有时叫 `user_material_id`，**入库列名是 `user_material`**） |
-| `tiktok_item_ids` | string | 视频帖子 ID 列表 |
-| `ad_material_needed` | int | 每个广告所需素材数 |
-| `copywriting` | string | 广告文案 |
-| `selling_points` | string | 卖点文案 |
-| `tiktok_account` | string | TikTok 账号 identity_id（来自 `options --type=identity` 的 `identity_id`） |
-| `identity_type` | string | 身份类型（来自 `options --type=identity` 的 `identity_type`） |
-| `identity_authorized_bc_id` | string | 商务中心 ID（identity_type=BC_AUTH_TT 时必填） |
-| `success_ad_id` | string | 创建成功后回写，submit 时不传 |
-
-### 4.4 常见 extra_params（落到 extra_params JSON 列，不是独立列）
-
-代码里见到的、确认会走 extra_params 的字段（不一定全，详见 TikTok Marketing API 文档）：
-
-- adgroup 层：`roas_bid`、`vbo_window`、`spc_audience_age`
-- ad 层：`landing_page_url`
-- campaign 层：`budget_optimize_on` 等
-
-> **agent 不需要区分**：任何不在 §4.3 已知字段列表的字段直接传，服务端会自动归到 extra_params。
-
-### 4.5 推广类型与字段规范
-
-#### 支持矩阵
-
-| `objective_type` | `app_promotion_type` | 中文说明 | 状态 |
-|---|---|---|---|
-| APP_PROMOTION | MINIS | TikTok Minis（小游戏/小程序） | ✅ 支持 |
-| APP_PROMOTION | APP_INSTALL | App Install（应用安装） | ✅ 支持 |
-| APP_PROMOTION | APP_RETARGETING | 应用再营销 | ❌ 暂不支持 |
-
----
-
-#### MINIS 字段规范
-
-**必填字段**
-
-| 层 | 产品字段 | 参数名 |
-|---|---|---|
-| Campaign | 广告账户 | `resource_id`（顶层 flag） |
-| Campaign | 推广系列名称 | `campaign_config.campaign_name` |
-| Campaign | 预算类型 | `campaign_config.budget_mode` |
-| Campaign | 预算金额 | `campaign_config.budget` |
-| Campaign | 推广系列数量 | `campaign_config.campaign_count` |
-| AdGroup | 广告组名称 | `adgroup_config.adgroup_name` |
-| AdGroup | 目标 ROAS 类型 | `adgroup_config.vbo_window` |
-| AdGroup | 目标 ROAS | `adgroup_config.roas_bid` |
-| AdGroup | 地域 | `adgroup_config.location_ids` |
-| AdGroup | 语言 | `adgroup_config.languages` |
-| AdGroup | 最低年龄 | `adgroup_config.spc_audience_age` |
-| AdGroup | 性别 | `adgroup_config.gender` |
-| AdGroup | 小游戏 | `adgroup_config.minis_id`（自动别名为 `app_id`） |
-| Ad | TikTok 账号 | `ad_config.identity_authorized_bc_id` / `ad_config.identity_type` / `ad_config.tiktok_account` |
-| Ad | 广告名称 | `ad_config.ad_name` |
-| Ad | 小程序 URL | `ad_config.landing_page_url` |
-| Ad | 素材组 | `ad_config.user_material` |
-| Ad | 每个广告所需素材数 | `ad_config.ad_material_needed` |
-| Ad | 仅作为广告展示 | `ad_config.dark_post_status` |
-| Ad | 文案 | `ad_config.copywriting` |
-
-**非必填字段**
-
-| 层 | 产品字段 | 参数名 |
-|---|---|---|
-| Ad | 卖点文案 | `ad_config.selling_points` |
-
----
-
-#### APP_INSTALL 字段规范
-
-**必填字段**
-
-| 层 | 产品字段 | 参数名 |
-|---|---|---|
-| Campaign | 广告账户 | `resource_id`（顶层 flag） |
-| Campaign | 推广系列名称 | `campaign_config.campaign_name` |
-| AdGroup | 广告组名称 | `adgroup_config.adgroup_name` |
-| AdGroup | 预算类型 | `adgroup_config.budget_mode` |
-| AdGroup | 预算金额 | `adgroup_config.budget` |
-| AdGroup | APP ID | `adgroup_config.app_id` |
-| AdGroup | 竞价策略 | `adgroup_config.bid_type` |
-| AdGroup | 优化目标 | `adgroup_config.optimization_goal` |
-| AdGroup | 版位 | `adgroup_config.placements` |
-| AdGroup | 点击归因窗口期 | `adgroup_config.click_attribution_window` |
-| AdGroup | 深度互动观看归因窗口期 | `adgroup_config.engaged_view_attribution_window` |
-| AdGroup | 观看归因窗口期 | `adgroup_config.view_attribution_window` |
-| AdGroup | 地域 | `adgroup_config.location_ids` |
-| AdGroup | 语言 | `adgroup_config.languages` |
-| AdGroup | 年龄组 | `adgroup_config.age_groups` |
-| AdGroup | 性别 | `adgroup_config.gender` |
-| Ad | TikTok 账号 | `ad_config.identity_authorized_bc_id` / `ad_config.identity_type` / `ad_config.tiktok_account` |
-| Ad | 每个广告组所需素材数 | `ad_config.adgroup_material_needed` |
-| Ad | 仅作为广告展示 | `ad_config.dark_post_status` |
-| Ad | 文案 | `ad_config.copywriting` |
-
-**条件必填字段**
-
-| 条件 | 产品字段 | 参数名 |
-|---|---|---|
-| `bid_type=BID_TYPE_NO_BID`（最大投放量）时 | 平均目标转化成本 | `adgroup_config.conversion_bid_price` |
-| 素材来源二选一（至少填其一） | 素材 ID | `ad_config.user_material` |
-| 素材来源二选一（至少填其一） | 视频帖子 ID | `ad_config.tiktok_item_ids` |
-
-**非必填字段**
-
-| 层 | 产品字段 | 参数名 |
-|---|---|---|
-| AdGroup | 大众兴趣定向 - 创作者互动 | `adgroup_config.targeting_spec.creator_interaction` |
-| AdGroup | 大众兴趣定向 - 话题互动 | `adgroup_config.targeting_spec.hashtag_interaction` |
-| AdGroup | 大众兴趣定向 - 兴趣分类 | `adgroup_config.targeting_spec.interest_category_ids` |
-| AdGroup | 大众兴趣定向 - 购买意向关键词 | `adgroup_config.targeting_spec.purchase_intention_keyword_ids` |
-| AdGroup | 大众兴趣定向 - 视频互动 | `adgroup_config.targeting_spec.video_interaction` |
-| AdGroup | 排除受众 | `adgroup_config.excluded_audience_ids` |
-| Ad | 点击监测 URL | `ad_config.tracking_info.click_tracking_url` |
-| Ad | 展示监测 URL | `ad_config.tracking_info.impression_tracking_url` |
-
----
-
-## 5. 命令完整 spec
-
-### 5.1 `vhcli tiktok task list` — 任务列表
-
-**HTTP**: `GET /open_api/v2/tiktok/task_list`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | `po_xxx` |
-| `--page-size` | | 默认 10 |
-| `--page-number` | | 默认 1 |
-
-**响应字段**（`TikTokCreativeTaskItem`）：
-
-| 字段 | 说明 |
-|---|---|
-| `id` | 任务 ID（int64） |
-| `tiktok_account` | 当前实现里返回的是 `resource_id`（见 `open_api_ads_creative.go:50` 已知偏差） |
-| `campaign_name` | |
-| `creative_app_id` | adgroup 的 app_id |
-| `create_time` | 格式 `MM/DD HH:mm` |
-| `task_status` | `PENDING` / 下游执行中或终态（运行态命名以下游 docker 实际写入为准） |
-| `fail_reason` | 失败原因（成功为空） |
-| `details` | 完整 `campaign_config` / `adgroup_config` / `ad_config`（含 extra） |
-
-**典型用途**：submit 后轮询直到 `task_status` 变为非 `PENDING`。
-
-### 5.2 `vhcli tiktok task submit` — 提交创编
-
-**HTTP**: `POST /open_api/v2/tiktok/submit`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | `po_xxx` |
-| `--resource-id` | ✅ | TikTok advertiser_id |
-| `--request-id` | ✅ | **幂等键**，10 分钟内同值会被拒绝（`Redis SetNX` 锁），建议用 UUID |
-| `--creative-app-id` | | 创编应用 ID（可选） |
-| `--config-file` | ✅ | JSON 文件，含 `campaign_config` / `adgroup_config` / `ad_config` |
-| `--follow` | | 提交成功后取最新一条任务，PENDING 则按 5s 间隔轮询直至非 PENDING（5min 超时）。由于 submit 不返回 task_id，本 flag 是拿到 task_id + 终态的最简方式。 |
-
-**服务端必要校验**：
-- `budget` 必须为数字且 > 20（`ads_creative.go:469`）
-
-**响应**：成功返回 `errId=0`，**不**返回 task_id；要拿 task_id 自己 `task list` 倒序看。
-
-**示例 config-file**（最小可跑，APP_PROMOTION + APP_INSTALL）：
-
-```json
-{
-  "campaign_config": {
-    "campaign_name": "demo_campaign",
-    "objective_type": "APP_PROMOTION",
-    "app_promotion_type": "APP_INSTALL",
-    "budget_mode": "BUDGET_MODE_DAY",
-    "budget": 50,
-    "campaign_count": 1
-  },
-  "adgroup_config": {
-    "adgroup_name": "demo_adgroup",
-    "app_id": "7234567890123456789",
-    "location_ids": "6252001",
-    "languages": "en",
-    "gender": "GENDER_UNLIMITED"
-  },
-  "ad_config": {
-    "ad_name": "demo_ad",
-    "tiktok_account": "7888888888888888888",
-    "identity_type": "CUSTOMIZED_USER",
-    "ad_material_needed": 1,
-    "user_material": "mat_group_001",
-    "copywriting": "Try our app today",
-    "selling_points": "Free | Easy"
-  }
-}
-```
-
-> 枚举值完整参考见 §11。
-
-### 5.3 `vhcli tiktok options` — 表单下拉（6 合 1）
-
-**HTTP**: `GET /open_api/v2/tiktok/options`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | |
-| `--resource-id` | ✅ | |
-| `--type` | ✅ | `language` / `region` / `identity` / `minis` / `app` / `audience` |
-| `--objective-type` | 仅 `region` | |
-| `--language` | 仅 `region` | 默认 `zh` |
-
-**返回结构因 type 而异**（list 元素是动态 map）：
-
-| type | list 元素字段 | 用途 |
-|---|---|---|
-| `language` | `code`, `name` | 选 `adgroup_config.languages` 的 code 值；服务端会插入 `code=""`（即 "All"）作为首项 |
-| `region` | `location_id`, `name`, `region_code`, `level`, `area_type`, `country_code`, `parent_id`, `next_level_ids`, `support_below_18` | 选 `adgroup_config.location_ids` |
-| `identity` | `display_name`, `identity_id`, `identity_type`, `identity_authorized_bc_id`, `profile_image` | 选 `ad_config.tiktok_account` (用 `identity_id`) + `ad_config.identity_type` + `identity_authorized_bc_id`；**服务端已过滤 `identity_type=AUTH_CODE`** |
-| `minis` | `minis_id`, `minis_name`, `minis_status`, `minis_type`, `minis_icon_url`, `region_codes` | 选 `adgroup_config.minis_id`（自动别名为 app_id），仅当 `app_promotion_type=MINIS`；注意过滤 `minis_status=ACTIVE` |
-| `app` | `app_id`, `app_name`, `advertiser_id`, `icon.web_uri` | 选 `adgroup_config.app_id`（用 `app_id` 字段），同时作为 submit 的 `--creative-app-id`；仅当 `app_promotion_type=APP_INSTALL` |
-| `audience` | `audience_id`, `name`, `audience_type`, `is_valid`, `create_time`, `expired_time`, `cover_num` | 选自定义受众（通常进 extra_params），用 `audience_id` 字段 |
-
-### 5.4 `vhcli tiktok dark-post-status` — dark_post_status 校验
-
-**HTTP**: `GET /open_api/v2/tiktok/dark_post_status`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | |
-| `--resource-id` | ✅ | |
-| `--identity-id` | ✅ | 来自 `options --type=identity` 的 `identity_id` |
-| `--identity-type` | ✅ | |
-| `--identity-authorized-bc-id` | identity_type=BC_AUTH_TT 时必填 | |
-
-**响应**：
-
-```json
-{ "allowed_values": ["ON", "OFF"], "reason": "" }
-// 或
-{ "allowed_values": ["ON"], "reason": "广告账号已强制开启 ads_only_mode，dark_post_status 只能设为 ON" }
-```
-
-**判定逻辑**（`AdsCreativeCase.CheckDarkPostStatus`）：
-- 并发查 `advertiser_info.ads_only_mode` + `identity_info.ads_only_mode`
-- 任一为 true → 只允许 `ON`
-- 都为 false → `["ON","OFF"]` 都允许
-
-**用途**：agent 在 `ad_config` 里设置 `dark_post_status` 之前应当先调本接口，避免 submit 后被 TikTok 拒。
-
-### 5.5 `vhcli tiktok optimization-event` — 优化事件
-
-**HTTP**: `GET /open_api/v2/tiktok/optimization_event`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | |
-| `--resource-id` | ✅ | |
-| `--app-id` | ✅ | adgroup 的 app_id |
-| `--objective` | ✅ | 同 `objective_type` |
-| `--optimization-goal` | ✅ | 期望的优化目标 |
-| `--placements` | ✅ | 版位列表，逗号分隔（重复 `placements` 参数也行）。**服务端固定 `placement_type=PLACEMENT_TYPE_NORMAL`、`app_promotion_type=APP_INSTALL`**（见 `third_party/tiktok.go:GetOptimizationEvent`） |
-
-**响应**：`["EVENT_NAME_1", "EVENT_NAME_2", ...]`，仅返回 `availability_status=READY` 的事件。
-
-**用途**：选择 `adgroup_config.optimization_event`（走 extra_params）之前先调这个，确保事件可用。
-
-### 5.6 `vhcli tiktok targeting-search` — 兴趣定向树
-
-**HTTP**: `GET /open_api/v2/tiktok/targeting_search`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | |
-| `--resource-id` | ✅ | |
-
-**响应**：树形结构，节点 `{label, label_key, children[]}`。biz 层固定按以下一级分组组装：
-
-| 一级 label | label_key |
-|---|---|
-| 视频互动 | `video_interaction` |
-| 兴趣 | `general_interest` |
-| 创作者互动 | `creator_interaction` |
-| 话题互动 | `hashtag_interaction` |
-| 购买意向 | `purchase_intention` |
-| additional_interest | `additional_interest` |
-
-**实现**：服务端按 TikTok 返回的 `children_ids` 还原层级（见 `ads_creative.go:buildTargetingTree`）。语言固定 `zh`、`targeting_type=INTEREST_AND_BEHAVIOR`。
-
-**用途**：agent 想精准选 `interest_keyword_ids` / `interest_category_v2` 等定向参数（走 extra_params）时用。
-
-### 5.7 `vhcli tiktok spark-ads authorize` — Spark Ads 批量授权
-
-**HTTP**: `POST /open_api/v2/tiktok/spark_ads/authorize`
-
-| Flag | Required | 说明 |
-|---|---|---|
-| `--project-id` | ✅ | |
-| `--resource-id` | ✅ | |
-| `--tiktok-account` | ✅ | TikTok identity_id |
-| `--auth-codes` | ✅ | auth_code 列表，逗号分隔，**最多 50 个并发** |
-
-**响应**：`{ "not_authorized_codes": [...] }` —— 返回 `identity_id != tiktok_account` 或授权失败的 auth_code。空数组意味全部成功。
-
----
-
-## 6. 端到端工作流（典型 Agent 流程）
-
-```
-                 ┌───────────────────┐
-                 │ 1. 选项发现        │
-                 │  options × 6      │
-                 │  + targeting/event│
-                 └─────────┬─────────┘
-                           ▼
-                 ┌───────────────────┐
-                 │ 2. 合规预检       │
-                 │  dark-post-status │
-                 └─────────┬─────────┘
-                           ▼
-                 ┌───────────────────┐
-                 │ 3. 拼配置 JSON    │
-                 │  3 层 config      │
-                 └─────────┬─────────┘
-                           ▼
-                 ┌───────────────────┐
-                 │ 4. submit (幂等)  │
-                 │  --request-id=UUID│
-                 └─────────┬─────────┘
-                           ▼
-                 ┌───────────────────┐
-                 │ 5. 轮询 task list │
-                 │  status / fail   │
-                 └───────────────────┘
-```
-
-### 6.1 详细步骤
-
-1. **建立项目上下文** — 用户给定 `project_id` (po_xxx) 和 `resource_id`（advertiser_id）。
-
-2. **拉元数据**（按需，可并行）：
-   ```bash
-   vhcli tiktok options --project-id $P --resource-id $R --type identity
-   vhcli tiktok options --project-id $P --resource-id $R --type app
-   vhcli tiktok options --project-id $P --resource-id $R --type region --objective-type APP_PROMOTION
-   vhcli tiktok options --project-id $P --resource-id $R --type language
-   ```
-
-3. **如果设 dark_post_status，先校验**：
-   ```bash
-   vhcli tiktok dark-post-status --project-id $P --resource-id $R \
-     --identity-id $IID --identity-type $ITYPE \
-     [--identity-authorized-bc-id $BC]
-   ```
-
-4. **如果用兴趣定向 / 优化事件**：
-   ```bash
-   vhcli tiktok targeting-search --project-id $P --resource-id $R
-   vhcli tiktok optimization-event --project-id $P --resource-id $R \
-     --app-id $APP --objective APP_PROMOTION \
-     --optimization-goal CONVERT --placements PLACEMENT_TIKTOK
-   ```
-
-5. **生成 config-file**（JSON），见 §5.2 示例。
-   - 已知字段直接放对应层
-   - 任何 TikTok Marketing API 支持但本表没列的字段也直接放对应层 → 自动 extra_params
-
-6. **提交**：
-   ```bash
-   REQ_ID=$(uuidgen)
-   vhcli tiktok task submit \
-     --project-id $P --resource-id $R --request-id $REQ_ID \
-     --config-file ./config.json
-   ```
-   - 用 `--dry-run` 可以先看 payload 不发请求
-   - 失败 "请勿重复提交" → request_id 命中幂等锁，换一个
-
-7. **轮询**：
-   ```bash
-   vhcli tiktok task list --project-id $P --page-size 5 --page-number 1
-   ```
-   - `task_status=PENDING` 表示下游 docker 还没跑完或还没启动
-   - 终态（非 PENDING）后看 `fail_reason` 判断成败
-
----
-
-## 7. 错误处理速查
-
-所有响应都是统一 envelope：
-
-```json
-{ "errId": 0, "errCode": "", "errMsg": "查询成功", "data": ... }
-```
-
-`errId != 0` 表示失败。常见错误：
-
-| 现象 | 含义 | 处理 |
-|---|---|---|
-| `请勿重复提交` | request_id 命中 10min 幂等锁 | 换 request_id 重提 |
-| `budget必须为数字且大于20` | submit 校验 | 改 `campaign_config.budget` |
-| `获取TikTok access token失败` | resource_id/project_id 没配对应授权，或授权过期 | 联系项目管理员重新授权 |
-| `dark_post_status` 只能 ON | identity 或 advertiser 已开启 `ads_only_mode` | 不要传 OFF |
-| options 里 identity 列表是空 | 该广告账户没有任何非 AUTH_CODE 身份 | 先在 TikTok Ads Manager 授权身份 |
-| optimization_event 返回空 | 当前 app/objective/goal/placement 组合没有 READY 事件 | 换 optimization_goal 或 placement |
-
-**调试技巧**：
-- `--format json` 拿原始响应
-- `--dry-run` 看 submit payload
-- `task list` 里的 `details` 字段会回放完整 config（含 extra_params），用于核对实际写入
-
----
-
-## 8. 边界与已知差异
-
-1. **task list 的 `tiktok_account` 字段实际是 resource_id**（`open_api_ads_creative.go:50`）。如果 agent 要展示账号名，需要再调 `options --type=identity` 自己 join。
-
-2. **`submit` 不返回 task_id**。需要立刻拿 task_id 时，submit 后立即 `task list --page-size 1 --page-number 1` 取第一条（自己 create_user 那条），或直接给 submit 加 `--follow` 让 CLI 自动取最新任务并轮询到非 PENDING。
-
-3. **整个流水线没有"取消任务"接口**。submit 后只能等下游 docker 跑出结果。
-
-4. **`identity_type=AUTH_CODE` 在 options 里被服务端过滤掉**（`ads_creative.go:258`）。如果一定要用 AUTH_CODE 身份（罕见场景），需要走 spark-ads authorize 流程。
-
-5. **`creative_app_id` 与 `adgroup_config.app_id` 的关系**：submit 顶层有 `creative_app_id`（VHM/编排层用），adgroup 内部有 `app_id`（TikTok API 用）。**两个都要传**，且通常是同值。
-
-6. **token 的来源不需要 agent 关心**。服务端按 `(project_id, resource_id)` 自己解析。
-
----
-
-## 9. 字段位置速查（cheat sheet）
-
-> 不确定一个字段该放哪一层时，按以下顺序判断：
-
-1. 在 §4.3 已知字段表里？→ 放对应层
-2. 是 TikTok Campaign API 字段？→ `campaign_config` extra_params
-3. 是 TikTok Adgroup API 字段（定向、出价、版位、优化目标、预算ABO）？→ `adgroup_config` extra_params
-4. 是 TikTok Ad API 字段（创意、文案、落地页、身份）？→ `ad_config` extra_params
-
-常见字段归属：
-
-| 字段 | 层 | 已知列 | 推广类型 |
-|---|---|---|---|
-| `campaign_name` / `objective_type` / `app_promotion_type` / `campaign_count` | campaign | ✅ | 通用 |
-| `budget_mode` / `budget`（MINIS 用 campaign 层，即 CBO） | campaign | ✅ | MINIS |
-| `budget_optimize_on` / `bid_strategy` | campaign | extra | 通用 |
-| `adgroup_name` / `location_ids` / `languages` / `gender` / `app_id` | adgroup | ✅ | 通用 |
-| `budget_mode` / `budget`（APP_INSTALL 用 adgroup 层，即 ABO） | adgroup | extra | APP_INSTALL |
-| `roas_bid` / `vbo_window` / `spc_audience_age` | adgroup | extra | MINIS |
-| `bid_type` / `conversion_bid_price` | adgroup | extra | APP_INSTALL |
-| `optimization_goal` / `optimization_event` | adgroup | extra | APP_INSTALL |
-| `placements` / `placement_type` | adgroup | extra | APP_INSTALL |
-| `age_groups` | adgroup | extra | APP_INSTALL |
-| `click_attribution_window` / `engaged_view_attribution_window` / `view_attribution_window` | adgroup | extra | APP_INSTALL |
-| `interest_keyword_ids` / `interest_category_v2` / `targeting_spec.*` | adgroup | extra | APP_INSTALL |
-| `audience_ids` / `excluded_audience_ids` | adgroup | extra | APP_INSTALL |
-| `ad_name` / `copywriting` / `selling_points` / `ad_material_needed` | ad | ✅ | 通用 |
-| `adgroup_material_needed` | ad | extra | APP_INSTALL |
-| `user_material` / `tiktok_item_ids` | ad | ✅ | 通用 |
-| `tiktok_account` / `identity_type` / `identity_authorized_bc_id` | ad | ✅ | 通用 |
-| `landing_page_url` | ad | extra | MINIS |
-| `dark_post_status` | ad | extra | 通用 |
-| `tracking_info.click_tracking_url` / `tracking_info.impression_tracking_url` | ad | extra | APP_INSTALL |
-
----
-
-## 10. 外部参考
-
-- TikTok Marketing API 文档：https://business-api.tiktok.com/portal/docs
-
----
-
-## 11. 枚举值速查
-
-### 推广目标（objective_type）
-
-| 枚举值 | 中文说明 |
-|---|---|
-| APP_PROMOTION | 应用推广 |
-
-### 应用推广类型（app_promotion_type）
-
-| 枚举值 | 中文说明 |
-|---|---|
-| MINIS | TikTok Minis（小游戏/小程序） |
-| APP_INSTALL | App Install（应用安装） |
-| APP_RETARGETING | 应用再营销（暂不支持） |
-
-### 预算类型（budget_mode）
-
-| 枚举值 | 中文说明 |
-|---|---|
-| BUDGET_MODE_DYNAMIC_DAILY_BUDGET | 动态日预算 |
-| BUDGET_MODE_TOTAL | 总预算 |
-
-### 性别（gender）
-
-| 枚举值 | 中文说明 |
-|---|---|
-| GENDER_FEMALE | 女性 |
-| GENDER_MALE | 男性 |
-| GENDER_UNLIMITED | 不限 |
-
-### 最低年龄（spc_audience_age）— MINIS
-
-| 枚举值 | 中文说明 |
-|---|---|
-| OVER_EIGHTEEN | 18+ |
-| OVER_TWENTY_FIVE | 25+ |
-
-### 年龄组（age_groups）— APP_INSTALL
-
-| 枚举值 |
-|---|
-| AGE_18_24 |
-| AGE_25_34 |
-| AGE_35_44 |
-| AGE_45_54 |
-| AGE_55_100 |
-
-### 竞价策略（bid_type）— APP_INSTALL
-
-| 枚举值 | 中文说明 |
-|---|---|
-| BID_TYPE_NO_BID | 最大投放量 |
-| BID_TYPE_CUSTOM | 目标 CPA |
-
-### 优化目标（optimization_goal）— APP_INSTALL
-
-| 枚举值 | 中文说明 |
-|---|---|
-| VALUE | 价值 / 总收入 |
-| IN_APP_EVENT | 应用内事件 |
-| INSTALL | 安装 |
-| CLICK | 点击数 |
-
-### 版位（placements）— APP_INSTALL
-
-| 枚举值 | 中文说明 |
-|---|---|
-| PLACEMENT_TIKTOK | TikTok |
-| PLACEMENT_PANGLE | Pangle |
-| PLACEMENT_GLOBAL_APP_BUNDLE | Global App Bundle |
-
-### 目标 ROAS 类型（vbo_window）— MINIS
-
-| 枚举值 | 中文说明 |
-|---|---|
-| ZERO_DAY | 第 0 天 |
-| SEVEN_DAYS | 第 7 天 |
-
-### 点击归因窗口期（click_attribution_window）— APP_INSTALL
-
-| 枚举值 | 中文说明 |
-|---|---|
-| OFF | 关闭 |
-| ONE_DAY | 1 天 |
-| SEVEN_DAYS | 7 天 |
-| FOURTEEN_DAYS | 14 天 |
-| TWENTY_EIGHT_DAYS | 28 天 |
-
-### 深度互动观看归因窗口期（engaged_view_attribution_window）— APP_INSTALL
-
-| 枚举值 | 中文说明 |
-|---|---|
-| OFF | 关闭 |
-| ONE_DAY | 1 天 |
-| SEVEN_DAYS | 7 天 |
-| FOURTEEN_DAYS | 14 天 |
-| TWENTY_EIGHT_DAYS | 28 天 |
-
-### 观看归因窗口期（view_attribution_window）— APP_INSTALL
-
-| 枚举值 | 中文说明 |
-|---|---|
-| OFF | 关闭 |
-| ONE_DAY | 1 天 |
-| SEVEN_DAYS | 7 天 |
-
-### 任务状态（task_status）
-
-| 枚举值 | 中文说明 |
-|---|---|
-| PENDING | 待处理 |
-| PROCESSING | 处理中 |
-| CREATING_AD | 创建广告中 |
-| SUCCESS | 成功 |
-| FAILED | 失败 |
-| CAMPAIGN_CREATE_FAILED | 创建推广系列失败 |
-| ADSET_CREATE_FAILED | 创建广告组失败 |
-| AD_CREATE_FAILED | 创建广告失败 |