dashboard — 仪表盘（5 action）

前缀：/api/v1/admin/dashboard/ 权限：全部 DASHBOARD_READ（三角色共享） 代码：src/app/admin/interface/api/dashboard_v1.py + application/usecase/dashboard_stats.py

3.2.1 overview —— 总览

GET /api/v1/admin/dashboard/overview?range=day

Query 参数：

字段	类型	必填	默认	说明
range	string	⬜	day	day | week | month

响应 data（⚠️ snake_case 新字段 + camelCase P0 存量字段混合）：

字段	类型	说明
range	string	回显口径
total_users	int	全量用户数
active_users	int	活跃用户数
total_orders	int	订单总数
total_revenue	float	累计营收
anomaly_count	int	异常数
totalAdmins	int	P0 存量：admin 账号总数
activeAdmins	int	P0 存量：活跃 admin 数
roleDistribution	object	P0 存量：{super: n, operator: n, it: n}
recentLogins24h	int	P0 存量：24h 内登录次数
pendingAudits	int	P0 存量：待审数

错误码：40201001 非法 range。

注：P0 版本 /overview 被本 v1 superset 覆盖（同路径，注册顺序优先），存量字段合并返回。

3.2.2 user-growth —— 用户增长曲线

GET /api/v1/admin/dashboard/user-growth?range=day&granularity=day

Query 参数：

字段	类型	必填	默认	说明
range	string	⬜	day	时间范围
granularity	string	⬜	day	day | hour

响应 data：{ "range": ..., "granularity": ..., "series": [ {时间点, 新增数…} ] }

错误码：40201001 非法 range / granularity。

3.2.3 order-stats —— 订单统计

GET /api/v1/admin/dashboard/order-stats?range=day

响应 data：

字段	类型	说明
range	string	回显口径
total	int	订单总数
paid	int	已支付数
refunded	int	已退款数
closed	int	已关闭数
series	array	时间序列

错误码：40201001 非法 range。

3.2.4 revenue —— 营收统计

GET /api/v1/admin/dashboard/revenue?range=day

响应 data：

字段	类型	说明
range	string	回显口径
gross_revenue	float	毛营收
net_revenue	float	净营收（扣退款）
refund_amount	float	退款总额
by_channel	array	按支付渠道拆分

错误码：40201001 非法 range。

3.2.5 anomalies —— 异常清单

GET /api/v1/admin/dashboard/anomalies?severity=high

Query 参数：

字段	类型	必填	默认	说明
severity	string	⬜	high	low | medium | high

响应 data：{ "severity": ..., "anomalies": [ {severity, …} ] }

错误码：40201001 非法 severity。

---

通用失败：未登录 → 401 + 40201002；权限不足 → 403 + 40201004（三角色均持有 DASHBOARD_READ，正常不会触发）。