docs: reorganize by module

2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
@@ -0,0 +1,626 @@
+# 系统使用统计开发任务拆解
+
+## 1. 目标
+
+基于以下文档，拆解“系统使用统计”功能的一期开发任务：
+
+- `docs/系统使用统计/系统使用统计最终需求.md`
+- `docs/系统使用统计/系统使用统计接口设计.md`
+- `docs/系统使用统计/系统使用统计表设计.md`
+
+本拆解以“一期可落地”为目标，优先实现：
+
+- 登录统计
+- 上传统计
+- 评查统计
+- 按用户、部门、地区、文档大类、文档类型、入口模块汇总
+- 概览页
+- 明细查询页
+- 导出能力
+
+## 2. 一期范围定义
+
+### 2.1 本期必须交付
+
+- 登录事件入库
+- `sso_users.last_login_at` 更新
+- 评查运行记录补齐 `trigger_user_id`
+- 系统使用统计后端接口
+- 概览页前端页面
+- 明细查询页前端页面
+- 明细导出
+
+### 2.2 本期建议交付
+
+- 文档大类映射表与管理方式
+- 趋势图与排行榜
+- 地区口径切换（用户地区 / 文档地区）
+
+### 2.3 本期不做
+
+- 全量行为审计流水
+- 页面访问轨迹
+- AI 对话统计
+- 聚合表预计算
+- 复杂驾驶舱
+
+## 3. 开发阶段拆分
+
+建议按 6 个阶段推进：
+
+1. 数据库变更
+2. 登录链路补数
+3. 评查链路补数
+4. 统计查询后端接口
+5. 前端页面开发
+6. 联调、验收与导出
+
+---
+
+## 4. 阶段一：数据库变更
+
+### 4.1 目标
+
+完成一期所需表结构调整与新增表落库。
+
+### 4.2 任务项
+
+#### 任务 1：为 `sso_users` 增加最近登录时间字段
+
+- 类型：数据库变更
+- 目标：新增 `last_login_at`
+- 影响：用户列表、登录成功时更新
+
+建议 SQL：
+
+```sql
+ALTER TABLE sso_users
+ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ NULL;
+```
+
+#### 任务 2：创建登录事件表 `usage_login_events`
+
+- 类型：数据库变更
+- 目标：支撑登录统计、登录明细、按部门/地区统计
+- 依赖：无
+
+建议执行内容：
+
+- 创建表
+- 创建索引
+- 检查权限
+
+#### 任务 3：创建文档大类映射表 `usage_document_category_mappings`（若决定一期落地）
+
+- 类型：数据库变更
+- 目标：实现动态文档大类统计
+- 依赖：需要业务确认是否复用现有一级分类
+
+### 4.3 产出
+
+- SQL 迁移脚本
+- 回滚脚本（至少提供字段/表删除草案）
+- 初始化数据脚本（若有文档大类映射）
+
+---
+
+## 5. 阶段二：登录链路补数
+
+### 5.1 目标
+
+在登录成功/失败时写入结构化登录统计数据。
+
+### 5.2 代码位置
+
+- `fastapi_modules/fastapi_leaudit/controllers/auth/authController.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/authServiceImpl.py`
+- `fastapi_common/fastapi_common_security/jwtService.py`
+
+### 5.3 任务项
+
+#### 任务 4：设计登录统计服务/仓储
+
+建议新增一个轻量服务，例如：
+
+- `fastapi_modules/fastapi_leaudit/services/usageStatsService.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py`
+
+职责：
+
+- 记录登录成功事件
+- 记录登录失败事件
+- 更新 `sso_users.last_login_at`
+
+#### 任务 5：登录成功时写入 `usage_login_events`
+
+需要记录：
+
+- `user_id`
+- `sub`
+- `username_snapshot`
+- `nick_name_snapshot`
+- `department_name_snapshot`
+- `ou_name_snapshot`
+- `area_snapshot`
+- `login_time`
+- `login_result = success`
+- `login_type`
+- `token_jti`（可选）
+- `ip_address`（可选）
+- `user_agent`（可选）
+
+#### 任务 6：登录成功后更新 `sso_users.last_login_at`
+
+规则：
+
+- 仅成功登录时更新
+- OAuth 与密码登录都要更新
+
+#### 任务 7：登录失败时写入 `usage_login_events`
+
+规则：
+
+- 不更新 `last_login_at`
+- 尽量保留失败原因
+- 若无法识别用户，可 `user_id` 为空，但保留 `sub`
+
+### 5.4 验收标准
+
+- 成功登录后数据库有事件记录
+- `sso_users.last_login_at` 被更新
+- 失败登录后数据库有失败记录
+- 不影响现有登录返回结构
+
+---
+
+## 6. 阶段三：评查链路补数
+
+### 6.1 目标
+
+补齐评查发起人的可统计性，解决“谁发起评查”问题。
+
+### 6.2 代码位置
+
+- `fastapi_modules/fastapi_leaudit/controllers/documentController.py`
+- `fastapi_modules/fastapi_leaudit/controllers/auditController.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
+
+### 6.3 问题说明
+
+当前 `leaudit_audit_runs` 已有字段：
+
+- `trigger_user_id`
+
+但创建 run 时没有写入。
+
+### 6.4 任务项
+
+#### 任务 8：调整 `AuditService.Run` 入参，接收 `CurrentUserId`
+
+现状：
+
+- `Run(DocumentId, RuleType, Force, Speed)`
+
+建议改为：
+
+- `Run(CurrentUserId, DocumentId, RuleType, Force, Speed)`
+
+#### 任务 9：在 `LeauditAuditRun` 创建时写入 `trigger_user_id`
+
+代码位置：
+
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py`
+
+#### 任务 10：梳理所有触发评查入口
+
+需要逐一确认是否能拿到当前用户：
+
+- 上传后自动评查
+- 手工发起评查
+- 重新评查
+
+如存在系统自动触发场景，可约定：
+
+- 系统触发：`trigger_user_id = NULL`
+- 用户触发：写入真实用户 ID
+
+### 6.5 验收标准
+
+- 用户上传自动触发评查时，有 `trigger_user_id`
+- 用户手工发起评查时，有 `trigger_user_id`
+- 统计接口可按用户正确统计评查次数
+
+---
+
+## 7. 阶段四：统计后端接口开发
+
+### 7.1 目标
+
+实现《系统使用统计接口设计》定义的一期接口。
+
+### 7.2 建议新增代码位置
+
+#### 控制器
+
+建议新增：
+
+- `fastapi_modules/fastapi_leaudit/controllers/usageStatsController.py`
+
+#### 服务接口
+
+建议新增：
+
+- `fastapi_modules/fastapi_leaudit/services/usageStatsService.py`
+
+#### 服务实现
+
+建议新增：
+
+- `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py`
+
+#### DTO / VO
+
+建议新增：
+
+- `fastapi_modules/fastapi_leaudit/domian/Dto/usageStatsDto.py`
+- `fastapi_modules/fastapi_leaudit/domian/vo/usageStatsVo.py`
+
+### 7.3 一期接口优先级
+
+#### P0
+
+- `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`
+
+#### P1
+
+- `GET /api/v3/usage-stats/by-categories`
+- `GET /api/v3/usage-stats/by-document-types`
+- `GET /api/v3/usage-stats/by-entry-modules`
+- `GET /api/v3/usage-stats/export`
+
+### 7.4 任务项
+
+#### 任务 11：实现统一筛选参数解析
+
+统一处理：
+
+- `dateFrom`
+- `dateTo`
+- `userId`
+- `departmentName`
+- `area`
+- `areaScope`
+- `entryModuleId`
+- `documentCategoryId`
+- `documentTypeId`
+- `page`
+- `pageSize`
+- `sortBy`
+- `sortOrder`
+
+#### 任务 12：实现概览统计接口
+
+返回：
+
+- 登录用户数
+- 登录次数
+- 活跃用户数
+- 上传文档数
+- 上传附件数
+- 评查次数
+- 完成评查数
+- 失败评查数
+
+#### 任务 13：实现趋势统计接口
+
+支持指标：
+
+- 登录
+- 上传
+- 评查
+- 活跃用户
+
+支持粒度：
+
+- 日
+- 周
+- 月
+
+#### 任务 14：实现按用户汇总接口
+
+输出：
+
+- 用户基础信息
+- 登录次数
+- 上传次数
+- 附件上传次数
+- 评查次数
+- 最近登录时间
+
+#### 任务 15：实现按部门汇总接口
+
+输出：
+
+- 部门名称
+- 用户数
+- 登录人数/次数
+- 上传次数
+- 评查次数
+
+#### 任务 16：实现按地区汇总接口
+
+支持：
+
+- 用户地区口径
+- 文档地区口径
+
+#### 任务 17：实现按文档类型 / 文档大类 / 入口模块汇总接口
+
+前提：
+
+- 若一期做文档大类映射表，则支持大类统计
+- 若一期不做，则可先上线文档类型与入口模块统计，大类接口后置
+
+#### 任务 18：实现明细查询接口
+
+至少支持：
+
+- 登录明细
+- 上传明细
+- 评查明细
+
+#### 任务 19：实现导出接口
+
+建议先支持：
+
+- CSV
+- XLSX（二期可补）
+
+### 7.5 验收标准
+
+- 所有接口按统一结构返回
+- 支持时间范围筛选
+- 支持分页与排序
+- 数据可回溯到明细
+
+---
+
+## 8. 阶段五：前端页面开发
+
+### 8.1 目标
+
+完成一期两个页面：
+
+- 使用概览页
+- 明细查询页
+
+### 8.2 建议前端位置
+
+基于现有 `legal-platform-frontend`，建议新增：
+
+#### 页面目录
+
+- `legal-platform-frontend/app/(audit)/usage-stats/page.tsx`
+- `legal-platform-frontend/app/(audit)/usage-stats/UsageStatsClient.tsx`
+
+#### 组件目录
+
+- `legal-platform-frontend/components/usage-stats/OverviewCards.tsx`
+- `legal-platform-frontend/components/usage-stats/TrendChart.tsx`
+- `legal-platform-frontend/components/usage-stats/RankTable.tsx`
+- `legal-platform-frontend/components/usage-stats/Filters.tsx`
+- `legal-platform-frontend/components/usage-stats/DetailsTable.tsx`
+
+#### API 封装
+
+- `legal-platform-frontend/lib/api/usage-stats.ts`
+
+### 8.3 任务项
+
+#### 任务 20：实现筛选区组件
+
+支持：
+
+- 时间范围
+- 用户
+- 部门
+- 地区
+- 地区口径
+- 入口模块
+- 文档类型
+- 文档大类
+- 数据类型
+
+#### 任务 21：实现概览卡片区
+
+展示：
+
+- 登录用户数
+- 活跃用户数
+- 上传文档数
+- 评查次数
+- 完成评查数
+- 失败评查数
+
+#### 任务 22：实现趋势图
+
+展示：
+
+- 登录趋势
+- 上传趋势
+- 评查趋势
+
+#### 任务 23：实现排行区
+
+展示：
+
+- 用户排行
+- 部门排行
+- 地区排行
+
+#### 任务 24：实现明细表格
+
+支持：
+
+- 切换登录 / 上传 / 评查
+- 分页
+- 排序
+- 导出
+
+### 8.4 验收标准
+
+- 页面在桌面端正常展示
+- 筛选逻辑生效
+- 与接口联调成功
+- 导出按钮可用
+
+---
+
+## 9. 阶段六：联调与验收
+
+### 9.1 联调顺序建议
+
+1. 登录事件入库联调
+2. 评查 `trigger_user_id` 联调
+3. 概览接口联调
+4. 明细接口联调
+5. 前端筛选联调
+6. 导出联调
+
+### 9.2 验收清单
+
+#### 登录统计
+
+- 成功登录后有事件记录
+- 失败登录后有失败记录
+- 用户表最近登录时间正确更新
+
+#### 上传统计
+
+- 主文件上传统计正确
+- 附件上传统计正确
+- 可按用户/部门/地区过滤
+
+#### 评查统计
+
+- 能统计发起次数
+- 能统计完成次数
+- 能统计失败次数
+- 能按用户统计评查次数
+
+#### 分类统计
+
+- 能按文档类型统计
+- 能按入口模块统计
+- 若一期做大类映射，则能按文档大类统计
+
+#### 页面功能
+
+- 概览页展示正常
+- 明细页查询正常
+- 导出正常
+
+---
+
+## 10. 角色分工建议
+
+### 后端
+
+负责：
+
+- SQL 变更
+- 登录/评查补数
+- 统计接口
+- 导出接口
+
+### 前端
+
+负责：
+
+- 页面开发
+- 筛选器
+- 图表与表格
+- 导出按钮
+
+### 测试/产品
+
+负责：
+
+- 统计口径确认
+- 用例验收
+- 历史数据校验
+
+---
+
+## 11. 风险点与注意事项
+
+### 风险 1：当前没有历史登录明细
+
+影响：
+
+- 上线前的历史登录次数无法完整回补
+
+建议：
+
+- 上线后开始累计
+- 历史阶段只展示“最近登录时间”或不展示登录趋势历史
+
+### 风险 2：`trigger_user_id` 目前未写入
+
+影响：
+
+- 历史评查记录按用户统计可能不完整
+
+建议：
+
+- 新逻辑上线后补齐新增数据
+- 历史 run 若无法还原则标记为“未知触发人”
+
+### 风险 3：文档大类口径不统一
+
+影响：
+
+- 报表分类不稳定
+
+建议：
+
+- 一期尽量确认是否复用现有一级分类
+- 若无法确认，优先落地映射表方案
+
+### 风险 4：部门/地区历史快照漂移
+
+影响：
+
+- 用户调岗后，历史统计可能变化
+
+建议：
+
+- 登录事件表采用快照字段
+- 上传/评查若后续要求强一致历史归属，可二期再补快照机制
+
+---
+
+## 12. 一期最终实施顺序建议
+
+推荐按照以下顺序推进：
+
+1. 出 SQL 迁移脚本
+2. 先补登录事件与最近登录时间
+3. 再补评查触发人
+4. 开发概览与明细接口
+5. 开发前端概览页与明细页
+6. 做导出
+7. 联调验收
+
+这样做的好处是：
+
+- 风险最小
+- 统计口径先稳定
+- 前后端可以并行推进
+- 一期就能较快交付可用结果
@@ -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. 后续优化建议
+
+- 增加日汇总表，提升一年跨度查询性能
+- 增加部门、地区快照，避免组织调整影响历史统计
+- 为明细与汇总增加统一缓存策略
+- 为导出增加异步任务模式，避免大数据量同步阻塞
@@ -0,0 +1,237 @@
+# 系统使用统计最终需求
+
+## 1. 背景与目标
+
+建设一个“系统使用统计”功能，用于按时间范围统计平台用户的登录、文档上传、文档评查等核心使用情况，并支持按用户、部门、地区、文档大类、文档类型、入口模块等维度进行动态汇总与明细查询。
+
+本功能定位为“使用统计”而非“全量行为审计”，目标是让管理人员快速回答以下问题：
+
+- 谁在使用系统
+- 哪些部门、哪些地区使用更活跃
+- 上传了多少文档
+- 发起了多少次评查
+- 哪些文档分类、入口模块使用最多
+
+## 2. 建设目标
+
+- 支持管理人员查看平台整体使用情况
+- 支持按用户、按部门、按地区查看使用成效
+- 支持按文档分类动态统计评查使用情况
+- 支持自定义时间范围查询
+- 支持查看汇总数据与明细数据
+- 支持后续新增文档分类后自动纳入统计
+
+## 3. 统计范围
+
+本次仅统计平台核心业务使用数据，范围限定为以下三类：
+
+- 登录使用数据
+- 文档上传数据
+- 文档评查数据
+
+本次暂不纳入以下范围：
+
+- 页面点击轨迹
+- 全量按钮操作日志
+- 文档浏览轨迹
+- AI 对话细粒度行为
+- 全量人工操作留痕回放
+- 风险预警与异常行为识别
+
+## 4. 统计维度
+
+系统应支持以下动态维度的筛选与汇总：
+
+- 时间范围
+- 用户
+- 部门
+- 地区
+- 入口模块
+- 文档大类
+- 文档类型
+
+约束要求：
+
+- 文档大类、文档类型、入口模块必须来源于系统实际配置或业务数据
+- 不允许在代码中写死“合同类”“案卷类”等固定业务名称
+- 后续若新增文档大类、文档类型或入口模块，应可自动纳入统计
+
+## 5. 核心统计指标
+
+### 5.1 登录使用指标
+
+- 登录次数
+- 登录用户数
+- 活跃用户数
+- 最近登录时间
+
+说明：
+
+- 活跃用户数指在指定时间范围内，发生过登录、上传或评查行为的去重用户数
+
+### 5.2 文档上传指标
+
+- 上传文档次数
+- 上传附件次数
+- 上传文档总数
+- 上传用户数
+- 按时间趋势统计上传量
+
+说明：
+
+- 上传文档次数仅统计主文件上传
+- 上传附件次数单独统计附件上传
+
+### 5.3 文档评查指标
+
+- 评查发起次数
+- 评查完成次数
+- 评查失败次数
+- 按文档大类统计评查次数
+- 按文档类型统计评查次数
+- 按入口模块统计评查次数
+- 按时间趋势统计评查次数
+
+说明：
+
+- 评查统计应基于评查运行记录
+- 分类统计应支持动态扩展，不依赖写死分类名称
+
+### 5.4 用户、部门、地区汇总指标
+
+- 按用户统计登录次数、上传次数、评查次数
+- 按部门统计登录人数、上传次数、评查次数
+- 按地区统计登录人数、上传次数、评查次数
+- 用户排行
+- 部门排行
+- 地区排行
+
+## 6. 地区统计口径
+
+地区统计需同时支持以下两种口径：
+
+### 6.1 用户地区口径
+
+按用户所属地区统计，适用于回答：
+
+- 哪个地区的人员在使用系统
+- 哪个地区的用户最活跃
+
+### 6.2 文档地区口径
+
+按文档所属地区统计，适用于回答：
+
+- 哪个地区的业务量更大
+- 哪个地区的文档评查量更高
+
+要求：
+
+- 地区统计查询时，应允许明确指定统计口径
+- 若未指定，系统应使用默认口径并在界面上清晰标注
+
+## 7. 页面功能需求
+
+### 7.1 使用概览页
+
+用于查看整体汇总情况，建议包含：
+
+- 时间范围筛选
+- 登录用户数
+- 活跃用户数
+- 上传文档数
+- 评查次数
+- 用户排行
+- 部门排行
+- 地区排行
+- 按时间趋势图
+- 按文档大类分布图
+- 按入口模块分布图
+- 按地区分布图
+
+### 7.2 明细查询页
+
+用于查看具体记录，需支持以下筛选条件：
+
+- 时间范围
+- 用户
+- 部门
+- 地区
+- 地区口径
+- 入口模块
+- 文档大类
+- 文档类型
+- 数据类型：登录 / 上传 / 评查
+
+明细字段建议包括：
+
+- 时间
+- 用户名
+- 所属部门
+- 所属地区
+- 数据类型
+- 文档名称
+- 文档类型
+- 文档大类
+- 入口模块
+- 结果状态
+
+并支持：
+
+- 分页
+- 排序
+- 导出
+
+## 8. 统计口径要求
+
+为保证扩展性与可维护性，系统必须遵循以下原则：
+
+- 固定统计项只保留通用业务指标，如登录、上传、评查
+- 分类统计必须走动态维度，不得写死业务类别名称
+- 文档大类应来源于系统中的实际分类结构或映射关系
+- 新增文档类型后，应可自动归属到对应统计维度
+- 报表展示应支持展示全部分类，而非只展示预设类别
+
+## 9. 数据准确性要求
+
+- 用户统计应以实际登录用户信息为准
+- 部门统计应以用户所属部门信息为准
+- 地区统计应支持“用户所属地区”与“文档所属地区”两种口径
+- 上传统计应以文档上传记录为准
+- 评查统计应以评查运行记录为准
+- 所有统计均应支持按指定时间范围计算
+- 汇总数据与明细数据应能相互追溯
+
+## 10. 扩展性要求
+
+系统应满足以下扩展能力：
+
+- 支持新增文档大类后自动纳入统计
+- 支持新增文档类型后自动纳入统计
+- 支持新增入口模块后自动纳入统计
+- 支持后续新增更多统计维度
+- 支持后续增加导出报表能力
+- 支持后续扩展为领导驾驶舱或运营看板
+
+## 11. 一期交付范围建议
+
+建议一期先实现以下能力：
+
+- 自定义时间范围查询
+- 使用概览页
+- 明细查询页
+- 登录、上传、评查三类核心指标
+- 按用户、部门、地区、文档大类、文档类型、入口模块统计
+- 导出明细
+
+## 12. 一期暂不实现内容
+
+- 全量行为审计流水
+- 页面访问轨迹
+- 全操作留痕回放
+- AI 对话审计分析
+- 风险预警模型
+- 复杂多层组织分析
+
+## 13. 一句话范围定义
+
+本次“系统使用统计”功能不做全量行为追踪，仅围绕登录、上传、评查三类核心业务数据，提供按用户、部门、地区、文档大类、文档类型、入口模块的动态统计与明细查询能力。
@@ -0,0 +1,612 @@
+# 系统使用统计表设计
+
+## 1. 设计目标
+
+基于《系统使用统计最终需求》和《系统使用统计接口设计》，设计一套可落地的数据库方案，用于支持以下统计场景：
+
+- 登录统计
+- 文档上传统计
+- 文档评查统计
+- 按用户、部门、地区、文档大类、文档类型、入口模块进行动态汇总
+- 支持时间范围查询、排行榜、趋势图与明细导出
+
+本次设计遵循两个原则：
+
+- 能复用现有业务表的地方尽量复用
+- 只为现有表无法满足的统计能力补最小新增表结构
+
+## 2. 总体设计思路
+
+统计数据来源分为两类：
+
+- 现有业务事实表
+- 新增统计事件表
+
+其中：
+
+- 上传、评查相关统计，尽量直接复用现有业务表
+- 登录统计由于当前没有稳定入库明细，需要新增登录事件表
+- 为了提升用户管理页的查询效率，建议给 `sso_users` 增加最近登录时间字段
+
+## 3. 现有可复用表
+
+### 3.1 用户表 `sso_users`
+
+用途：
+
+- 用户基础信息来源
+- 部门、地区、组织维度来源
+- 最近登录时间展示
+
+当前已使用字段：
+
+- `id`
+- `sub`
+- `username`
+- `nick_name`
+- `phone_number`
+- `email`
+- `ou_id`
+- `ou_name`
+- `area`
+- `tenant_name`
+- `dep_name`
+- `dep_short_name`
+- `status`
+- `deleted_at`
+
+代码参考：
+
+- `fastapi_modules/fastapi_leaudit/services/impl/authServiceImpl.py:36`
+- `fastapi_modules/fastapi_leaudit/services/impl/rbacAdminServiceImpl.py:374`
+
+### 3.2 文档主表 `leaudit_documents`
+
+用途：
+
+- 文档主记录
+- 文档类型、地区、版本、处理状态来源
+
+主要字段：
+
+- `id`
+- `type_id`
+- `group_id`
+- `region`
+- `processing_status`
+- `current_run_id`
+- `version_group_key`
+- `version_no`
+- `is_latest_version`
+- `created_at`
+- `updated_at`
+- `deleted_at`
+
+代码参考：
+
+- `fastapi_modules/fastapi_leaudit/models/leauditDocument.py:19`
+
+### 3.3 文档文件表 `leaudit_document_files`
+
+用途：
+
+- 上传主文件统计
+- 上传附件统计
+- 上传人、上传时间明细来源
+
+主要字段：
+
+- `id`
+- `document_id`
+- `file_role`
+- `file_name`
+- `file_ext`
+- `mime_type`
+- `file_size`
+- `oss_url`
+- `is_active`
+- `created_by`
+- `created_at`
+
+口径建议：
+
+- 主文件上传：`file_role = 'primary'`
+- 附件上传：`file_role = 'attachment'`
+
+代码参考：
+
+- `fastapi_modules/fastapi_leaudit/models/leauditDocumentFile.py:15`
+- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py:224`
+- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py:889`
+
+### 3.4 评查运行表 `leaudit_audit_runs`
+
+用途：
+
+- 评查发起次数
+- 评查完成次数
+- 评查失败次数
+- 评查时间趋势
+- 评查状态与结果明细
+
+主要字段：
+
+- `id`
+- `document_id`
+- `document_file_id`
+- `run_no`
+- `trigger_source`
+- `trigger_user_id`
+- `status`
+- `phase`
+- `rule_set_id`
+- `rule_version_id`
+- `result_status`
+- `total_score`
+- `passed_count`
+- `failed_count`
+- `skipped_count`
+- `started_at`
+- `finished_at`
+- `created_at`
+- `updated_at`
+
+现状说明：
+
+- 表结构已预留 `trigger_user_id`
+- 但当前代码创建 run 时尚未写入该字段
+- 统计功能上线前建议补齐该字段写入逻辑
+
+代码参考：
+
+- `fastapi_modules/fastapi_leaudit/models/leauditAuditRun.py:16`
+- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py:203`
+
+### 3.5 评查指标表 `leaudit_run_metrics`
+
+用途：
+
+- 评查页数
+- 评查耗时
+- 规则数量等运行指标
+
+主要字段：
+
+- `run_id`
+- `ocr_seconds`
+- `normalize_seconds`
+- `extract_seconds`
+- `evaluate_seconds`
+- `rescue_seconds`
+- `total_seconds`
+- `page_count`
+- `sub_document_count`
+- `field_count`
+- `rule_count`
+- `llm_call_count`
+- `vlm_call_count`
+- `rescue_rule_count`
+- `artifact_count`
+
+代码参考：
+
+- `fastapi_modules/fastapi_leaudit/leaudit_bridge/storage_adapter.py:260`
+
+### 3.6 文档类型表 `leaudit_document_types`
+
+用途：
+
+- 文档类型维度统计
+- 入口模块归属
+
+建议依赖字段：
+
+- `id`
+- `code`
+- `name`
+- `entry_module_id`
+- `is_enabled`
+- `sort_order`
+
+### 3.7 入口模块表 `leaudit_entry_modules`
+
+用途：
+
+- 入口模块维度统计
+- 首页/业务模块使用分析
+
+建议依赖字段：
+
+- `id`
+- `name`
+- `path`
+- `sort_order`
+- `is_enabled`
+
+## 4. 建议调整的现有表
+
+### 4.1 为 `sso_users` 增加最近登录时间字段
+
+#### 建议新增字段
+
+```sql
+ALTER TABLE sso_users
+ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ NULL;
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 允许空 | 说明 |
+| --- | --- | --- | --- |
+| `last_login_at` | `TIMESTAMPTZ` | 是 | 最近一次登录成功时间 |
+
+#### 用途
+
+- 用户列表展示“最近登录时间”
+- 后台快速判断用户活跃情况
+- 避免每次都扫登录事件表取最大时间
+
+#### 更新规则
+
+- 登录成功：更新 `last_login_at`
+- 登录失败：不更新
+
+## 5. 新增表设计
+
+### 5.1 登录事件表 `usage_login_events`
+
+#### 设计目的
+
+当前系统缺少结构化登录明细表，无法稳定支撑：
+
+- 登录次数
+- 登录用户数
+- 按部门登录统计
+- 按地区登录统计
+- 登录趋势图
+- 最近登录明细导出
+
+因此建议新增登录事件表。
+
+#### 建表建议
+
+```sql
+CREATE TABLE IF NOT EXISTS usage_login_events (
+    id BIGSERIAL PRIMARY KEY,
+    user_id BIGINT NULL,
+    sub VARCHAR(128) NULL,
+    username_snapshot VARCHAR(128) NULL,
+    nick_name_snapshot VARCHAR(128) NULL,
+    department_name_snapshot VARCHAR(255) NULL,
+    ou_id_snapshot VARCHAR(128) NULL,
+    ou_name_snapshot VARCHAR(255) NULL,
+    area_snapshot VARCHAR(64) NULL,
+    login_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    login_result VARCHAR(16) NOT NULL,
+    login_type VARCHAR(32) NOT NULL,
+    ip_address VARCHAR(64) NULL,
+    user_agent VARCHAR(1024) NULL,
+    client_type VARCHAR(32) NULL,
+    token_jti VARCHAR(128) NULL,
+    failure_reason VARCHAR(255) NULL,
+    extra JSONB NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `BIGSERIAL` | 主键 |
+| `user_id` | `BIGINT` | 用户 ID，失败登录时可为空 |
+| `sub` | `VARCHAR(128)` | 登录标识，兼容账号字段 |
+| `username_snapshot` | `VARCHAR(128)` | 登录时用户名快照 |
+| `nick_name_snapshot` | `VARCHAR(128)` | 登录时姓名快照 |
+| `department_name_snapshot` | `VARCHAR(255)` | 登录时部门快照 |
+| `ou_id_snapshot` | `VARCHAR(128)` | 登录时组织 ID 快照 |
+| `ou_name_snapshot` | `VARCHAR(255)` | 登录时组织名称快照 |
+| `area_snapshot` | `VARCHAR(64)` | 登录时地区快照 |
+| `login_time` | `TIMESTAMPTZ` | 登录时间 |
+| `login_result` | `VARCHAR(16)` | `success` / `failed` |
+| `login_type` | `VARCHAR(32)` | `password` / `oauth` |
+| `ip_address` | `VARCHAR(64)` | 登录来源 IP |
+| `user_agent` | `VARCHAR(1024)` | 浏览器/终端标识 |
+| `client_type` | `VARCHAR(32)` | `pc` / `mobile` / `other` |
+| `token_jti` | `VARCHAR(128)` | 成功登录后的 token jti，可选 |
+| `failure_reason` | `VARCHAR(255)` | 失败原因 |
+| `extra` | `JSONB` | 扩展字段 |
+| `created_at` | `TIMESTAMPTZ` | 记录创建时间 |
+
+#### 索引建议
+
+```sql
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_login_time
+ON usage_login_events(login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_user_id
+ON usage_login_events(user_id, login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_department
+ON usage_login_events(department_name_snapshot, login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_area
+ON usage_login_events(area_snapshot, login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_result
+ON usage_login_events(login_result, login_time DESC);
+```
+
+#### 统计口径建议
+
+- 登录次数：仅统计 `login_result = 'success'`
+- 登录失败次数：统计 `login_result = 'failed'`
+- 最近登录时间：按用户取最后一次成功登录时间
+
+### 5.2 文档大类映射表 `usage_document_category_mappings`（可选但强烈建议）
+
+#### 设计目的
+
+需求中明确要求：
+
+- 不写死“合同类”“案卷类”
+- 后续新增文档大类、文档类型后可自动纳入统计
+
+如果当前系统已经有稳定的一级文档大类实体，可直接复用；
+如果没有一张适合统计使用的稳定“大类表”，建议新增一张统计映射表。
+
+#### 建表建议
+
+```sql
+CREATE TABLE IF NOT EXISTS usage_document_category_mappings (
+    id BIGSERIAL PRIMARY KEY,
+    category_code VARCHAR(64) NOT NULL,
+    category_name VARCHAR(128) NOT NULL,
+    document_type_id BIGINT NOT NULL,
+    entry_module_id BIGINT NULL,
+    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    created_by BIGINT NULL,
+    updated_by BIGINT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    deleted_at TIMESTAMPTZ NULL
+);
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `BIGSERIAL` | 主键 |
+| `category_code` | `VARCHAR(64)` | 统计大类编码 |
+| `category_name` | `VARCHAR(128)` | 统计大类名称 |
+| `document_type_id` | `BIGINT` | 关联文档类型 ID |
+| `entry_module_id` | `BIGINT` | 可选，关联入口模块 |
+| `is_enabled` | `BOOLEAN` | 是否启用 |
+| `sort_order` | `INTEGER` | 排序 |
+| `created_by` | `BIGINT` | 创建人 |
+| `updated_by` | `BIGINT` | 更新人 |
+| `created_at` | `TIMESTAMPTZ` | 创建时间 |
+| `updated_at` | `TIMESTAMPTZ` | 更新时间 |
+| `deleted_at` | `TIMESTAMPTZ` | 软删除时间 |
+
+#### 约束与索引建议
+
+```sql
+CREATE UNIQUE INDEX IF NOT EXISTS uq_usage_document_category_type
+ON usage_document_category_mappings(document_type_id)
+WHERE deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_usage_document_category_code
+ON usage_document_category_mappings(category_code, is_enabled);
+
+CREATE INDEX IF NOT EXISTS idx_usage_document_category_module
+ON usage_document_category_mappings(entry_module_id, is_enabled);
+```
+
+#### 说明
+
+- 一种文档类型只归属一个统计大类
+- 若后续系统已有成熟的一级文档大类表，可取消本表，直接复用业务表
+
+## 6. 查询口径与表关系建议
+
+### 6.1 登录统计
+
+来源：
+
+- `usage_login_events`
+- `sso_users.last_login_at`
+
+用途：
+
+- 登录次数
+- 登录用户数
+- 最近登录时间
+- 按部门、地区统计登录情况
+
+### 6.2 上传统计
+
+来源：
+
+- `leaudit_document_files`
+- `leaudit_documents`
+- `sso_users`
+- `leaudit_document_types`
+- `leaudit_entry_modules`
+- `usage_document_category_mappings`（若启用）
+
+口径：
+
+- 主文件上传：`leaudit_document_files.file_role = 'primary'`
+- 附件上传：`leaudit_document_files.file_role = 'attachment'`
+
+### 6.3 评查统计
+
+来源：
+
+- `leaudit_audit_runs`
+- `leaudit_documents`
+- `leaudit_document_types`
+- `leaudit_entry_modules`
+- `usage_document_category_mappings`（若启用）
+
+口径：
+
+- 发起评查次数：`leaudit_audit_runs` 记录数
+- 完成评查次数：`status = 'completed'`
+- 失败评查次数：`status = 'failed'`
+
+### 6.4 地区统计
+
+支持两种口径：
+
+- 用户地区口径
+  - 登录：取 `usage_login_events.area_snapshot`
+  - 上传：取上传人 `sso_users.area`
+  - 评查：优先取触发人地区
+- 文档地区口径
+  - 上传：取 `leaudit_documents.region`
+  - 评查：取 `leaudit_documents.region`
+
+## 7. 一期是否需要聚合表
+
+### 7.1 一期建议
+
+一期先不新增日汇总聚合表，先使用：
+
+- 明细事实表 + SQL 聚合
+
+原因：
+
+- 功能验证阶段，需求还可能变
+- 统计范围目前只有登录、上传、评查三类，复杂度可控
+- 先把口径跑通，比过早做聚合更重要
+
+### 7.2 二期建议
+
+若后续数据量变大，再补以下日汇总表：
+
+- `usage_user_daily_stats`
+- `usage_department_daily_stats`
+- `usage_area_daily_stats`
+- `usage_document_category_daily_stats`
+- `usage_entry_module_daily_stats`
+
+## 8. 配套代码改造建议
+
+### 8.1 登录成功时
+
+需要做两件事：
+
+- 写入 `usage_login_events`
+- 更新 `sso_users.last_login_at`
+
+### 8.2 登录失败时
+
+建议：
+
+- 写入 `usage_login_events`
+- 不更新 `sso_users.last_login_at`
+
+### 8.3 触发评查时
+
+建议补齐：
+
+- `leaudit_audit_runs.trigger_user_id`
+
+当前表已存在该字段，但创建 run 时未写入，需要补逻辑。
+
+## 9. 推荐 SQL 变更清单
+
+### 9.1 为 `sso_users` 增加最近登录时间
+
+```sql
+ALTER TABLE sso_users
+ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ NULL;
+```
+
+### 9.2 新增登录事件表
+
+```sql
+CREATE TABLE IF NOT EXISTS usage_login_events (
+    id BIGSERIAL PRIMARY KEY,
+    user_id BIGINT NULL,
+    sub VARCHAR(128) NULL,
+    username_snapshot VARCHAR(128) NULL,
+    nick_name_snapshot VARCHAR(128) NULL,
+    department_name_snapshot VARCHAR(255) NULL,
+    ou_id_snapshot VARCHAR(128) NULL,
+    ou_name_snapshot VARCHAR(255) NULL,
+    area_snapshot VARCHAR(64) NULL,
+    login_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    login_result VARCHAR(16) NOT NULL,
+    login_type VARCHAR(32) NOT NULL,
+    ip_address VARCHAR(64) NULL,
+    user_agent VARCHAR(1024) NULL,
+    client_type VARCHAR(32) NULL,
+    token_jti VARCHAR(128) NULL,
+    failure_reason VARCHAR(255) NULL,
+    extra JSONB NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+### 9.3 新增登录事件索引
+
+```sql
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_login_time
+ON usage_login_events(login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_user_id
+ON usage_login_events(user_id, login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_department
+ON usage_login_events(department_name_snapshot, login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_area
+ON usage_login_events(area_snapshot, login_time DESC);
+
+CREATE INDEX IF NOT EXISTS idx_usage_login_events_result
+ON usage_login_events(login_result, login_time DESC);
+```
+
+### 9.4 新增统计大类映射表（可选）
+
+```sql
+CREATE TABLE IF NOT EXISTS usage_document_category_mappings (
+    id BIGSERIAL PRIMARY KEY,
+    category_code VARCHAR(64) NOT NULL,
+    category_name VARCHAR(128) NOT NULL,
+    document_type_id BIGINT NOT NULL,
+    entry_module_id BIGINT NULL,
+    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    created_by BIGINT NULL,
+    updated_by BIGINT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    deleted_at TIMESTAMPTZ NULL
+);
+```
+
+## 10. 一期最终建议
+
+一期最小可落地表设计建议如下：
+
+必须做：
+
+- `sso_users.last_login_at`
+- `usage_login_events`
+- 补齐 `leaudit_audit_runs.trigger_user_id` 写入逻辑
+
+建议做：
+
+- `usage_document_category_mappings`
+
+可后置：
+
+- 各类日汇总聚合表
+- 复杂会话表
+- 全量行为审计表