# 系统使用统计前后端落地文件清单

## 1. 本次提交信息

### 后端

- 仓库：`leaudit-platform-backend`
- 分支：`main`
- 提交：`0fec8ba`
- 提交信息：`fix(rbac): expose usage stats menu in settings`

### 前端

- 仓库：`legal-platform-frontend`
- 分支：`wren-dev`
- 提交：`09ed1d7`
- 提交信息：`feat(usage-stats): add system usage statistics page`

---

## 2. 后端文件清单

### 2.1 `fastapi_modules/fastapi_leaudit/services/impl/rbacServiceImpl.py`

本次对应该文件的职责是把“系统使用统计”正式接入系统设置菜单和 RBAC 路由兼容层。

已完成内容：

- 把 `/usage-stats` 加入最小可见路由前缀列表
- 在系统设置兼容菜单蓝图下新增子菜单：
  - 路径：`/usage-stats`
  - 标题：`系统使用统计`
  - 图标：`ri-bar-chart-box-line`
- 给 `/usage-stats` 补充权限前缀映射：
  - `usage_stats:`

落地效果：

- 后端返回的系统设置菜单中会包含“系统使用统计”
- 前端在系统设置模式下能够根据 RBAC 路由正常显示该菜单

---

## 3. 前端文件清单

### 3.1 `legal-platform-frontend/app/(audit)/usage-stats/page.tsx`

页面路由入口文件。

已完成内容：

- 新增 `/usage-stats` 页面入口
- 挂载 `UsageStatsClient`

### 3.2 `legal-platform-frontend/app/(audit)/usage-stats/UsageStatsClient.tsx`

系统使用统计页面主实现文件，也是本次前端改动的核心文件。

已完成内容：

- 总览区
  - 登录人数
  - 活跃用户数
  - 主文档上传数
  - 评查发起次数
- 筛选区
  - 统计时间
  - 地区
  - 地区口径
  - 趋势指标
  - 趋势粒度
- 趋势区
  - 支持折线图 / 面积图 / 柱状图切换
  - 支持 hover 提示框，展示“时间 + 次数”
  - 支持时间轴补齐，缺数据月份/周/日按 `0` 显示
  - 支持图表内部横向滚动
  - 支持“时间窗口”滑条控制图表内部滚动
- 列表区
  - 按部门查看使用成效
  - 按地区查看使用成效
  - 支持分页
  - 支持导出当前页 CSV
- 联动修复
  - 统计时间、地区、地区口径筛选会联动趋势、部门、地区区块
  - 地区列表改为前端完整拉取后再分页，避免只取后端第一页导致数据不全

### 3.3 `legal-platform-frontend/lib/api/legacy/usage-stats/usage-stats.ts`

系统使用统计接口封装文件。

已完成内容：

- 新增类型定义：
  - `UsageStatsOverview`
  - `UsageStatsTrend`
  - `UsageStatsDepartmentPage`
  - `UsageStatsAreaPage`
  - 以及对应 item 类型
- 新增接口封装：
  - `getUsageStatsOverview`
  - `getUsageStatsTrends`
  - `getUsageStatsDepartments`
  - `getUsageStatsAreas`
  - 预留了 `getUsageStatsUsers`
  - 预留了 `getUsageStatsDetails`
- 统一封装 usage-stats 响应解包逻辑

### 3.4 `legal-platform-frontend/styles/pages/usage-stats.css`

系统使用统计页面专属样式文件。

已完成内容：

- 页面头部、总览卡片、表格卡片样式
- 趋势图专属样式：
  - 折线/面积/柱状图视觉风格
  - hover 提示框
  - 图表切换按钮
  - 时间窗口滑条
- 卡片风格统一到现有系统设置页视觉语言
- 多轮修复图表导致整页横向滚动的问题

### 3.5 `legal-platform-frontend/components/layout/Sidebar.tsx`

系统设置菜单识别与侧边栏渲染逻辑。

已完成内容：

- 把 `/usage-stats` 纳入系统设置路径识别
- 系统设置模式下允许显示 `/usage-stats`
- 非系统设置模式下继续隐藏设置类菜单
- 修复系统设置模式路由切换时的依赖问题

### 3.6 `legal-platform-frontend/styles/main.css`

页面主布局样式文件。

已完成内容：

- 对 `.main-content` 增加：
  - `min-width: 0`
  - `overflow-x: hidden`
- 对 `.content-container` 增加：
  - `min-width: 0`
  - `overflow-x: hidden`

落地效果：

- 防止趋势图等宽内容把整个页面撑出横向滚动
- 确保图表横向滚动只发生在内部视口，而不是整页

---

## 4. 本次页面能力范围

本次已落地的系统使用统计页面能力为：

- 总览
- 总览趋势
- 按部门查看使用成效
- 按地区查看使用成效

本次未在页面中展开，但接口层已经预留的能力包括：

- 按用户查看使用成效
- 使用明细明细流

---

## 5. 相关联动说明

### 菜单显示链路

系统使用统计菜单显示依赖以下链路全部打通：

1. 后端 RBAC 路由兼容层返回 `/usage-stats`
2. 前端侧边栏把 `/usage-stats` 识别为系统设置子页面
3. 当前账号具备 `usage_stats:*` 权限

### 图表与布局修复链路

为解决“整页横向滚动”“时间窗口拖了图不动”等问题，本次实际同时改动了：

1. 趋势图 SVG 实际宽度控制
2. 趋势图内部滚动视口
3. 时间窗口滑条与 `scrollLeft` 联动
4. 主内容区与内容容器的 `min-width / overflow-x`

因此这部分不是单点改动，而是一组联动修复。

---

## 6. 建议后续增强项

后续如果继续迭代系统使用统计，建议优先按下面顺序推进：

1. 接入“按用户查看使用成效”
2. 接入“行为明细”查看页
3. 增加更细粒度筛选：
   - 入口模块
   - 文档类型
4. 趋势图增加更完整的交互：
   - tooltip 优化
   - 缩略导航
   - 导出趋势图
5. 增加系统使用统计专属权限点配置页说明文档