docs: reorganize backend project documentation

docs/HANDOFF.md

@@ -1,7 +1,8 @@
-# 开发交接文档 — leaudit-platform 前后端
+# 开发交接文档 — leaudit-platform
 
-> 本会话时间：2026-04-29 ~ 2026-04-30
-> 工作目录：`/home/wren-dev/Porject/leaudit-platform/`
+> 本轮整理时间：2026-04-29 ~ 2026-05-04
+> 工作目录：`/home/wren-dev/Porject/leaudit-platform`
+> 当前主线：前端 `new_doc_review` + 后端 `fastapi_modules/fastapi_leaudit`
 
 ---
 
@@ -9,223 +10,404 @@
 
 | 项目 | 路径 | 分支 | Remote |
 |------|------|------|--------|
-| **后端** | `/home/wren-dev/Porject/leaudit-platform/` | `main` | **无**（需配置） |
-| **前端** | `/home/wren-dev/Porject/leaudit-platform/new_doc_review/` | `wren` | `http://git.7bm.co:1024/jande/new_doc_review.git` |
+| 后端 | `/home/wren-dev/Porject/leaudit-platform` | `main` | 当前未配置 remote |
+| 前端 | `/home/wren-dev/Porject/leaudit-platform/new_doc_review` | `wren` | `http://git.7bm.co:1024/jande/new_doc_review.git` |
 
-后端未推送（无 remote），前端 `wren` 分支领先 origin 7 个提交。
+## 数据库 / 环境
+
+| 项目 | 当前值 |
+|------|--------|
+| 后端 API | `http://nas.7bm.co:8096` |
+| 前端开发地址 | `http://nas.7bm.co:5173` / 本地 `http://localhost:5173` |
+| PostgreSQL Host | `nas.7bm.co` |
+| PostgreSQL Port | `54302` |
+| Database | `leaudit_platform` |
+| DB User | `docauditai_admin` |
+
+说明：
+- 仓库内不记录数据库密码，仍需通过安全渠道获取
+- 当前用户已明确允许按现在配置的真实库继续联调
+- 文档里的“旧系统 / 老库”通常指 `docauditai` 侧历史表，不是让前端继续直接走旧接口
 
 ---
 
-## 数据库
+## 一、先看结论
 
-| 项 | 值 |
-|------|-----|
-| Host | `nas.7bm.co:54302` |
-| 用户 | `docauditai_admin` |
-| 密码 | `zhfw*123*` |
-| 数据库 | `leaudit_platform` |
+当前项目状态可以直接概括成 4 句话：
+
+1. 首页入口、菜单、RBAC、文档类型、规则组、文档上传这条主链路已经基本串起来了。
+2. 当前主要问题不是“完全不能用”，而是“新旧模型并存，部分语义还没完全收口”。
+3. 当前正确方向很明确：前端尽量统一走新后端接口，PostgREST 只保留存量过渡，不再新增依赖。
+4. 还要继续收口的核心是：上传后评查链路、文档类型到规则集的关系表达、以及旧字段旧文案清理。
+
+### 当前正式阅读顺序
+
+1. `docs/HANDOFF.md`
+2. `docs/接口/README.md`
+3. `docs/权限与地区隔离文档导航.md`
+4. `docs/leaudit/README.md`
+5. `docs/规则编辑/README.md`
 
 ---
 
-## 一、已完成的工作
+## 二、本轮已完成的关键工作
 
-### 1. 首页入口模块 RBAC 过滤修复
+### 1. 文档列表详情 / 更新 / 删除已从 PostgREST 迁到新后端接口
 
-**问题**：`内部公文` 入口模块配置存在（id=3, path=/home），但首页不显示。  
-**根因**：`HomeServiceImpl` 做二次过滤——入口模块的 targetPath 必须匹配用户有路由权限的路径。`provincial_admin` 的 `role_route` 里没有 `/home`。  
-**修复**：插入 `role_route` — role_id=2, route_id=10 (/home), permission='RW', status=1。  
-**后端提交**：`19c70d2`
+后端已补接口：
+- `GET /api/documents/{id}`
+- `PUT /api/documents/{id}`
+- `DELETE /api/documents/{id}`
 
