TanWenyan/leaudit-platform-backend

Fork 0

Files

T

wren c9d7a693b8 docs: reorganize by module

2026-05-09 20:04:08 +08:00

11 KiB

Raw Blame History

系统使用统计接口设计

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

响应示例

{
  "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`
其余通用筛选参数	-	否	同上

响应示例

{
  "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	否	用户名/姓名模糊搜索

响应示例

{
  "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（部门模糊搜索）

响应示例

{
  "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

响应示例

{
  "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

响应示例

{
  "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

作用

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

请求参数

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

响应示例

{
  "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

响应示例

{
  "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

响应示例

{
  "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. 返回结构约定

所有统计接口统一使用：

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

分页结构统一使用：

{
  "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. 后续优化建议

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

11 KiB Raw Blame History

系统使用统计接口设计

1. 设计目标

2. 设计原则

3. 统一筛选参数

4. 接口清单

4.1 获取使用统计概览

作用

请求参数

响应示例

4.2 获取时间趋势统计

作用

请求参数

响应示例

4.3 获取按用户汇总统计

作用

请求参数

响应示例

4.4 获取按部门汇总统计

作用

请求参数

响应示例

4.5 获取按地区汇总统计

作用

请求参数

响应示例

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

作用

请求参数

响应示例

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

作用

请求参数

响应示例

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

作用

请求参数

响应示例

4.9 获取使用明细列表

作用

请求参数

响应示例

4.10 导出明细

作用

请求参数

响应

5. 返回结构约定

6. 数据来源建议

6.1 登录数据

6.2 上传数据

6.3 评查数据

6.4 用户与组织信息

7. 动态分类建议

8. 权限建议

9. 一期实现优先级建议

P0

P1

P2

10. 后续优化建议

11 KiB

Raw Blame History