shaguabijia-app-server/docs/api/other/order-report.md

POST /api/v1/order/report — 上报归因订单

所属:Order 组（前缀 /api/v1/order） | 鉴权:Bearer | ← 返回 API 索引

比价后 5 分钟内点链接下单、支付金额与比价价相差 ≤1 元时，客户端上报归因订单。落 savings_record（source='compare'），客户端幂等键防重。

入参

字段	类型	必填	说明
client_event_id	string	✅（≤64）	客户端幂等键（UUID）
platform	string	✅（≤32）	平台展示名（如 美团）
platform_package	string | null	❌	平台包名
pay_channel	string	✅（≤16）	支付渠道（wechat / alipay）
compared_price_cents	int	✅（≥0）	我们给出的比价价（分）
paid_amount_cents	int	✅（≥0）	实际支付金额（分）
device_id	string | null	❌	设备 ID
shop_name	string | null	❌	门店名（如 肯德基宅急送（天北路店））
dishes	list[string]	❌	菜品名列表
original_price_cents	int | null	❌	源平台原价（分），省额 = 原价 − 实付
source_platform_name	string | null	❌	源平台展示名（如 美团）
source_deeplink	string | null	❌	源平台重进链接（预留，本期只存不展示）

Mock 入参:

{
  "client_event_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "美团",
  "platform_package": "com.sankuai.meituan",
  "pay_channel": "wechat",
  "compared_price_cents": 2850,
  "paid_amount_cents": 2800,
  "device_id": "android_abc123def456",
  "shop_name": "肯德基宅急送（天北路店）",
  "dishes": ["香辣鸡腿堡套餐", "可口可乐（中）"],
  "original_price_cents": 4200,
  "source_platform_name": "美团",
  "source_deeplink": null
}

出参

响应 200:OrderReportOut

字段	类型	说明
id	int	省钱记录 ID
platform	string	平台
pay_channel	string	支付渠道
compared_price_cents	int	比价价（分）
paid_amount_cents	int	实付金额（分）
duplicated	bool	是否为重复上报（幂等命中）

Mock 出参:

{
  "id": 1234,
  "platform": "美团",
  "pay_channel": "wechat",
  "compared_price_cents": 2850,
  "paid_amount_cents": 2800,
  "duplicated": false
}

错误码

• 401 未鉴权 / token 失效
• 422 必填字段缺失或类型不符

说明

• 记账唯一真相表是 savings_record（source='compare'）
• client_event_id 幂等防重（网络重试不重复记）
• 省额 = original_price_cents − paid_amount_cents（若原价可用）