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

```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`

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