@bluevs/vhcli 0.5.8 → 0.5.9

package/skill/docs/material-report.md

@@ -0,0 +1,191 @@
+# Material Report - 素材与广告效果报表
+
+> 素材报表、归因报表（Adjust/AppsFlyer）、TikTok 素材报表、广告预览。
+
+---
+
+## get
+
+获取素材报表（Meta/Google/TikTok 等平台）。
+
+**CLI:**
+```bash
+vhcli material-report get \
+  --customer-project-id <int> \
+  --platform <Meta|Google|TikTok> \
+  --start-time 2025-01-01 \
+  --end-time 2025-01-31 \
+  [--campaign-names <name1,name2>] \
+  [--ad-group-name <name>] \
+  [--ad-name <name>] \
+  [--material-name <name>] \
+  [--material-formats <image,video>] \
+  [--account-ids <id1,id2>] \
+  [--page-size 20] [--page-num 1] \
+  [--order-param <field:asc|desc>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| customer_project_id | int32 | ✅ | | 客户项目 ID |
+| platform | string | ✅ | | 广告平台（Meta/Google/TikTok） |
+| start_time | string | ✅ | | 开始日期（2025-01-01） |
+| end_time | string | ✅ | | 结束日期（2025-01-01） |
+| campaign_names | []string | | | 广告系列名称过滤 |
+| ad_group_name | string | | | 广告组名模糊搜索 |
+| ad_name | string | | | 广告名模糊搜索 |
+| material_name | string | | | 素材名模糊搜索 |
+| material_formats | []string | | | 素材格式（image/video） |
+| account_ids | []string | | | 账户 ID 过滤 |
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+| order_param | Sort | | | 排序（字段+顺序） |
+
+**响应:** MaterialReportData（含 pagination + list）
+
+---
+
+## filter
+
+获取素材报表筛选选项（可用的 campaign 名称列表）。
+
+**CLI:**
+```bash
+vhcli material-report filter \
+  --customer-project-id <int> \
+  --platform <Meta|Google|TikTok> \
+  --start-time 2025-01-01 \
+  --end-time 2025-01-31 \
+  [--campaign-name <fuzzy>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| platform | string | ✅ | 广告平台 |
+| start_time | string | ✅ | 开始日期 |
+| end_time | string | ✅ | 结束日期 |
+| campaign_name | string | | Campaign 名模糊搜索 |
+
+**响应:** []string（campaign 名称列表）
+
+---
+
+## adjust
+
+获取 Adjust 归因报表。
+
+**CLI:**
+```bash
+vhcli material-report adjust \
+  --customer-project-id <int> \
+  --start-time 2025-01-01 \
+  --end-time 2025-01-31 \
+  [--keyword <search>] \
+  [--page-size 20] [--page-num 1] \
+  [--order-param <field:asc|desc>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| customer_project_id | int32 | ✅ | | 客户项目 ID |
+| start_time | string | ✅ | | 开始日期 |
+| end_time | string | ✅ | | 结束日期 |
+| keyword | string | | | 关键词搜索 |
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+| order_param | Sort | | | 排序 |
+
+**响应:** AdjustReportData（含 pagination + list）
+
+---
+
+## appsflyer
+
+获取 AppsFlyer 归因报表。
+
+**CLI:**
+```bash
+vhcli material-report appsflyer \
+  --customer-project-id <int> \
+  --start-time 2025-01-01 \
+  --end-time 2025-01-31 \
+  [--keyword <search>] \
+  [--page-size 20] [--page-num 1] \
+  [--order-param <field:asc|desc>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| customer_project_id | int32 | ✅ | | 客户项目 ID |
+| start_time | string | ✅ | | 开始日期 |
+| end_time | string | ✅ | | 结束日期 |
+| keyword | string | | | 关键词搜索 |
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+| order_param | Sort | | | 排序 |
+
+**响应:** AppsFlyerReportData（含 pagination + list）
+
+---
+
+## tiktok
+
+获取 TikTok 素材报表。
+
+**CLI:**
+```bash
+vhcli material-report tiktok \
+  --customer-project-id <int> \
+  --platform TikTok \
+  --start-time 2025-01-01 \
+  --end-time 2025-01-31 \
+  [--page-size 20] [--page-num 1]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| customer_project_id | int32 | ✅ | | 客户项目 ID |
+| platform | string | ✅ | | 广告平台 |
+| start_time | string | ✅ | | 开始日期 |
+| end_time | string | ✅ | | 结束日期 |
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+
+**响应:** TikTokMaterialReportData（含 pagination + list）
+
+---
+
+## ad-preview
+
+获取广告预览 iframe HTML。
+
+**CLI:**
+```bash
+vhcli material-report ad-preview \
+  --customer-project-id <int> \
+  --platform <Meta|Google|TikTok> \
+  --ad-id <string> \
+  --account-id <string>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| platform | string | ✅ | 广告平台 |
+| ad_id | string | ✅ | 广告 ID |
+| account_id | string | ✅ | 广告账户 ID |
+
+**响应:** string（iframe HTML）

package/skill/docs/project.md

@@ -0,0 +1,435 @@
+# Project - 项目管理
+
+> 项目查询、账户管理、成员管理、授权配置、功能开关。
+
+---
+
+## list
+
+列出项目，支持分页和搜索。
+
+**CLI:**
+```bash
+vhcli project list [--page-size 20] [--page-num 1] [--project-name <name>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+| project_name | string | | | 按项目名搜索 |
+
+**响应:** ProjectListData（含 pagination + list）
+
+---
+
+## info
+
+获取项目基本信息和知识库。
+
+**CLI:**
+```bash
+vhcli project info --project-id <po_xxx>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | ✅ | 项目 ID（po_xxxx） |
+
+**响应:** ProjectInfoData
+- project, alliance, members, switches, affiliate_operators, brand_category
+
+---
+
+## accounts
+
+获取项目下的广告账户列表。
+
+**CLI:**
+```bash
+vhcli project accounts --project-id <po_xxx> [--platform-list Meta,Google]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | ✅ | 项目 ID |
+| platform_list | string | | 逗号分隔的平台过滤 |
+
+**响应:** []AccountListItem（含 account_list + platform）
+
+---
+
+## account_token
+
+获取广告账户的 access token。
+
+**CLI:**
+```bash
+vhcli project account-token --customer-project-id <int> --account-id <string>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID（数字） |
+| account_id | string | ✅ | 广告账户 ID |
+
+**响应:** AccountTokenData（含 access_token）
+
+---
+
+## resource
+
+获取项目资源（账户和 campaign）。
+
+**CLI:**
+```bash
+vhcli project resource --project-id <po_xxx>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | ✅ | 项目 ID |
+
+**响应:** ProjectResourceData（含 accounts + campaigns）
+
+---
+
+## config_list
+
+获取项目授权配置（绑定了哪些第三方平台授权）。
+
+**CLI:**
+```bash
+vhcli project config-list --customer-project-id <int> [--config-key Meta]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| config_key | string | | 按平台过滤（Meta/TikTok/Google/Impact/Snapchat） |
+
+**响应:** ConfigListData（含 list）
+
+---
+
+## config_save
+
+保存项目授权配置。原子性替换所有配置。⚠️ 需要项目管理员权限，需 `--yes` 确认。
+
+**CLI:**
+```bash
+vhcli project config-save --customer-project-id <int> --config-list '<json>' --yes
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| config_list | []ConfigEntry | ✅ | [{config_key, config_value}] 数组 |
+
+**响应:** CommonResponse
+
+---
+
+## account_discover
+
+发现授权下可用的广告账户。用于添加账户前的探索步骤。
+
+**前置依赖:** 先调用 `config_list` 和 `account_organizations` 获取 authorization_id 和 organization_id。
+
+**CLI:**
+```bash
+vhcli project account-discover \
+  --customer-project-id <int> \
+  --config-key <Meta|TikTok|Google> \
+  --authorization-id <string> \
+  [--organization-id <string>] \
+  [--search <keyword>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| config_key | string | ✅ | 平台名 |
+| authorization_id | string | ✅ | 授权 ID（从 config_list 获取） |
+| organization_id | string | | 组织 ID（部分平台可选） |
+| search | string | | 搜索关键词 |
+
+**响应:** []AccountByAuthData（含 config_key + authorization_id + account_item）
+
+---
+
+## account_organizations
+
+获取授权下的组织列表。添加账户前的中间步骤。
+
+**前置依赖:** 先调用 `config_list` 获取 authorization_id。
+
+**CLI:**
+```bash
+vhcli project account-organizations \
+  --customer-project-id <int> \
+  --config-key <Meta|TikTok|Google> \
+  --authorization-id <string>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| config_key | string | ✅ | 平台名 |
+| authorization_id | string | ✅ | 授权 ID |
+
+**响应:** []OrganizationItem（含 organization_id + organization_name）
+
+---
+
+## account_add
+
+添加广告账户到项目。⚠️ 必须先调用 `account_discover`，只接受其返回的账户 ID。需 `--yes` 确认。
+
+**前置依赖:** config_list → account_organizations → account_discover
+
+**CLI:**
+```bash
+vhcli project account-add \
+  --customer-project-id <int> \
+  --platform <Meta|TikTok|Google|Impact|Snapchat|Awin|Adjust|AppsFlyer> \
+  --ads-account-list '<json>' \
+  --yes
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| platform | string | ✅ | 平台 |
+| ads_account_list | []AdsAccountEntry | ✅ | [{account_id, account_name, authorization_id, organization_id, medium}] |
+
+**响应:** CommonResponse
+
+---
+
+## account_enable / account_disable
+
+启用/禁用项目中的广告账户。需项目管理员权限。
+
+**CLI:**
+```bash
+vhcli project account-enable --customer-project-id <int> --ads-account-list <id1,id2>
+vhcli project account-disable --customer-project-id <int> --ads-account-list <id1,id2>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| ads_account_list | []string | ✅ | 要操作的账户 ID 列表 |
+
+**响应:** CommonResponse
+
+---
+
+## account_remove
+
+从项目中移除广告账户。⚠️ 需项目管理员权限，需 `--yes` 确认。
+
+**CLI:**
+```bash
+vhcli project account-remove \
+  --customer-project-id <int> \
+  --ads-account-list <id1,id2> \
+  --platform <Meta|TikTok|Google|Impact|Snapchat|Awin> \
+  --yes
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| ads_account_list | []string | ✅ | 要移除的账户 ID |
+| platform | string | ✅ | 平台 |
+
+**响应:** CommonResponse
+
+---
+
+## members_list
+
+列出项目成员。
+
+**CLI:**
+```bash
+vhcli project members-list --customer-project-id <int> [--keyword <search>] [--page-num 1] [--page-size 20]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| customer_project_id | int32 | ✅ | | 客户项目 ID |
+| keyword | string | | | 搜索关键词 |
+| page_num | int32 | | 1 | 页码 |
+| page_size | int32 | | 20 | 每页条数 |
+
+**响应:** MembersListData（含 list + pagination）
+
+---
+
+## members_add
+
+添加成员到项目（幂等）。需项目管理员权限。
+
+**CLI:**
+```bash
+vhcli project members-add --customer-project-id <int> --user-ids <id1,id2>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| user_ids | []int32 | ✅ | 要添加的用户 ID 列表 |
+
+**响应:** CommonResponse
+
+---
+
+## members_remove
+
+从项目移除成员。⚠️ 需项目管理员权限，需 `--yes` 确认。
+
+**CLI:**
+```bash
+vhcli project members-remove --customer-project-id <int> --user-id <int> --yes
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| user_id | int32 | ✅ | 要移除的用户 ID |
+
+**响应:** CommonResponse
+
+---
+
+## members_update_role
+
+更新成员角色。需项目管理员权限。
+
+**CLI:**
+```bash
+vhcli project members-update-role --customer-project-id <int> --user-id <int> --role <admin|user>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| user_id | int32 | ✅ | 用户 ID |
+| role | string | ✅ | 新角色（admin / user） |
+
+**响应:** CommonResponse
+
+---
+
+## members_roles
+
+获取可分配的角色列表。
+
+**CLI:**
+```bash
+vhcli project members-roles
+```
+
+**响应:** []RoleItem（含 role_key + role_name）
+
+---
+
+## members_transfer_owner
+
+转让项目所有权。⚠️ 需项目所有者权限，需 `--yes` 确认。
+
+**CLI:**
+```bash
+vhcli project members-transfer-owner --customer-project-id <int> --new-owner-id <int64> [--transfer-reason <text>] --yes
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| new_owner_id | int64 | ✅ | 新所有者用户 ID |
+| transfer_reason | string | | 转让原因 |
+
+**响应:** CommonResponse
+
+---
+
+## switch_list
+
+获取项目功能开关列表。
+
+**CLI:**
+```bash
+vhcli project switch-list --customer-project-id <int> [--switch-key material_report,adjust_report]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| switch_key | []string | | 过滤开关：material_report / adjust_report / appsflyer_report / chat_analysis / affiliate_anomaly_det / affiliate_operator |
+
+**响应:** SwitchListData（含 list）
+
+---
+
+## switch_save
+
+保存项目功能开关。需项目管理员权限。
+
+**CLI:**
+```bash
+vhcli project switch-save \
+  --customer-project-id <int> \
+  --switch-key <key> \
+  --switch-status <enable|disable> \
+  [--switch-value <value>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID |
+| switch_key | string | ✅ | 开关名 |
+| switch_status | string | ✅ | enable / disable |
+| switch_value | string | | 开关值（取决于类型） |
+
+**响应:** CommonResponse