wren
579 lines
11 KiB
Markdown
579 lines
11 KiB
Markdown
# 系统使用统计接口设计
|
|
|
|
## 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. 后续优化建议
|
|
|
|
- 增加日汇总表，提升一年跨度查询性能
|
|
- 增加部门、地区快照，避免组织调整影响历史统计
|
|
- 为明细与汇总增加统一缓存策略
|
|
- 为导出增加异步任务模式，避免大数据量同步阻塞
|