-### 2. 首页地区过滤修正
+实现口径：
+- 文档列表、详情、更新、删除都围绕 `leaudit_documents` / `leaudit_document_files`
+- 删除为软删除，并自动维护最新版本标记
+- 更新允许维护 `documentNumber`、`remark`、`isTestDocument`、`auditStatus` 等元数据
 
-**问题**：`provincial_admin` 跳过了入口模块的 areas 地区过滤，导致取消地区后仍可见。  
-**修复**：`homeServiceImpl.py` 的 `bypass_area` 逻辑从包含 `provincial_admin` 改为只包含 `super_admin`。  
-**后端提交**：`c16bb84`
+对应文档：
+- `docs/接口/文档上传与列表接口分析.md`
 
-### 3. 细粒度权限执行
+### 2. 文档数据隔离已补到后端强约束
 
-**问题**：后端 `_assertManagePermission` 只检查用户是否属于 super_admin/provincial_admin/admin（粗粒度），不检查具体的 `rbac:roles:create` 等细粒度权限。  
-**修复**：
-- 新增 `_assertPermission(CurrentUserId, PermissionKey)` 方法
-- 所有 RBAC 管理端点补全细粒度权限检查：
-  - `CreateRole` → `rbac:roles:create`
-  - `UpdateRole` → `rbac:roles:update`
-  - `DeleteRole` → `rbac:roles:delete`
-  - `ListRoles/GetRoleRoutes/GetRolePermissions` → `rbac:roles:read`
-  - `ListUsers/ListRoleUsers/GetUserRoles` → `rbac:users:read`
-  - `AssignUserRoles/RevokeUserRole` → `rbac:user_roles:write`
-  - `UpdateRoleRoutes` → `rbac:role_routes:write`
-  - `SaveRolePermissions` → `rbac:role_permissions:write`
-  - `GetRoutePermissions` → `rbac:permissions:read`
-  - `super_admin` 自动跳过细粒度权限检查
-- 数据库给 `provincial_admin` (role_id=2) 和 `admin` (role_id=3) 补充了缺失的权限点
-**后端提交**：`33255e8`, `b6d7f15`
+当前规则：
+- `super_admin` / `provincial_admin`：看全量
+- `admin`：只能看本地市 `region = user.area`
+- `common`：只能看自己上传的文档
 
-### 4. 统一异常处理
+已覆盖范围：
+- 文档列表
+- 文档详情
+- 文档更新
+- 文档删除
 
-**问题**：`LeauditException` 没有注册 FastAPI exception handler，所有业务异常都变成 500。  
-**修复**：`app.py` 新增 `@app.exception_handler(BusinessException)`，返回带状态码的 JSON。  
-**后端提交**：`292b187`
+这意味着“每个地市管理员只能改各自数据”的要求，已经不只是前端过滤，而是后端接口层强制执行。
 
-### 5. 403 错误信息中文化
+### 3. 上传页主依赖已改为新接口
 
-**问题**：403 返回 `"缺少权限: rbac:roles:delete"` 显示的是 permission key。  
-**修复**：`_assertPermission` 查 `permissions` 表的 `display_name`，改为显示 `"缺少「删除角色」权限"`。  
-**后端提交**：`ab31c80`
+已完成：
+- `GET /api/document-types`
+- `GET /api/documents/list` 支持 `userId`、日期范围等过滤
+- `GET /api/v2/system/queue/status`
+- `POST /api/upload` 前端已改为扁平 `multipart/form-data`
 
-**前端**：axios 拦截器不再硬编码 `"无权限"`，改为透传后端的具体消息。`frontendJWT` 改为 `canEdit`，包含 `provincial_admin` + `admin` 两个角色。  
-**前端提交**：`185f55c`, `e2ae791`
+当前口径：
+- 主文件上传已经走新后端
+- 合同附件上传仍然是要继续收口的重点场景，因为它与规则抽取、评查触发紧密耦合
 
