TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reorganize by module

Browse Source
This commit is contained in:
wren
2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/HANDOFF.md
+6 -6
View File
@@ -43,8 +43,8 @@
### 当前正式阅读顺序
1. `docs/HANDOFF.md`
2. `docs/接口/README.md`
3. `docs/权限与地区隔离文档导航.md`
2. `docs/迁移与兼容/旧接口文档导航.md`
3. `docs/权限与地区隔离/权限与地区隔离文档导航.md`
4. `docs/leaudit/README.md`
5. `docs/规则编辑/README.md`
@@ -65,7 +65,7 @@
- 更新允许维护 `documentNumber`、`remark`、`isTestDocument`、`auditStatus` 等元数据
对应文档：
- `docs/接口/文档上传与列表接口分析.md`
- `docs/文档管理/文档上传与列表接口分析.md`
### 2. 文档数据隔离已补到后端强约束
@@ -221,7 +221,7 @@
- `scripts/precheck_rule_group_migration.sql`
- `scripts/migrate_rule_groups_to_business_roots.sql`
- `scripts/migrate_rule_groups_to_doc_type_roots.sql`
- `docs/接口/评查点分组迁移执行前检查清单.md`
- `docs/评查点分组/评查点分组迁移执行前检查清单.md`
说明：
- 这部分还属于“迁移方案与执行准备已就绪”
@@ -406,8 +406,8 @@
## 八、配套主文档
- `docs/README.md`：后端 `/docs` 总导航
- `docs/接口/README.md`：接口文档导航
- `docs/权限与地区隔离文档导航.md`：权限主线导航
- `docs/迁移与兼容/旧接口文档导航.md`：接口文档导航
- `docs/权限与地区隔离/权限与地区隔离文档导航.md`：权限主线导航
- `docs/leaudit/README.md`：后端架构主线
- `docs/规则编辑/README.md`：规则链路主线
- `new_doc_review/docs/route-alias-guidelines.md`：前端子页权限映射规范
docs/RAG后端上线清单.md → docs/RAG/RAG后端上线清单.md
View File
docs/接口/RAG聊天接口.md → docs/RAG/RAG聊天接口.md
View File
docs/README.md
+47 -134
View File
@@ -1,152 +1,65 @@
# leaudit-platform 文档地图
> 最后更新：2026-05-07
> 这份文档只做一件事：告诉你“现在该看哪份文档”。
> 当前统一口径以 `docs/HANDOFF.md` 为准，不再使用分散的旧阶段说明当主事实源。
> 最后更新：2026-05-09
> 当前已按“业务模块 / 专题模块”重组 `docs/` 目录，根目录只保留总导航与总交接文档。
## 一句话先说清楚
## 根目录只看这两份
- 想看项目现在做到哪了：看 `docs/HANDOFF.md`
- 想查后端接口怎么对接：看 `docs/接口/README.md`
- 想查 LeAudit 后端链路和存储结构：看 `docs/leaudit/README.md`
- 想查规则管理、YAML、Bridge、规则执行链：看 `docs/规则编辑/README.md`
- 想查权限、角色、地区隔离：看 `docs/权限与地区隔离文档导航.md`
- 想翻旧资料：看 `docs/历史API与权限文档索引.md`
- `docs/HANDOFF.md`：当前真实状态、已完成事项、剩余阻塞、关键代码位置
- `docs/README.md`：模块化文档导航
## 现在的模块目录
| 模块 | 目录 | 主要内容 |
|---|---|---|
| 项目总览 / 协作 | `docs/项目总览/` | Git 协作规范、项目级补充资料 |
| 文档管理 | `docs/文档管理/` | 文档上传、列表、详情、评查触发 |
| 入口模块 | `docs/入口模块/` | 首页入口、入口模块绑定、模块归属 |
| 评查点分组 | `docs/评查点分组/` | 一级分组、二级分组、规则集迁移方案 |
| 系统使用统计 | `docs/系统使用统计/` | 需求、表设计、接口设计、任务拆解 |
| 权限与地区隔离 | `docs/权限与地区隔离/` | RBAC、权限点、地区隔离、初始化 SQL |
| RAG | `docs/RAG/` | RAG 聊天接口、RAG 上线清单 |
| 交叉评查 | `docs/交叉评查/` | 交叉评查业务方案、表结构、流程图 |
| 规则编辑 | `docs/规则编辑/` | YAML 规则、Bridge 接入、规则链实施计划 |
| LeAudit 架构 | `docs/leaudit/` | 核心表结构、Bridge、处理流水线、AuditCtx |
| 迁移与兼容 | `docs/迁移与兼容/` | 老用户迁移、历史 API / 权限文档索引、旧导航 |
## 推荐阅读顺序
### 1. 老板汇报 / 快速了解现状
### 1. 快速了解当前项目
1. `docs/HANDOFF.md`
2. `docs/接口/README.md`
2. `docs/文档管理/文档上传与列表接口分析.md`
3. `docs/权限与地区隔离/权限与地区隔离文档导航.md`
### 2. 新人接手继续开发
### 2. 新人接手开发
1. `docs/HANDOFF.md`
2. `docs/接口/README.md`
3. `docs/leaudit/README.md`
4. `docs/规则编辑/README.md`
5. 根据具体模块再进入对应专题文档
2. `docs/README.md`
3. 按业务进入对应模块目录
4. 如涉及底层链路，再看 `docs/leaudit/README.md`
5. 如涉及规则执行，再看 `docs/规则编辑/README.md`
### 3. 联调排障
1. `docs/HANDOFF.md`
2. `docs/接口/README.md`
3. 对应模块专项文档
4. 必要时再去看 `new_doc_review/docs/README.md`
## 按事情找文档
### 3. 按事情找文档
| 你要做的事 | 先看哪份 | 再看哪份 |
|---|---|---|
| 看当前项目状态、已完成、剩余阻塞 | `docs/HANDOFF.md` | - |
| 查首页入口、入口模块绑定 | `docs/接口/入口模块绑定最终设计方案.md` | `docs/接口/README.md` |
| 查文档上传、文档列表、详情、评查触发 | `docs/接口/文档上传与列表接口分析.md` | `docs/HANDOFF.md` |
| 查文档类型、一级分组、二级分组、规则集关系 | `docs/接口/评查点分组目标结构与迁移方案.md` | `docs/接口/评查点分组迁移执行前检查清单.md` |
| 查权限点、路由、角色、地区隔离 | `docs/权限与地区隔离文档导航.md` | `docs/接口/用户权限与权限点清单.md` |
| 查用户与地区隔离完整模型 | `docs/用户与地区权限完整设计方案.md` | `docs/HANDOFF.md` |
| 查 LeAudit 表结构、产物、处理流水线 | `docs/leaudit/README.md` | `docs/leaudit/document_schema_design.md` |
| 查规则编辑、YAML、规则版本、Bridge 接入 | `docs/规则编辑/README.md` | `docs/规则编辑/统一OSS与规则管理实施计划.md` |
| 查老系统 API / 权限历史口径 | `docs/历史API与权限文档索引.md` | `new_doc_review/auth_doc/` |
| 查前端工程实现文档 | `new_doc_review/docs/README.md` | 对应页面专项文档 |
| 查文档上传、文档列表、详情、评查触发 | `docs/文档管理/文档上传与列表接口分析.md` | `docs/HANDOFF.md` |
| 查首页入口、入口模块绑定 | `docs/入口模块/入口模块绑定最终设计方案.md` | `docs/HANDOFF.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` |
| 查规则链、YAML、Bridge 接入 | `docs/规则编辑/README.md` | `docs/规则编辑/统一OSS与规则管理实施计划.md` |
| 查 LeAudit 核心链路和表结构 | `docs/leaudit/README.md` | `docs/leaudit/document_schema_design.md` |
| 查老系统迁移 / 历史资料 | `docs/迁移与兼容/老用户迁移脚本说明.md` | `docs/迁移与兼容/历史API与权限文档索引.md` |
## 当前主文档分层
## 当前维护规则
### A. 项目级主入口
- `docs/HANDOFF.md`
- 当前真实状态
- 已完成事项
- 剩余待做
- 关键代码位置
- 这是整个项目的第一事实源
- `docs/README.md`
- 只负责导航
- 不再重复写大段阶段性现状
### B. 后端业务与接口文档
- `docs/接口/README.md`
- 后端接口文档总导航
- `docs/接口/文档上传与列表接口分析.md`
- 上传、列表、详情、更新、删除、评查链路
- `docs/接口/入口模块绑定最终设计方案.md`
- 入口模块、文档类型、绑定逻辑
- `docs/接口/评查点分组目标结构与迁移方案.md`
- 一级分组 / 二级分组 / 规则集 的目标模型
- `docs/接口/评查点分组迁移执行前检查清单.md`
- 迁移前核对项
- `docs/接口/用户权限与权限点清单.md`
- 权限点、路由、菜单权限口径
- `docs/接口/老用户迁移脚本说明.md`
- 老用户迁移说明
### C. 后端架构与规则链路文档
- `docs/leaudit/README.md`
- LeAudit 架构导航
- `docs/leaudit/document_schema_design.md`
- 文档域 / 产物域 / 表结构设计
- `docs/leaudit/dsl_rule_schema_design.md`
- DSL 规则域结构
- `docs/leaudit/bridge_directory_design.md`
- Bridge 目录职责
- `docs/leaudit/processing_logic.md`
- 处理流水线说明
- `docs/规则编辑/README.md`
- 规则编辑与规则链路导航
- `docs/规则编辑/统一OSS与规则管理实施计划.md`
- 当前规则链路主实施文档
- `docs/规则编辑/原生AuditCtx接入重构方案.md`
- AuditCtx 接入重构
### D. 权限与历史资料
- `docs/权限与地区隔离文档导航.md`
- 权限与地区隔离专题导航
- `docs/用户与地区权限完整设计方案.md`
- 用户 / 角色 / 地区权限完整设计
- `docs/历史API与权限文档索引.md`
- 历史资料入口，不是当前主事实源
## 哪些文档是“当前有效”，哪些只是“历史参考”
### 当前有效
- `docs/HANDOFF.md`
- `docs/接口/README.md`
- `docs/接口/*.md`（当前保留的专题文档）
- `docs/leaudit/README.md`
- `docs/规则编辑/README.md`
- `docs/权限与地区隔离文档导航.md`
- `docs/用户与地区权限完整设计方案.md`
### 历史参考
- `docs/历史API与权限文档索引.md`
- `new_doc_review/auth_doc/`
- `new_doc_review/docs/` 里偏旧阶段联调记录的文档
## 现在这个目录怎么维护
- `docs/README.md` 只做导航，不堆阶段性过程记录
- 当前状态变化，优先更新 `docs/HANDOFF.md`
- 接口变化，优先更新 `docs/接口/` 下对应文档
- 架构或规则链路变化，更新 `docs/leaudit/` 或 `docs/规则编辑/`
- 已经失效的临时文档，不要继续挂在主导航里
- 带 `(1)`、`最终版2`、`新版-副本` 这类文件名，原则上不再新增
## 你如果只剩 3 分钟
按这个顺序看：
1. `docs/HANDOFF.md`
2. `docs/接口/README.md`
3. `docs/leaudit/README.md`
4. `docs/规则编辑/README.md`
这样至少能先知道：
- 现在做到哪
- 主链路怎么跑
- 文档 / 规则 / 权限 分别在哪些文档里维护
- 根目录不再堆放零散专题文档
- 新文档优先放进对应模块目录
- 项目状态变化，优先更新 `docs/HANDOFF.md`
- 模块实现变化，优先更新对应模块目录下的主文档
- 历史参考、兼容说明、旧阶段索引统一放 `docs/迁移与兼容/`
- 带 `(1)`、`副本`、`最终版2` 这类文件名不再新增
docs/AuditCtx深度解读-2026-04-27.html → docs/leaudit/AuditCtx深度解读-2026-04-27.html
View File
docs/接口/入口模块绑定最终设计方案.md → docs/入口模块/入口模块绑定最终设计方案.md
View File
docs/接口/README.md
-41
View File
@@ -1,41 +0,0 @@
# 接口文档导航
> 最后整理：2026-05-04
> 说明：这里记录的是 `leaudit-platform` 当前主线已落地、正在联调、或明确作为迁移目标的接口文档。
## 阅读顺序
1. `docs/HANDOFF.md`
2. `文档上传与列表接口分析.md`
3. `入口模块绑定最终设计方案.md`
4. `用户权限与权限点清单.md`
5. 根据具体模块继续往下看
## 按模块查找
| 模块 | 文档 | 说明 |
|------|------|------|
| 首页入口 / 菜单 | `入口模块绑定最终设计方案.md` | 入口模块、文档类型、规则链路绑定模型 |
| 文档上传 / 列表 / 评查 | `文档上传与列表接口分析.md` | 上传、列表、详情、更新、删除、评查触发、数据隔离 |
| RAG 聊天 | `RAG聊天接口.md` | `/api/v3/rag/*` 自有聊天接口、SSE、权限、表结构映射 |
| 文档类型 / 评查组 | `评查点分组目标结构与迁移方案.md` | 文档类型、一级分组、二级分组、规则集与迁移口径 |
| 评查点分组迁移 | `评查点分组目标结构与迁移方案.md` | 新老分组结构对齐方案 |
| 评查点分组迁移 | `评查点分组迁移执行前检查清单.md` | 正式迁移前检查项 |
| 权限 / 路由 | `用户权限与权限点清单.md` | RBAC、路由、权限点清单 |
| 用户迁移 | `老用户迁移脚本说明.md` | 老用户迁移脚本与校验说明 |
## 本次归并
- `新系统版_documents_list接口.md` 已并入 `文档上传与列表接口分析.md`
- `文档上传与评查接口.md` 已并入 `文档上传与列表接口分析.md`
- `首页入口接口落地说明.md` 已并入 `入口模块绑定最终设计方案.md`
- `评查点分组正式迁移执行建议.md` 已并入 `评查点分组迁移执行前检查清单.md`
- `文档类型与评查组关联方案.md` 已并入 `评查点分组目标结构与迁移方案.md`
- `首页菜单最小可用收口说明.md`、`系统设置入口恢复说明.md` 的阶段性收口内容已并入 `docs/HANDOFF.md`
- `前端联调404与资源缺口收口清单.md` 属于前端联调阶段记录，已从后端主文档目录移除
## 使用约束
- 这里的文档优先级高于 `new_doc_review/auth_doc/` 的历史快照资料
- 如果某份文档描述和当前代码不一致，以当前代码与 `docs/HANDOFF.md` 为准，并尽快回补文档
- 新接口如果已经用于当前主链路，必须同步补到本目录
docs/接口/文档上传与列表接口分析.md → docs/文档管理/文档上传与列表接口分析.md
View File
docs/权限与地区隔离文档导航.md → docs/权限与地区隔离/权限与地区隔离文档导航.md
+7 -7
View File
@@ -6,24 +6,24 @@
## 建议阅读顺序
1. `docs/HANDOFF.md`
2. `docs/接口/用户权限与权限点清单.md`
3. `docs/用户与地区权限完整设计方案.md`
2. `docs/权限与地区隔离/用户权限与权限点清单.md`
3. `docs/权限与地区隔离/用户与地区权限完整设计方案.md`
## 各文档角色
| 文档 | 作用 | 建议 |
|------|------|------|
| `docs/接口/用户权限与权限点清单.md` | 当前新系统权限点、路由、初始化说明 | 日常开发先看这个 |
| `docs/用户与地区权限完整设计方案.md` | 当前正式权限设计稿 | 作为现行设计主文档 |
| `docs/权限与地区隔离/用户权限与权限点清单.md` | 当前新系统权限点、路由、初始化说明 | 日常开发先看这个 |
| `docs/权限与地区隔离/用户与地区权限完整设计方案.md` | 当前正式权限设计稿 | 作为现行设计主文档 |
## 本次收口
- `docs/用户权限开发TaskList.md` 已删除
- `docs/老系统_docauditai_用户权限架构深度分析.md` 已并入 `docs/用户与地区权限完整设计方案.md`
- `docs/老系统_docauditai_用户权限架构深度分析.md` 已并入 `docs/权限与地区隔离/用户与地区权限完整设计方案.md`
- 其“执行清单”价值已经被下面几类文档覆盖：
- `docs/HANDOFF.md`：当前真实状态与下一步
- `docs/接口/用户权限与权限点清单.md`：当前可执行接口与权限点
- `docs/用户与地区权限完整设计方案.md`：正式设计边界
- `docs/权限与地区隔离/用户权限与权限点清单.md`：当前可执行接口与权限点
- `docs/权限与地区隔离/用户与地区权限完整设计方案.md`：正式设计边界
## 当前口径
docs/用户与地区权限完整设计方案.md → docs/权限与地区隔离/用户与地区权限完整设计方案.md
View File
docs/接口/用户权限与权限点清单.md → docs/权限与地区隔离/用户权限与权限点清单.md
+8 -8
View File
@@ -1,6 +1,6 @@
# 用户权限初始化 SQL 与权限点清单
这份文档对应：`docs/接口/用户权限初始化SQL.sql`
这份文档对应：`docs/权限与地区隔离/用户权限初始化SQL.sql`
用途只有两个：
@@ -19,8 +19,8 @@
## 1. 本次交付文件
- SQL：`docs/接口/用户权限初始化SQL.sql`
- 说明：`docs/接口/用户权限与权限点清单.md`
- SQL：`docs/权限与地区隔离/用户权限初始化SQL.sql`
- 说明：`docs/权限与地区隔离/用户权限与权限点清单.md`
---
@@ -396,7 +396,7 @@ SQL 里初始化了以下核心菜单：
建议按这个顺序：
1. 先在测试库执行 `docs/接口/用户权限初始化SQL.sql`
1. 先在测试库执行 `docs/权限与地区隔离/用户权限初始化SQL.sql`
2. 检查 `roles / permissions / role_permissions / role_route` 是否初始化成功
3. 给几个测试账号分别挂 `provincial_admin / admin / common`
4. 再用接口实际验证：
@@ -410,9 +410,9 @@ SQL 里初始化了以下核心菜单：
如果你后面忘了这套体系总原则，看这里：
- 总设计：`docs/用户与地区权限完整设计方案.md`
- 导航说明：`docs/权限与地区隔离文档导航.md`
- 本文：`docs/接口/用户权限与权限点清单.md`
- SQL：`docs/接口/用户权限初始化SQL.sql`
- 总设计：`docs/权限与地区隔离/用户与地区权限完整设计方案.md`
- 导航说明：`docs/权限与地区隔离/权限与地区隔离文档导航.md`
- 本文：`docs/权限与地区隔离/用户权限与权限点清单.md`
- SQL：`docs/权限与地区隔离/用户权限初始化SQL.sql`
这四份组合起来，就是当前新系统用户权限方案的完整本地留档。
docs/接口/用户权限初始化SQL.sql → docs/权限与地区隔离/用户权限初始化SQL.sql
View File
docs/系统使用统计/系统使用统计开发任务拆解.md
+626
View File
@@ -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. 联调验收
这样做的好处是：
- 风险最小
- 统计口径先稳定
- 前后端可以并行推进
- 一期就能较快交付可用结果
docs/系统使用统计/系统使用统计接口设计.md
+578
View File
@@ -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. 后续优化建议
- 增加日汇总表，提升一年跨度查询性能
- 增加部门、地区快照，避免组织调整影响历史统计
- 为明细与汇总增加统一缓存策略
- 为导出增加异步任务模式，避免大数据量同步阻塞
docs/系统使用统计/系统使用统计最终需求.md
+237
View File
@@ -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. 一句话范围定义
本次“系统使用统计”功能不做全量行为追踪，仅围绕登录、上传、评查三类核心业务数据，提供按用户、部门、地区、文档大类、文档类型、入口模块的动态统计与明细查询能力。
docs/系统使用统计/系统使用统计表设计.md
+612
View File
@@ -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`
可后置：
- 各类日汇总聚合表
- 复杂会话表
- 全量行为审计表
docs/接口/旧规则绑定表下线观察与删表草案.md → docs/评查点分组/旧规则绑定表下线观察与删表草案.md
View File
docs/接口/评查点分组目标结构与迁移方案.md → docs/评查点分组/评查点分组目标结构与迁移方案.md
View File
docs/接口/评查点分组迁移执行前检查清单.md → docs/评查点分组/评查点分组迁移执行前检查清单.md
View File
docs/历史API与权限文档索引.md → docs/迁移与兼容/历史API与权限文档索引.md
+1 -1
View File
@@ -5,7 +5,7 @@
## 使用方式
- 当前主链路以 `docs/HANDOFF.md` 与 `docs/接口/README.md` 为准
- 当前主链路以 `docs/HANDOFF.md` 与 `docs/迁移与兼容/旧接口文档导航.md` 为准
- `new_doc_review/auth_doc/` 里的文档，多数写于旧接口或 PostgREST 仍是主依赖的时期
- 若历史文档与现网代码冲突，以现网代码和主文档为准
docs/迁移与兼容/旧接口文档导航.md
+39
View File
@@ -0,0 +1,39 @@
# 旧接口文档导航（已归档）
> 最后更新：2026-05-09
> 说明：原 `docs/接口/` 目录已按模块拆分。本文只保留“旧分类到新位置”的映射，避免老链接失效后找不到文档。
## 旧目录去向
| 旧分类 | 新位置 |
|---|---|
| 接口总导航 | `docs/README.md` |
| 首页入口 / 菜单 | `docs/入口模块/` |
| 文档上传 / 列表 / 评查 | `docs/文档管理/` |
| 文档类型 / 评查点分组 | `docs/评查点分组/` |
| 系统使用统计 | `docs/系统使用统计/` |
| 权限 / 路由 / 初始化 SQL | `docs/权限与地区隔离/` |
| RAG 聊天 | `docs/RAG/` |
| 用户迁移 / 历史资料 | `docs/迁移与兼容/` |
## 旧文档对应新路径
- `入口模块绑定最终设计方案.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`
- `老用户迁移脚本说明.md` → `docs/迁移与兼容/老用户迁移脚本说明.md`
## 使用建议
- 日常开发不要再新增 `docs/接口/` 这种“文档类型目录”
- 以后统一按模块建目录、按模块归档
- 如果某个新文档同时涉及多个模块，优先放主要责任模块目录，并在 `docs/README.md` 里补导航
docs/接口/老用户迁移脚本说明.md → docs/迁移与兼容/老用户迁移脚本说明.md
View File
docs/团队Git协作完整规范-2026-05-07.md → docs/项目总览/团队Git协作完整规范-2026-05-07.md
View File