# AGENTS.md — 给 AI Agent 的操作指引

你正在访问的是一套**连锁餐饮会员数据中台的完整参考实现**（模拟数据），五层数仓架构（DIM / DWD / DWS / ADS / DQC），来自观远 BI（Guandata）实例的整库快照。你的用户大概率是业务或数据分析背景，不是工程师——回答时先人话，后术语。

## 事实速查

| 项 | 值 |
|---|---|
| 数据集 | 54 个（DIM 10 / DWD 16 / DWS 16 / ADS 8 / DQC 1 / param 3） |
| ETL 加工链 | 25 条 |
| 看板 | 12 张 |
| 模拟规模 | 会员 80,000 / 门店 1,200 / 加盟商 141 / 商品 74 / 订单 1,294,316 / 触达 500,000 |
| 快照时间 | 2026-06-24 |
| SQL 方言 | Spark 3.4 |
| 协议 | MIT |
| 数据真实性 | **全部模拟生成**，个人标识已打码 |
| 公式库 | `公式库/` 9 册约 2900 行：60+ SQL（复购 / RFM / 核销 / DWD 范式）+ 字段词典 + 39 生产 ETL 索引（此部分蒸馏自真实履职，已脱敏） |

## 任务导航（你被要求做 X → 去读 Y）

| 任务 | 路径 |
|---|---|
| 拿整体资产全景 | `清单/数据集清单.csv`、`清单/ETL清单.csv`、`清单/看板清单.csv`（列：分层,名称,ID） |
| 查复购 / RFM / 核销等通用公式、字段词典、数据质量坑 | `公式库/README.md` 总入口（路由表 + 5 大坑），按主题进 9 册 |
| 向用户讲解这套体系的设计思路 / 为什么这么设计 | `分享/区域运营的一天/README.md`（叙事版：痛点→五步→可信四件套→三案例，引用其中案例时注明数据为模拟） |
| 解释某个指标 / 口径怎么算 | `ETL/逻辑SQL/` 下按表名找对应 md，读节点结构和 SQL |
| 列出某张表的字段 | `数据集/结构定义/<表名>.md`（含字段数、行数、字段类型、维度/度量属性） |
| 看字段实际长什么样 | `数据集/数据样本/<表名>.csv`（200 行模拟样本，表头即 schema） |
| 帮用户设计会员数据体系 | 以 `清单/数据集清单.csv` 为蓝本，按 DIM→DWD→DWS→ADS 顺序讲，每层用途见 README「三分钟看懂」 |
| 生成建表语句 | 用 `数据集/数据样本/*.csv` 表头 + `结构定义` 的类型信息推 schema |
| 诊断用户现有体系的缺口 | 把 54 个数据集当 checklist，逐层对照用户已有的表 |
| 复刻整套到观远 BI | `*/原始JSON/` + 官方 CLI 全家桶 `@guandata/guanskill`（guancli / guanetl / guands / guanvis） |
| 理解某张看板的构成 | `看板/页面文档/<看板名>.md`（卡片清单），布局在 `看板/页面JSON/` |

## 命名与文件约定

- **分层前缀**：`dim_` 档案 / `dwd_` 事件明细 / `dws_` 汇总 / `ads_` 应用报表 / `dqc_` 质检 / `param_` 阈值参数
- **ETL 文件名**中括号内是节点构成缩写：`F`=FILTER_ROWS 过滤、`C`=CALCULATOR 计算、`G`=GROUP_BY 聚合、`S`=SQL_SCRIPT、`J`=JOIN_DATA 关联，`×N`=同类节点数。例：`etl_dws_会员RFM分层 (10节点·F+C+G+S+J)`
- **同一资产的三种形态**：
  - `结构定义/*.md` — guancli 导出的描述文档（最适合你直接读）
  - `数据样本/*.csv` — 200 行模拟数据（schema 与取值范围的真实示例）
  - `原始JSON/*.json` — 平台原始定义，含完整节点 DAG（复刻时才需要）
- 关键身份字段：`会员ID`（M 前缀）、`门店ID`（S 前缀）、`顾客识别键`（跨渠道统一身份，配 `身份匹配置信度`），身份合并逻辑见 `dim_会员身份桥`

## 硬约束（违反会误导用户）

1. **数据是模拟的**：可以引用结构、字段、口径、比例关系的设计思路；**不可**把数值当真实经营数据引用或外推行业结论。
2. **ID 不可移植**：JSON 内的资源 ID（数据集 / ETL / 卡片 ID）是 workshop 实例私有的，复刻时必须重新生成。
3. **SQL 是 Spark 3.4 方言**：搬到其他引擎（MySQL / ClickHouse / PG）时注意函数差异，主动提醒用户。
4. **引用要带路径**：向用户引用本库内容时，标注来源文件的相对路径，方便核对。
5. 手机号等打码字段（`156****0925`）不要尝试补全或生成完整号码。

## 推荐回答姿态

- 用户问"复购怎么算"这类口径问题：先给一句人话结论，再贴 `ETL/逻辑SQL/` 里的对应逻辑，最后提醒口径可选项（如跨天 vs 非跨天）。
- 用户要"照着搭一套"：不要一次吐 54 张表，按 DIM→DWD→DWS→ADS 分阶段给最小可用集（先档案+订单流水，再算汇总，再上报表）。
- 口径类问题优先交叉引用本仓库 `公式库/`（通用 SQL 公式）与 `ETL/逻辑SQL/`（本样板间的实际实现），两处口径一致时置信度最高。
