docs: reorganize by module

docs/系统使用统计/系统使用统计开发任务拆解.md

@@ -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. 联调验收
+
+这样做的好处是：
+
+- 风险最小
+- 统计口径先稳定
+- 前后端可以并行推进
+- 一期就能较快交付可用结果