-### 6. 上传页 PostgREST 依赖替换
+### 4. 文档类型 CRUD 与绑定能力已切到新后端
 
-**问题**：上传页 loader 里 `getTodayDocuments`、`getDocumentTypes`、`getQueueStatus` 调 PostgREST 返回 404。  
-**后端新增**：
-- `GET /api/document-types` — 文档类型列表
-- `GET /api/documents/list` 新增 `userId`、`dateFrom`、`dateTo` 过滤参数
-- `GET /api/v2/system/queue/status` — 队列状态（查询 `leaudit_documents` 的 `processing_status` 统计）
-**后端提交**：`8f307ae`, `9e1b7a6`, `e6e129c`
+后端已支持：
+- `GET /api/document-types`
+- `GET /api/document-types/{id}`
+- `POST /api/document-types`
+- `PUT /api/document-types/{id}`
+- `DELETE /api/document-types/{id}`
 
-**前端**：
-- `getDocumentTypes()` → `GET /api/document-types`
-- `getTodayDocuments()` → `GET /api/documents/list?userId=&dateFrom=`
-- `getQueueStatus()` → 404 时返回空状态不报错
-**前端提交**：`dd249cc`
+当前文档类型支持维护：
+- 编码 / 名称 / 描述
+- 入口模块绑定
+- 启停状态
+- 规则集绑定（`ruleSetIds`）
 
-### 7. 上传接口对齐
+说明：
+- 这部分是“文档类型绑定入口模块”和“文档类型绑定规则集”的基础设施
+- 目前页面 UI 仍在继续按老系统风格收口，但主接口已具备
 
-**问题**：前端上传 `POST ${UPLOAD_URL}/upload` 用的是嵌套 JSON 的 `upload_info` 格式，与新后端 `POST /api/upload` 的扁平 `multipart/form-data` 不兼容。  
-**修复**：
-- `uploadDocumentToServer()` 重写，用扁平 FormData（typeId, region, fileRole, createdBy, autoRun, speed）
-- `handleFileUpload()` 适配：从 `userInfo.area` 取 `region`，从 `Priority` 枚举映射 `speed`
-- 响应类型从 `FileUploadResponse` 改为 `UploadResult`（`documentId` 替代 `result.id`）
-**前端提交**：`73fd861`
+### 5. 文档类型子页权限问题已收口一轮
 
-### 8. 文档类型 CRUD 后端
+已补的关键修复：
+- `route-alias` 从零散判断升级为配置表
+- 给新建/编辑/详情/结果页补齐父列表权限映射
+- 新增约束文档，明确：什么时候该加 alias，什么时候该补真实菜单路由
+- 已增加独立测试脚本，`npm run test:route-aliases` 可直接回归
 
-**新增端点**：
-```
-POST   /api/document-types       创建（含 rule_set_ids 自动绑定）
-PUT    /api/document-types/{id}   更新（rule_set_ids 全量替换）
-DELETE /api/document-types/{id}   软删除（级联解绑 rule_type_bindings）
-GET    /api/document-types/{id}   详情
-GET    /api/document-types        列表（扩展字段：description, entryModuleId, isEnabled, ruleSetIds）
-```
+关键文件：
+- `new_doc_review/app/utils/route-alias.shared.js`
+- `new_doc_review/docs/route-alias-guidelines.md`
 
