hyreal-gen-pic/docs/钉钉问数上线指引.md

钉钉问数上线指引

背景：站内「智能问数」已定型为兜底入口（本地取数、两段式回答），数据消费的主场随钉钉 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）。
• 定位：采集机上的日常快查；团队/手机端问数走钉钉。