---
name: full-data-refresh
description: |
  细水入海 — 销售数据全量刷新技能。
  从飞书销售三表（小龙/吴迪/成都）读取手机号 → XXTEA 加密匹配 PG 数据库 UID →
  查询订单/退费/行课数据 → 回填销售表各列 → 汇总写入订单汇总。
  触发词：细水入海、全量刷新、跑全量、full refresh、刷新销售数据
metadata:
  openclaw:
    requires: { "tools": ["exec"] }
    categories: ["data", "sales", "feishu"]
---

# 细水入海 — 销售数据全量刷新

> **版本：** v3.0（2026-06-18 · UID 口径 · 删 X 列订单号）
> **协作契约：** `xhs-ark-dashboard/docs/bot-uid-centric-orders-v1.md`
> **大麦侧主文档：** `xhs-ark-dashboard/docs/damai-full-refresh-skill.md`
>
> ### v3.0 变更（2026-06-18 · 列契约更新）
> - **三表 A–Y（25列）：** 物理删除 X 列（订单号），X→有效0/1，Y→渠道归属
> - **汇总 1 UID = 1 行：** 按 UID 去重聚合 N/O/P，W 留空（不再写 trade_no）
> - **gate 门禁：** X=1（GSV>0 且非全额退且 K≥C）
> - **线索绑单（Step 4）仍用 `pick_valid_order()` 不变**

## 核心架构规则（写死，不可漂移）

### 1. Step 4 + Step 5 同一 run · 共用数据源
- 三表写入（Step 4）和订单汇总重建（Step 5）在**同一个 `sales_leads_full_refresh.py` 执行**中完成
- 共用 `pick_valid_order()` 函数 + 同一份 `db_info` 数据
- 禁止分两次 run 或使用不同数据源

### 2. 汇总 W 留空（不再写 trade_no）
- 订单汇总 W 列留空，不再写订单号
- 汇总唯一真源 = 三表 X=1 gate 的 unique UID
- 1 UID = 1 行，按 UID 聚合 N/O/P

### 3. 2smjwA：clear → UID gate 全量覆盖
- 先 `clear_summary_sheet()` 清空旧数据区
- 再 gate 全量重建：从三表 X=1 行收集 unique UID → 每 UID 一行
- **不保留旧 W**，不 append
- 同 UID 多进线 → 只保留行号最小的 1 行

### 4. 「保留 X/Y」只三表 mirror，不含汇总
- 三表 D/I/J 只补空、G 列不动 → 这些是 mirror 规则
- 汇总 2smjwA **永远全量清空重写**，不保留任何旧行

### 5. 线索 1进线=1行 · 只绑有效单
- 三表永远 1 次进线 = 1 行，不因多单拆行
- X=1 时 K/L/M/N/O/P 全写有效主单真实值
- 已退单不写旧 K/L（`pick_valid_order` 自动跳过全额退 + K<C 的订单）
- 无有效单 → X=0，K/L 留空

### 6. 完成后群回「full_refresh 完成」
- 在数据更新群（`oc_4687e8f9f38e4f5c819238c78f97ae44`）回复
- 附带验证结果：gate UID 数 = 汇总 UID 数

## 验收标准

Cursor 侧跑（大麦可自测）：
- `audit_xishui_orders.py --strict`
- `audit_lead_primary_order_bind.py`

PASS 条件：
- unique UID 三表 = 汇总
- 绑单审计 E1–E9 全部 0
- 孤儿 UID（有 UID 但 X≠1）= 0

## 脚本位置

所有脚本位于大麦 workspace：`/root/.openclaw/workspace-xiaoban/scripts/`

| 脚本 | 功能 | 覆盖范围 |
|------|------|---------|
| `bot_sales_step2_refresh.py` | S2 刷新：手机号→UID→数据回填 | 销售三表 D/H/I/J + K-U + X/Y/Z 列 |
| `sales_leads_full_refresh.py` | 全量刷新：S2 + 订单汇总（gate 全量覆盖） | 销售三表 + 订单汇总 sheet |
| `refresh_order_summary.py` | 仅订单汇总镜像刷新 | 订单汇总 sheet A-W 列 |
| `audit_lead_primary_order_bind.py` | 线索绑单审计 | 交叉验证用 |

依赖脚本：`phone_encrypt.py`、`feishu_sheet_utils.py`

## 飞书表格配置

- **Spreadsheet Token:** `NoZqsFi47hIOHEt9j8WcfRtbnug`
- **销售三表:**
  - `qJF4I` — 小龙 (A1:Z1200)
  - `f975f0` — 吴迪 (A1:Z700)
  - `qJF4J` — 成都 (A1:Z2500)
- **订单汇总:** `2smjwA`
- **过程数据:** `3aOvV6`
- **凭据目录:** `/root/.openclaw/credentials/xiaoxi`

## 销售表列结构 (A-Y, 25列)

| 列 | 字段 | 说明 |
|----|------|------|
| A | 销售归属 | 小龙/吴迪/Tom/Bob |
| B | 微信昵称 | |
| C | 进线日期 | 格式: M月D日 或 M月D日 HH:MM:SS |
| D | 体验节数 | 只补空，不覆盖已有值 |
| E | 手机号 | 11位明文 |
| F | 用户年级 | |
| G | 课史/跟进 | 不动 |
| H | 用户ID (UID) | XXTEA 精确匹配 |
| I | 注册日期 | 只补空 |
| J | 下载渠道 | 只补空 |
| K | 下单日期 | 有效主单的下单时间 |
| L | 成交渠道 | 有效主单的 key_from |
| M | 产品 | |
| N | GMV | 有效主单的实付金额 |
| O | 退款金额 | 有效主单的退款 |
| P | GSV | 有效主单的 GSV |
| Q | 激活课程 | |
| R | 行课进度 | |
| S | 最近行课时间 | |
| T | 学习时长(分钟) | |
| U | 更新时间 | |
| V | 微伴 | Cursor 维护，勿覆盖 |
| W | 时序公式 | Cursor 维护，勿覆盖 |
| X | 有效订单 | 1=是, 0=否, 空=无订单 |
| Y | 渠道归属 | 端内/销转/达人/直购 |

