TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reorganize by module

Browse Source
This commit is contained in:
wren
2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/系统使用统计/系统使用统计接口设计.md
+578
View File
@@ -0,0 +1,578 @@
# 系统使用统计接口设计
## 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. 后续优化建议
- 增加日汇总表，提升一年跨度查询性能
- 增加部门、地区快照，避免组织调整影响历史统计
- 为明细与汇总增加统一缓存策略
- 为导出增加异步任务模式，避免大数据量同步阻塞