营销模块

营销模块面向平台管理员，提供代金券的全生命周期管理，包括活动创建、券类型定义、批量生成券码、自动/手动发放和数据统计。

用户侧的代金券查看与兑换在钱包模块（03）。
下单时使用代金券，在订单模块（05）的 voucher_id 字段传入。

活动（Campaign）
  └── 券类型（VoucherType）—— 定义面值/有效期/使用条件
        └── 券码（VoucherCode）—— 批量生成的实体码
              └── 发放记录（Distribution）—— 发给哪个用户

14.1 营销活动管理

活动列表

GET /admin/v1/marketing/campaigns

查询参数	说明
`status`	`draft` / `active` / `paused` / `ended`
`page`	页码

{
  "code": 0,
  "data": {
    "items": [
      {
        "campaign_id": "camp_01HX...",
        "name": "新用户注册礼包",
        "description": "新注册用户即送 20 元代金券",
        "status": "active",
        "trigger": "user_register",
        "start_at": "2024-01-01T00:00:00Z",
        "end_at": "2024-06-30T23:59:59Z",
        "budget_total": "50000.00",
        "budget_used": "12400.00",
        "issued_count": 620,
        "redeemed_count": 310,
        "redeem_rate": "50%"
      }
    ]
  }
}

创建活动

POST /admin/v1/marketing/campaigns

{
  "name": "五一充值优惠",
  "description": "五一期间充值满 200 元赠 30 元券",
  "trigger": "recharge_threshold",
  "start_at": "2024-05-01T00:00:00Z",
  "end_at": "2024-05-07T23:59:59Z",
  "budget_total": "10000.00"
}

活动详情

GET /admin/v1/marketing/campaigns/{campaign_id}

编辑活动

PUT /admin/v1/marketing/campaigns/{campaign_id}

上线活动

POST /admin/v1/marketing/campaigns/{campaign_id}/launch

暂停活动

POST /admin/v1/marketing/campaigns/{campaign_id}/pause

终止活动

POST /admin/v1/marketing/campaigns/{campaign_id}/end

活动统计

GET /admin/v1/marketing/campaigns/{campaign_id}/stats

{
  "code": 0,
  "data": {
    "campaign_id": "camp_01HX...",
    "issued_count": 620,
    "redeemed_count": 310,
    "redeem_rate": "50%",
    "total_discount_given": "6200.00",
    "converted_recharge": "98500.00",
    "roi": "15.9x",
    "daily_trend": [
      { "date": "2024-01-01", "issued": 45, "redeemed": 22 }
    ]
  }
}

14.2 券类型管理

券类型列表

GET /admin/v1/marketing/voucher-types

查询参数	说明
`campaign_id`	按活动筛选

{
  "code": 0,
  "data": {
    "items": [
      {
        "type_id": "vtype_01HX...",
        "campaign_id": "camp_01HX...",
        "name": "新用户礼包 - 20元券",
        "voucher_type": "fixed_amount",
        "amount": "20.00",
        "min_recharge": "0.00",
        "applicable_models": [],
        "valid_days": 30,
        "per_user_limit": 1,
        "total_limit": 10000,
        "issued_count": 620
      }
    ]
  }
}

券类型（voucher_type）枚举：

值	说明	示例
`fixed_amount`	固定金额抵扣	满 0 可用 20 元
`percentage`	折扣券	首充 9 折
`free_tokens`	赠送 Token 额度	送 100 万 tokens
`model_trial`	指定模型免费试用次数	gpt-4o 免费调用 10 次

创建券类型

POST /admin/v1/marketing/voucher-types

{
  "campaign_id": "camp_01HX...",
  "name": "新用户礼包 - 20元券",
  "voucher_type": "fixed_amount",
  "amount": "20.00",
  "min_recharge": "0.00",
  "applicable_models": [],
  "valid_days": 30,
  "per_user_limit": 1,
  "total_limit": 10000
}

券类型详情

GET /admin/v1/marketing/voucher-types/{type_id}

更新券类型

PUT /admin/v1/marketing/voucher-types/{type_id}

删除券类型

DELETE /admin/v1/marketing/voucher-types/{type_id}

14.3 券码批量生成

批量生成券码

POST /admin/v1/marketing/voucher-codes/generate

