leaudit-platform-backend/docs/系统使用统计/系统使用统计开发任务拆解.md

# 系统使用统计开发任务拆解

## 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. 联调验收

这样做的好处是：

- 风险最小
- 统计口径先稳定
- 前后端可以并行推进
- 一期就能较快交付可用结果