diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index e5799e9..b9d91cb 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -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`：前端子页权限映射规范 diff --git a/docs/RAG后端上线清单.md b/docs/RAG/RAG后端上线清单.md similarity index 100% rename from docs/RAG后端上线清单.md rename to docs/RAG/RAG后端上线清单.md diff --git a/docs/接口/RAG聊天接口.md b/docs/RAG/RAG聊天接口.md similarity index 100% rename from docs/接口/RAG聊天接口.md rename to docs/RAG/RAG聊天接口.md diff --git a/docs/README.md b/docs/README.md index 9ea7b1a..c6f21e5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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` 这类文件名不再新增 diff --git a/docs/AuditCtx深度解读-2026-04-27.html b/docs/leaudit/AuditCtx深度解读-2026-04-27.html similarity index 100% rename from docs/AuditCtx深度解读-2026-04-27.html rename to docs/leaudit/AuditCtx深度解读-2026-04-27.html diff --git a/docs/接口/入口模块绑定最终设计方案.md b/docs/入口模块/入口模块绑定最终设计方案.md similarity index 100% rename from docs/接口/入口模块绑定最终设计方案.md rename to docs/入口模块/入口模块绑定最终设计方案.md diff --git a/docs/接口/README.md b/docs/接口/README.md deleted file mode 100644 index e1f3541..0000000 --- a/docs/接口/README.md +++ /dev/null @@ -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` 为准，并尽快回补文档 -- 新接口如果已经用于当前主链路，必须同步补到本目录 diff --git a/docs/接口/文档上传与列表接口分析.md b/docs/文档管理/文档上传与列表接口分析.md similarity index 100% rename from docs/接口/文档上传与列表接口分析.md rename to docs/文档管理/文档上传与列表接口分析.md diff --git a/docs/权限与地区隔离文档导航.md b/docs/权限与地区隔离/权限与地区隔离文档导航.md similarity index 52% rename from docs/权限与地区隔离文档导航.md rename to docs/权限与地区隔离/权限与地区隔离文档导航.md index cb909e1..9812f79 100644 --- a/docs/权限与地区隔离文档导航.md +++ b/docs/权限与地区隔离/权限与地区隔离文档导航.md @@ -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`：正式设计边界 ## 当前口径 diff --git a/docs/用户与地区权限完整设计方案.md b/docs/权限与地区隔离/用户与地区权限完整设计方案.md similarity index 100% rename from docs/用户与地区权限完整设计方案.md rename to docs/权限与地区隔离/用户与地区权限完整设计方案.md diff --git a/docs/接口/用户权限与权限点清单.md b/docs/权限与地区隔离/用户权限与权限点清单.md similarity index 93% rename from docs/接口/用户权限与权限点清单.md rename to docs/权限与地区隔离/用户权限与权限点清单.md index 62056a5..260381c 100644 --- a/docs/接口/用户权限与权限点清单.md +++ b/docs/权限与地区隔离/用户权限与权限点清单.md @@ -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` 这四份组合起来，就是当前新系统用户权限方案的完整本地留档。 diff --git a/docs/接口/用户权限初始化SQL.sql b/docs/权限与地区隔离/用户权限初始化SQL.sql similarity index 100% rename from docs/接口/用户权限初始化SQL.sql rename to docs/权限与地区隔离/用户权限初始化SQL.sql diff --git a/docs/系统使用统计/系统使用统计开发任务拆解.md b/docs/系统使用统计/系统使用统计开发任务拆解.md new file mode 100644 index 0000000..d691cec --- /dev/null +++ b/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. 联调验收 + +这样做的好处是： + +- 风险最小 +- 统计口径先稳定 +- 前后端可以并行推进 +- 一期就能较快交付可用结果 diff --git a/docs/系统使用统计/系统使用统计接口设计.md b/docs/系统使用统计/系统使用统计接口设计.md new file mode 100644 index 0000000..8437b29 --- /dev/null +++ b/docs/系统使用统计/系统使用统计接口设计.md @@ -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. 后续优化建议 + +- 增加日汇总表，提升一年跨度查询性能 +- 增加部门、地区快照，避免组织调整影响历史统计 +- 为明细与汇总增加统一缓存策略 +- 为导出增加异步任务模式，避免大数据量同步阻塞 diff --git a/docs/系统使用统计/系统使用统计最终需求.md b/docs/系统使用统计/系统使用统计最终需求.md new file mode 100644 index 0000000..1003a48 --- /dev/null +++ b/docs/系统使用统计/系统使用统计最终需求.md @@ -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. 一句话范围定义 + +本次“系统使用统计”功能不做全量行为追踪，仅围绕登录、上传、评查三类核心业务数据，提供按用户、部门、地区、文档大类、文档类型、入口模块的动态统计与明细查询能力。 diff --git a/docs/系统使用统计/系统使用统计表设计.md b/docs/系统使用统计/系统使用统计表设计.md new file mode 100644 index 0000000..3da08e9 --- /dev/null +++ b/docs/系统使用统计/系统使用统计表设计.md @@ -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` + +可后置： + +- 各类日汇总聚合表 +- 复杂会话表 +- 全量行为审计表 diff --git a/docs/接口/旧规则绑定表下线观察与删表草案.md b/docs/评查点分组/旧规则绑定表下线观察与删表草案.md similarity index 100% rename from docs/接口/旧规则绑定表下线观察与删表草案.md rename to docs/评查点分组/旧规则绑定表下线观察与删表草案.md diff --git a/docs/接口/评查点分组目标结构与迁移方案.md b/docs/评查点分组/评查点分组目标结构与迁移方案.md similarity index 100% rename from docs/接口/评查点分组目标结构与迁移方案.md rename to docs/评查点分组/评查点分组目标结构与迁移方案.md diff --git a/docs/接口/评查点分组迁移执行前检查清单.md b/docs/评查点分组/评查点分组迁移执行前检查清单.md similarity index 100% rename from docs/接口/评查点分组迁移执行前检查清单.md rename to docs/评查点分组/评查点分组迁移执行前检查清单.md diff --git a/docs/历史API与权限文档索引.md b/docs/迁移与兼容/历史API与权限文档索引.md similarity index 95% rename from docs/历史API与权限文档索引.md rename to docs/迁移与兼容/历史API与权限文档索引.md index 612caeb..d7eb74a 100644 --- a/docs/历史API与权限文档索引.md +++ b/docs/迁移与兼容/历史API与权限文档索引.md @@ -5,7 +5,7 @@ ## 使用方式 -- 当前主链路以 `docs/HANDOFF.md` 与 `docs/接口/README.md` 为准 +- 当前主链路以 `docs/HANDOFF.md` 与 `docs/迁移与兼容/旧接口文档导航.md` 为准 - `new_doc_review/auth_doc/` 里的文档，多数写于旧接口或 PostgREST 仍是主依赖的时期 - 若历史文档与现网代码冲突，以现网代码和主文档为准 diff --git a/docs/迁移与兼容/旧接口文档导航.md b/docs/迁移与兼容/旧接口文档导航.md new file mode 100644 index 0000000..e51fbfe --- /dev/null +++ b/docs/迁移与兼容/旧接口文档导航.md @@ -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` 里补导航 diff --git a/docs/接口/老用户迁移脚本说明.md b/docs/迁移与兼容/老用户迁移脚本说明.md similarity index 100% rename from docs/接口/老用户迁移脚本说明.md rename to docs/迁移与兼容/老用户迁移脚本说明.md diff --git a/docs/团队Git协作完整规范-2026-05-07.md b/docs/项目总览/团队Git协作完整规范-2026-05-07.md similarity index 100% rename from docs/团队Git协作完整规范-2026-05-07.md rename to docs/项目总览/团队Git协作完整规范-2026-05-07.md