leaudit-platform-backend/docs/系统使用统计/系统使用统计前后端落地文件清单.md

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

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. 增加系统使用统计专属权限点配置页说明文档