---
name: 福利品用户名单
slug: welfare-user-list
version: 1.0.0
description: 统计拥有两个年包课包（level1+level2 / 双level1 / 双level2）的福利品发放用户，关联收货地址并生成多 Sheet Excel。
---

## When to Use

用户提到"福利品"、"两个年包"、"发福利"、"level1+level2用户"、"双年包用户统计"时触发。

## Core Rules

1. **先确认日期范围。** 如果用户未指定日期范围，默认不限制日期；用户可以指定 `pay_success_date` 的起止日期（含当日）。

2. **三步执行流程：**
   - **第一步：** 读入 `scripts/welfare_query.sql`，将 `${DATE_FILTER}` 替换为实际日期条件（有日期则 `AND pay_success_date::date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'`，无则注释掉），在 `vala_bi` 库执行，结果保存到 `output/welfare_step1_result.txt`
   - **第二步：** 从第一步结果提取 `account_id` 列表，查询 `vala_class.parent_address` 获取收货地址（name, phone_number, region, address），保存到 `output/parent_address_result.txt`
   - **第三步：** 运行 `python3 skills/welfare-user-list/scripts/welfare_merge.py output/welfare_step1_result.txt [起始日期] [结束日期]` 生成最终 Excel

3. **三种判定情况：**
   - 情况1：goods_id=61（level1+2）且无任何退费
   - 情况2：goods_id IN (31,60) 至少 2 笔有效订单，最多 1 笔 400 元部分退费
   - 情况3：goods_id IN (31,60) 至少 1 笔无退费 + goods_id=61 有 1 笔退费 1999 元

4. **数据清洗：** 剔除 pay_amount_int < 100,000 分的异常低价订单；输出前按 (account_id, trade_no) 去重。

5. **输出 Excel 三个 Sheet：** 福利品用户名单（完整订单明细）、统计汇总、用户地址汇总（按用户去重仅保留地址字段）。

6. **发送文件时附上统计摘要：** 总用户数、有/无地址数、三种情况用户分布。

7. **默认发送群组：** Excel 生成后，默认发送到群聊 `oc_3cf45dda24e78c29ccc477dddcd724a5`（福利品相关群），使用 `message` 工具 `action=send` + `filePath` 发送文件并附统计摘要。除非用户明确指定其他发送目标。

## Quick Reference

| 内容 | 文件 |
|------|------|
| SQL 查询模板 | `scripts/welfare_query.sql` |
| Python 合并脚本 | `scripts/welfare_merge.py` |
| 数据库连接 | 见 `TOOLS.md`：`vala_bi`（订单/退费）和 `vala_class`（地址） |
| 年包 goods_id | 31（level2/年包）、60（level1）、61（level1+2） |
| 退费关键金额 | 400 元 = 40,000 分 / 1999 元 = 199,900 分 |
| goods_id=61 价格 | 3,598 元 |

## Database Credentials

使用 `TOOLS.md` 中已有的 Online PostgreSQL 只读连接：
- 主机：`bj-postgres-16pob4sg.sql.tencentcdb.com:28591`
- 数据库：`vala_bi`（订单/退费/账号表）、`vala_class`（parent_address 表）
- 用户：`ai_member`，密码从 `secrets.env` 中 `$PG_ONLINE_PASSWORD` 读取