docs: consolidate usage stats documentation

2026-05-10 21:04:07 +08:00
parent 601811f957
commit 58ee6a1085
9 changed files with 534 additions and 2060 deletions
@@ -0,0 +1,270 @@
+# 系统使用统计实施版
+
+## 1. 实施目标
+
+基于《系统使用统计最终版》，落地一期可用方案，范围收敛为：
+
+- 后端统计接口
+- 登录统计补数
+- 上传/评查统计查询
+- 权限隔离
+- 前端“总览 + 按部门 + 按地区”页面
+- 上线 SQL 与验收流程
+
+## 2. 实际落地方案
+
+### 2.1 数据来源
+
+统计数据来源分两类：
+
+- 复用现有业务事实表
+- 补最小新增事件表
+
+其中：
+
+- 上传统计：复用现有文档与文件表
+- 评查统计：复用现有评查运行表
+- 登录统计：新增登录事件表
+- 用户最近登录时间：补 `sso_users.last_login_at`
+
+### 2.2 复用的现有表
+
+- `sso_users`
+  - 用户、部门、地区来源
+  - 最近登录时间展示
+
+- `leaudit_documents`
+  - 文档主记录
+  - 文档类型、地区、状态来源
+
+- `leaudit_document_files`
+  - 主文件上传、附件上传统计
+  - 上传人、上传时间明细来源
+
+- `leaudit_audit_runs`
+  - 评查发起、完成、失败统计
+  - 评查时间趋势
+  - 发起人必须依赖 `trigger_user_id`
+
+- `leaudit_document_types`
+  - 文档类型维度
+  - 入口模块归属
+
+- `leaudit_entry_modules`
+  - 入口模块维度
+
+## 3. 新增与补齐的库结构
+
+### 3.1 新增字段
+
+- `sso_users.last_login_at`
+  - 含义：最近一次成功登录时间
+  - 作用：用户维度统计、最近登录展示
+
+### 3.2 新增表
+
+- `usage_login_events`
+  - 用途：记录登录成功/失败事件
+  - 核心字段：
+    - `user_id`
+    - `sub`
+    - `username_snapshot`
+    - `nick_name_snapshot`
+    - `department_name_snapshot`
+    - `ou_name_snapshot`
+    - `area_snapshot`
+    - `login_time`
+    - `login_result`
+    - `login_type`
+    - `ip_address`
+    - `user_agent`
+    - `failure_reason`
+
+### 3.3 已落地 SQL
+
+统一放在：`scripts/创建sql/`
+
+本功能核心脚本：
+
+- `scripts/创建sql/schema_add_usage_stats.sql`
+- `scripts/创建sql/seed_usage_stats_rbac.sql`
+
+## 4. 后端接口口径
+
+统一前缀：`/api/v3/usage-stats`
+
+已定义的一期接口：
+
+- `GET /api/v3/usage-stats/overview`
+- `GET /api/v3/usage-stats/trends`
+- `GET /api/v3/usage-stats/by-users`
+- `GET /api/v3/usage-stats/by-departments`
+- `GET /api/v3/usage-stats/by-areas`
+- `GET /api/v3/usage-stats/details`
+
+一期前端先接：
+
+- `overview`
+- `by-departments`
+- `by-areas`
+
+## 5. 核心权限与地区隔离
+
+### 5.1 页面入口
+
+页面入口放在：
+
+- 系统设置
+- 路由：`/usage-stats`
+
+### 5.2 权限点
+
+已定义权限：
+
+- `usage_stats:overview:read`
+- `usage_stats:trends:read`
+- `usage_stats:users:read`
+- `usage_stats:departments:read`
+- `usage_stats:areas:read`
+- `usage_stats:details:read`
+
+### 5.3 角色范围
+
+- `super_admin`：看全量
+- `provincial_admin`：看全量
+- `admin`：作为地区管理员，仅看本地区
+
+### 5.4 实施要求
+
+- 不能只靠前端限制
+- 必须由后端按当前登录用户地区做数据过滤
+- 按地区页在 `admin` 角色下只能返回当前地区数据
+
+## 6. 一期前端范围
+
+一期页面只做：
+
+- 总览
+- 按部门
+- 按地区
+
+放置位置：
+
+- 系统设置
+
+页面要求：
+
+- 支持时间范围筛选
+- 支持按地区筛选
+- 按地区页支持地区口径切换
+- 页面可用优先，不继续堆复杂交互
+
+## 7. 后端实现拆解
+
+### 7.1 登录链路补数
+
+代码位置：
+
+- `fastapi_modules/fastapi_leaudit/controllers/auth/authController.py`
+- `fastapi_modules/fastapi_leaudit/services/usageStatsService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py`
+
+要求：
+
+- 成功登录写 `usage_login_events`
+- 失败登录写 `usage_login_events`
+- 成功登录更新 `sso_users.last_login_at`
+- 不影响现有登录返回结构
+
+### 7.2 评查链路补数
+
+代码位置：
+
+- `fastapi_modules/fastapi_leaudit/controllers/auditController.py`
+- `fastapi_modules/fastapi_leaudit/services/auditService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`
+
+要求：
+
+- 创建评查 run 时写入 `trigger_user_id`
+- 上传后自动评查与手工发起评查都要补齐
+
+### 7.3 统计查询接口
+
+代码位置：
+
+- `fastapi_modules/fastapi_leaudit/controllers/usageStatsController.py`
+- `fastapi_modules/fastapi_leaudit/services/usageStatsService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py`
+
+要求：
+
+- 概览页可直接取数
+- 部门页可分页汇总
+- 地区页支持地区口径切换
+- 后端完成权限与地区过滤
+
+## 8. 上线顺序
+
+### 8.1 SQL
+
+先执行：
+
+1. `scripts/创建sql/schema_add_usage_stats.sql`
+2. `scripts/创建sql/seed_usage_stats_rbac.sql`
+
+### 8.2 服务
+
+- 发布后端代码
+- 重启后端服务
+- 用管理员账号重新登录一次
+- 手动上传一次文档
+- 手动发起一次评查
+
+### 8.3 验收
+
+必须验证：
+
+- `usage_login_events` 有数据
+- `sso_users.last_login_at` 有更新
+- `leaudit_audit_runs.trigger_user_id` 有写入
+- `/usage-stats` 菜单可见
+- 超级管理员可看全量
+- 地区管理员只能看本地区
+
+## 9. 当前推荐验收 SQL
+
+```sql
+SELECT column_name
+FROM information_schema.columns
+WHERE table_name = 'sso_users'
+  AND column_name = 'last_login_at';
+
+SELECT to_regclass('public.usage_login_events');
+
+SELECT id, username, last_login_at
+FROM sso_users
+WHERE last_login_at IS NOT NULL
+ORDER BY last_login_at DESC
+LIMIT 10;
+
+SELECT id, user_id, login_result, login_type, login_time
+FROM usage_login_events
+ORDER BY id DESC
+LIMIT 10;
+
+SELECT id, trigger_user_id, status, created_at
+FROM leaudit_audit_runs
+ORDER BY id DESC
+LIMIT 10;
+```
+
+## 10. 当前文档收口原则
+
+本目录只保留这两份：
+
+- `docs/系统使用统计/系统使用统计最终版.md`
+- `docs/系统使用统计/系统使用统计实施版.md`
+
+老的“最终需求 / 表设计 / 接口设计 / 开发任务拆解”内容，统一并入这两份主文档，不再继续扩散。