-**关键实现**：
-- `DocumentTypeItemVO` 新增 `description`, `entryModuleId`, `isEnabled`, `ruleSetIds`
-- `DocumentTypeCreateDTO` / `DocumentTypeUpdateDTO` 支持 `ruleSetIds` 传入
-- 创建/更新时自动调用 `_syncRuleBindings()` 全量替换 `leaudit_rule_type_bindings`
-- 软删除级联清理 bindings
-**后端提交**：`52c2bed`
+已覆盖的典型路径：
+- `/documents/list -> /documents`
+- `/document-types/new -> /document-types`
+- `/contract-template/detail/:id -> /contract-template/list`
+- `/contract-draft/:id -> /contract-template/list`
+- `/chat-with-llm/chat -> /chat-with-llm`
+- `/chat-with-llm/dataset-manager -> /chat-with-llm`
 
-### 9. 文档类型管理前端页面
+### 6. 首页、菜单、最小可见路由与真实 RBAC 路由已补齐
 
-**文件**：
-- `app/api/document-types/document-types.ts` — 重写，调用新后端 `/api/document-types` + `/api/rule-sets`
-- `app/routes/document-types._index.tsx` — 列表页（编码、名称、入口模块、规则集数量、状态）
-- `app/routes/document-types.new.tsx` — 新建/编辑页（编码、名称、描述、入口模块下拉、规则集多选）
+这轮不只是 alias 修了一下，而是把“用户能否看到模块、能否从侧边栏稳定进入”的缺口补了：
+- `minimal-scope.ts` 已补 `/contract-template`、`/cross-checking`、`/document-types`
+- 后端 `rbacServiceImpl.py` 同步补最小可见路由逻辑
+- 已新增并执行首页 / 前端路由范围 seed 脚本
 
-**前端提交**：`81c5e98`, `477bcaf`
+结果：
+- `chat-with-llm`
+- `contract-template`
+- `cross-checking`
+- `document-types`
 
-### 10. 文档类型路由注册
+这些模块不再只靠历史残留路由“碰运气出现”，而是进入了真实的 RBAC 可见范围。
 
-**修复**：
-- `_MANAGEABLE_ROUTE_BLUEPRINTS` 添加 `/document-types` 路由
-- `_MANAGEABLE_PERMISSION_BLUEPRINTS` 添加 `doc_type:*` 权限定义
-- `_MINIMAL_VISIBLE_ROUTE_PREFIXES` 添加 `/document-types`（关键！）
-- `_PERMISSION_PREFIXES_BY_PATH` 添加 `/document-types` → `["doc_type:"]`
-- 数据库 `sys_routes` 和 `role_route` 已补 `/document-types`
-**后端提交**：`283c822`, `acdcfeb`
+### 7. Sidebar 已补路径兜底，不再只依赖 sessionStorage
+
+之前问题：
+- 直接刷新子页面或从地址栏直开，侧边栏上下文容易丢失
+
+已完成：
+- `new_doc_review/app/components/layout/Sidebar.tsx` 增加基于路径的 fallback 识别
+- 已覆盖 settings / cross-checking / chat / contract-template / contract-draft 等模块
+
+结果：
+- 刷新后仍能显示正确模块上下文
+- 用户不会因为 sessionStorage 丢失而看到错误的侧栏状态
+
+### 8. 合同管理模块命名已统一一轮
+
+统一方向：
+- 模块层叫：`合同管理`
+- 子功能叫：`模板搜索`、`模板列表`
+
+已覆盖：
+- 路由 seed
+- 最小路由 scope
+- 页面标题与描述
+- 侧边栏模块名
+
+说明：
+- 这次统一的是“首页入口 / 侧边栏 / 页面标题”的基础口径
+- 仍需继续检查细碎页面文案，避免出现“合同模板 / 合同管理 / 模板列表”混用过多
+
+### 9. 规则集可用性问题已定位到真实规则文件并修复
+
+发现的问题：
+- `借款合同` 的规则集显示“可用规则数 0”
+- 根因不是前端，而是 MinIO 上真实规则文件 DSL 非法
+
+已修复：
+- `rules/contract_loan/rules.yaml`
+- `new_doc_review/mock-data/leaudit-rules/packs/yc/contract_loan/rules.yaml`
+- 同步替换了 MinIO 对象并保留备份
+
+结果：
+- `contract.loan.general` 的 `usableRuleCount` 已恢复为 `10`
+
+### 10. 评查点分组与评查点主数据已进入“新接口包旧数据”的过渡形态
+
+这是当前系统最容易混乱的部分，结论要写清楚：
+
+- 前端页面与后端接口层，正在往新系统接口收口
+- 但评查点分组 / 评查点主数据的正式新库模型还没有完全替代旧数据
+- 所以这部分当前采用的是：**新接口 + 老库存量数据** 的过渡方案
+
+已补接口：
+- `GET /api/v3/evaluation-point-groups/by-document-types`
+- `GET /api/v3/evaluation-point-groups/{id}/children`
+- `GET /api/v3/evaluation-points`
+- `GET /api/v3/evaluation-points/{id}`
+- `POST /api/v3/evaluation-points`
+- `PUT /api/v3/evaluation-points/{id}`
+- `DELETE /api/v3/evaluation-points/{id}`
+- `GET /api/v3/evaluation-points/attribute-types`
+
+当前业务解释：
+- 一级分组：业务大类根节点
+- 二级分组：实际挂评查点、挂规则集的子类型节点
+- 文档类型绑定的是一级分组范围
+- 业务页面实际使用时，再展开到对应二级分组与规则
+
+### 11. 规则组迁移方案文档与脚本已经补齐
+
+已补充：
+- `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`
+
+说明：
+- 这部分还属于“迁移方案与执行准备已就绪”
+- 是否在正式库落地，需要按检查清单逐步执行
+
+### 12. 合同上传失败原因已开始朝前端可读化方向收口
+
+当前已明确的真实报错语义包括：
+- 当前文档类型未绑定可用规则数
+- 入口模块配置异常
+- 某规则集不可运行 / 规则文件异常
+
+说明：
+- 这块产品表达要统一成“可用规则数”，不要再出现“可用版本”旧说法
+- 页面上还需要继续把这些错误稳定映射成用户可理解提示
 
 ---
 
