qipai/docs/business-report-metrics.md

M10-B 经营报表指标口径

本文件固定 M10-B-v1 的统计口径。页面、CSV 导出、日汇总任务和明细复算均使用 BusinessReportService，不得分别实现不同算法。

时间与范围

• 请求使用闭区间本地日期 from、to，最长 93 天；“今日”和“近 7 日”只是该范围的快捷入口。
• 每家门店按 qipai_stores.timezone 的 IANA 时区独立换算本地零点，数据库时间仍为 UTC DATETIME(3)。
• 全门店报表只包含调用人获授权的门店；租户管理员和平台管理员可读取当前租户全部门店。
• 夏令时自然日可能是 23 或 25 小时，因此利用率分母按相邻两个门店本地零点的真实分钟差计算，不固定写死 1440 分钟。

金额指标

所有金额单位均为整数分。

指标	明细来源与公式
房费实收	qipai_payments 中成功、部分退款或全额退款状态的原支付，按 paid_at 归属日期；退款后的状态变化不能抹掉原始实收
房费退款	qipai_refunds 中成功退款，按 completed_at 归属日期
房费净收入	房费实收减房费退款
商品实收	qipai_product_payments 中成功或已全额退款的原支付，按 paid_at 归属日期
商品退款	qipai_product_refunds 中成功退款，按 completed_at 归属日期
商品净收入	商品实收减商品退款
总净收入	房费净收入加商品净收入
保洁成本	已付款结算明细按结算 paid_at 计正数；冲正明细按 reversed_at 计负数
贡献额	总净收入减保洁成本；不是会计利润，不包含租金、水电、渠道手续费和税费

支付渠道读取支付单的 channel，统一映射为微信、余额、套餐、团购平台和其他；退款按原支付渠道反向扣减。各渠道净额之和必须等于总净收入。

订单、人数和房间利用率

• 订单数按房间订单 created_at 归属日期统计，不包含商品订单。
• 下单人数按请求范围内房间订单 OWNER 用户去重；逐日行按当日去重，范围汇总不会把同一用户跨日重复计算。
• 实际使用开始时间优先取订单状态历史首次进入 IN_PROGRESS 的时间，结束时间优先取首次进入 FINISHED 的时间。
• 历史迁移订单缺状态时间时，只有 IN_PROGRESS/FINISHED/CLOSED 才回退到预订起止时间；其他状态不计实际使用。
• 跨日使用按每个门店自然日边界切分；进行中订单最多计算到查询时刻。
• 可用分钟 = 当日未删除房间数 × 当日真实分钟数；利用率基点 = 实际使用分钟 × 10000 ÷ 可用分钟，页面用百分比展示。
• 为避免异常重叠历史造成超过 100%，逐店逐日实际分钟最多取可用分钟；原始异常仍应通过订单/房间对账修复。

日汇总与复算

• qipai_business_daily_summaries 以 (tenant_id, store_id, business_date) 唯一保存逐店逐日结果和 source_checksum。
• Worker 每 5 分钟检查一次任务，每小时幂等安排最近 7 个门店自然日；管理员可对最多 93 天范围人工重算。
• 查询和 CSV 始终从业务明细实时复算，不把可能陈旧的日汇总当作资金事实源。
• 实时结果与日汇总 checksum 全部相同时返回 MATCHED；没有汇总返回 NOT_AGGREGATED；缺行或内容不同返回 MISMATCH。
• 退款、冲正或订单完成时间变化后，汇总允许被同一明细结果覆盖更新；不累计旧汇总，避免重复计账。

权限与导出

• report.read：读取授权门店报表。
• report.export：导出与页面同源的 UTF-8 CSV。
• report.manage：加入日汇总重算任务，仅租户管理员和平台管理员默认拥有。
• 所有接口仍执行租户、门店范围和服务端日期边界校验；前端筛选不构成权限边界。