docs(usage-stats): add implementation file inventory

2026-05-11 01:13:31 +08:00
parent 0fec8baafd
commit 900fc2e8a2
1 changed files with 207 additions and 0 deletions
@@ -0,0 +1,207 @@
+# 系统使用统计前后端落地文件清单
+
+## 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. 增加系统使用统计专属权限点配置页说明文档
+