-## 二、关键代码位置速查
+## 三、当前业务逻辑口径
+
+### 1. 入口模块、文档类型、规则组、规则集之间的关系
+
+当前建议口径：
+
+1. 入口模块：业务入口容器，例如合同、卷宗、后续新增模块
+2. 文档类型：属于某个入口模块下的具体业务类型
+3. 一级分组：该文档类型所属的评查业务大类
+4. 二级分组：该业务大类下的实际子类型
+5. 规则集：挂在二级分组下的具体可执行规则包
+
+也就是：
+
+`入口模块 -> 文档类型 -> 一级分组 -> 二级分组 -> 规则集 -> 上传抽取评查`
+
+### 2. 为什么规则集挂在二级分组下
+
+原因不是硬编码，而是为了和老系统评查实际执行逻辑对齐：
+- 一级分组负责定义“这类文档能进入哪棵规则树”
+- 二级分组才是实际选择具体规则配置的位置
+- 上传或评查运行时，最终命中的也是子类型级别的规则集
+
+### 3. 为什么不能继续新增 PostgREST 依赖
+
+因为现在最容易出问题的地方，几乎都和它有关：
+- 路径找不到
+- 结构和现有后端不一致
+- 权限口径分裂
+- 老字段命名污染当前页面文案
+
+所以现在的原则已经很明确：
+- 已经有新后端接口的页面，不再回退到 PostgREST
+- 还没替换完的地方，只做过渡，不扩散
+
+---
+
+## 四、关键代码位置速查
 
 ### 后端
 
-| 功能 | 文件 |
+| 位置 | 作用 |
 |------|------|
