# 系统使用统计接口设计

## 1. 设计目标

基于“系统使用统计最终需求”，提供一套统一的统计查询接口，满足以下场景：

- 概览页查看核心指标与分布情况
- 明细页查看登录、上传、评查记录
- 支持按用户、部门、地区、文档大类、文档类型、入口模块筛选
- 支持动态分类，不写死业务名称
- 支持后续扩展导出、聚合表与驾驶舱

## 2. 设计原则

- 统一前缀：`/api/v3/usage-stats`
- 所有接口均需登录鉴权
- 汇总接口与明细接口分离
- 所有查询默认支持时间范围筛选
- 分类字段尽量返回 `id + code + name`
- 地区统计支持 `user` / `document` 两种口径

## 3. 统一筛选参数

以下参数为统计接口通用参数，按接口需要选用。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dateFrom` | string | 否 | 起始日期，格式 `YYYY-MM-DD` |
| `dateTo` | string | 否 | 结束日期，格式 `YYYY-MM-DD` |
| `userId` | integer | 否 | 用户 ID |
| `departmentName` | string | 否 | 部门名称 |
| `area` | string | 否 | 地区编码/地区值 |
| `areaScope` | string | 否 | 地区口径：`user` / `document`，默认 `user` |
| `entryModuleId` | integer | 否 | 入口模块 ID |
| `documentCategoryId` | integer | 否 | 文档大类 ID |
| `documentTypeId` | integer | 否 | 文档类型 ID |
| `dataType` | string | 否 | 明细类型：`login` / `upload` / `audit` |
| `page` | integer | 否 | 页码，默认 1 |
| `pageSize` | integer | 否 | 每页大小，默认 20，最大 200 |
| `sortBy` | string | 否 | 排序字段 |
| `sortOrder` | string | 否 | 排序方向：`asc` / `desc` |

## 4. 接口清单

### 4.1 获取使用统计概览

`GET /api/v3/usage-stats/overview`

#### 作用

返回概览页顶部核心指标与基础汇总。

#### 请求参数

支持：
- `dateFrom`
- `dateTo`
- `area`
- `areaScope`
- `entryModuleId`
- `documentCategoryId`
- `documentTypeId`

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "loginUserCount": 128,
    "loginCount": 346,
    "activeUserCount": 152,
    "uploadDocumentCount": 512,
    "uploadAttachmentCount": 203,
    "auditRunCount": 438,
    "auditCompletedCount": 401,
    "auditFailedCount": 19,
    "lastUpdatedAt": "2026-05-09 18:30:00"
  }
}
```

### 4.2 获取时间趋势统计

`GET /api/v3/usage-stats/trends`

#### 作用

返回按日、周或月聚合的趋势数据。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dateFrom` | string | 否 | 起始日期 |
| `dateTo` | string | 否 | 结束日期 |
| `granularity` | string | 否 | 聚合粒度：`day` / `week` / `month`，默认 `day` |
| `metric` | string | 否 | 指标：`login` / `upload` / `audit` / `active_user` |
| 其余通用筛选参数 | - | 否 | 同上 |

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "granularity": "month",
    "metric": "audit",
    "items": [
      { "label": "2026-01", "value": 42 },
      { "label": "2026-02", "value": 57 },
      { "label": "2026-03", "value": 63 }
    ]
  }
}
```

### 4.3 获取按用户汇总统计

`GET /api/v3/usage-stats/by-users`

#### 作用

按用户汇总登录、上传、评查情况，可用于用户排行与用户分析。

#### 请求参数

支持全部通用参数，另外支持：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `keyword` | string | 否 | 用户名/姓名模糊搜索 |

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "userId": 101,
        "username": "zhangsan",
        "nickName": "张三",
        "departmentName": "法规科",
        "area": "mz",
        "loginCount": 12,
        "uploadDocumentCount": 20,
        "uploadAttachmentCount": 8,
        "auditRunCount": 15,
        "auditCompletedCount": 14,
        "auditFailedCount": 1,
        "lastLoginTime": "2026-05-09 09:12:00"
      },
      {
        "userId": 102,
        "username": "lisi",
        "nickName": "李四",
        "departmentName": "合同管理部",
        "area": "jy",
        "loginCount": 8,
        "uploadDocumentCount": 11,
        "uploadAttachmentCount": 3,
        "auditRunCount": 9,
        "auditCompletedCount": 9,
        "auditFailedCount": 0,
        "lastLoginTime": "2026-05-08 16:20:00"
      }
    ]
  }
}
```

### 4.4 获取按部门汇总统计

`GET /api/v3/usage-stats/by-departments`

#### 作用

按部门汇总登录、上传、评查使用情况。

#### 请求参数

支持：
- `dateFrom`
- `dateTo`
- `area`
- `areaScope`
- `entryModuleId`
- `documentCategoryId`
- `documentTypeId`
- `keyword`（部门模糊搜索）

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "items": [
      {
        "departmentName": "法规科",
        "userCount": 18,
        "loginUserCount": 15,
        "loginCount": 63,
        "uploadDocumentCount": 40,
        "auditRunCount": 52,
        "auditCompletedCount": 48,
        "auditFailedCount": 2
      }
    ]
  }
}
```

### 4.5 获取按地区汇总统计

`GET /api/v3/usage-stats/by-areas`

#### 作用

按地区汇总统计，支持用户地区口径和文档地区口径。

#### 请求参数

