feat(M10-B): 完成可复算经营报表与日汇总

docs/business-report-metrics.md

@@ -0,0 +1,53 @@
+# 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`：加入日汇总重算任务，仅租户管理员和平台管理员默认拥有。
+- 所有接口仍执行租户、门店范围和服务端日期边界校验；前端筛选不构成权限边界。