227 lines
8.8 KiB
Markdown
227 lines
8.8 KiB
Markdown
---
|
||
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`
|