TanWenyan/leaudit-platform-backend

Fork 0

Files

T

wren c9d7a693b8 docs: reorganize by module

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

12 KiB

Raw Blame History

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

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 个阶段推进：

数据库变更
登录链路补数
评查链路补数
统计查询后端接口
前端页面开发
联调、验收与导出

4. 阶段一：数据库变更

4.1 目标

完成一期所需表结构调整与新增表落库。

4.2 任务项

任务 1：为 `sso_users` 增加最近登录时间字段

类型：数据库变更
目标：新增 last_login_at
影响：用户列表、登录成功时更新

建议 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 联调顺序建议

登录事件入库联调
评查 trigger_user_id 联调
概览接口联调
明细接口联调
前端筛选联调
导出联调

9.2 验收清单

登录统计

成功登录后有事件记录
失败登录后有失败记录
用户表最近登录时间正确更新

上传统计

主文件上传统计正确
附件上传统计正确
可按用户/部门/地区过滤

评查统计

能统计发起次数
能统计完成次数
能统计失败次数
能按用户统计评查次数

分类统计

能按文档类型统计
能按入口模块统计
若一期做大类映射，则能按文档大类统计

页面功能

概览页展示正常
明细页查询正常
导出正常

10. 角色分工建议

后端

负责：

SQL 变更
登录/评查补数
统计接口
导出接口

前端

负责：

页面开发
筛选器
图表与表格
导出按钮

测试/产品

负责：

统计口径确认
用例验收
历史数据校验

11. 风险点与注意事项

风险 1：当前没有历史登录明细

影响：

上线前的历史登录次数无法完整回补

建议：

上线后开始累计
历史阶段只展示“最近登录时间”或不展示登录趋势历史

风险 2：`trigger_user_id` 目前未写入

影响：

历史评查记录按用户统计可能不完整

建议：

新逻辑上线后补齐新增数据
历史 run 若无法还原则标记为“未知触发人”

风险 3：文档大类口径不统一

影响：

报表分类不稳定

建议：

一期尽量确认是否复用现有一级分类
若无法确认，优先落地映射表方案

风险 4：部门/地区历史快照漂移

影响：

用户调岗后，历史统计可能变化

建议：

登录事件表采用快照字段
上传/评查若后续要求强一致历史归属，可二期再补快照机制

12. 一期最终实施顺序建议

推荐按照以下顺序推进：

出 SQL 迁移脚本
先补登录事件与最近登录时间
再补评查触发人
开发概览与明细接口
开发前端概览页与明细页
做导出
联调验收

这样做的好处是：

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

12 KiB Raw Blame History Unescape Escape

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

1. 目标

2. 一期范围定义

2.1 本期必须交付

2.2 本期建议交付

2.3 本期不做

3. 开发阶段拆分

4. 阶段一：数据库变更

4.1 目标

4.2 任务项

任务 1：为 sso_users 增加最近登录时间字段

任务 2：创建登录事件表 usage_login_events

任务 3：创建文档大类映射表 usage_document_category_mappings（若决定一期落地）

4.3 产出

5. 阶段二：登录链路补数

5.1 目标

5.2 代码位置

5.3 任务项

任务 4：设计登录统计服务/仓储

任务 5：登录成功时写入 usage_login_events

任务 6：登录成功后更新 sso_users.last_login_at

任务 7：登录失败时写入 usage_login_events

5.4 验收标准

6. 阶段三：评查链路补数

6.1 目标

6.2 代码位置

6.3 问题说明

6.4 任务项

任务 8：调整 AuditService.Run 入参，接收 CurrentUserId

任务 9：在 LeauditAuditRun 创建时写入 trigger_user_id

任务 10：梳理所有触发评查入口

6.5 验收标准

7. 阶段四：统计后端接口开发

7.1 目标

7.2 建议新增代码位置

控制器

服务接口

服务实现

DTO / VO

7.3 一期接口优先级

P0

P1

7.4 任务项

任务 11：实现统一筛选参数解析

任务 12：实现概览统计接口

任务 13：实现趋势统计接口

任务 14：实现按用户汇总接口

任务 15：实现按部门汇总接口

任务 16：实现按地区汇总接口

任务 17：实现按文档类型 / 文档大类 / 入口模块汇总接口

任务 18：实现明细查询接口

任务 19：实现导出接口

7.5 验收标准

8. 阶段五：前端页面开发

8.1 目标

8.2 建议前端位置

页面目录

组件目录

API 封装

8.3 任务项

任务 20：实现筛选区组件

任务 21：实现概览卡片区

任务 22：实现趋势图

任务 23：实现排行区

任务 24：实现明细表格

8.4 验收标准

9. 阶段六：联调与验收

9.1 联调顺序建议

9.2 验收清单

登录统计

上传统计

评查统计

分类统计

页面功能

10. 角色分工建议

后端

前端

测试/产品

11. 风险点与注意事项

12 KiB

Raw Blame History

任务 1：为 `sso_users` 增加最近登录时间字段

任务 2：创建登录事件表 `usage_login_events`

任务 3：创建文档大类映射表 `usage_document_category_mappings`（若决定一期落地）

任务 5：登录成功时写入 `usage_login_events`

任务 6：登录成功后更新 `sso_users.last_login_at`

任务 7：登录失败时写入 `usage_login_events`

任务 8：调整 `AuditService.Run` 入参，接收 `CurrentUserId`

任务 9：在 `LeauditAuditRun` 创建时写入 `trigger_user_id`

风险 2：`trigger_user_id` 目前未写入