-| 异常处理 | `fastapi_admin/app.py:67-76` |
-| 权限检查 | `rbacAdminServiceImpl.py:571-606` (`_assertPermission`) |
-| 用户上下文 | `rbacAdminServiceImpl.py:608-620` (`_getCurrentUserContext`) |
-| 文档上传 | `documentServiceImpl.py:44-246` (`Upload`) |
-| 文档列表 | `documentServiceImpl.py:248-443` (`ListDocuments`) |
-| 文档类型 CRUD | `documentServiceImpl.py:477-560` |
-| 文档类型列表 | `documentController.py:87-130` |
-| 队列状态 | `documentController.py:135-180` |
-| 路由可见白名单 | `rbacServiceImpl.py:21-29` (`_MINIMAL_VISIBLE_ROUTE_PREFIXES`) |
-| 权限前缀映射 | `rbacServiceImpl.py:539-550` (`_PERMISSION_PREFIXES_BY_PATH`) |
-| 首页地区过滤 | `homeServiceImpl.py:39` (`bypass_area`) |
-| 首页路由过滤 | `homeServiceImpl.py:91-108` |
+| `fastapi_modules/fastapi_leaudit/controllers/documentController.py` | 文档上传、列表、详情、更新、删除 |
+| `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py` | 文档主服务实现、数据隔离、版本链处理 |
+| `fastapi_modules/fastapi_leaudit/services/impl/auditServiceImpl.py` | 上传后触发评查 |
+| `fastapi_modules/fastapi_leaudit/controllers/rbacAdminController.py` | RBAC 管理接口 |
+| `fastapi_modules/fastapi_leaudit/services/impl/rbacAdminServiceImpl.py` | 角色、用户、权限管理逻辑 |
+| `fastapi_modules/fastapi_leaudit/services/impl/rbacServiceImpl.py` | 路由权限、最小可见路由、菜单可见性 |
+| `fastapi_modules/fastapi_leaudit/controllers/evaluationPointGroupController.py` | 评查点分组 v3 接口 |
+| `fastapi_modules/fastapi_leaudit/services/impl/evaluationPointGroupServiceImpl.py` | 分组树、按文档类型反查分组 |
+| `fastapi_modules/fastapi_leaudit/controllers/evaluationPointController.py` | 评查点主数据 v3 接口 |
+| `fastapi_modules/fastapi_leaudit/services/impl/evaluationPointServiceImpl.py` | 评查点列表/详情/增删改 |
+| `fastapi_modules/fastapi_leaudit/services/impl/ruleServiceImpl.py` | 规则集列表、可用规则数、规则文件校验 |
 
 ### 前端
 
-| 功能 | 文件 |
+| 位置 | 作用 |
 |------|------|
-| 上传 API | `app/api/files/files-upload.ts` |
-| 文档类型 API | `app/api/document-types/document-types.ts` |
-| 上传页面 | `app/routes/files.upload.tsx` |
-| 文档类型列表 | `app/routes/document-types._index.tsx` |
-| 文档类型编辑 | `app/routes/document-types.new.tsx` |
-| 403 拦截器 | `app/api/axios-client.ts:183-190` |
+| `new_doc_review/app/api/files/files-upload.ts` | 上传主文件 / 附件相关前端调用 |
+| `new_doc_review/app/api/files/documents.ts` | 文档列表、详情、更新、删除 API |
+| `new_doc_review/app/api/document-types/document-types.ts` | 文档类型 CRUD 与绑定接口 |
+| `new_doc_review/app/api/evaluation_points/rules.ts` | 评查点列表、详情、按文档类型分组查询 |
+| `new_doc_review/app/api/evaluation_points/rule-groups.ts` | 评查点分组页 API |
+| `new_doc_review/app/components/layout/Sidebar.tsx` | 侧边栏模块识别与路径 fallback |
+| `new_doc_review/app/hooks/usePermission.tsx` | 路由权限判断与 alias 应用 |
+| `new_doc_review/app/utils/route-alias.shared.js` | 子页权限映射配置表 |
+| `new_doc_review/app/routes/document-types.*` | 文档类型列表 / 新建编辑页 |
+| `new_doc_review/app/routes/documents.*` | 文档列表 / 编辑页 |
+| `new_doc_review/app/routes/rule-groups*` | 评查点分组页 |
+| `new_doc_review/app/routes/rules.*` | 评查点规则列表 / 新建编辑页 |
+| `new_doc_review/app/routes/files.upload.tsx` | 上传页 |
 
