docs: reorganize by module

2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
@@ -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` 这类文件名不再新增