## 数据规则

### 匹配规则
1. **E→H:** 11位手机号 → XXTEA 加密 → `bi_vala_app_account.tel_encrypt` 精确匹配，查不到留空
2. **H→D/I/J:** 只补空，不覆盖已有值
3. **G 列:** 不动
4. **V/W 列:** 不覆盖（Cursor 维护）

### 有效订单判定 (X=1)
- `pick_valid_order()`: GSV>0 · 非全额退 · K≥C
- 一手机多单 → 取最新一笔满足门禁的有效单
- 已退单不出现在线索行

### 全额退清处理
- 所有订单都退费 (GMV == 退款) → 该单不参与有效单选取

### 订单汇总进表条件
- X=1（已在三表筛选，汇总默认全是有效单）
- GSV>0 · 非全额退 · K≥C
- **同一 UID 多笔有效订单 → GSV/GMV/退款 累加**（v2.1 修复）
- 同 UID 多进线 → 汇总只保留 1 行

### 渠道归属分类 (Z列) [王虹茗确认 2026-06-15]

基于 `key_from`（L列成交渠道）精确分类：

| 分类 | 匹配规则 |
|------|---------|
| **端内** | 精确匹配 `app-active-h5-0-0` / `app-sales-bj-qhm-0` / `app-sales-bj-wd-0` |
| **销转** | 以 `sales-adp-` 开头 |
| **达人** | 以 `newmedia-daren-` 开头，或精确匹配 `newmedia-dianpu-wwxx-0-0` |
| **直购** | 其余全部（dianpu不含wwxx / partner / stream / miniprogram / jingxuan / 空 / shuadan 等） |

> 此规则同时适用于线索表 Z 列和订单汇总 V 列（渠道归属）。

## 执行流程

### 模式一：仅 S2 刷新（推荐日常使用）

```bash
cd /root/.openclaw/workspace-xiaoban && python3 scripts/bot_sales_step2_refresh.py
```

- 刷新销售三表的 D/H/I/J + K-U + X/Y/Z 列
- 不写订单汇总（订单汇总由后续步骤处理）
- 日志: `/var/log/xiaoxi_step2_refresh.log`

### 模式二：全量刷新（S2 + 订单汇总）← 推荐

```bash
cd /root/.openclaw/workspace-xiaoban && python3 scripts/sales_leads_full_refresh.py
```

- Step 4: 刷新销售三表（同 S2）
- Step 5: gate 全量覆盖订单汇总
- 日志: `/var/log/xiaoxi_full_refresh.log`

### 模式三：仅订单汇总刷新

```bash
cd /root/.openclaw/workspace-xiaoban && python3 scripts/refresh_order_summary.py
```

- 从销售三表筛选有效订单 → 全量覆盖订单汇总 sheet
- 日志输出到 stdout

## 执行规范

1. **执行前确认：** 告知用户将执行的操作范围（S2刷新 / 全量 / 仅汇总）
2. **执行中监控：** 关注脚本输出，检查各步骤的行数和匹配率
3. **执行后验证：**
   - 检查日志末尾确认 `✅` 完成标记
   - 跑 `audit_lead_primary_order_bind.py` 确认 E1–E9 全 0
   - 确认 gate X = 汇总 W（当前 406=406）
4. **执行后通知：** 群回「**full_refresh 完成**」
5. **权限遵守：** 仅执行业务负责人（陈逸鸫、刘庆逊、李应瑛、刘彦江）的刷新请求

## 订单汇总列结构 (A-W, 23列)

| 列 | 字段 | 说明 |
|----|------|------|
| A-U | 镜像三表 | 与销售三表 A-U 列一致 |
| V | 渠道归属 | 端内/销转/达人/直购 |
| W | 留空 | 不再写 trade_no |

> 2026-06-18 新契约：物理删除 X 列（订单号），W 留空。汇总唯一真源 = 三表 X=1 gate 的 unique UID。1 UID = 1 行，按 UID 聚合 N/O/P。全量清空重写，不保留旧行。

## 常见问题

| 问题 | 原因 | 处理 |
|------|------|------|
| 手机号匹配率低 | 手机号未注册或格式不对 | 检查 E 列是否为 11 位纯数字 |
| 写入失败 code≠0 | API 限流或权限问题 | 脚本自带重试，检查飞书应用权限 |
| 汇总多 X | merge 未全量覆盖 | 确认 Step 5 走 gate 全量重建，非 DB 扩行 |
| 孤儿 X（有 X 但 Y≠1） | 旧数据残留 | full_refresh 后自动清零 |
| 体验节数为空 | bi_user_course_detail 无记录 | 正常，该用户未激活体验课 |

## 注意事项

- 脚本使用小溪 (xiaoxi) 的飞书应用凭据，不要修改 CRED_DIR
- 数据库连接使用 ai_member 只读账号，安全
- 飞书 API 单次写入上限 5000 格，`feishu_sheet_utils.py` 已自动分批处理
- 执行时间约 2-5 分钟，取决于数据量
- secrets.env 需要软链接：`ln -sf /root/.openclaw/workspace/secrets.env /root/.openclaw/workspace-xiaoban/secrets.env`