ai_member_xiaoban/skills/full-data-refresh/SKILL.md

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

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

版本： v2.1（2026-06-17 · GSV 聚合修复） 协作契约： xhs-ark-dashboard/docs/bot-full-refresh-v2.md 大麦侧主文档： xhs-ark-dashboard/docs/damai-full-refresh-skill.md

v2.1 变更（2026-06-17）

• GSV 聚合修复： 订单汇总 Step 5 改用 aggregate_valid_orders() 替代 pick_valid_order()
  • 同一账户多笔有效订单 → GSV/GMV/退款 全部累加（不再只取最新一笔）
  • 订单号取未退款那笔（多笔未退款取最新）
  • 产品列多单用 + 拼接
  • 线索绑单（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 = 三表 X（gate 同源）

• 订单汇总 W 列取的是 valid_order["trade_no"]，与三表 X 列写入的值完全一致
• 不是 merge 时再查 DB 写 W
• 唯一真源 = 三表 Y=1 gate 的 unique X

3. 2smjwA：clear → gate 全量覆盖

• 先 clear_summary_sheet() 清空旧数据区
• 再 gate 全量重建：从三表 Y=1 行收集 unique X → 每 X 一行
• 不保留旧 W，不 append
• 同 X 多进线 → 只保留行号最小的 1 行

4. 「保留 X/Y」只三表 mirror，不含汇总

• 三表 D/I/J 只补空、G 列不动 → 这些是 mirror 规则
• 汇总 2smjwA 永远全量清空重写，不保留任何旧行

5. 线索 1进线=1行 · 只绑有效单

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

6. 完成后群回「full_refresh 完成」

• 在数据更新群（oc_4687e8f9f38e4f5c819238c78f97ae44）回复
• 附带验证结果：gate X 数 = 汇总 W 数

验收标准

Cursor 侧跑（大麦可自测）：

• audit_xishui_orders.py --strict
• audit_lead_primary_order_bind.py

PASS 条件：

• unique X 三表 = 汇总（当前 406=406）
• 绑单审计 E1–E9 全部 0
• 孤儿 X（有 X 但 Y≠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-Z)

列	字段	说明
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	订单号	仅 Y=1 时写入有效主单号
Y	有效订单	1=是, 空=否
Z	渠道归属	端内/销转/达人/直购

数据规则

匹配规则

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

有效订单判定 (Y=1)

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

全额退清处理

• 所有订单都退费 (GMV == 退款) → 该单不参与有效单选取

订单汇总进表条件

• Y=1（已在三表筛选，汇总默认全是有效单）
• GSV>0 · 非全额退 · K≥C
• 同一账户多笔有效订单 → GSV/GMV/退款 累加，订单号取未退款那笔（v2.1 修复）
• 同 X 多进线 → 汇总只保留 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 刷新（推荐日常使用）

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 + 订单汇总）← 推荐

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

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

模式三：仅订单汇总刷新

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	订单号	= 三表 X（gate 同源）

2026-06-16 新契约：去掉原 W「有效成单」列，订单号从 X 左移到 W。汇总唯一真源 = 三表 Y=1 gate 的 unique X。全量清空重写，不保留旧行。

常见问题

问题	原因	处理
手机号匹配率低	手机号未注册或格式不对	检查 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