-### 数据库关键表
+### 规则 / 脚本 / 文档
 
-| 表 | 用途 |
-|----|------|
-| `leaudit_document_types` | 文档类型（20 条种子数据） |
-| `leaudit_rule_type_bindings` | 文档类型→规则集绑定 |
-| `leaudit_rule_sets` | 规则集 |
-| `leaudit_documents` | 文档（含版本管理） |
-| `leaudit_document_files` | 文档文件 |
-| `role_permissions` | 角色细粒度权限 |
-| `role_route` | 角色路由授权 |
-| `sys_routes` | 系统路由定义 |
+| 位置 | 作用 |
+|------|------|
+| `rules/contract_loan/rules.yaml` | 借款合同规则集修复点 |
+| `scripts/seed_frontend_route_scope.sql` | 前端真实路由范围 seed |
+| `scripts/user_rbac_seed.sql` | RBAC 基础 seed |
+| `scripts/seed_home_entry_modules.sql` | 首页入口模块 seed |
+| `scripts/precheck_rule_group_migration.sql` | 分组迁移前检查 |
+| `scripts/migrate_rule_groups_to_business_roots.sql` | 按业务根迁移分组 |
+| `scripts/migrate_rule_groups_to_doc_type_roots.sql` | 按文档类型根迁移分组 |
+| `docs/接口/` | 当前有效接口主文档 |
 
 ---
 
-## 三、未完成 / 待做
+## 五、下一步最该做什么
 
-### 高优先级
+### P0：必须继续做
 
-1. **上传端到端验证** — 上传接口已重写但未实际测试。需在前端上传一份文件，确认 `POST /api/upload` 返回正确、文件入 MinIO、`leaudit_documents` 有记录。
+1. 合同附件上传与抽取评查链路继续收口
+   - 当前用户强调：合同附件上传是正式业务链的一部分
+   - 需要继续明确：附件追加 -> 合并上传 -> 抽取 -> 评查 的最终接口与页面反馈
 
-2. **附件上传** — `appendContractAttachments` 和 `uploadContractTemplate` 仍调用旧 API，后端无对应接口。需新增：
-   - `POST /api/documents/{id}/attachments`（fileRole=attachment）
-   - `POST /api/documents/{id}/template`（fileRole=template）
+2. 文档类型绑定页与规则组页的语义继续收口
+   - 用户已经多次反馈“看不直观”
+   - 核心不是再堆字段，而是要把“入口模块 / 文档类型 / 一级分组 / 二级分组 / 规则集”的层级展示清楚
 
-3. **文档列表字段精简** — `documents.ts` 里 `LeauditListItem → DocumentUI` 有 80 行映射代码（`mapLeauditDocToAuditStatus`、`mapProcessingStatusToFileStatus` 等）。建议逐步直接消费新后端字段名。
+3. 上传失败提示继续前端友好化
+   - 明确提示“哪个规则集不可用 / 哪个入口模块配置异常 / 当前文档类型没有可用规则数”
+   - 避免只弹统一 400/500
 
-### 中优先级
+4. 继续清理文档与代码中的旧术语
+   - `可用版本` 统一改为 `可用规则数`
+   - 避免“规则组 / 分组 / 规则集 / 评查点”混用造成误解
 
-4. **文档 CRUD 补全** — 后端缺：
-   - `DELETE /api/documents/{id}` — 软删除
-   - `PUT /api/documents/{id}` — 更新元数据（备注、测试标记）
-   - `GET /api/documents/{id}` — 文档详情
+### P1：建议继续做
 
-5. **文档类型管理页 CSS** — `document-types._index.tsx` 用了 `.data-table`、`.tag`、`.status-badge` 等类名，需要检查 `document-types_index.css` 是否包含这些样式，或改用现有组件（如 `Table`）。
+1. 评查点分组正式迁移是否执行
+   - 现在脚本和方案已具备
+   - 但正式执行前要先完成 precheck 并确认现网数据
 
