# 钉钉问数上线指引

> 背景：站内「智能问数」已定型为兜底入口（本地取数、两段式回答），数据消费的主场随钉钉 AI 表格迁到钉钉。
> 云端表按维度拆成三张单粒度表后，才能放心在钉钉侧用 AI 问数 / 透视表做聚合——否则任何求和都会把门店、连锁、公司行加总，数字直接翻几倍。

## 一、云端表结构（已就绪）

同一 Base 下三张数据表，每张表内粒度唯一：

| 数据表 | 存什么 | 对应本地 scope | 业务键 |
|---|---|---|---|
| 门店明细 | 日期 × 门店的逐日指标 | `shop` | 日期｜账号名｜门店维度｜连锁ID｜门店ID |
| 连锁汇总 | 日期 × 连锁的逐日汇总 | `chain` | 日期｜账号名｜连锁维度｜连锁ID |
| 公司汇总 | 日期 × 账号（全公司）逐日汇总 | `company` | 日期｜账号名｜公司维度 |

- 三张表同一套 23 列（7 个维度列 + 16 个指标列），缺维度的列留空：
  `日期、账号名、维度、门店ID、门店名称、连锁ID、连锁名称、有效订单、收入(元)、营业额(元)、支出(元)、曝光人数、下单人数、进店转化率、下单转化率、客单价(元)、活动订单、活动补贴(元)、推广ROI、30日复购率、营业时长(h)、异常关店时长(h)、商品销售额(元)`
- 本地区间汇总行（scope=summary）不上云：可由门店行推导，混入任何一张表都会造成表内算重。
- 旧「数据表」（混维度单表）已停写归档，确认新表数据无误后可在钉钉里手动删除。
- 表名可在「系统设置 → 钉钉 AI 表格」修改（留空用默认名）；表名变更后首次推送会自动全量重推。

## 二、建表说明（已完成，备用）

本次三张表由程序通过钉钉 notable API 自动创建（应用自身凭据）。如日后需要在新 Base 重建：

- 建表：`POST /v1.0/notable/bases/{baseId}/sheets?operatorId=…`，请求体 `{ "name": "门店明细", "columns": [{ "name": "日期", "type": "text" }, …] }`（维度列 `text`、指标列 `number`）
- 补列：`POST …/sheets/{表名}/fields?operatorId=…`，请求体 `{ "name": "营业额(元)", "type": "number" }`
- ⚠ 建表/建列接口有应用级限流：突发约 5 次后返回 500 `internalError`，慢速补列即可（每列间隔几秒）；记录读写接口不受影响
- ⚠ 记录写入遇到不存在的列名会整批 404（`failed to find the field '…'`）——先建齐列再推送

## 三、数据推送与核对

1. 「数据采集」页同步历史面板的「推送云端」，或同步完成后自动推送（含定时自动同步）。
2. 首次切换到三表后推送为全量（表名指纹变化自动触发，无需手动强推）。
3. 核对口径：三张云端表行数之和 = 本地湖行数 − 本地区间汇总行数；门店行大量全零会被「全零拦截」挡下（确认无误可强推）。
4. 历史连锁/汇总行：旧版本行键缺连锁ID，同日多连锁曾互相覆盖。修复后新同步自动正确；如需回补历史，在装有商家客户端的机器上对历史区间重跑一次同步再推送。

## 四、钉钉侧问数实测清单（验收 = 数字与站内报表一致）

在钉钉里打开该 AI 表格（或建一个绑定此表的钉钉 AI 助理），逐条问：

| # | 问题 | 期望 |
|---|---|---|
| 1 | 上个月总营业额是多少 | 只汇总「公司汇总」表（或门店明细求和），数字 = 站内经营分析同区间营业额 |
| 2 | 上个月营业额 Top10 门店 | 来自「门店明细」，排序与站内排行一致 |
| 3 | 各连锁上个月营业额对比 | 来自「连锁汇总」，只有连锁粒度、不含公司/门店行 |
| 4 | 昨天XX门店的有效订单和客单价 | 单门店单日，与站内明细一致 |
| 5 | 最近 30 天营业额趋势 | 按日期汇总，无翻倍 |
| 6 | 进店转化率最近一周变化 | 比率类不做求和（应取均值或按日展示） |

验收要点：**任一问题的答案都不能出现跨维度加总**（如门店+连锁+公司相加）。若钉钉 AI 在单表上仍算错，检查它是否绑定到了正确的一张表。

## 五、站内问数（兜底）现状

- 机制：第一段对话模型只做「问题 → 结构化查询」的规划（指标语义 + 门店清单进 prompt，行数据不出网），本地数据湖执行；第二段把 Top≤10 聚合结果回传模型写出带真实数字的结论句，失败自动降级模板句。
- 配置：「系统设置 → API 设置 → 对话模型」（默认 deepseek-v4.1-flash，Key 留空复用生图 Key）。
- 定位：采集机上的日常快查；团队/手机端问数走钉钉。