Activity API Integration Document Generator (联调文档生成器)

Overview

Generate a complete frontend integration document for a Huiwan activity by combining:

1. Activity config JSON (from Apollo/admin) — identifies which widgets are used and their parameters
2. Activity code (model.go, route/, service/, store/) — documents custom interfaces
3. Feishu operation doc (optional) — adds business context and parameter explanations
4. Widget component knowledge — standard widget API reference

Execution Steps

Step 1: Gather Inputs

Required:

• act_id (integer)
• Activity config JSON (the full JSON blob from admin/Apollo, user must provide)

Optional:

• Feishu doc URL (e.g. https://wepie.feishu.cn/wiki/xxx) — if provided, use /feishu2md skill to convert it first

If user only provides act_id without config JSON, ask them to paste it.

Step 2: Read Feishu Doc (if URL provided)

Use the feishu2md skill to convert the Feishu doc to Markdown:

cd ~/.claude/skills/feishu2md\ 2
FEISHU_APP_ID=$FEISHU_APP_ID FEISHU_APP_SECRET=$FEISHU_APP_SECRET python3 scripts/feishu2md.py "<feishu_url>" /tmp/act_ops_doc.md

Read the output and use it as operational context for parameter descriptions.

Step 3: Parse Activity Config

From the config JSON, extract which components are used:

Config Key	Widget	API Prefix
lottery	Lottery (抽奖)	/activity_v2/lottery/
exchange_store	Exchange Store (兑换商店)	/activity_v2/exchange_store/
collect_chip	Collect Chip (活动碎片)	/activity_v2/collect_chip/
tasks + task_groups	Task Group (任务组)	/activity_v2/task_group/
tasks (without task_groups)	Level Task (阶段任务)	/activity_v2/level_task/
energy_config	Energy System (能量系统)	(embedded in gift events)
star_config	Star (星星抽奖)	(embedded in gift events)
gift_pkg	Gift Package (礼包)	/activity_v2/gift_pkg/
chain_gift_pkg	Chain Gift Pkg (连锁礼包)	/activity_v2/gift_pkg/
charge_coupon	Charge Coupon (充值优惠)	/activity_v2/level_task/ (task type)
collect_gifts	Collect Gift (礼物计数)	/activity_v2/collect_gift/
chip_notify	Chip Notify (碎片提醒)	(server-side only)
daily_task_repeat	Daily Task (每日任务)	/activity_v2/daily_task_repeat/
rank config in model.go	Rank (排行榜)	/activity_v2/rank/

Step 4: Identify Custom Activity Interfaces

Find the activity's model.go by searching for the act_id in the codebase:

grep -r "ActId = <act_id>" app/activity/

Then read model.go → GetRouter() to find all custom SubRouter entries.

For each custom route:

1. Read route/route.go to find the handler function
2. Read the request struct definition (in store/rsp.go or inline)
3. Read the service function to understand the logic
4. Read the response struct

Step 5: Generate the Document

Output a Markdown document with the following structure:

Hard requirement:

1. Every documented interface must include both a request example and a response example.
2. This applies to:
   • custom activity interfaces
   • standard widget/component interfaces
   • query interfaces, action interfaces, and reward-claim interfaces
3. If the real response struct is unknown, infer a minimal valid example from the handler/service logic and clearly keep the example structurally aligned with the project convention, typically:

   {"code":200,"msg":"success","data":{...}}
   

4. A document that lists an interface without both example input and example output is considered incomplete.

---

Output Template

# {activity_name} 联调文档

> act_id: {act_id}
> 活动时间: {start_time} ~ {end_time}
> 活动链接: {act_url}
> 运营文档: {doc_url}

## 一、基础信息

### 通用入参
所有接口都需要携带以下基础参数：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| act_id | int | 是 | 活动ID: {act_id} |
| uid | int | 是 | 用户ID |

### 碎片(道具)列表
| chip_id | fe_id | 名称 | 单价(金币) | 说明 |
|---------|-------|------|-----------|------|
(从 collect_chip 配置中提取)

### 礼物列表
| gift_id | 说明 |
|---------|------|
(从 gift_list 和 collect_gifts 配置中提取，结合运营文档补充名称)

## 二、活动自定义接口

(仅当活动有自定义路由时输出此节)

### 2.1 {action_name}
- **URL**: `POST /activity_v2/{domain}/{action}`
- **功能**: {从代码注释或service逻辑推断}
- **入参**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
(从 request struct 提取)

- **出参**:
```json
{从 response struct 生成示例JSON}

• 输入示例:

{"act_id": {act_id}, "uid": 12345, ...}

• 输出示例:

{"code": 200, "data": {...}}

三、组件接口

3.1 碎片组件 (collect_chip)

(仅当配置中有 collect_chip 时输出)

获取碎片数量

• URL: POST /activity_v2/collect_chip/get_collect_chip
• 入参: act_id, uid
• 出参: 各碎片当前数量
• 输入示例:

{"act_id": {act_id}, "uid": 12345}

• 输出示例:

{"code": 200, "data": {"list": [{"chip_id": 1, "num": 10}]}}

购买碎片

• URL: POST /activity_v2/collect_chip/buy_collect_chip
• 额外入参: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | chip_id | int | 是 | 碎片ID，可选值见碎片列表 | | number | int | 是 | 购买数量 |
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "chip_id": 1, "number": 5}

• 输出示例:

{"code": 200, "data": {"reward_list": [], "chip_num": 15}}

3.2 抽奖组件 (lottery)

(仅当配置中有 lottery 时输出)

本活动抽奖池列表:

type	fe_id	名称	消耗	box_type	说明
(从 lottery 配置中提取 type、name、cost_chip_meta_list、box_type)

执行抽奖

• URL: POST /activity_v2/lottery/do_lottery
• 额外入参: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | type | string | 是 | 抽奖类型，可选值见上表 | | number | int | 是 | 抽奖次数 | | box_type | int | 否 | 宝箱类型，对应上表 |
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "type": "lucky_bag", "number": 1}

• 输出示例:

{"code": 200, "data": {"reward_list": [{"reward_type": "prop", "reward_id": 1207089, "reward_val": 1}]}}

查询抽奖信息

• URL: POST /activity_v2/lottery/get_lottery_info
• 额外入参: type (string, 必填)
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "type": "lucky_bag"}

• 输出示例:

{"code": 200, "data": {"type": "lucky_bag", "cost_list": [], "reward_list": []}}

查询保底信息

• URL: POST /activity_v2/lottery/get_guarantee_info
• 额外入参: type (string, 必填)
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "type": "life_never_part"}

• 输出示例:

{"code": 200, "data": {"type": "life_never_part", "guarantee_num": 50, "current_num": 12}}

重置不放回轮次

• URL: POST /activity_v2/lottery/reset_round
• 额外入参: type (string, 必填)
• 说明: 仅 fe_lottery_mode="not_back" 的抽奖池使用
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "type": "lucky_value"}

• 输出示例:

{"code": 200, "data": {"success": true}}

3.3 兑换商店 (exchange_store)

(仅当配置中有 exchange_store 时输出)

本活动商店列表:

store_name	fe_id	商品数量	说明
(从 exchange_store 配置中提取)

兑换商品列表 (store_name: {name}):

exchange_type	fe_id	消耗	限购	奖励
(从 exchange 列表中提取 exchange_type、cost_chip_meta、limit、rewards)

获取商店配置

• URL: POST /activity_v2/exchange_store/get_config
• 额外入参: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | store_name | string | 否 | 商店名称，不传返回所有 |
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "store_name": "rabbit_coin"}

• 输出示例:

{"code": 200, "data": {"store_name": "rabbit_coin", "exchange_list": []}}

执行兑换

• URL: POST /activity_v2/exchange_store/exchange
• 额外入参: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | target_uid | int | 是 | 目标用户(通常传自己的uid) | | store_name | string | 是 | 商店名称 | | exchange_type | string | 是 | 兑换类型，见上表 | | exchange_count | int | 是 | 兑换数量 |
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "target_uid": 12345, "store_name": "rabbit_coin", "exchange_type": "21935", "exchange_count": 1}

• 输出示例:

{"code": 200, "data": {"reward_list": [{"reward_type": "avatar_prop", "reward_id": 21935, "reward_val": 0}]}}

获取兑换记录

• URL: POST /activity_v2/exchange_store/get_exchange_log
• 额外入参: store_name, offset, limit
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "store_name": "rabbit_coin", "offset": 0, "limit": 20}

• 输出示例:

{"code": 200, "data": {"list": [], "next_offset": 0}}

3.4 排行榜 (rank)

(仅当活动使用了排行榜组件时输出)

本活动排行榜列表:

rank_type	period_type	说明
(从活动代码或配置中提取)

获取排行榜列表

• URL: POST /activity_v2/rank/rank_list
• 额外入参: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | rank_type | string | 是 | 榜单类型，见上表 | | period_type | int | 是 | 周期：0=总榜 1=日榜 2=周榜 | | offset | int | 是 | 偏移量 | | limit | int | 是 | 每页数量 |
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "rank_type": "gift_rank", "period_type": 0, "offset": 0, "limit": 20}

• 输出示例:

{"code": 200, "data": {"list": [], "self_rank": {"rank": 0, "score": 0}}}

获取我的排名

• URL: POST /activity_v2/rank/rank_info
• 额外入参: rank_type, period_type
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "rank_type": "gift_rank", "period_type": 0}

• 输出示例:

{"code": 200, "data": {"rank": 12, "score": 3456}}

3.5 任务组 (task_group)

(仅当配置中有 task_groups 时输出)

本活动任务组:

group_id	名称	包含任务ID
(从 task_groups 配置中提取)

任务列表:

task_id	fe_id	名称	触发条件	阶段数	是否自动发奖
(从 tasks 配置中提取)

获取任务组列表

• URL: POST /activity_v2/task_group/get_group_list
• 入参: act_id, uid
• 输入示例:

{"act_id": {act_id}, "uid": 12345}

• 输出示例:

{"code": 200, "data": {"group_list": []}}

获取单个任务信息

• URL: POST /activity_v2/task_group/get_task_info
• 额外入参: task_id (int, 必填)
• 输入示例:

{"act_id": {act_id}, "uid": 12345, "task_id": 1}

• 输出示例:

{"code": 200, "data": {"task_id": 1, "stage_list": []}}

领取任务奖励

• URL: POST /activity_v2/task_group/receive_task_reward
• 额外入参: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | task_id | int | 是 | 任务ID | | stage_id | int | 否 | 阶段ID |

批量领取

• URL: POST /activity_v2/task_group/batch_receive_task_reward
• 额外入参: task_id_str (string, 逗号分隔的task_id)

3.6 阶段任务 (level_task)

(仅当配置中有 tasks 但无 task_groups 时输出)

获取任务进度

• URL: POST /activity_v2/level_task/get_task_status
• 额外入参: type (string, 任务类型标识)

批量获取任务进度

• URL: POST /activity_v2/level_task/get_task_status_list
• 额外入参: type_list (string, 逗号分隔)

领取奖励

• URL: POST /activity_v2/level_task/recv_reward
• 额外入参: type, stage (int, 阶段编号)

3.7 礼包 (gift_pkg)

(仅当配置中有 gift_pkg 或 chain_gift_pkg 时输出)

本活动礼包列表:

pkg_id	fe_id	最大购买次数	说明
(从 gift_pkg.list 中提取)

连锁礼包 (如有):

层级	pkg_id	说明
(从 chain_gift_pkg.chain_list 中提取)

3.8 充值优惠 (charge_coupon)

(仅当配置中有 charge_coupon 时输出)

• 触发条件: 累计消耗 {coin_cost} 金币
• 额外优惠次数: {extra_times}
• 说明: 通过 task (id=对应task) 的 stage 达标自动触发

3.9 能量系统 (energy_system)

(仅当配置中有 energy_config 时输出)

能量玩法列表:

source	触发礼物	触发方式	轮次数	说明
(从 energy_config.gift_configs 中提取)

3.10 星星抽奖 (star)

(仅当配置中有 star_config 时输出)

• 抽奖池: {lottery_type}
• 触发礼物: {star_gift_id}
• 碎片: star={chip_id_star}, guarantee={chip_id_guarantee_star}, chance={chip_id_chance_star}

四、通用组件接口参考

获取活动时间

• URL: POST /activity_v1/common/get_act_date
• 入参: act_id
• 出参: start_time, end_time

获取用户基本信息

• URL: POST /activity_v1/common/get_userinfo
• 入参: act_id, uid

获取服务器时间

• URL: POST /activity_v1/common/get_now_time

---

## Key Rules

1. **Only document components that exist in the config** — don't include lottery section if no `lottery` key
2. **Use actual values from config** — fill in real chip_ids, lottery types, store names, exchange_types
3. **Combine with Feishu doc context** — when the operations doc describes a feature, reference that description in the API doc
4. **EVERY interface MUST include ALL four parts (NON-NEGOTIABLE, applies to BOTH widget component interfaces AND custom activity interfaces)**:
   - **入参表格**: 列出每个参数的 名称/类型/必填/说明，包括通用的 act_id、uid
   - **出参表格**: 列出响应 data 中每个字段的 名称/类型/说明，解释每个字段的业务含义
   - **请求示例**: 用真实 act_id 和配置中的真实参数值的完整 JSON
   - **响应示例**: 包含完整 JSON 结构，字段值要合理
   This applies to ALL interfaces without exception:
   - Widget interfaces: collect_chip, lottery, exchange_store, rank, task_group, level_task, gift_pkg, etc.
   - Custom activity interfaces: from model.go GetRouter()
   - Common interfaces: get_act_date, get_userinfo, get_now_time
   Even the simplest interface (only act_id+uid) must show all four parts. Missing any part = document is incomplete.
5. **For custom interfaces** — read the actual Go code, don't guess the parameters
6. **Chinese output** — the document should be in Chinese since it's for internal use
7. **Output to working directory** — save as `{activity_name}_联调文档.md`

## Config Parameter Mapping Quick Reference

| Config Field | Maps to API Parameter |
|---|---|
| `lottery[].type` | `do_lottery` 的 `type` 参数 |
| `lottery[].cost_chip_meta_list[].cost_chip_meta` | 抽奖消耗的碎片 |
| `lottery[].fe_lottery_mode` | 抽奖模式(normal/not_back) |
| `exchange_store[].store_name` | `exchange` 的 `store_name` 参数 |
| `exchange_store[].exchange[].exchange_type` | `exchange` 的 `exchange_type` 参数 |
| `exchange_store[].exchange[].cost_chip_meta` | 兑换消耗 |
| `collect_chip[].chip_id` | `buy_collect_chip` 的 `chip_id` 参数 |
| `collect_chip[].price` | 碎片单价(金币) |
| `tasks[].id` | `task_id` 参数 |
| `tasks[].condition_config.condition_list[].trigger.type` | 任务触发类型 |
| `task_groups[].id` | `group_id` 参数 |
| `gift_pkg.list[].pkg_id` | 礼包购买ID |
| `energy_config.gift_configs.{gift_id}` | 能量系统关联的礼物ID |