-6. **前端 role-permissions 页面权限 UI** — 规则集绑定已改为 `ruleSetIds`（替代老系统的 `group_ids`），但 role-permissions 页面显示的权限分组文案可能需要更新。
+2. 文档列表页与上传页剩余 PostgREST 旁路彻底清理
+   - 已经不是主依赖，但要继续排查存量调用
 
-### 低优先级
+3. 规则组页 UI 再向老系统样式收口
+   - 用户多次强调不要大改配色
+   - 要沿用现有系统保守风格，不做“新设计感”重构
 
-7. **规则集选择器优化** — 当前新建/编辑文档类型页以 checkbox 列表展示所有规则集。规则集数量增长后需要加搜索/分组。
+### P2：后续再做
 
-8. **队列状态接口完善** — 当前 `/api/v2/system/queue/status` 只查了数据库的 `processing_status`，未接入 Celery 实时队列深度。后续可以调 Celery inspect API 补充 `pending_tasks` / `processing_tasks`。
-
-9. **后端推送** — 后端仓库无 git remote，需要配置后推送。
-
-10. **旧 PostgREST 完全清理** — 确认无其他 PostgREST 调用后移除旧 RPC 函数。
+1. 历史文档与临时脚本继续归档清理
+2. 合同管理与 AI 对话模块命名细节再统一
+3. 少量无数据导致的详情 404 页面做更友好空态提示
 
 ---
 
-## 四、当前用户/角色状态
+## 六、当前用户 / 角色 / 权限状态
 
-| 角色 | role_key | ID | 用户数 |
-|------|----------|-----|--------|
-| 系统超级管理员 | super_admin | 1 | 0 |
-| 省级管理员 | provincial_admin | 2 | 1 (id=5, username=admin, area=梅州) |
-| 地区管理员 | admin | 3 | 4 (揭阳惠来烟草, 梅州烟草, 云浮烟草, 潮州烟草) |
-| 普通用户 | common | 4 | ~200 (000... 用户) |
+当前已知关注角色：
+- `super_admin`
+- `provincial_admin`
+- `admin`
+- `common`
 
-省级管理员 (id=5) 拥有所有权限点，包括新增的 `doc_type:*`（通过 `_ensureAdminSeeds` 自动补种）。
+当前已经明确生效的权限方向：
+- RBAC 管理接口已补细粒度权限检查
+- 中文化 403 提示已打通
+- 文档相关接口已带地区 / 用户隔离
+- 前端子页权限映射已补一轮，但后续新页面仍要按 `route-alias-guidelines.md` 判断是否该进 alias
+
+---
+
+## 七、接手时不要再踩的坑
+
+1. 不要再把“评查点分组页看到的树”理解成纯前端写死结构
+   - 现在目标是后端接口给树，前端只负责展示与管理
+
+2. 不要遇到 403 就直接继续堆 alias
+   - 先判断：这是子页派生权限问题，还是后端根本没注册真实菜单路由
+
+3. 不要新增 PostgREST 依赖
+   - 当前主线是迁出，不是再混回去
+
+4. 不要把“文档类型绑定规则集”和“规则组页绑定规则集”理解成互斥逻辑
+   - 它们是不同层级的配置入口，最终都要服务同一条上传评查链路
+
+5. 不要在文档里继续留下带密码的连接信息
+
+---
+
+## 八、配套主文档
+
+- `docs/README.md`：后端 `/docs` 总导航
+- `docs/接口/README.md`：接口文档导航
+- `docs/权限与地区隔离文档导航.md`：权限主线导航
+- `docs/leaudit/README.md`：后端架构主线
+- `docs/规则编辑/README.md`：规则链路主线
+- `new_doc_review/docs/route-alias-guidelines.md`：前端子页权限映射规范