{
  "type_id": "vtype_01HX...",
  "quantity": 1000,
  "code_prefix": "NEW2024",
  "code_length": 12
}

响应（异步任务）：

{
  "code": 0,
  "data": {
    "task_id": "gen_task_01HX...",
    "type_id": "vtype_01HX...",
    "quantity": 1000,
    "status": "processing",
    "estimated_seconds": 5
  }
}

查询生成任务状态

GET /admin/v1/marketing/voucher-codes/generate/{task_id}

{
  "code": 0,
  "data": {
    "task_id": "gen_task_01HX...",
    "status": "completed",
    "generated_count": 1000,
    "download_url": "https://oss.example.com/exports/codes_xxx.csv",
    "download_expires_at": "2024-01-01T13:00:00Z"
  }
}

券码列表

GET /admin/v1/marketing/voucher-codes

查询参数	说明
`campaign_id`	按活动筛选
`type_id`	按券类型筛选
`status`	`unused` / `issued` / `used` / `expired`

查询指定券码详情

GET /admin/v1/marketing/voucher-codes/{code}

{
  "code": 0,
  "data": {
    "code": "NEW2024XXXXXXXX",
    "type_id": "vtype_01HX...",
    "status": "used",
    "issued_to_user_id": "u_01HX...",
    "issued_at": "2024-01-01T12:00:00Z",
    "used_at": "2024-01-02T10:00:00Z"
  }
}

导出券码

GET /admin/v1/marketing/voucher-codes/export

14.4 自动发放规则

规则列表

GET /admin/v1/marketing/distribution-rules

{
  "code": 0,
  "data": {
    "items": [
      {
        "rule_id": "rule_01HX...",
        "name": "新用户注册礼包规则",
        "trigger": "user_register",
        "conditions": {
          "user_type": "personal"
        },
        "voucher_type_id": "vtype_01HX...",
        "status": "enabled",
        "total_issued": 620,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

触发条件（trigger）枚举：

值	触发时机	营销目标
`user_register`	新用户注册	降低首次使用门槛
`first_recharge`	首次充值	促进首充转化
`recharge_threshold`	充值满额	提升客单价
`membership_subscribe`	订阅会员	会员开通激励
`invitation_success`	邀请好友注册成功	裂变拉新
`birthday`	用户生日	提升用户粘性
`inactive_user`	用户 N 天未登录	召回流失用户

创建自动发放规则

POST /admin/v1/marketing/distribution-rules

{
  "name": "新用户注册礼包规则",
  "trigger": "user_register",
  "conditions": {
    "user_type": "personal"
  },
  "voucher_type_id": "vtype_01HX..."
}

更新规则

PUT /admin/v1/marketing/distribution-rules/{rule_id}

删除规则

DELETE /admin/v1/marketing/distribution-rules/{rule_id}

启用规则

POST /admin/v1/marketing/distribution-rules/{rule_id}/enable

禁用规则

POST /admin/v1/marketing/distribution-rules/{rule_id}/disable

14.5 手动发放

手动向指定用户发放

POST /admin/v1/marketing/distribute

{
  "user_ids": ["u_01HX...", "u_02HX..."],
  "voucher_type_id": "vtype_01HX...",
  "reason": "用户投诉补偿"
}

响应：

{
  "code": 0,
  "data": {
    "success_count": 2,
    "failed_count": 0,
    "failed_users": []
  }
}

批量发放（上传 CSV）

POST /admin/v1/marketing/distribute/batch

Content-Type: multipart/form-data

file: user_ids.csv
voucher_type_id: vtype_01HX...
reason: 活动补偿

CSV 格式（第一列为 user_id）：

u_01HX...
u_02HX...
u_03HX...

发放记录

GET /admin/v1/marketing/distributions

查询参数	说明
`campaign_id`	按活动筛选
`user_id`	按用户筛选
`trigger`	按触发方式筛选（`auto` / `manual`）
`page`	页码

{
  "code": 0,
  "data": {
    "items": [
      {
        "dist_id": "dist_01HX...",
        "user_id": "u_01HX...",
        "voucher_type_id": "vtype_01HX...",
        "voucher_code": "NEW2024XXXXXXXX",
        "trigger": "auto",
        "trigger_event": "user_register",
        "issued_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

14-marketing-api.md