支持：
- `dateFrom`
- `dateTo`
- `areaScope`
- `entryModuleId`
- `documentCategoryId`
- `documentTypeId`

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "areaScope": "user",
    "items": [
      {
        "area": "mz",
        "loginUserCount": 36,
        "loginCount": 120,
        "uploadDocumentCount": 75,
        "auditRunCount": 82,
        "auditCompletedCount": 78,
        "auditFailedCount": 3
      }
    ]
  }
}
```

### 4.6 获取按文档大类汇总统计

`GET /api/v3/usage-stats/by-categories`

#### 作用

动态统计各文档大类下的评查使用情况，不写死业务名称。

#### 请求参数

支持：
- `dateFrom`
- `dateTo`
- `area`
- `areaScope`
- `entryModuleId`
- `documentCategoryId`

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "items": [
      {
        "documentCategoryId": 1,
        "documentCategoryCode": "contract",
        "documentCategoryName": "合同类",
        "auditRunCount": 145,
        "auditCompletedCount": 138,
        "auditFailedCount": 4
      }
    ]
  }
}
```

### 4.7 获取按文档类型汇总统计

`GET /api/v3/usage-stats/by-document-types`

#### 作用

统计各文档类型下的上传与评查使用情况。

#### 请求参数

支持全部核心通用筛选参数。

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "items": [
      {
        "documentTypeId": 12,
        "documentTypeCode": "contract_tech",
        "documentTypeName": "技术合同",
        "entryModuleId": 3,
        "entryModuleName": "合同管理",
        "uploadDocumentCount": 32,
        "auditRunCount": 29,
        "auditCompletedCount": 28,
        "auditFailedCount": 1
      }
    ]
  }
}
```

### 4.8 获取按入口模块汇总统计

`GET /api/v3/usage-stats/by-entry-modules`

#### 作用

统计各入口模块下的上传与评查使用情况。

#### 请求参数

支持：
- `dateFrom`
- `dateTo`
- `area`
- `areaScope`
- `entryModuleId`

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "items": [
      {
        "entryModuleId": 3,
        "entryModuleName": "合同管理",
        "uploadDocumentCount": 120,
        "auditRunCount": 118,
        "auditCompletedCount": 112,
        "auditFailedCount": 4
      }
    ]
  }
}
```

### 4.9 获取使用明细列表

`GET /api/v3/usage-stats/details`

#### 作用

统一查询登录、上传、评查三类明细数据。

#### 请求参数

支持全部通用参数，其中 `dataType` 建议必传：

- `login`
- `upload`
- `audit`

#### 响应示例

```json
{
  "success": true,
  "message": "ok",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "time": "2026-05-09 10:23:11",
        "dataType": "audit",
        "userId": 101,
        "username": "zhangsan",
        "nickName": "张三",
        "departmentName": "法规科",
        "area": "mz",
        "documentId": 886,
        "documentName": "采购合同.docx",
        "documentCategoryId": 1,
        "documentCategoryName": "合同类",
        "documentTypeId": 12,
        "documentTypeName": "技术合同",
        "entryModuleId": 3,
        "entryModuleName": "合同管理",
        "status": "completed",
        "extra": {
          "runId": 9981,
          "resultStatus": "pass"
        }
      }
    ]
  }
}
```

### 4.10 导出明细

`GET /api/v3/usage-stats/export`

#### 作用

导出当前筛选条件下的明细数据。

#### 请求参数

与 `/details` 相同，另支持：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `format` | string | 否 | 导出格式：`csv` / `xlsx`，默认 `xlsx` |

#### 响应

- 文件流下载
- 响应头返回文件名

## 5. 返回结构约定

所有统计接口统一使用：

```json
{
  "success": true,
  "message": "ok",
  "data": {}
}
```

分页结构统一使用：

```json
{
  "total": 100,
  "page": 1,
  "pageSize": 20,
  "items": []
}
```

## 6. 数据来源建议

### 6.1 登录数据

当前系统若尚未持久化登录记录，建议补充登录统计来源表，例如：

- `usage_login_events`

至少记录：
- 用户 ID
- 登录时间
- 部门快照
- 地区快照

### 6.2 上传数据

建议来源：
- `leaudit_document_files`
- `leaudit_documents`
- `sso_users`

其中：
- 主文件上传：`file_role = 'primary'`
- 附件上传：`file_role = 'attachment'`

### 6.3 评查数据

建议来源：
- `leaudit_audit_runs`
- `leaudit_documents`
- `leaudit_document_types`
- `leaudit_entry_modules`

### 6.4 用户与组织信息

建议来源：
- `sso_users`

主要字段：
- `id`
- `username`
- `nick_name`
- `dep_name`
- `ou_name`
- `area`

## 7. 动态分类建议

为避免写死业务名称，建议使用以下动态归类链路：

- 文档 -> 文档类型
- 文档类型 -> 文档大类
- 文档类型 -> 入口模块

若当前系统尚无稳定的“文档大类”实体，可采用以下两种方式之一：

- 方式一：基于已有一级分组/一级文档类型直接汇总
- 方式二：增加一张“统计分类映射表”进行归类

## 8. 权限建议

建议接口默认仅开放给具备管理权限的角色，例如：

- 超级管理员
- 省级管理员
- 地市管理员
- 具备统计查看权限的业务管理角色

后续可增加独立权限点，例如：

- `usage_stats:overview:read`
- `usage_stats:details:read`
- `usage_stats:export:read`

## 9. 一期实现优先级建议

### P0

- `/overview`
- `/trends`
- `/by-users`
- `/by-departments`
- `/by-areas`
- `/details`

### P1

- `/by-categories`
- `/by-document-types`
- `/by-entry-modules`
- `/export`

### P2

- 聚合表优化
- 驾驶舱接口
- 大屏接口

## 10. 后续优化建议

- 增加日汇总表，提升一年跨度查询性能
- 增加部门、地区快照，避免组织调整影响历史统计
- 为明细与汇总增加统一缓存策略
- 为导出增加异步任务模式，避免大数据量同步阻塞