# majia-huiyuan · 会员运营家底（开源样板间）

[![Skill Version](https://img.shields.io/badge/skill-v1.4.1-blue)](./SKILL.md)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
[![skills.sh](https://skills.sh/b/maojiebc/majia-huiyuan)](https://skills.sh/maojiebc/majia-huiyuan)
[![Release](https://img.shields.io/github/v/release/maojiebc/majia-huiyuan?label=release&color=success)](https://github.com/maojiebc/majia-huiyuan/releases)
[![Quality](https://github.com/maojiebc/majia-huiyuan/actions/workflows/quality.yml/badge.svg)](https://github.com/maojiebc/majia-huiyuan/actions/workflows/quality.yml)
[![AI Agent Friendly](https://img.shields.io/badge/AI_Agent-friendly-1abc9c)](./AGENTS.md)
[![Data](https://img.shields.io/badge/%E6%95%B0%E6%8D%AE-%E5%85%A8%E6%A8%A1%E6%8B%9F%E7%94%9F%E6%88%90-orange)](#数据说明必读)

> **会员运营 · 马甲实战版** — 一套**完整、可审计、可改造的**连锁会员数据参考体系。以一家虚构的咖啡连锁为例，从会员注册的第一行数据，到老板看的经营驾驶舱：**55 个逻辑数据集、25 条数据加工链、12 张看板，外加约 3100 行的实战公式库**，全部摊开。
>
> 数据全部模拟生成，与任何真实企业无关。MIT 协议，个人用、公司用、商用，都随便。

<p align="center">
  <img src="https://raw.githubusercontent.com/maojiebc/majia-huiyuan/main/docs/architecture.png" width="440" alt="majia-huiyuan v1.4.1 功能架构：三大资产 + 五层数仓 + 会员数据顾问十类活 + 与 majia-siyu（执行内容）及 majia-guanyuan（平台工具）的分工"/>
</p>

**谁适合看**：做会员、做私域的业务同学；做数据分析、数据建设的同学；想给自己公司从零搭一套会员数据体系的人。**不需要会写代码。**

**AI 也适合看**：如果你是 AI Agent（WorkBuddy / Claude / Codex / Cursor …），你的入口在 [llms.txt](./llms.txt) 和 [AGENTS.md](./AGENTS.md)；本仓库同时是一个可安装的 **Agent Skill**（[SKILL.md](./SKILL.md)），装法见[下方](#-当-agent-skill-用)。

---

**你是谁，直接去哪里：**

| 我想做的事 | 直接去 |
|---|---|
| 找某个指标怎么算（复购率、RFM、核销率…） | [公式库/README.md](./公式库/README.md) → 按主题找分册 |
| 看表结构 / 字段定义 / 数据长什么样 | [数据集/结构定义/](./数据集/结构定义/) + [数据集/数据样本/](./数据集/数据样本/) |
| 理解某条 ETL 的加工逻辑和 SQL 口径 | [ETL/逻辑SQL/](./ETL/逻辑SQL/) 按表名找对应 md |
| 搭观远 BI，理解原 workshop DAG / 布局 | [ETL/原始JSON/](./ETL/原始JSON/) + [数据集/原始JSON/](./数据集/原始JSON/) + [看板/页面JSON/](./看板/页面JSON/)（均为历史快照，不含 v1.4.1 字段修复；资源 ID 也不可移植） |
| 用 AI 工具直接问会员数据问题 | [SKILL.md](./SKILL.md) 装成 Agent Skill，或把仓库地址扔给 AI |
| 先看故事再翻表 | [分享/区域运营的一天/](./分享/区域运营的一天/README.md) |

> **v1.4.1 可信边界：**`ETL/逻辑SQL/`、[`ETL/公共口径/`](./ETL/公共口径/) 与 `看板/页面文档/` 是当前校正后的参考口径；仍需用自家数据验证后再生产化。`*/原始JSON/` 和 `看板/页面JSON/` 是 2026-06-24 的 workshop 历史快照，保留用于审计原 DAG / 布局，**未同步改造成 v1.4.1 可直接导入包**，其中仍可能出现旧字段名。当前 SQL 定位是“待验证示例”，不是标准答案。

---

## 这是什么

会员运营这行有块三不管地带：字段怎么定义、口径怎么算、看板怎么搭，做业务的嫌它是技术细节，做数据的嫌它是业务琐事，两边都懂的人当它是吃饭本事。结果就是，想学的人找不到一份能从头看到尾的完整参照。

这个仓库就是那份参照——一个"样板间"。

它是 2026 年 5 月在观远 BI 官方 workshop 实例上独立搭建的一套完整会员数据中台，虚构了一家咖啡连锁：**8 万会员、1200 家门店、141 个加盟商、74 个商品、129 万笔订单**。麻雀不大，五脏俱全：会员注册、订单、发券、积分、私域触达、投诉评价、加盟分账、门店成本，全链路的数据都有，而且是打通的。

毛坯房教不会人装修，样板间可以。你不一定照单全收，但每面墙长什么样、水电怎么走，这里都看得见。

本仓库会持续迭代，路线图见[下方](#路线图)。

## 三分钟看懂：数据分五层

所有数据集按五层组织（这是数据行业的通用做法，名字唬人，事情简单）：

| 层 | 行话 | 人话 | 本库数量 |
|---|---|---|---|
| **DIM** | 维度层 | **档案柜**：会员档案、门店档案、商品档案，一行 = 一个人 / 一家店 / 一件商品 | 10 |
| **DWD** | 明细层 | **流水账**：每笔订单、每次发券、每条评价，一行 = 发生过的一件事 | 16 |
| **DWS** | 汇总层 | **台账**：把流水按人、按店、按月归拢，复购率、RFM 分层都在这层算出来 | 16 |
| **ADS** | 应用层 | **驾驶舱**：老板、店长、运营直接看的最终报表 | 8 |
| **DQC** | 质检层 | **质检员**：两套数对不上时，先来这层查 | 1 |
| param | 参数表 | 阈值配置（比如"几天没来算流失"，写在表里而不是写死在公式里） | 4 |

数据的流向一句话：**档案柜 + 流水账 →（25 条加工链）→ 台账 → 驾驶舱**。

## 资产地图（55 个逻辑数据集）

每个数据集一句人话。字段级明细看 [数据集/结构定义/](./数据集/结构定义/)，长什么样看 [数据集/数据样本/](./数据集/数据样本/)。

### DIM 档案柜（10）

| 数据集 | 一句话 |
|---|---|
| dim_会员主档 | 每个会员一行：等级、注册渠道、城市、状态（8 万行） |
| dim_会员身份桥 | 一个人的多个身份（手机号 / 微信 / 支付宝）怎么认成同一个人 |
| dim_门店主档 | 每家店一行：城市、店型、开业日期（1200 家） |
| dim_加盟商主档 | 每个加盟商一行（141 个） |
| dim_商品主档 | 每个商品一行：品类、价格带（74 个） |
| dim_券模板 | 每种券一行：面额、门槛、有效期 |
| dim_活动主档 | 每场营销活动一行 |
| dim_员工导购 | 每个店员 / 导购一行 |
| dim_成本科目 | 房租、人力、原料……成本怎么分类 |
| dim_日期 | 日期维表：节假日、周末、月份归属 |

### DWD 流水账（16）

| 数据集 | 一句话 |
|---|---|
| dwd_订单 | 每笔订单一行：金额、渠道、是否会员、是否用券（129 万行） |
| dwd_订单商品 | 订单里的每件商品一行 |
| dwd_会员注册绑定 | 每次注册 / 绑定一行 |
| dwd_券事件 | 每张券的发放、核销、过期 |
| dwd_积分事件 | 每笔积分的挣与花 |
| dwd_会员触达 | 每次触达一行：短信 / 企微 / Push，发给谁、谁打开（50 万行） |
| dwd_私域事件 | 进群、退群、加好友、会话 |
| dwd_活动参与 | 谁参加了哪场活动 |
| dwd_评价 | 每条顾客评价 |
| dwd_投诉 | 每条投诉 |
| dwd_会员经营任务 | 总部派给门店的会员任务及完成情况 |
| dwd_加盟合同明细 | 每份加盟合同 |
| dwd_加盟分账明细 | 每笔加盟分账 |
| dwd_门店成本明细 | 每笔门店成本 |
| dwd_门店投资明细 | 每笔开店投资 |
| dwd_门店目标 | 每店每期的目标值 |

### DWS 台账（16）

| 数据集 | 一句话 |
|---|---|
| dws_会员RFM分层 | 每个会员的 R / F / M 打分和分层标签（做精准营销的底座） |
| dws_会员生命周期 | 新客 / 活跃 / 沉睡 / 流失，每人当前在哪一段 |
| dws_会员同期群留存 | 按注册月份分组，看每批人第 N 月还剩多少（Cohort 留存） |
| dws_私域转化漏斗 | 触达 → 查看 → 下单，每场活动的漏斗和转化率 |
| dws_券效益分析 | 每种券核销了多少、对应订单 GMV 多少；无对照时不报增量 ROI |
| dws_渠道迁移分析 | 顾客在堂食 / 外卖 / 小程序之间怎么流动 |
| dws_商品销售分析 | 每个商品卖得怎么样 |
| dws_门店日报 | 每店每天的核心经营数 |
| dws_目标达成 | 每店目标完成进度 |
| dws_新店爬坡_Comp老店 | 新店爬坡曲线，和可比老店（Comp）对照 |
| dws_单店利润月汇总 | 每店每月的利润账 |
| dws_成本结构汇总 | 成本按科目的构成 |
| dws_加盟商经营汇总 | 每个加盟商名下门店的经营汇总 |
| dws_加盟回本测算 | 每家加盟店投了多少、回了多少、预计几个月回本、风险等级 |
| dws_员工导购效能 | 每个导购拉新、复购带动的效能 |
| dws_体验口碑汇总 | 评价、投诉汇总成门店体验分 |

### ADS 驾驶舱（8）

| 数据集 | 一句话 |
|---|---|
| ads_高层经营驾驶舱 | 给老板：大盘营收、会员销售、触达后关联销售与风险信号 |
| ads_会员私域驾驶舱 | 给会员负责人：活跃、新增、触达、会员销售占比 |
| ads_会员经营任务池 | 给运营：待办的会员经营任务清单 |
| ads_门店每日指挥台 | 给店长：今天该看的数、该做的事 |
| ads_活动权益复盘 | 给营销：每场活动的核销、触达后关联与增量测算状态 |
| ads_单店利润健康 | 给财务 / 拓展：每店利润健康度 |
| ads_加盟商单店报告 | 给加盟商：他自己店的经营报告 |
| ads_异常归因清单 | 数据异动的归因线索清单 |

### DQC 质检 + param 参数（5）

| 数据集 | 一句话 |
|---|---|
| dqc_归因清单对账 | 两条链路算同一个数，对不上就报警 |
| param_会员生命周期阈值 | 几天算沉睡、几天算流失，阈值配置 |
| param_门店会员占比预警阈值 | 不同门店类型的会员订单占比月度下降预警线 |
| param_利润健康阈值 | 利润健康度的分档线 |
| param_豁免日历 | 大促 / 特殊日期豁免名单（防止误判异常） |

> **复刻这套体系，先填这四张表。**
> `param_` 参数表是整套 ETL 的阈值配置中心：哪些日期算豁免不报警、多少天不来算沉睡、会员占比下降多少报警、利润率多少算健康，都写在这里——而不是硬编码进公式。v1.4.1 已把原先误名的生命周期参数拆成真正的 `param_会员生命周期阈值` 与 `param_门店会员占比预警阈值`。

## 12 张看板

从老板到店长到加盟商，每个角色一张自己的报表。清单见 [清单/看板清单.csv](./清单/看板清单.csv)，每张的卡片明细在 [看板/页面文档/](./看板/页面文档/)。

01 高层经营驾驶舱 · 02 会员私域驾驶舱 · 03 会员经营任务池 · 04 门店每日指挥台 · 05 活动权益复盘 · 06 体验风险专题 · 07 单店利润健康 · 08 加盟商单店报告 · 09 总览（ECharts 重构版）· 10 异常归因作战页 · 外卖业绩近 30 天 GMV（卖了多少钱）· 参赛作品提交页

## 公式库（60+ 段可复用、上线前须验证的 SQL）

样板间给你看结构，公式库提供算法参考。[公式库/](./公式库/) 蒸馏自两段连锁餐饮 BI 实战履职（已全脱敏，约 3100 行），2026-07-12 从 majia-guanyuan 迁入本仓库统一维护，按主题分 10 册：

| 分册 | 管什么 |
|---|---|
| [01 日期与时间](./公式库/01-date-and-time.md) | T-1、本月、近 N 天、用餐时段、跨月对齐、观远时间宏 |
| [02 顾客与会员](./公式库/02-customer-and-membership.md) | 新老客、消费频次 3 口径、复购（跨天 vs 非跨天）、RFM 8 类 × 营销策略、留存流失 |
| [03 营收 KPI](./公式库/03-revenue-kpi.md) | 客单价 AC、ADS、ADT、Comp 同店、会员贡献占比 |
| [04 渠道与门店](./公式库/04-channel-and-store.md) | 堂食外卖分流、门店生命周期、多渠道评价 pipeline |
| [05 券与折扣](./公式库/05-coupon-and-discount.md) | 核销率、折扣率、折扣分桶、注册首张券 |
| [06 SQL 工具箱](./公式库/06-sql-utils.md) | 字符串拆解、开窗排名、累计窗口 |
| [07 数据质量坑](./公式库/07-data-quality-traps.md) | NULL / 空串 / 'null' 三态、口径歧义、通用字段词典 |
| [08 ETL 工程范式](./公式库/08-etl-engineering-patterns.md) | DWD 宽表底座、财务双源对账、POS 归一化、Cohort 网格 |
| [09 生产 ETL 索引](./公式库/09-etl-catalog.md) | 39 个生产 ETL 按 11 个业务域的索引与复用决策表 |
| [10 任务与触达回收](./公式库/10-task-and-touch-recovery.md) | 白盒 NBA 任务池模型、九类任务×圈选依据、防打扰与仲裁、漏斗四率回收、差评客户挽回 |

总入口和"5 条最容易踩的坑"见 [公式库/README.md](./公式库/README.md)。**样板间的表结构 + 公式库的算法，两样凑齐，是方案评审和二次开发的图纸；生产上线还要完成字段映射、口径确认和回归验收。**

## 一场直播，把这套东西讲了一遍

2026 年 7 月，这套体系的设计思路在观远「对话 AI Hero」直播里完整讲过一次（AI 创新赛一等奖作品《区域运营的一天》）：区域运营一上午的巡店分析，AI 怎么压缩到几分钟，怎么归因到人、怎么学会闭嘴、怎么多看一眼。

**[📖 分享/区域运营的一天/](./分享/区域运营的一天/README.md)** —— 34 页插画板全嵌的书面实录，当时演示的数据环境就是本仓库。想先看故事再翻表的，从这里进。

## 目录结构（怎么翻）

```
清单/          三张总清单 CSV（数据集 / ETL / 看板，含 ID）——先看这里拿全景
公式库/        餐饮 BI 公式实战库（README + 10 册）★ 算法和口径 SQL 都在这
分享/          直播分享书面实录（34 页插画长文）★ 想先看故事的从这进
数据集/
  结构定义/    每个数据集的字段结构说明 ★ 最值得先看
  数据样本/    每表最多 200 行模拟样本 CSV（小表按实际规模），表头即当前 schema
  原始JSON/    观远平台 v1.4.0 历史快照（审计用）
ETL/
  逻辑SQL/     25 条加工链的节点结构和 SQL 逻辑 ★ 口径都在这
  公共口径/    v1.4.1 三条事实桥 + 业务不变量验收 SQL ★ 多链共用的正确性底座
  原始JSON/    v1.4.0 workshop 历史快照（不是 v1.4.1 可导入包）
看板/
  页面文档/    v1.4.1 校正后的卡片字段清单
  页面JSON/    v1.4.0 页面布局历史快照（旧字段，不可直接导入）
skillhub/      ⚙️ 自动生成产物（ClawHub / npm 发布包的瘦身文本子集）
               勿手动修改——改根目录再跑 python3 tools/build_skillhub_bundle.py
tools/         构建脚本（含 --check 漂移检测模式）
```

## 三种用法

**① 业务同学：对照自查。** 打开 [数据集/数据样本/dws_会员RFM分层.csv](./数据集/数据样本/)，你嘴里的"复购""流失""分层"在数据里就长这样。拿 [清单/数据集清单.csv](./清单/数据集清单.csv) 当清单，对照你公司现在的会员体系，缺哪层、缺哪几张表，一眼看得出来。

**② 数据同学：改造字段和口径。** [结构定义](./数据集/结构定义/)里有全部字段，[逻辑SQL](./ETL/逻辑SQL/) 与 [公共口径](./ETL/公共口径/) 里有加工口径，[公式库](./公式库/) 里有复购 / RFM（按最近来没来、来得勤不勤、花得多不多给顾客分层）/ 核销等算法。先完成自家字段映射、边界条件和小样本回放，再进入生产。SQL 方言是 Spark 3.4。

**③ 参考复刻。** 用观远 BI 的话，`原始JSON` 可帮助理解原 workshop 的节点 DAG，但它仍是 v1.4.0 历史快照；请先把 v1.4.1 的校正逻辑重新落到目标平台再运行。不用观远也没关系，五层结构和字段设计仍可作为跨平台架构样板。

## 让 AI 替你干活（推荐）

这个库特意做成了 AI Agent 友好的。把仓库地址扔给你的 AI 工具（WorkBuddy / Claude Code / Codex / Cursor……），直接说人话：

- "对照这个库，看看我们公司的会员数据还缺什么"
- "把 dws_会员RFM分层 的口径翻译成我们数仓的建表语句"
- "照这套结构，给我出一版我们品牌的会员看板规划"

AI 会自己顺着 [llms.txt](./llms.txt) 和 [AGENTS.md](./AGENTS.md) 找到路，不用你解释仓库结构。

## 🎛 当 Agent Skill 用

本仓库同时是一个 **Agent Skill**（[SKILL.md](./SKILL.md) 在仓库根部）——装进任何支持 SKILL.md 的 agent（Claude Code / OpenClaw / Codex / WorkBuddy …），它就变成一个随叫随到的**会员数据顾问**，能干十类活：口径与公式咨询、**会员运营动作的数据依据**（召回/提频/防流失该圈谁、何时触达、给什么力度、派给谁、怎么回收）、**CDP 与标签体系设计**（OneID 身份打通、人群圈选、标签规则外置）、从零设计会员数据体系、现有体系缺口诊断、生成建表 DDL、按角色规划看板、数据质量排障、方法论内训、观远整套复刻。

```bash
# ClawHub / OpenClaw
clawhub install majia-huiyuan
openclaw skills install majia-huiyuan

# GitHub CLI（gh 2.90+）
gh skill install maojiebc/majia-huiyuan majia-huiyuan --agent claude-code --scope user

# 手动 clone 到对应 agent 的 skills 目录
git clone https://github.com/maojiebc/majia-huiyuan.git ~/.claude/skills/majia-huiyuan   # Claude Code
git clone https://github.com/maojiebc/majia-huiyuan.git ~/.codex/skills/majia-huiyuan    # Codex
```

装完试一句："帮我看看我们公司的会员数据体系缺什么"，或者"复购率的口径给我几种标准算法"。

## 数据说明（必读）

- **全部数据由程序模拟生成**，与任何真实企业无关；手机号等个人标识列已打码（形如 `156****0925`）
- 仓库内每表附模拟样本，明细大表最多 200 行、参数和小表按实际样例规模；完整规模（如会员 8 万、订单 129 万）标在各表的结构定义里
- JSON 里的资源 ID 是 workshop 实例私有的，复刻时会生成你自己的
- 快照时间 2026-06-24，导出工具为观远官方 `guancli`；统一运行参数 `as_of_date` 也默认使用该日
- `原始JSON` 与 `看板/页面JSON` 保留的是历史平台快照；v1.4.1 的修复以 `ETL/逻辑SQL`、`ETL/公共口径`、`看板/页面文档` 和自动验收为准
- 结构定义若同时保留平台历史字段，会在文件顶部标出 `v1.4.1 结构覆盖`；当前 CSV 样本表头已按该覆盖口径同步，不能用下方明确标注的 v1.4.0 历史字段反推新表

## 兄弟项目

| 项目 | 关系 |
|---|---|
| [majia-siyu](https://github.com/maojiebc/majia-siyu-team) | 私域经营动作入口。**朋友圈、群发、欢迎语、社群触达与整盘经营诊断在那边；指标、公式、SQL 与看板在本库。** |
| [majia-guanyuan](https://github.com/maojiebc/majia-guanyuan) | 观远 BI 实战增益层 skill。**工具与踩坑手册在那边，数据与公式在这边**；本库的模拟中台和公式库都源自它，现独立迭代 |

## 路线图

- [ ] **口径卡片**：每张核心表配一页"这张表回答什么业务问题"
- [ ] **通用建表 DDL**：不用观远也能一键建表的 SQL 版本
- [ ] **实战问题包**：常见会员运营问题 → 用哪几张表、怎么查（脱敏后的真实场景）
- [ ] **行业变体**：茶饮 / 正餐 / 零售的差异字段说明
- [ ] 字段词典中英对照

想看哪个先做，[提个 issue](https://github.com/maojiebc/majia-huiyuan/issues) 投票。

## 📋 版本记录

**最新：V1.4.1** (2026-08-09) — **业务正确性修复**：重做触达、券实例、活动参与三条订单事实桥；统一 `as_of_date` 和 SCD2 时间关联；修复同期群留存、零销售成本月、连续亏损、加盟回本、零订单日和投诉-only 日期；拆分误名参数表；新增 9 项业务不变量回归测试、GitHub Actions 与发布包漂移检查。SQL 对外定位从“可直接复制”调整为“待验证示例”。

**V1.4.0** (2026-08-07) — **能力边界深挖**：SKILL.md 十类活（新增"业务动作的数据依据"与"CDP/标签体系"两类）；公式库新增第 10 册《任务与触达回收》；与 majia-siyu 的边界改为"同一动作两半"协同。

**V1.3.2** (2026-07-28) — **触发边界修复**：聚焦会员数据、指标口径、SQL、数仓与看板；私域内容、触达和经营动作明确交给 `majia-siyu`。

**V1.3.1** (2026-07-23) — **文档装修**：新增功能架构图（`docs/architecture.svg` + PNG，三大资产 / 五层数仓 / 八类活一图看全）、README.en.md 英文版、品牌后缀「· 马甲实战版」pixel-perfect 落到各展示面。内容零改动。

完整历史见 [GitHub Releases](https://github.com/maojiebc/majia-huiyuan/releases)。

## FAQ

**是真实数据吗？** 不是，全部模拟生成，放心引用结构、不要引用数值。
**能商用吗？** MIT 协议，能，注明出处就行。
**我不用观远 BI，这库对我有用吗？** 有。五层结构、55 张逻辑表的字段设计和 25 条链的参考口径都可跨平台评审；具体 SQL 仍要按引擎和自家数据验证。
**发现错误 / 想要新内容？** [提 issue](https://github.com/maojiebc/majia-huiyuan/issues)。你提一条，这套东西就厚一点。

## 👤 作者 / 联系

**马甲（@maojiebc）** · 超级马甲 · 14 年用户运营，连锁餐饮"数据与运营之间的翻译官"

| 渠道 | 链接 |
|---|---|
| 📧 Email | [m9224@163.com](mailto:m9224@163.com) |
| 🐙 GitHub | [github.com/maojiebc](https://github.com/maojiebc) |
| 🐦 X | [@maojiebc](https://x.com/maojiebc) |
| 📕 小红书 | [超级马甲](https://xhslink.com/m/4fQMJeHHWKC) |
| 📰 微信公众号 | [超级马甲](https://mp.weixin.qq.com/mp/profile_ext?action=home&__biz=MzY5NzIzODk2NA==#wechat_redirect) |

> 踩过的坑、总结的经验，不叫私有，是群策群力。
