feat(distribution): 新增分销看板

2026-10-30 15:51:56 +08:00
parent 090ab02a67
commit d37cbad323
8 changed files with 427 additions and 2 deletions
@@ -0,0 +1,81 @@
+# Phase 2 验收报告（分销看板）
+
+> 日期：2026-10-30  
+> 项目：解忧商行（hfb_jysh）  
+> 范围：后台分销看板  
+> 结论：**本切片通过，只读统计页已接真实接口，typecheck/build 通过**
+
+---
+
+## 1. 页面与路由
+
+| 页面 | 路由 | 文件 |
+| --- | --- | --- |
+| 分销看板 | `/console-jy8k3m/distribution/dashboard` | `frontend/src/features/admin/AdminDistributionDashboardPage.tsx` |
+
+权限：`distribution:site_view`。
+
+## 2. 接口
+
+| 能力 | 接口 | 权限码 |
+| --- | --- | --- |
+| 站点经营分析 | `GET /api/admin/distribution/sites/:id/analytics` | `distribution:site_view` |
+
+后端返回：
+
+- 今日/累计收号
+- 在售商品数
+- 今日订单数
+- 今日 GMV、今日利润、本月利润
+- 站点可用余额
+- 今日新增用户、累计注册用户、成交客户数
+- 最近 7 天趋势：日期、收号、订单、GMV、利润
+
+结果在 Redis 缓存 60 秒，前端刷新会重新请求。
+
+## 3. 页面能力
+
+- 站点选择器复用 `DistributionSiteSelect`，站点 ID 写入 URL。
+- 10 个 KPI 卡片：今日收号、在售商品、今日订单、今日 GMV、今日利润、本月利润、可用余额、今日新增、成交客户、累计用户。
+- 金额全部按整数分展示，统一使用 `formatMoney(cents)`。
+- 近 7 天趋势：
+  - 日期、收号、订单、GMV、利润
+  - 利润横向条形图，按 7 天最大利润归一化
+  - 窄屏横向滚动，不压缩表格
+- 快捷入口：分销订单、分销用户、站点钱包。
+- 无权限时停止请求并提示；站点为空时显示统一空态。
+
+## 4. 共用改造
+
+- `frontend/src/features/admin/types.ts`：新增分销分析、趋势点类型。
+- `frontend/src/features/admin/api.ts`：新增 `fetchAdminDistributionAnalytics`。
+- `frontend/src/app/AppRouter.tsx`：新增 `distribution/dashboard`。
+- `frontend/src/layouts/AdminLayout.tsx`：分销菜单新增「分销看板」并置于分组首位。
+- `frontend/src/styles/admin-distribution.css`：新增看板网格、趋势列表与利润条样式。
+
+## 5. 验证结果
+
+```text
+cd frontend && npx tsc --noEmit                         通过
+cd frontend && npm run build                            通过（入口 525.59 kB，gzip 168.56 kB）
+
+GET /console-jy8k3m/distribution/dashboard              200
+GET /api/admin/distribution/sites/1/analytics           200
+```
+
+开发库无分销数据，接口返回全 0，并正常返回最近 7 天日期趋势（2026-10-24 至 2026-10-30）。未调用任何写接口。
+
+## 6. 已知限制
+
+1. 趋势窗口固定为最近 7 天，后端暂不支持自定义区间。
+2. 统计缓存 60 秒，刚发生的订单/收号可能短暂延迟。
+3. 今日口径按服务器时区自然日计算。
+4. 不提供导出；需要导出时可另接报表能力。
+5. 开发库无真实站点数据，仅验证了零值响应与页面空态，未做真实经营数据视觉回归。
+
+## 7. 下一步建议
+
+1. 分销账号同步入口。
+2. 主站支付配置管理页（如主后台仍未迁移）。
+3. 真实站点数据下回归看板口径与趋势。
+4. 订单结算比例全面 bps 化与真实订单端到端回归。
@@ -395,7 +395,7 @@ hfb_jysh/

 ### Phase 4：管理后台核心（4–5 周）

-> 状态：**进行中（2026-10-30）**。已完成仪表盘、订单、退款、提现、商品、用户、申诉、财务看板、资金出款、运营开支、公告管理、审计日志、系统配置、分销站点、站点钱包、分销订单、结算批次、分销用户、站点公告、分销商品、支付通道、规则版本、二维码池、站点短信与邀请返利；剩余分销看板、账号同步、主站支付配置管理等细分长尾和真实订单端到端回归。
+> 状态：**进行中（2026-10-30）**。已完成仪表盘、订单、退款、提现、商品、用户、申诉、财务看板、资金出款、运营开支、公告管理、审计日志、系统配置、分销站点、分销看板、站点钱包、分销订单、结算批次、分销用户、站点公告、分销商品、支付通道、规则版本、二维码池、站点短信与邀请返利；剩余分销账号同步、主站支付配置管理等细分长尾和真实订单端到端回归。

 - 后台登录、工作台、订单列表、订单详情。
 - 商品列表、商品详情、审核。