sino-bc-cli 1.0.0-beta.0

package/dist/api-doc/oapi/biz-line-metrics.md

@@ -0,0 +1,419 @@
+# 业务线策略广告成效数据
+
+对应命令：`biz-line-metrics +<shortcut>` 与 `biz-line-metrics api <name>`。
+
+执行前 MUST 读取 [sino-bc-shared](../../skills/sino-bc-shared/SKILL.md) 轻量入口，再按命中条件读取其 references；当前上下文已读且仍适用时可复用。可用 `sino-bc-cli /skill` 查询真实路径。
+
+## 1. Facebook广告策略维度数据
+
+`POST /sino-icenter/mcp/strategy/dimension/facebook/ad/list`
+
+主体上下文：`tenant=false`。
+
+角色范围：`sso/system`。
+
+风险：`read`。
+
+查询 Facebook（Meta）渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（广告目标、成效目标、创意类型、出价方式、调整出价、受众类型、兴趣词包、年龄、性别等），用于分析某批账户在某段时间内各广告的策略配置分布。本接口只返回策略维度，不含消耗、点击等成效指标，需要成效数据请改用「Facebook广告策略成效数据」接口。
+
+【国家维度特别说明】
+country_code（国家）只能单独传，或与 calendar_date（投放日期）两个一起传；与其他任何维度同传都会报错「[country_code]只能和[calendar_date]同时传入」。
+传入 country_code 时服务端转走跨渠道广告数据接口取数，由此有两点差异：
+一是 dimensionValues 里额外支持 country_code 作为过滤条件，传国家码数组即可按国家筛选；不传 country_code 维度时该过滤条件无效。
+二是 headerMap 的列名来自跨渠道接口，calendar_date 列名为「日期」而不是「投放日期」，country_code 列名为「国家/地区」；展示列名请以 headerMap 实际返回值为准，不要写死。
+
+【入参填写规则】
+1. startDate / endDate：字符串，格式 yyyy-MM-dd，两者都必填。
+2. dimensionValues：过滤条件，结构是「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>）。每个 key 是字段 code，对应的 value 必须是数组，即使只筛一个值也要用数组包裹；同一个 key 内的多个值之间是「或」关系，命中任意一个即返回。本接口默认只有 account_id 这一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件。传入其余 key 不会报错，但也不会产生任何过滤效果。
+3. dimensions：分组维度数组，必填。传多个维度时按多个字段组合分组，效果等同 SQL 的 GROUP BY 多列，维度越多返回行数越多、粒度越细。
+4. 排序：单字段排序用 order（字段名）+ orderType（desc / asc）；多字段排序用 orders，结构是「字段名 → 排序方向」的有序键值对，按书写顺序依次排序，例如 {"calendar_date":"desc","account_id":"asc"}。两者可同时使用，order 指定的字段会追加到 orders 之后。
+5. 分页：page 从 1 开始（默认 1），size 为每页条数（默认 10）。返回的 result.total 是总条数，据此判断是否还有下一页。
+
+【请求示例】
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": [
+      "act_1036928420879324"
+    ]
+  },
+  "dimensions": [
+    "calendar_date",
+    "optimization_goal"
+  ],
+  "order": "calendar_date",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+
+【返回格式】
+result.data 为数据行数组，每行的每个字段有两个 key：
+一是原始值，key 即请求的 code，做计算或比较时用这个；
+二是展示值，key 加 display_ 前缀，直接呈现给用户时用这个，空值为 "-"。
+result.headerMap 是字段 code 到中文列名的映射，用于给用户展示列名。
+result.total 为总条数，result.page 和 result.size 为当前分页。
+
+**输入参数（--data）**
+
+| 字段 | 类型 | 位置 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `startDate` | string | body | 是 | 统计开始日期，字符串，格式 yyyy-MM-dd，例如 "2026-08-01"。必填。 |
+| `endDate` | string | body | 是 | 统计结束日期，字符串，格式 yyyy-MM-dd，例如 "2026-08-31"。必填，需大于等于 startDate。 |
+| `dimensionValues` | object | body | 是 | 过滤条件。结构为「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>），value 必须是数组，即使只筛一个值也要用数组包裹。本接口默认只有 account_id 一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件（国家码数组）。其余 key 传入不报错但无过滤效果。示例：{"account_id": ["act_123", "act_456"]} |
+| `dimensions` | array | body | 是 | 分组维度，字符串数组，必传且不能为空数组（传空数组返回结果为空）。传多个维度时按多字段组合分组，等同 SQL 的 GROUP BY 多列，维度越多粒度越细、返回行数越多。各维度含义：calendar_date（投放日期）、account_id（广告账户ID）、account_name（广告账户名称）、campaign_id（广告系列ID）、campaign_name（广告系列名称）、adgroup_id（广告组ID）、adgroup_name（广告组名称）、ad_id（广告ID）、ad_name（广告名称）、bid_amount（调整出价）、objective（广告目标）、optimization_goal（成效目标）、ad_format（创意类型）、bid_strategy（出价方式）、audience_type（受众类型）、targeting_interests（兴趣词包）、targeting_flexible_interests（弹性兴趣词包）、targeting_exclusion_interests（排除兴趣词包）、targeting_age（年龄）、targeting_genders（性别）、country_code（国家，只能单独传或与 calendar_date 两个一起传） |
+| `order` | string | body | 否 | 单字段排序的字段名，填单个 code，取值范围为 dimensions 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回。与 orders 可同时使用，order 指定的字段会追加到 orders 之后。 |
+| `orderType` | string | body | 否 | 排序方向，配合 order 使用。desc 降序，asc 升序，默认 asc。 |
+| `orders` | object | body | 否 | 多字段排序，结构为「字段名 → 排序方向」的有序键值对（Java 类型 LinkedHashMap<String, String>），按 key 的书写顺序依次排序，方向取值 desc 或 asc。示例：{"calendar_date":"desc","account_id":"asc"}。只需单字段排序时用 order + orderType 即可，不必传本字段。 |
+| `page` | integer | body | 否 | 页码，从 1 开始，默认 1。 |
+| `size` | integer | body | 否 | 每页条数，默认 10，建议显式指定。返回的 result.total 为总条数，据此判断是否还有下一页。 |
+
+## 2. Google广告策略维度数据
+
+`POST /sino-icenter/mcp/strategy/dimension/google/ad/list`
+
+主体上下文：`tenant=false`。
+
+角色范围：`sso/system`。
+
+风险：`read`。
+
+查询 Google 渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（成效目标、创意类型、出价方式、CPC/CPM/CPV 出价、广告系列类型、关键字等），用于分析某批账户在某段时间内各广告的策略配置分布。Google 渠道不支持广告目标和兴趣词包维度，出价字段使用 cpc_bid_amount、cpm_bid_amount、cpv_bid_amount 三个独立维度。本接口只返回策略维度，不含消耗、点击等成效指标，需要成效数据请改用「Google广告策略成效数据」接口。
+
+【国家维度特别说明】
+country_code（国家）只能单独传，或与 calendar_date（投放日期）两个一起传；与其他任何维度同传都会报错「[country_code]只能和[calendar_date]同时传入」。
+传入 country_code 时服务端转走跨渠道广告数据接口取数，由此有两点差异：
+一是 dimensionValues 里额外支持 country_code 作为过滤条件，传国家码数组即可按国家筛选；不传 country_code 维度时该过滤条件无效。
+二是 headerMap 的列名来自跨渠道接口，calendar_date 列名为「日期」而不是「投放日期」，country_code 列名为「国家/地区」；展示列名请以 headerMap 实际返回值为准，不要写死。
+
+【入参填写规则】
+1. startDate / endDate：字符串，格式 yyyy-MM-dd，两者都必填。
+2. dimensionValues：过滤条件，结构是「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>）。每个 key 是字段 code，对应的 value 必须是数组，即使只筛一个值也要用数组包裹；同一个 key 内的多个值之间是「或」关系，命中任意一个即返回。本接口默认只有 account_id 这一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件。传入其余 key 不会报错，但也不会产生任何过滤效果。
+3. dimensions：分组维度数组，必填。传多个维度时按多个字段组合分组，效果等同 SQL 的 GROUP BY 多列，维度越多返回行数越多、粒度越细。
+4. 排序：单字段排序用 order（字段名）+ orderType（desc / asc）；多字段排序用 orders，结构是「字段名 → 排序方向」的有序键值对，按书写顺序依次排序，例如 {"calendar_date":"desc","account_id":"asc"}。两者可同时使用，order 指定的字段会追加到 orders 之后。
+5. 分页：page 从 1 开始（默认 1），size 为每页条数（默认 10）。返回的 result.total 是总条数，据此判断是否还有下一页。
+
+【请求示例】
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": [
+      "<广告账户ID，格式同 account_id 维度返回值>"
+    ]
+  },
+  "dimensions": [
+    "calendar_date",
+    "optimization_goal"
+  ],
+  "order": "calendar_date",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+
+【返回格式】
+result.data 为数据行数组，每行的每个字段有两个 key：
+一是原始值，key 即请求的 code，做计算或比较时用这个；
+二是展示值，key 加 display_ 前缀，直接呈现给用户时用这个，空值为 "-"。
+result.headerMap 是字段 code 到中文列名的映射，用于给用户展示列名。
+result.total 为总条数，result.page 和 result.size 为当前分页。
+
+**输入参数（--data）**
+
+| 字段 | 类型 | 位置 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `startDate` | string | body | 是 | 开始日期，格式 yyyy-MM-dd，例如 2026-08-01 |
+| `endDate` | string | body | 是 | 结束日期，格式 yyyy-MM-dd，例如 2026-08-31 |
+| `dimensionValues` | object | body | 是 | 过滤条件。结构为「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>），value 必须是数组，即使只筛一个值也要用数组包裹。本接口默认只有 account_id 一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件（国家码数组）。其余 key 传入不报错但无过滤效果。示例：{"account_id": ["act_123", "act_456"]} |
+| `dimensions` | array | body | 是 | 分组维度，必传且不能为空数组，否则返回结果为空。各维度含义：calendar_date（投放日期）、account_id（广告账户ID）、account_name（广告账户名称）、campaign_id（广告系列ID）、campaign_name（广告系列名称）、adgroup_id（广告组ID）、adgroup_name（广告组名称）、ad_id（广告ID）、ad_name（广告名称）、optimization_goal（成效目标）、ad_format（创意类型）、bid_strategy（出价方式）、audience_type（受众类型）、targeting_age（年龄）、targeting_genders（性别）、cpc_bid_amount（CPC出价）、cpm_bid_amount（CPM出价）、cpv_bid_amount（CPV出价）、advertising_channel_type（广告系列类型）、keywords（关键字）、country_code（国家，只能单独传或与 calendar_date 两个一起传） |
+| `order` | string | body | 否 | 排序字段，填单个 code，取值范围为 dimensions 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| `orderType` | string | body | 否 | 排序方向，默认 asc |
+| `orders` | object | body | 否 | 多字段排序，结构为「字段名 → 排序方向」的有序键值对（Java 类型 LinkedHashMap<String, String>），按 key 的书写顺序依次排序，方向取值 desc 或 asc。示例：{"calendar_date":"desc","account_id":"asc"}。只需单字段排序时用 order + orderType 即可，不必传本字段。 |
+| `page` | integer | body | 否 | 页码，从1开始，默认1 |
+| `size` | integer | body | 否 | 每页条数，默认10，建议显式传且不超过1000 |
+
+## 3. TikTok广告策略维度数据
+
+`POST /sino-icenter/mcp/strategy/dimension/tiktok/ad/list`
+
+主体上下文：`tenant=false`。
+
+角色范围：`sso/system`。
+
+风险：`read`。
+
+查询 TikTok 渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（广告目标、成效目标、创意类型、出价方式、调整出价、转化出价、深度转化出价、兴趣词包、年龄、性别等），用于分析某批账户在某段时间内各广告的策略配置分布。转化出价和深度转化出价是 TikTok 渠道独有的维度。本接口只返回策略维度，不含消耗、点击等成效指标，需要成效数据请改用「TikTok广告策略成效数据」接口。
+
+【国家维度特别说明】
+country_code（国家）只能单独传，或与 calendar_date（投放日期）两个一起传；与其他任何维度同传都会报错「[country_code]只能和[calendar_date]同时传入」。
+传入 country_code 时服务端转走跨渠道广告数据接口取数，由此有两点差异：
+一是 dimensionValues 里额外支持 country_code 作为过滤条件，传国家码数组即可按国家筛选；不传 country_code 维度时该过滤条件无效。
+二是 headerMap 的列名来自跨渠道接口，calendar_date 列名为「日期」而不是「投放日期」，country_code 列名为「国家/地区」；展示列名请以 headerMap 实际返回值为准，不要写死。
+
+【入参填写规则】
+1. startDate / endDate：字符串，格式 yyyy-MM-dd，两者都必填。
+2. dimensionValues：过滤条件，结构是「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>）。每个 key 是字段 code，对应的 value 必须是数组，即使只筛一个值也要用数组包裹；同一个 key 内的多个值之间是「或」关系，命中任意一个即返回。本接口默认只有 account_id 这一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件。传入其余 key 不会报错，但也不会产生任何过滤效果。
+3. dimensions：分组维度数组，必填。传多个维度时按多个字段组合分组，效果等同 SQL 的 GROUP BY 多列，维度越多返回行数越多、粒度越细。
+4. 排序：单字段排序用 order（字段名）+ orderType（desc / asc）；多字段排序用 orders，结构是「字段名 → 排序方向」的有序键值对，按书写顺序依次排序，例如 {"calendar_date":"desc","account_id":"asc"}。两者可同时使用，order 指定的字段会追加到 orders 之后。
+5. 分页：page 从 1 开始（默认 1），size 为每页条数（默认 10）。返回的 result.total 是总条数，据此判断是否还有下一页。
+
+【请求示例】
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": [
+      "<广告账户ID，格式同 account_id 维度返回值>"
+    ]
+  },
+  "dimensions": [
+    "calendar_date",
+    "optimization_goal"
+  ],
+  "order": "calendar_date",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+
+【返回格式】
+result.data 为数据行数组，每行的每个字段有两个 key：
+一是原始值，key 即请求的 code，做计算或比较时用这个；
+二是展示值，key 加 display_ 前缀，直接呈现给用户时用这个，空值为 "-"。
+result.headerMap 是字段 code 到中文列名的映射，用于给用户展示列名。
+result.total 为总条数，result.page 和 result.size 为当前分页。
+
+**输入参数（--data）**
+
+| 字段 | 类型 | 位置 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `startDate` | string | body | 是 | 统计开始日期，字符串，格式 yyyy-MM-dd，例如 "2026-08-01"。必填。 |
+| `endDate` | string | body | 是 | 统计结束日期，字符串，格式 yyyy-MM-dd，例如 "2026-08-31"。必填，需大于等于 startDate。 |
+| `dimensionValues` | object | body | 是 | 过滤条件。结构为「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>），value 必须是数组，即使只筛一个值也要用数组包裹。本接口默认只有 account_id 一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件（国家码数组）。其余 key 传入不报错但无过滤效果。示例：{"account_id": ["act_123", "act_456"]} |
+| `dimensions` | array | body | 是 | 分组维度，字符串数组，必传且不能为空数组（传空数组返回结果为空）。传多个维度时按多字段组合分组，等同 SQL 的 GROUP BY 多列，维度越多粒度越细、返回行数越多。各维度含义：calendar_date（投放日期）、account_id（广告账户ID）、account_name（广告账户名称）、campaign_id（广告系列ID）、campaign_name（广告系列名称）、adgroup_id（广告组ID）、adgroup_name（广告组名称）、ad_id（广告ID）、ad_name（广告名称）、bid_amount（调整出价）、objective（广告目标）、optimization_goal（成效目标）、ad_format（创意类型）、bid_strategy（出价方式）、audience_type（受众类型）、targeting_interests（兴趣词包）、targeting_age（年龄）、targeting_genders（性别）、conversion_bid（转化出价）、deep_cpabid（深度转化出价）、country_code（国家，只能单独传或与 calendar_date 两个一起传） |
+| `order` | string | body | 否 | 单字段排序的字段名，填单个 code，取值范围为 dimensions 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回。与 orders 可同时使用，order 指定的字段会追加到 orders 之后。 |
+| `orderType` | string | body | 否 | 排序方向，配合 order 使用。desc 降序，asc 升序，默认 asc。 |
+| `orders` | object | body | 否 | 多字段排序，结构为「字段名 → 排序方向」的有序键值对（Java 类型 LinkedHashMap<String, String>），按 key 的书写顺序依次排序，方向取值 desc 或 asc。示例：{"calendar_date":"desc","account_id":"asc"}。只需单字段排序时用 order + orderType 即可，不必传本字段。 |
+| `page` | integer | body | 否 | 页码，从 1 开始，默认 1。 |
+| `size` | integer | body | 否 | 每页条数，默认 10，建议显式指定。返回的 result.total 为总条数，据此判断是否还有下一页。 |
+
+## 4. Facebook广告策略成效数据
+
+`POST /sino-icenter/mcp/strategy/metrics/facebook/ad/list`
+
+主体上下文：`tenant=false`。
+
+角色范围：`sso/system`。
+
+风险：`read`。
+
+查询 Facebook（Meta）渠道广告的策略维度加成效指标数据。在广告策略配置（广告目标、成效目标、创意类型、出价方式、受众定向等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
+
+【国家维度特别说明】
+country_code（国家）只能单独传，或与 calendar_date（投放日期）两个一起传；与其他任何维度同传都会报错「[country_code]只能和[calendar_date]同时传入」。
+传入 country_code 时服务端转走跨渠道广告数据接口取数，indicators 里的 12 个指标在该接口同样支持、照常返回聚合值，但有两点差异：
+一是 dimensionValues 里额外支持 country_code 作为过滤条件，传国家码数组即可按国家筛选；不传 country_code 维度时该过滤条件无效。
+二是 headerMap 的列名来自跨渠道接口，calendar_date 列名为「日期」而不是「投放日期」，country_code 列名为「国家/地区」；展示列名请以 headerMap 实际返回值为准，不要写死。
+
+【入参填写规则】
+1. startDate / endDate：字符串，格式 yyyy-MM-dd，两者都必填。
+2. dimensionValues：过滤条件，结构是「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>）。每个 key 是字段 code，对应的 value 必须是数组，即使只筛一个值也要用数组包裹；同一个 key 内的多个值之间是「或」关系，命中任意一个即返回。本接口默认只有 account_id 这一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件。传入其余 key 不会报错，但也不会产生任何过滤效果。
+3. dimensions：分组维度数组，必填。传多个维度时按多个字段组合分组，效果等同 SQL 的 GROUP BY 多列，维度越多返回行数越多、粒度越细。
+4. indicators：成效指标数组，必填。指标会在 dimensions 指定的分组粒度上做求和聚合。
+5. 排序：单字段排序用 order（字段名）+ orderType（desc / asc）；多字段排序用 orders，结构是「字段名 → 排序方向」的有序键值对，按书写顺序依次排序，例如 {"spend_usd":"desc","clicks":"asc"}。两者可同时使用，order 指定的字段会追加到 orders 之后。
+6. 分页：page 从 1 开始（默认 1），size 为每页条数（默认 10）。返回的 result.total 是总条数，据此判断是否还有下一页。
+
+【请求示例】
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": [
+      "act_1036928420879324"
+    ]
+  },
+  "dimensions": [
+    "calendar_date",
+    "optimization_goal"
+  ],
+  "indicators": [
+    "spend_usd",
+    "impressions",
+    "clicks"
+  ],
+  "order": "spend_usd",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+
+【返回格式】
+result.data 为数据行数组，每行的每个字段有两个 key：
+一是原始值，key 即请求的 code，如 spend_usd 的值为 618.42，做计算或比较时用这个；
+二是展示值，key 加 display_ 前缀，如 display_spend_usd 的值带货币符号，直接呈现给用户时用这个，空值为 "-"。
+result.headerMap 是字段 code 到列名的映射，维度列名为中文，指标列名为英文（如 spend_usd 对应 Spend）。
+result.total 为总条数，result.page 和 result.size 为当前分页。
+result.conflictField 是传入但当前渠道不支持的指标，会被忽略且不报错，为空数组表示全部指标都生效。
+
+**输入参数（--data）**
+
+| 字段 | 类型 | 位置 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `startDate` | string | body | 是 | 统计开始日期，字符串，格式 yyyy-MM-dd，例如 "2026-08-01"。必填。 |
+| `endDate` | string | body | 是 | 统计结束日期，字符串，格式 yyyy-MM-dd，例如 "2026-08-31"。必填，需大于等于 startDate。成效数据最多支持查询近21天，超出范围可能返回空数据。 |
+| `dimensionValues` | object | body | 是 | 过滤条件。结构为「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>），value 必须是数组，即使只筛一个值也要用数组包裹。本接口默认只有 account_id 一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件（国家码数组）。其余 key 传入不报错但无过滤效果。示例：{"account_id": ["act_123", "act_456"]} |
+| `dimensions` | array | body | 是 | 分组维度，字符串数组，必传且不能为空数组（传空数组返回结果为空）。传多个维度时按多字段组合分组，等同 SQL 的 GROUP BY 多列，维度越多粒度越细、返回行数越多。各维度含义：calendar_date（投放日期）、account_id（广告账户ID）、account_name（广告账户名称）、campaign_id（广告系列ID）、campaign_name（广告系列名称）、adgroup_id（广告组ID）、adgroup_name（广告组名称）、ad_id（广告ID）、ad_name（广告名称）、objective（广告目标）、optimization_goal（成效目标）、ad_format（创意类型）、bid_strategy（出价方式）、audience_type（受众类型）、targeting_interests（兴趣词包）、targeting_flexible_interests（弹性兴趣词包）、targeting_exclusion_interests（排除兴趣词包）、targeting_age（年龄）、targeting_genders（性别）、country_code（国家，只能单独传或与 calendar_date 两个一起传） |
+| `indicators` | array | body | 是 | 成效指标，字符串数组，必传且不能为空数组。指标会在 dimensions 指定的分组粒度上做求和聚合。各指标含义：spend_usd（消耗金额，美元）、impressions（曝光量）、clicks（点击量）、video_views（视频观看次数）、add_to_cart（添加购物车次数）、checkouts（发起结账次数）、purchase（购买次数）、purchase_value（购买金额，美元）、installs（应用安装量）、complete_registration（完成注册量）、leads（留下潜客信息次数）、engagement（互动次数） |
+| `order` | string | body | 否 | 单字段排序的字段名，填单个 code，取值范围为 dimensions 或 indicators 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回。与 orders 可同时使用，order 指定的字段会追加到 orders 之后。 |
+| `orderType` | string | body | 否 | 排序方向，配合 order 使用。desc 降序，asc 升序，默认 asc。 |
+| `orders` | object | body | 否 | 多字段排序，结构为「字段名 → 排序方向」的有序键值对（Java 类型 LinkedHashMap<String, String>），按 key 的书写顺序依次排序，方向取值 desc 或 asc。示例：{"spend_usd":"desc","clicks":"asc"}。只需单字段排序时用 order + orderType 即可，不必传本字段。 |
+| `page` | integer | body | 否 | 页码，从 1 开始，默认 1。 |
+| `size` | integer | body | 否 | 每页条数，默认 10，建议显式指定。返回的 result.total 为总条数，据此判断是否还有下一页。 |
+
+## 5. Google广告策略成效数据
+
+`POST /sino-icenter/mcp/strategy/metrics/google/ad/list`
+
+主体上下文：`tenant=false`。
+
+角色范围：`sso/system`。
+
+风险：`read`。
+
+查询 Google 渠道广告的策略维度加成效指标数据。在广告策略配置（成效目标、创意类型、出价方式、广告系列类型、关键字等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。Google 渠道不支持广告目标和兴趣词包维度。
+
+【国家维度特别说明】
+country_code（国家）只能单独传，或与 calendar_date（投放日期）两个一起传；与其他任何维度同传都会报错「[country_code]只能和[calendar_date]同时传入」。
+传入 country_code 时服务端转走跨渠道广告数据接口取数，indicators 里的 12 个指标在该接口同样支持、照常返回聚合值，但有两点差异：
+一是 dimensionValues 里额外支持 country_code 作为过滤条件，传国家码数组即可按国家筛选；不传 country_code 维度时该过滤条件无效。
+二是 headerMap 的列名来自跨渠道接口，calendar_date 列名为「日期」而不是「投放日期」，country_code 列名为「国家/地区」；展示列名请以 headerMap 实际返回值为准，不要写死。
+
+【入参填写规则】
+1. startDate / endDate：字符串，格式 yyyy-MM-dd，两者都必填。
+2. dimensionValues：过滤条件，结构是「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>）。每个 key 是字段 code，对应的 value 必须是数组，即使只筛一个值也要用数组包裹；同一个 key 内的多个值之间是「或」关系，命中任意一个即返回。本接口默认只有 account_id 这一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件。传入其余 key 不会报错，但也不会产生任何过滤效果。
+3. dimensions：分组维度数组，必填。传多个维度时按多个字段组合分组，效果等同 SQL 的 GROUP BY 多列，维度越多返回行数越多、粒度越细。
+4. indicators：成效指标数组，必填。指标会在 dimensions 指定的分组粒度上做求和聚合。
+5. 排序：单字段排序用 order（字段名）+ orderType（desc / asc）；多字段排序用 orders，结构是「字段名 → 排序方向」的有序键值对，按书写顺序依次排序，例如 {"spend_usd":"desc","clicks":"asc"}。两者可同时使用，order 指定的字段会追加到 orders 之后。
+6. 分页：page 从 1 开始（默认 1），size 为每页条数（默认 10）。返回的 result.total 是总条数，据此判断是否还有下一页。
+
+【请求示例】
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": [
+      "<广告账户ID，格式同 account_id 维度返回值>"
+    ]
+  },
+  "dimensions": [
+    "calendar_date",
+    "optimization_goal"
+  ],
+  "indicators": [
+    "spend_usd",
+    "impressions",
+    "clicks"
+  ],
+  "order": "spend_usd",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+
+【返回格式】
+result.data 为数据行数组，每行的每个字段有两个 key：
+一是原始值，key 即请求的 code，如 spend_usd 的值为 618.42，做计算或比较时用这个；
+二是展示值，key 加 display_ 前缀，如 display_spend_usd 的值带货币符号，直接呈现给用户时用这个，空值为 "-"。
+result.headerMap 是字段 code 到列名的映射，维度列名为中文，指标列名为英文（如 spend_usd 对应 Spend）。
+result.total 为总条数，result.page 和 result.size 为当前分页。
+result.conflictField 是传入但当前渠道不支持的指标，会被忽略且不报错，为空数组表示全部指标都生效。
+
+**输入参数（--data）**
+
+| 字段 | 类型 | 位置 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `startDate` | string | body | 是 | 开始日期，格式 yyyy-MM-dd，例如 2026-08-01 |
+| `endDate` | string | body | 是 | 结束日期，格式 yyyy-MM-dd，例如 2026-08-31。最多支持查询近21天 |
+| `dimensionValues` | object | body | 是 | 过滤条件。结构为「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>），value 必须是数组，即使只筛一个值也要用数组包裹。本接口默认只有 account_id 一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件（国家码数组）。其余 key 传入不报错但无过滤效果。示例：{"account_id": ["act_123", "act_456"]} |
+| `dimensions` | array | body | 是 | 分组维度，必传且不能为空数组，否则返回结果为空。各维度含义：calendar_date（投放日期）、account_id（广告账户ID）、account_name（广告账户名称）、campaign_id（广告系列ID）、campaign_name（广告系列名称）、adgroup_id（广告组ID）、adgroup_name（广告组名称）、ad_id（广告ID）、ad_name（广告名称）、optimization_goal（成效目标）、ad_format（创意类型）、bid_strategy（出价方式）、audience_type（受众类型）、targeting_age（年龄）、targeting_genders（性别）、cpc_bid_amount（CPC出价）、cpm_bid_amount（CPM出价）、cpv_bid_amount（CPV出价）、advertising_channel_type（广告系列类型）、keywords（关键字）、country_code（国家，只能单独传或与 calendar_date 两个一起传） |
+| `indicators` | array | body | 是 | 成效指标，必传且不能为空数组。各指标含义：spend_usd（消耗金额，美元）、impressions（曝光量）、clicks（点击量）、video_views（视频观看次数）、add_to_cart（添加购物车次数）、checkouts（发起结账次数）、purchase（购买次数）、purchase_value（购买金额，美元）、installs（应用安装量）、complete_registration（完成注册量）、leads（留下潜客信息次数）、engagement（互动次数） |
+| `order` | string | body | 否 | 排序字段，填单个 code，取值范围为 dimensions 或 indicators 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| `orderType` | string | body | 否 | 排序方向，默认 asc |
+| `orders` | object | body | 否 | 多字段排序，结构为「字段名 → 排序方向」的有序键值对（Java 类型 LinkedHashMap<String, String>），按 key 的书写顺序依次排序，方向取值 desc 或 asc。示例：{"spend_usd":"desc","clicks":"asc"}。只需单字段排序时用 order + orderType 即可，不必传本字段。 |
+| `page` | integer | body | 否 | 页码，从1开始，默认1 |
+| `size` | integer | body | 否 | 每页条数，默认10，建议显式传且不超过1000 |
+
+## 6. TikTok广告策略成效数据
+
+`POST /sino-icenter/mcp/strategy/metrics/tiktok/ad/list`
+
+主体上下文：`tenant=false`。
+
+角色范围：`sso/system`。
+
+风险：`read`。
+
+查询 TikTok 渠道广告的策略维度加成效指标数据。在广告策略配置（广告目标、成效目标、创意类型、出价方式、转化出价、深度转化出价、兴趣词包等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
+
+【国家维度特别说明】
+country_code（国家）只能单独传，或与 calendar_date（投放日期）两个一起传；与其他任何维度同传都会报错「[country_code]只能和[calendar_date]同时传入」。
+传入 country_code 时服务端转走跨渠道广告数据接口取数，indicators 里的 12 个指标在该接口同样支持、照常返回聚合值，但有两点差异：
+一是 dimensionValues 里额外支持 country_code 作为过滤条件，传国家码数组即可按国家筛选；不传 country_code 维度时该过滤条件无效。
+二是 headerMap 的列名来自跨渠道接口，calendar_date 列名为「日期」而不是「投放日期」，country_code 列名为「国家/地区」；展示列名请以 headerMap 实际返回值为准，不要写死。
+
+【入参填写规则】
+1. startDate / endDate：字符串，格式 yyyy-MM-dd，两者都必填。
+2. dimensionValues：过滤条件，结构是「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>）。每个 key 是字段 code，对应的 value 必须是数组，即使只筛一个值也要用数组包裹；同一个 key 内的多个值之间是「或」关系，命中任意一个即返回。本接口默认只有 account_id 这一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件。传入其余 key 不会报错，但也不会产生任何过滤效果。
+3. dimensions：分组维度数组，必填。传多个维度时按多个字段组合分组，效果等同 SQL 的 GROUP BY 多列，维度越多返回行数越多、粒度越细。
+4. indicators：成效指标数组，必填。指标会在 dimensions 指定的分组粒度上做求和聚合。
+5. 排序：单字段排序用 order（字段名）+ orderType（desc / asc）；多字段排序用 orders，结构是「字段名 → 排序方向」的有序键值对，按书写顺序依次排序，例如 {"spend_usd":"desc","clicks":"asc"}。两者可同时使用，order 指定的字段会追加到 orders 之后。
+6. 分页：page 从 1 开始（默认 1），size 为每页条数（默认 10）。返回的 result.total 是总条数，据此判断是否还有下一页。
+
+【请求示例】
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": [
+      "<广告账户ID，格式同 account_id 维度返回值>"
+    ]
+  },
+  "dimensions": [
+    "calendar_date",
+    "optimization_goal"
+  ],
+  "indicators": [
+    "spend_usd",
+    "impressions",
+    "clicks"
+  ],
+  "order": "spend_usd",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+
+【返回格式】
+result.data 为数据行数组，每行的每个字段有两个 key：
+一是原始值，key 即请求的 code，如 spend_usd 的值为 618.42，做计算或比较时用这个；
+二是展示值，key 加 display_ 前缀，如 display_spend_usd 的值带货币符号，直接呈现给用户时用这个，空值为 "-"。
+result.headerMap 是字段 code 到列名的映射，维度列名为中文，指标列名为英文（如 spend_usd 对应 Spend）。
+result.total 为总条数，result.page 和 result.size 为当前分页。
+result.conflictField 是传入但当前渠道不支持的指标，会被忽略且不报错，为空数组表示全部指标都生效。
+
+**输入参数（--data）**
+
+| 字段 | 类型 | 位置 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `startDate` | string | body | 是 | 开始日期，格式 yyyy-MM-dd，例如 2026-08-01 |
+| `endDate` | string | body | 是 | 结束日期，格式 yyyy-MM-dd，例如 2026-08-31。最多支持查询近21天 |
+| `dimensionValues` | object | body | 是 | 过滤条件。结构为「字段名 → 取值数组」的键值对（Java 类型 Map<String, List<Object>>），value 必须是数组，即使只筛一个值也要用数组包裹。本接口默认只有 account_id 一个 key 生效；当 dimensions 里传了 country_code 时，额外支持 country_code 作为过滤条件（国家码数组）。其余 key 传入不报错但无过滤效果。示例：{"account_id": ["act_123", "act_456"]} |
+| `dimensions` | array | body | 是 | 分组维度，必传且不能为空数组，否则返回结果为空。各维度含义：calendar_date（投放日期）、account_id（广告账户ID）、account_name（广告账户名称）、campaign_id（广告系列ID）、campaign_name（广告系列名称）、adgroup_id（广告组ID）、adgroup_name（广告组名称）、ad_id（广告ID）、ad_name（广告名称）、optimization_goal（成效目标）、ad_format（创意类型）、bid_strategy（出价方式）、audience_type（受众类型）、targeting_age（年龄）、targeting_genders（性别）、objective（广告目标）、targeting_interests（兴趣词包）、conversion_bid（转化出价）、deep_cpabid（深度转化出价）、country_code（国家，只能单独传或与 calendar_date 两个一起传） |
+| `indicators` | array | body | 是 | 成效指标，必传且不能为空数组。各指标含义：spend_usd（消耗金额，美元）、impressions（曝光量）、clicks（点击量）、video_views（视频观看次数）、add_to_cart（添加购物车次数）、checkouts（发起结账次数）、purchase（购买次数）、purchase_value（购买金额，美元）、installs（应用安装量）、complete_registration（完成注册量）、leads（留下潜客信息次数）、engagement（互动次数） |
+| `order` | string | body | 否 | 排序字段，填单个 code，取值范围为 dimensions 或 indicators 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| `orderType` | string | body | 否 | 排序方向，默认 asc |
+| `orders` | object | body | 否 | 多字段排序，结构为「字段名 → 排序方向」的有序键值对（Java 类型 LinkedHashMap<String, String>），按 key 的书写顺序依次排序，方向取值 desc 或 asc。示例：{"spend_usd":"desc","clicks":"asc"}。只需单字段排序时用 order + orderType 即可，不必传本字段。 |
+| `page` | integer | body | 否 | 页码，从1开始，默认1 |
+| `size` | integer | body | 否 | 每页条数，默认10，建议显式传且不超过1000 |