后台数据看板如何区分经营口径和资金口径

一个“营业额”字段为什么会误导人

栖光后台数据看板做过一次重要重构：后台看板聚合接口不再用一个泛化的“营业额”承载所有含义，而是拆成经营指标和资金指标。

这个改动看起来像是 数据看板 页面优化，实际更接近一次业务口径重构。因为在餐饮和酒吧场景里，“钱”不是一个单一概念。顾客支付了一笔点餐订单、用户给账户充值、后台审核了一笔退款、用户用余额支付了一部分金额，这些事件都和金额有关，但它们不能全部算进同一个营业额。

如果后台只显示一个总数，运营人员很难判断今天到底发生了什么：是堂食和商城订单卖得好，还是充值比较多？微信实际收款有没有增加？退款对经营结果影响多少？余额支付消耗的是账户余额，不一定代表当天新增现金流。如果这些问题都被一个数字盖住，看板就会从“辅助判断”变成“制造误解”。

经营口径看业务，资金口径看流动

这次重构后，栖光把指标拆成两组。

经营指标回答“业务卖得怎么样”，包括经营成交额、退款金额、净营业额、营业订单数和客单价。它关心的是点餐和商城这类真实经营订单的结果。

资金指标回答“钱实际怎么流动”，包括微信实收净额、微信经营收款、微信退款、余额支付净额、余额支付、余额退款和充值入账。它关心的是微信渠道、余额账户、充值和退款之间的资金变化。

这个拆分的价值在于，它让后台看板不再只展示一个漂亮数字，而是把业务结果和资金结果分开说明。经营成交额高，说明业务订单规模高；微信实收净额高，说明微信渠道带来的实际收款高；充值入账高，说明用户账户资金增加，但不能直接等同于当期经营收入。

测试环境截图，数据仅用于展示看板结构，不代表真实经营数据。

统计时间必须跟业务事件绑定

看板口径真正容易出错的地方，是统计时间字段。

营业订单应该按 orders.paid_at 统计，因为支付成功才代表这笔经营订单进入有效成交。退款影响应该按 refund_records.processed_at 统计，因为退款审核处理完成后才会影响经营结果和资金结果。充值订单也要和它自己的支付或入账事件绑定，不能为了查询方便强行跟普通订单混在一起。

这听起来很细，但这正是业务系统和演示页面的区别。演示页面只要能显示金额；业务系统必须说明金额从哪里来、什么时候发生、影响哪个口径。

栖光这次重构的重点就是把这些事件拆清楚：营业订单、充值订单和退款记录分别进入不同聚合，再由后台页面用经营概览、资金概览、经营趋势、资金趋势和分组最近订单展示出来。

接口返回结构也要跟着变

指标口径变化后，后端返回结构一定会变化。栖光这次不是在前端硬改几个文案，而是让后端接口新增经营/资金指标、双趋势和最近订单分组，再同步生成 Admin 类型。

这一步很关键。因为如果后端已经拆出口径，前端仍然用旧的 revenue 之类概念接收，页面就会继续把不同业务含义揉在一起。反过来，如果前端页面先拆了卡片，但后端接口没有真正拆聚合，页面只是换了标题，也不是真正的数据看板重构。

栖光的数据看板涉及 DashboardStats、DashboardBusinessTrendPoint、DashboardFundTrendPoint 和 DashboardRecentOrder 等生成类型。它们让页面知道：经营趋势和资金趋势不是同一个列表，最近营业订单、最近充值和最近退款也不是同一种记录。

这就是接口契约在数据看板里的意义：它迫使“页面怎么展示”和“后端怎么算”围绕同一套结构同步变化。

验证不应该只看页面有没有报错

数据看板最危险的地方，是页面看起来正常，但数字是错的。

所以栖光这次重构的验证链路不只包含页面构建。任务看板和测试策略里记录了完整验证：后端执行 config.service.test.ts，确认聚合逻辑；后端执行 npm run build；Admin 执行 npm run generate-api；Dashboard 页面执行 dashboard-page.test.mjs 和 dashboard-filter-navigation.test.mjs；再执行 tsc --noEmit 和 npm run build。

这些自动化检查能证明结构和页面没有明显断裂，但还不能完全替代人工验收。测试策略里仍然保留了人工验收项：用真实后台数据确认“微信实收净额”是否等于经营微信收款加充值入账再减微信退款；抽查混合支付订单和部分退款订单，确认看板金额与订单详情一致；切换到有充值记录的日期，确认最近充值不会混入营业订单。

这类人工验收不是形式主义，而是金额口径类功能必须保留的最后确认。

这次重构真正体现了什么能力

如果只说“我做了一个数据看板”，其实很容易被理解成后台图表页面。但栖光这次更值得写出来的，是指标拆分背后的判断。

我需要先确认业务事件：订单支付、充值入账、退款处理。再确认统计字段：paid_at、退款处理时间和充值对应时间。然后设计后端聚合结构、OpenAPI 返回结构、Admin 页面信息层级，最后用测试和人工验收确认结果。

这条链路比写一个图表复杂得多，也更接近真实业务项目。因为真实后台系统的看板不是装饰，它会影响运营人员对今天经营情况的判断。口径错了，图表越漂亮越危险。