foodie-server/specs/039-merchant-order-receipt/frontend-app-integration.md

商家 App 小票数据接入

接口使用请求头 token: 商家登录token，返回统一包装 {code:200,msg:"...",data:...}。接口只提供数据，连接打印机、排版和出纸由 App 实现。

订单小票信息

小票功能直接提供，无需查询启用状态或配置字典。

GET /system/orderShOprate/getOrderPrintInfo?orderId=3173

orderId 是订单列表里的 pos_order.id，不是订单号 ddId、父单号或多店批次 ID。多店订单对每张子单分别读取，按对应门店打印。

返回字段（data）

字段	类型	说明
orderId / orderNo	long / string	订单主键 / 完整订单号，订单号按字符串处理
storeId / storeName	long / string	门店ID / 下单时店名快照（没有快照才取当前店名）
storeAddress / storeTelephone	string	当前门店地址 / 电话；可能为空
createTime	string	下单时间，yyyy-MM-dd HH:mm:ss，UTC+8
orderType	long	0外送、1自取、2堂食
selfDelivery	int	1商家自配送、0平台配送；老单可能为空
state	long	订单现有状态码，沿用商家订单页面解释
payType / payStatus	string / long	原订单支付方式 / 支付状态，不做文字转换
pickUpNum / tableNo	long / string	取餐号 / 桌号；不适用时为空
delryTime / pickUpTime	string	原订单预约配送信息 / 自取时间，原样展示；可能为空
reservePhone	string	自取预留电话；可能为空
recipient	object或null	收货信息，仅 {name,phone,address,addressDetail}；无地址时为 null
items	array	商品快照，结构见下表，不需要再解析 JSON 字符串
foodAmount	int或null	原订单保存的商品总额；不根据当前菜单重算
amount	int或null	原订单应付总额，作为小票总额直接展示
freight	number	原配送费，包含客户实付和商家承担部分
customerDeliveryFee	number	客户实付配送费；老单无此快照时回退 freight，小票客户运费显示此字段
merchantDeliverySubsidy	number	商家承担的免运金额；老单返回0，与商品优惠分开
discounts	object	商品优惠分项和合计，结构见下文
remarks	string	整张子单备注

items[]

字段	类型	说明
foodId	long或null	商品ID；老单可能缺失
name	string	下单时商品名称
quantity	int	商品数量，取快照 number
price / otherPrice	number或null	快照商品价格 / 规格加价；保留原值，老单字段可能为空
specifications	string[]	取快照 ask，例如 ["小","中辣"]；没有时为空数组
remarks	string或null	该商品备注，取快照 beizhu

discounts 字段均为 number，缺失按0返回：

• platformCouponAmount：平台优惠券，取 discountAmount。
• storeCouponAmount：门店优惠券，取 mdDiscountAmount。
• platformPromotionAmount：平台促销，取 salesReduction。
• storePromotionAmount：门店促销，取 mdSalesReduction。
• pointsAmount：积分抵扣，取 pointsReduction。
• totalAmount：上述五项之和，不包含商家运费补贴。

所有金额沿用订单单位（TWD元），不要再除100。amount 是权威订单总额；优惠只用于列示，不能再从 amount 扣一次。历史订单 price/otherPrice 不统一重算，App 不应靠逐行金额重建应付。没有存储税额，不返回固定为0的 tax。

关键处理

• 收货人、商品、规格、备注、金额取下单快照，不因用户改地址、商品改价或规格删除而改变。
• 到付 payType="1" 即使 payStatus=1，也不代表客户已经交现金，应标记到付，不能标记已收款。
• 用户、骑手和无权限的商家不能读取；分管账号受授权门店限制，摊主受绑定摊位限制。
• 商品或地址快照损坏会返回业务错误，App 提示错误，不打印空白小票。
• 本轮未接入自动打印、设备绑定、打印状态回执、去重或补打记录。App 不应把每一次推送都直接当作可重复出纸的命令；新订单触发、重试与设备能力需要后续单独完成。
• 这里是订单小票，不是电子发票证明联；不返回发票防伪码或打印发票凭证。