From 58ee6a10850200c6daece2e80ff2c194d70b1e43 Mon Sep 17 00:00:00 2001 From: wren <“porlong@qq.com”> Date: Sun, 10 May 2026 21:04:07 +0800 Subject: [PATCH] docs: consolidate usage stats documentation --- docs/HANDOFF.md | 37 +- docs/README.md | 4 +- docs/系统使用统计/系统使用统计实施版.md | 270 ++++++++ docs/系统使用统计/系统使用统计开发任务拆解.md | 626 ------------------ docs/系统使用统计/系统使用统计接口设计.md | 578 ---------------- docs/系统使用统计/系统使用统计最终版.md | 222 +++++++ docs/系统使用统计/系统使用统计最终需求.md | 237 ------- docs/系统使用统计/系统使用统计表设计.md | 612 ----------------- docs/迁移与兼容/旧接口文档导航.md | 8 +- 9 files changed, 534 insertions(+), 2060 deletions(-) create mode 100644 docs/系统使用统计/系统使用统计实施版.md delete mode 100644 docs/系统使用统计/系统使用统计开发任务拆解.md delete mode 100644 docs/系统使用统计/系统使用统计接口设计.md create mode 100644 docs/系统使用统计/系统使用统计最终版.md delete mode 100644 docs/系统使用统计/系统使用统计最终需求.md delete mode 100644 docs/系统使用统计/系统使用统计表设计.md diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index a2849ae..21aef41 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -238,6 +238,32 @@ - 这块产品表达要统一成“可用规则数”，不要再出现“可用版本”旧说法 - 页面上还需要继续把这些错误稳定映射成用户可理解提示 +### 13. 系统使用统计口径已经收口到“两份主文档 + 一期三视角” + +当前这块不要再按“需求 / 表设计 / 接口设计 / 任务拆解”四散维护，已经统一收口为两份主文档： + +- `docs/系统使用统计/系统使用统计最终版.md` +- `docs/系统使用统计/系统使用统计实施版.md` + +当前正式口径： + +- 功能定位是“使用统计”，不是“全量行为审计” +- 一期只统计：登录、上传、评查 +- 一期前端页面只做 3 个视角： + - 总览 + - 按部门 + - 按地区 +- 页面入口放在“系统设置” +- 地区管理员只能看本地区数据，必须由后端做地区隔离 + +当前实现状态： + +- 后端统计接口、登录补数、评查触发人补数、RBAC 与 SQL 已落地 +- SQL 已统一整理到 `scripts/创建sql/` +- 上线与验收入口文档统一看： + - `scripts/创建sql/README.md` + - `docs/系统使用统计/系统使用统计实施版.md` + --- ## 三、当前业务逻辑口径 @@ -294,6 +320,8 @@ | `fastapi_modules/fastapi_leaudit/controllers/evaluationPointController.py` | 评查点主数据 v3 接口 | | `fastapi_modules/fastapi_leaudit/services/impl/evaluationPointServiceImpl.py` | 评查点列表/详情/增删改 | | `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py` | 规则集列表、可用规则数、规则文件校验 | +| `fastapi_modules/fastapi_leaudit/controllers/usageStatsController.py` | 系统使用统计接口 | +| `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py` | 登录统计写入、总览/部门/地区统计查询 | ### 前端 @@ -345,7 +373,12 @@ - 明确提示“哪个规则集不可用 / 哪个入口模块配置异常 / 当前文档类型没有可用规则数” - 避免只弹统一 400/500 -4. 继续清理文档与代码中的旧术语 +4. 系统使用统计前端继续按“一期三视角”联调 + - 只优先保证“总览 + 按部门 + 按地区”整体可用 + - 先不要继续扩展复杂驾驶舱、全量明细审计、额外统计口径页面 + - 所有实现口径统一以 `docs/系统使用统计/系统使用统计最终版.md` 为准 + +5. 继续清理文档与代码中的旧术语 - `可用版本` 统一改为 `可用规则数` - 避免“规则组 / 分组 / 规则集 / 评查点”混用造成误解 @@ -409,6 +442,8 @@ - `docs/README.md`：后端 `/docs` 总导航 - `docs/迁移与兼容/旧接口文档导航.md`：接口文档导航 - `docs/权限与地区隔离/权限与地区隔离文档导航.md`：权限主线导航 +- `docs/系统使用统计/系统使用统计最终版.md`：系统使用统计业务口径 +- `docs/系统使用统计/系统使用统计实施版.md`：系统使用统计实施与上线口径 - `docs/leaudit/README.md`：后端架构主线 - `docs/规则编辑/README.md`：规则链路主线 - `new_doc_review/docs/route-alias-guidelines.md`：前端子页权限映射规范 diff --git a/docs/README.md b/docs/README.md index c6f21e5..66f04cb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ | 文档管理 | `docs/文档管理/` | 文档上传、列表、详情、评查触发 | | 入口模块 | `docs/入口模块/` | 首页入口、入口模块绑定、模块归属 | | 评查点分组 | `docs/评查点分组/` | 一级分组、二级分组、规则集迁移方案 | -| 系统使用统计 | `docs/系统使用统计/` | 需求、表设计、接口设计、任务拆解 | +| 系统使用统计 | `docs/系统使用统计/` | 最终业务口径、实施方案、上线与验收 | | 权限与地区隔离 | `docs/权限与地区隔离/` | RBAC、权限点、地区隔离、初始化 SQL | | RAG | `docs/RAG/` | RAG 聊天接口、RAG 上线清单 | | 交叉评查 | `docs/交叉评查/` | 交叉评查业务方案、表结构、流程图 | @@ -47,7 +47,7 @@ | 查文档上传、文档列表、详情、评查触发 | `docs/文档管理/文档上传与列表接口分析.md` | `docs/HANDOFF.md` | | 查首页入口、入口模块绑定 | `docs/入口模块/入口模块绑定最终设计方案.md` | `docs/HANDOFF.md` | | 查评查点分组、文档类型、规则集迁移 | `docs/评查点分组/评查点分组目标结构与迁移方案.md` | `docs/评查点分组/评查点分组迁移执行前检查清单.md` | -| 查系统使用统计 | `docs/系统使用统计/系统使用统计最终需求.md` | `docs/系统使用统计/系统使用统计接口设计.md` | +| 查系统使用统计 | `docs/系统使用统计/系统使用统计最终版.md` | `docs/系统使用统计/系统使用统计实施版.md` | | 查权限、角色、地区隔离 | `docs/权限与地区隔离/权限与地区隔离文档导航.md` | `docs/权限与地区隔离/用户权限与权限点清单.md` | | 查 RAG 聊天接口 | `docs/RAG/RAG聊天接口.md` | `docs/RAG/RAG后端上线清单.md` | | 查交叉评查业务 | `docs/交叉评查/新项目交叉评查详细业务逻辑定稿.md` | `docs/交叉评查/新项目交叉评查新表结构与接口清单.md` | diff --git a/docs/系统使用统计/系统使用统计实施版.md b/docs/系统使用统计/系统使用统计实施版.md new file mode 100644 index 0000000..c0206ea --- /dev/null +++ b/docs/系统使用统计/系统使用统计实施版.md @@ -0,0 +1,270 @@ +# 系统使用统计实施版 + +## 1. 实施目标 + +基于《系统使用统计最终版》，落地一期可用方案，范围收敛为： + +- 后端统计接口 +- 登录统计补数 +- 上传/评查统计查询 +- 权限隔离 +- 前端“总览 + 按部门 + 按地区”页面 +- 上线 SQL 与验收流程 + +## 2. 实际落地方案 + +### 2.1 数据来源 + +统计数据来源分两类： + +- 复用现有业务事实表 +- 补最小新增事件表 + +其中： + +- 上传统计：复用现有文档与文件表 +- 评查统计：复用现有评查运行表 +- 登录统计：新增登录事件表 +- 用户最近登录时间：补 `sso_users.last_login_at` + +### 2.2 复用的现有表 + +- `sso_users` + - 用户、部门、地区来源 + - 最近登录时间展示 + +- `leaudit_documents` + - 文档主记录 + - 文档类型、地区、状态来源 + +- `leaudit_document_files` + - 主文件上传、附件上传统计 + - 上传人、上传时间明细来源 + +- `leaudit_audit_runs` + - 评查发起、完成、失败统计 + - 评查时间趋势 + - 发起人必须依赖 `trigger_user_id` + +- `leaudit_document_types` + - 文档类型维度 + - 入口模块归属 + +- `leaudit_entry_modules` + - 入口模块维度 + +## 3. 新增与补齐的库结构 + +### 3.1 新增字段 + +- `sso_users.last_login_at` + - 含义：最近一次成功登录时间 + - 作用：用户维度统计、最近登录展示 + +### 3.2 新增表 + +- `usage_login_events` + - 用途：记录登录成功/失败事件 + - 核心字段： + - `user_id` + - `sub` + - `username_snapshot` + - `nick_name_snapshot` + - `department_name_snapshot` + - `ou_name_snapshot` + - `area_snapshot` + - `login_time` + - `login_result` + - `login_type` + - `ip_address` + - `user_agent` + - `failure_reason` + +### 3.3 已落地 SQL + +统一放在：`scripts/创建sql/` + +本功能核心脚本： + +- `scripts/创建sql/schema_add_usage_stats.sql` +- `scripts/创建sql/seed_usage_stats_rbac.sql` + +## 4. 后端接口口径 + +统一前缀：`/api/v3/usage-stats` + +已定义的一期接口： + +- `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` + +一期前端先接： + +- `overview` +- `by-departments` +- `by-areas` + +## 5. 核心权限与地区隔离 + +### 5.1 页面入口 + +页面入口放在： + +- 系统设置 +- 路由：`/usage-stats` + +### 5.2 权限点 + +已定义权限： + +- `usage_stats:overview:read` +- `usage_stats:trends:read` +- `usage_stats:users:read` +- `usage_stats:departments:read` +- `usage_stats:areas:read` +- `usage_stats:details:read` + +### 5.3 角色范围 + +- `super_admin`：看全量 +- `provincial_admin`：看全量 +- `admin`：作为地区管理员，仅看本地区 + +### 5.4 实施要求 + +- 不能只靠前端限制 +- 必须由后端按当前登录用户地区做数据过滤 +- 按地区页在 `admin` 角色下只能返回当前地区数据 + +## 6. 一期前端范围 + +一期页面只做： + +- 总览 +- 按部门 +- 按地区 + +放置位置： + +- 系统设置 + +页面要求： + +- 支持时间范围筛选 +- 支持按地区筛选 +- 按地区页支持地区口径切换 +- 页面可用优先，不继续堆复杂交互 + +## 7. 后端实现拆解 + +### 7.1 登录链路补数 + +代码位置： + +- `fastapi_modules/fastapi_leaudit/controllers/auth/authController.py` +- `fastapi_modules/fastapi_leaudit/services/usageStatsService.py` +- `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py` + +要求： + +- 成功登录写 `usage_login_events` +- 失败登录写 `usage_login_events` +- 成功登录更新 `sso_users.last_login_at` +- 不影响现有登录返回结构 + +### 7.2 评查链路补数 + +代码位置： + +- `fastapi_modules/fastapi_leaudit/controllers/auditController.py` +- `fastapi_modules/fastapi_leaudit/services/auditService.py` +- `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py` +- `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py` + +要求： + +- 创建评查 run 时写入 `trigger_user_id` +- 上传后自动评查与手工发起评查都要补齐 + +### 7.3 统计查询接口 + +代码位置： + +- `fastapi_modules/fastapi_leaudit/controllers/usageStatsController.py` +- `fastapi_modules/fastapi_leaudit/services/usageStatsService.py` +- `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py` + +要求： + +- 概览页可直接取数 +- 部门页可分页汇总 +- 地区页支持地区口径切换 +- 后端完成权限与地区过滤 + +## 8. 上线顺序 + +### 8.1 SQL + +先执行： + +1. `scripts/创建sql/schema_add_usage_stats.sql` +2. `scripts/创建sql/seed_usage_stats_rbac.sql` + +### 8.2 服务 + +- 发布后端代码 +- 重启后端服务 +- 用管理员账号重新登录一次 +- 手动上传一次文档 +- 手动发起一次评查 + +### 8.3 验收 + +必须验证： + +- `usage_login_events` 有数据 +- `sso_users.last_login_at` 有更新 +- `leaudit_audit_runs.trigger_user_id` 有写入 +- `/usage-stats` 菜单可见 +- 超级管理员可看全量 +- 地区管理员只能看本地区 + +## 9. 当前推荐验收 SQL + +```sql +SELECT column_name +FROM information_schema.columns +WHERE table_name = 'sso_users' + AND column_name = 'last_login_at'; + +SELECT to_regclass('public.usage_login_events'); + +SELECT id, username, last_login_at +FROM sso_users +WHERE last_login_at IS NOT NULL +ORDER BY last_login_at DESC +LIMIT 10; + +SELECT id, user_id, login_result, login_type, login_time +FROM usage_login_events +ORDER BY id DESC +LIMIT 10; + +SELECT id, trigger_user_id, status, created_at +FROM leaudit_audit_runs +ORDER BY id DESC +LIMIT 10; +``` + +## 10. 当前文档收口原则 + +本目录只保留这两份： + +- `docs/系统使用统计/系统使用统计最终版.md` +- `docs/系统使用统计/系统使用统计实施版.md` + +老的“最终需求 / 表设计 / 接口设计 / 开发任务拆解”内容，统一并入这两份主文档，不再继续扩散。 diff --git a/docs/系统使用统计/系统使用统计开发任务拆解.md b/docs/系统使用统计/系统使用统计开发任务拆解.md deleted file mode 100644 index d691cec..0000000 --- a/docs/系统使用统计/系统使用统计开发任务拆解.md +++ /dev/null @@ -1,626 +0,0 @@ -# 系统使用统计开发任务拆解 - -## 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. 联调验收 - -这样做的好处是： - -- 风险最小 -- 统计口径先稳定 -- 前后端可以并行推进 -- 一期就能较快交付可用结果 diff --git a/docs/系统使用统计/系统使用统计接口设计.md b/docs/系统使用统计/系统使用统计接口设计.md deleted file mode 100644 index 8437b29..0000000 --- a/docs/系统使用统计/系统使用统计接口设计.md +++ /dev/null @@ -1,578 +0,0 @@ -# 系统使用统计接口设计 - -## 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. 后续优化建议 - -- 增加日汇总表，提升一年跨度查询性能 -- 增加部门、地区快照，避免组织调整影响历史统计 -- 为明细与汇总增加统一缓存策略 -- 为导出增加异步任务模式，避免大数据量同步阻塞 diff --git a/docs/系统使用统计/系统使用统计最终版.md b/docs/系统使用统计/系统使用统计最终版.md new file mode 100644 index 0000000..6379226 --- /dev/null +++ b/docs/系统使用统计/系统使用统计最终版.md @@ -0,0 +1,222 @@ +# 系统使用统计最终版 + +## 1. 功能定位 + +“系统使用统计”定位为管理视角的业务使用成效统计，不做全量行为审计。 + +它主要回答三类问题： + +- 谁在使用系统 +- 哪些部门、哪些地区使用更活跃 +- 上传了多少文档、发起了多少次评查 + +本期只围绕真实业务结果做统计，不扩展到页面点击轨迹、按钮级留痕或 AI 对话细粒度行为。 + +## 2. 一期统计范围 + +本期只统计以下三类数据： + +- 登录使用数据 +- 文档上传数据 +- 文档评查数据 + +本期不纳入： + +- 页面点击轨迹 +- 全量按钮操作日志 +- 文档浏览轨迹 +- AI 对话细粒度行为 +- 全量人工操作留痕回放 +- 风险预警与异常行为识别 + +## 3. 统计目标 + +系统应支持： + +- 按时间范围统计平台整体使用情况 +- 按用户、按部门、按地区查看使用成效 +- 按入口模块、文档大类、文档类型查看使用分布 +- 查看汇总数据与明细数据 +- 支持后续新增文档分类、入口模块后自动纳入统计 + +## 4. 统计维度 + +一期统一按动态维度设计，不能在代码里写死“合同类”“案卷类”等固定业务名称。 + +支持维度： + +- 时间范围 +- 用户 +- 部门 +- 地区 +- 地区口径 +- 入口模块 +- 文档大类 +- 文档类型 + +约束： + +- 文档大类、文档类型、入口模块必须来源于系统真实配置或业务数据 +- 新增文档大类、文档类型、入口模块后，应自动纳入统计 +- 页面展示不能依赖写死业务名称 + +## 5. 核心指标口径 + +### 5.1 登录指标 + +- 登录次数 +- 登录用户数 +- 活跃用户数 +- 最近登录时间 + +说明： + +- 活跃用户数指在指定时间范围内，发生过登录、上传或评查行为的去重用户数 +- 最近登录时间以成功登录为准 + +### 5.2 上传指标 + +- 上传文档次数 +- 上传附件次数 +- 上传文档总数 +- 上传用户数 +- 上传时间趋势 + +说明： + +- 主文件上传统计口径：`file_role = 'primary'` +- 附件上传统计口径：`file_role = 'attachment'` + +### 5.3 评查指标 + +- 评查发起次数 +- 评查完成次数 +- 评查失败次数 +- 按文档大类统计评查次数 +- 按文档类型统计评查次数 +- 按入口模块统计评查次数 +- 按时间趋势统计评查次数 + +说明： + +- 评查统计以 `leaudit_audit_runs` 为准 +- “谁发起评查”必须依赖 `trigger_user_id` +- 分类统计走动态维度，不写死业务类型名称 + +### 5.4 用户 / 部门 / 地区汇总指标 + +- 按用户统计登录次数、上传次数、评查次数 +- 按部门统计登录人数、上传次数、评查次数 +- 按地区统计登录人数、上传次数、评查次数 +- 用户排行 +- 部门排行 +- 地区排行 + +## 6. 地区统计口径 + +地区统计需同时支持两种口径： + +### 6.1 用户地区口径 + +适用于回答： + +- 哪个地区的人员在使用系统 +- 哪个地区的用户最活跃 + +### 6.2 文档地区口径 + +适用于回答： + +- 哪个地区的业务量更大 +- 哪个地区的文档评查量更高 + +要求： + +- 查询时允许明确指定口径 +- 未指定时使用默认口径，并在页面上明确标识 +- 地区管理员只能看到本地区数据 + +## 7. 页面范围 + +### 7.1 一期先做的页面 + +放在“系统设置”里，先做这 3 个视角： + +- 总览 +- 按部门 +- 按地区 + +说明： + +- 如果这 3 个视角整体可用，本期不再继续叠加更多复杂页面 +- 用户视角、明细导出、趋势增强等后续按需要再补 + +### 7.2 总览页应包含 + +- 时间范围筛选 +- 登录用户数 +- 活跃用户数 +- 上传文档数 +- 评查次数 +- 基础趋势 +- 关键分布 + +### 7.3 按部门页应包含 + +- 部门列表汇总 +- 登录人数 +- 上传次数 +- 评查次数 +- 支持时间范围筛选 +- 支持地区过滤 + +### 7.4 按地区页应包含 + +- 地区列表汇总 +- 登录人数 +- 上传次数 +- 评查次数 +- 支持用户地区 / 文档地区口径切换 +- 地区管理员仅能看本地区 + +## 8. 数据准确性要求 + +- 用户统计以实际登录用户信息为准 +- 部门统计以用户所属部门信息为准 +- 地区统计同时支持用户地区与文档地区两种口径 +- 上传统计以文档上传记录为准 +- 评查统计以评查运行记录为准 +- 所有统计均支持时间范围筛选 +- 汇总数据与明细数据应能相互追溯 + +## 9. 一期正式交付口径 + +本期正式交付范围收敛为： + +- 自定义时间范围查询 +- 系统设置下的“系统使用统计”页面入口 +- 总览页 +- 按部门页 +- 按地区页 +- 登录 / 上传 / 评查三类核心统计 +- 地区管理员按地区隔离 + +本期不强行纳入： + +- 复杂驾驶舱 +- 全量行为审计 +- 页面访问日志 +- AI 对话统计 +- 大规模预计算聚合 + +## 10. 文档关系 + +本目录后续统一只保留两份主文档： + +- `docs/系统使用统计/系统使用统计最终版.md` +- `docs/系统使用统计/系统使用统计实施版.md` + +其中： + +- 最终版负责定义业务口径与交付边界 +- 实施版负责定义表结构、接口、权限、开发拆解与上线顺序 diff --git a/docs/系统使用统计/系统使用统计最终需求.md b/docs/系统使用统计/系统使用统计最终需求.md deleted file mode 100644 index 1003a48..0000000 --- a/docs/系统使用统计/系统使用统计最终需求.md +++ /dev/null @@ -1,237 +0,0 @@ -# 系统使用统计最终需求 - -## 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. 一句话范围定义 - -本次“系统使用统计”功能不做全量行为追踪，仅围绕登录、上传、评查三类核心业务数据，提供按用户、部门、地区、文档大类、文档类型、入口模块的动态统计与明细查询能力。 diff --git a/docs/系统使用统计/系统使用统计表设计.md b/docs/系统使用统计/系统使用统计表设计.md deleted file mode 100644 index 3da08e9..0000000 --- a/docs/系统使用统计/系统使用统计表设计.md +++ /dev/null @@ -1,612 +0,0 @@ -# 系统使用统计表设计 - -## 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` - -可后置： - -- 各类日汇总聚合表 -- 复杂会话表 -- 全量行为审计表 diff --git a/docs/迁移与兼容/旧接口文档导航.md b/docs/迁移与兼容/旧接口文档导航.md index e51fbfe..6657608 100644 --- a/docs/迁移与兼容/旧接口文档导航.md +++ b/docs/迁移与兼容/旧接口文档导航.md @@ -23,10 +23,10 @@ - `评查点分组目标结构与迁移方案.md` → `docs/评查点分组/评查点分组目标结构与迁移方案.md` - `评查点分组迁移执行前检查清单.md` → `docs/评查点分组/评查点分组迁移执行前检查清单.md` - `旧规则绑定表下线观察与删表草案.md` → `docs/评查点分组/旧规则绑定表下线观察与删表草案.md` -- `系统使用统计最终需求.md` → `docs/系统使用统计/系统使用统计最终需求.md` -- `系统使用统计接口设计.md` → `docs/系统使用统计/系统使用统计接口设计.md` -- `系统使用统计表设计.md` → `docs/系统使用统计/系统使用统计表设计.md` -- `系统使用统计开发任务拆解.md` → `docs/系统使用统计/系统使用统计开发任务拆解.md` +- `系统使用统计最终需求.md` → `docs/系统使用统计/系统使用统计最终版.md` +- `系统使用统计接口设计.md` → `docs/系统使用统计/系统使用统计实施版.md` +- `系统使用统计表设计.md` → `docs/系统使用统计/系统使用统计实施版.md` +- `系统使用统计开发任务拆解.md` → `docs/系统使用统计/系统使用统计实施版.md` - `用户权限与权限点清单.md` → `docs/权限与地区隔离/用户权限与权限点清单.md` - `用户权限初始化SQL.sql` → `docs/权限与地区隔离/用户权限初始化SQL.sql` - `RAG聊天接口.md` → `docs/RAG/RAG聊天接口.md`