leaudit-platform-backend/docs/系统使用统计/系统使用统计实施版.md

系统使用统计实施版

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

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

老的“最终需求 / 表设计 / 接口设计 / 开发任务拆解”内容，统一并入这两份主文档，不再继续扩散。