diff --git a/docs/README.md b/docs/README.md index 2b0ee66..9ea7b1a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,99 +1,152 @@ # leaudit-platform 文档地图 -> 最后整理：2026-05-04 -> 当前主线：以后端 `fastapi_leaudit` 的 `/docs` 为主整理入口，前端文档仅保留必要索引引用。 +> 最后更新：2026-05-07 +> 这份文档只做一件事：告诉你“现在该看哪份文档”。 +> 当前统一口径以 `docs/HANDOFF.md` 为准，不再使用分散的旧阶段说明当主事实源。 -## 先看什么 +## 一句话先说清楚 -- 给老板汇报当前状态：先看 `docs/HANDOFF.md` -- 接手继续开发：先看 `docs/HANDOFF.md`，再看 `docs/接口/README.md` -- 查具体模块：按下面“功能模块索引”找对应文档 -- 查规则引擎与后端处理链路：看 `docs/leaudit/README.md` 与 `docs/规则编辑/README.md` -- 查前端历史对接资料：看 `new_doc_review/docs/README.md` -- 查旧版 RBAC / API 存量资料：看 `docs/历史API与权限文档索引.md` +- 想看项目现在做到哪了：看 `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/权限与地区隔离文档导航.md`：权限、路由、地区隔离主线 -- `docs/leaudit/README.md`：稳定架构、表结构、处理流水线 -- `docs/规则编辑/README.md`：规则管理、Bridge 接入、落地实施顺序 +### 1. 老板汇报 / 快速了解现状 -## 功能模块索引 +1. `docs/HANDOFF.md` +2. `docs/接口/README.md` -| 模块 | 重点文档 | 说明 | -|------|----------|------| -| 全局交接 / 当前状态 | `docs/HANDOFF.md` | 当前主线、已完成事项、剩余阻塞、关键代码位置 | -| 后端接口总览 | `docs/接口/README.md` | 当前有效接口文档的阅读入口 | -| 首页入口模块 / 菜单 | `docs/接口/入口模块绑定最终设计方案.md` | 首页入口展示、绑定、RBAC 最小可用链路 | -| 文档上传 / 文档列表 / 文档详情 | `docs/接口/文档上传与列表接口分析.md` | 上传、列表、详情/更新/删除、评查触发、数据隔离 | -| 文档类型 / 规则绑定 | `docs/接口/评查点分组目标结构与迁移方案.md` | 文档类型、入口模块、规则组、规则集关系 | -| 评查点分组迁移 | `docs/接口/评查点分组目标结构与迁移方案.md`、`docs/接口/评查点分组迁移执行前检查清单.md` | 新老分组模型梳理与迁移脚本执行建议 | -| 权限 / 路由 / 地区隔离 | `docs/权限与地区隔离文档导航.md`、`docs/接口/用户权限与权限点清单.md`、`docs/用户与地区权限完整设计方案.md` | RBAC、路由、用户与地区隔离设计 | -| 规则引擎 / OSS / Bridge | `docs/规则编辑/README.md`、`docs/leaudit/README.md` | 规则 DSL、执行链路、对象存储、Bridge 设计 | -| 历史资料索引 | `docs/历史API与权限文档索引.md` | 老阶段 RBAC / API 快照的使用入口 | -| 前端权限别名 | `new_doc_review/docs/route-alias-guidelines.md` | 什么时候加 alias，什么时候补真实菜单路由 | +### 2. 新人接手继续开发 -## 文档目录约束 +1. `docs/HANDOFF.md` +2. `docs/接口/README.md` +3. `docs/leaudit/README.md` +4. `docs/规则编辑/README.md` +5. 根据具体模块再进入对应专题文档 -### `docs/` +### 3. 联调排障 -- 这里是当前项目的主文档目录 -- 只保留当前主线设计、接口、交接、迁移、规则架构文档 -- 新增业务说明优先写到这里，不要再散落到临时目录 +1. `docs/HANDOFF.md` +2. `docs/接口/README.md` +3. 对应模块专项文档 +4. 必要时再去看 `new_doc_review/docs/README.md` -### `new_doc_review/docs/` +## 按事情找文档 -- 这里保留前端工程实现文档 -- 偏实现、联调、部署、组件能力说明 -- 如果某项内容已经上升为“全项目共识”，应同步沉淀回 `docs/` +| 你要做的事 | 先看哪份 | 再看哪份 | +|---|---|---| +| 看当前项目状态、已完成、剩余阻塞 | `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` | 对应页面专项文档 | -### `new_doc_review/auth_doc/` +## 当前主文档分层 -- 这里以历史 API / RBAC / 前端对接资料为主 -- 多数是老阶段快照，不应直接当成当前系统唯一事实来源 -- 使用前先对照 `docs/HANDOFF.md` 与 `docs/接口/README.md` +### A. 项目级主入口 -## 本次已清理 +- `docs/HANDOFF.md` + - 当前真实状态 + - 已完成事项 + - 剩余待做 + - 关键代码位置 + - 这是整个项目的第一事实源 -- 删除重复或已被新版本覆盖的 Markdown： - - `docs/routes/http_routes_dedup_2026-04-27.md` - - `docs/superpowers/plans/2026-04-28-fix-double-finalize-and-bindings-api.md` - - `docs/用户权限开发TaskList.md` - - `docs/leaudit/SYSTEM_OVERVIEW.md` - - `docs/接口/新系统版_documents_list接口.md` - - `docs/接口/首页菜单最小可用收口说明.md` - - `docs/接口/系统设置入口恢复说明.md` - - `docs/规则编辑/开发任务拆解清单.md` - - `docs/规则编辑/跑通全流程所需准备项.md` - - `docs/规则编辑/为什么仍然需要Bridge适配层.md` - - `docs/规则编辑/yaml规则在线编辑设计.md` - - `docs/规则编辑/worker并发执行改造方案.md` - - `docs/leaudit/并发与重试参数说明.md` - - `docs/接口/文档上传与评查接口.md` - - `docs/接口/首页入口接口落地说明.md` - - `docs/接口/评查点分组正式迁移执行建议.md` - - `docs/接口/文档类型与评查组关联方案.md` - - `docs/老系统_docauditai_用户权限架构深度分析.md` - - `docs/接口/前端联调404与资源缺口收口清单.md` - - `new_doc_review/auth_doc/entry_modules_api(1).md` - - `new_doc_review/auth_doc/交叉评查接口文档(1).md` - - `new_doc_review/auth_doc/API_RESPONSE_EXAMPLES_V3.2.md` - - `new_doc_review/docs/URGENT-前端必须修改.md` -- 补齐文档导航： - - `docs/README.md` - - `docs/接口/README.md` - - `docs/权限与地区隔离文档导航.md` - - `docs/leaudit/README.md` - - `docs/规则编辑/README.md` - - `docs/历史API与权限文档索引.md` - - `new_doc_review/docs/README.md` -- 统一现状入口：`docs/HANDOFF.md` +- `docs/README.md` + - 只负责导航 + - 不再重复写大段阶段性现状 -## 后续维护规则 +### B. 后端业务与接口文档 -- 新功能如果已经进入当前主线，优先补 `docs/HANDOFF.md` 的“已完成 / 待做” -- 接口发生变化时，优先更新 `docs/接口/` 下对应文档 -- 只用于阶段排障的“临时说明”在问题关闭后要么合并进正式文档，要么删除 -- 带版本号或带 `(1)` 的副本文件，原则上不继续新增 +- `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` + +这样至少能先知道： +- 现在做到哪 +- 主链路怎么跑 +- 文档 / 规则 / 权限 分别在哪些文档里维护