POS 数据接入
诊断能力的上限由数据粒度决定。未接入 POS 时，系统只能用汇总指标做归因；接入后才能拆到品类 / 时段 / 支付方式 / 真实复购。
接入是逐店操作：POS 数据属于门店，一家店一份授权 / 一份对账单
门店接入总览
三种接入方式
| 方式 | 怎么接 | 覆盖 POS | 时效与代价 |
|---|
① 文件导入
本期可用 |
门店在 POS 后台导出对账单（CSV / JSON），在本页上传或粘贴；系统校验后入库 |
所有 POS（只要能导出） |
T+1；门店每天导出一次，或由督导代导。代价：人工操作，可能漏导 |
② API 直连
本期可用 |
门店在 POS 厂商开放平台授权后，系统凭 token 定时拉取 |
主流 POS：客如云 / 美团收银 / 银豹 / 思迅 |
准实时（15 分钟）；代价：需厂商商务对接 + 门店逐家授权 |
③ 平台推送
规划 |
POS 厂商按 Webhook 主动推送交易事件 |
仅少数厂商支持 |
实时；代价：依赖厂商改造，本期未排期 |
数据契约（门店侧必须提供的字段）
| 字段 | 类型 | 必填 | 口径说明 |
|---|
| trade_time | datetime | 是 | 交易完成时间，门店本地时区；用于按时段拆分 |
| order_id | string | 是 | 订单号，幂等去重键；重复 order_id 只计一次 |
| amount | int（分） | 是 | 实付金额，单位分，禁止浮点； coupons 已抵扣后的金额 |
| channel | enum | 是 | 堂食 / 外卖 / 自提；用于算外卖占比 |
| pay_type | enum | 是 | 微信 / 支付宝 / 银行卡 / 储值；储值充值不计入营业额 |
| category | enum | 否 | 咖啡 / 非咖 / 轻食 / 周边；缺失则该笔不计入品类结构 |
| member_id | string | 否 | 会员标识，须脱敏；用于算真实复购率 |
| item_count | int | 否 | 件数；用于算件单价 |
接入质量校验（任一硬性项不过，拒绝入库）
| 校验项 | 阈值 | 性质 | 不通过时的处理 |
|---|
| 必填字段缺失率 | > 5% | 硬性 | 拒绝接入，提示缺失字段与样例行号 |
| order_id 重复率 | > 1% | 硬性 | 拒绝接入（重复说明导出逻辑有误，重算会虚增营业额） |
| 异常金额（≤0 或 >1000 元） | 逐笔 | 硬性 | 该笔挂起不入库，其余照常；挂起数 > 2% 则整体拒绝 |
| 时间跨度 | < 7 天 | 提示 | 入库但在诊断里标记「样本不足 7 天，仅作参考」 |
| 品类字段覆盖率 | < 80% | 提示 | 品类结构标记为「部分覆盖」，不阻断 |
接入后立即解锁的能力
客单价实付金额合计 ÷ 订单数（可拆到时段/渠道）
品类结构各品类实付金额占比，可看新品动销
支付方式分布识别储值占比异常（充值≠消费）
时段产能曲线按小时看订单分布，定位低谷时段
执行接入
门店在 POS 后台导出对账单，在本页粘贴或上传。需要人工操作，T+1 生效。
API 直连不需要门店导出任何文件。流程：门店店主在 POS 厂商开放平台授权 → 系统拿到 token → 定时拉取交易明细。准实时（15 分钟）。
| POS 厂商 | 开放接口 | 授权主体 | 限制 |
|---|
| 客如云 | 有 | 门店店主 | 需先在厂商侧创建应用，取得 AppKey / Secret |
| 美团收银 | 有 | 门店店主 | 仅限品牌连锁，单店需商务对接 |
| 银豹 | 有 | 门店店主 | 按门店授权，token 有效期 180 天 |
| 思迅 | 有 | 门店店主 | 接口有调用频次限制 |
| 其他 / 自建 POS | 不确定 | — | 需人工确认是否有开放接口，没有则只能走文件导入 |
真实上线时，这条链路是这样跑的（本页模拟的是第 ③ 步的返回结果）：
- 平台入驻：我们在客如云 / 美团收银等开放平台注册开发者应用，拿到 AppKey / Secret —— 一次性商务流程，约 1–2 周。
- 门店授权：店主在我们的系统点「连接 POS」→ 跳转厂商授权页 → 店主确认 → 厂商回调我们的服务器，用临时 code 换 access_token，并与该门店 ID 绑定（一家店一个 token）。
- 定时拉取：服务器每 15 分钟用 token 调厂商「交易明细查询」接口 → 解析 → 落库。本页演示环境没有后端服务器，点「拉取」是用内置样例数据模拟这一步的返回结果。
- 每日对账：与厂商对账单核对笔数与金额，差异单挂起人工确认 —— 防止拉取丢单虚增或漏算。
- 诊断读取：诊断引擎从数据库读这份明细，算出客单价 / 品类 / 时段 —— 这一步在本页是真的，口径与上线版一致。
一句话：接入协议、数据契约、诊断口径是真的；缺的是后端服务器、厂商 AppKey 和落库 —— 这三样是工程实施，不是产品逻辑的缺环。