leaudit-platform-backend/docs/HANDOFF.md

# 开发交接文档 — leaudit-platform

> 本轮整理时间：2026-04-29 ~ 2026-05-04
> 工作目录：`/home/wren-dev/Porject/leaudit-platform`
> 当前主线：前端 `new_doc_review` + 后端 `fastapi_modules/fastapi_leaudit`

---

## 仓库信息

| 项目 | 路径 | 分支 | Remote |
|------|------|------|--------|
| 后端 | `/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` |

## 数据库 / 环境

| 项目 | 当前值 |
|------|--------|
| 后端 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` 侧历史表，不是让前端继续直接走旧接口

---

## 一、先看结论

当前项目状态可以直接概括成 4 句话：

1. 首页入口、菜单、RBAC、文档类型、规则组、文档上传这条主链路已经基本串起来了。
2. 当前主要问题不是“完全不能用”，而是“新旧模型并存，部分语义还没完全收口”。
3. 当前正确方向很明确：前端尽量统一走新后端接口，PostgREST 只保留存量过渡，不再新增依赖。
4. 还要继续收口的核心是：上传后评查链路、文档类型到规则集的关系表达、以及旧字段旧文案清理。

### 当前正式阅读顺序

1. `docs/HANDOFF.md`
2. `docs/迁移与兼容/旧接口文档导航.md`
3. `docs/权限与地区隔离/权限与地区隔离文档导航.md`
4. `docs/leaudit/README.md`
5. `docs/规则编辑/README.md`

---

## 二、本轮已完成的关键工作

### 1. 文档列表详情 / 更新 / 删除已从 PostgREST 迁到新后端接口

后端已补接口：
- `GET /api/documents/{id}`
- `PUT /api/documents/{id}`
- `DELETE /api/documents/{id}`

实现口径：
- 文档列表、详情、更新、删除都围绕 `leaudit_documents` / `leaudit_document_files`
- 删除为软删除，并自动维护最新版本标记
- 更新允许维护 `documentNumber`、`remark`、`isTestDocument`、`auditStatus` 等元数据

对应文档：
- `docs/文档管理/文档上传与列表接口分析.md`

### 2. 文档数据隔离已补到后端强约束

当前规则：
- `super_admin` / `provincial_admin`：看全量
- `admin`：只能看本地市 `region = user.area`
- `common`：只能看自己上传的文档

已覆盖范围：
- 文档列表
- 文档详情
- 文档更新
- 文档删除

这意味着“每个地市管理员只能改各自数据”的要求，已经不只是前端过滤，而是后端接口层强制执行。

### 3. 上传页主依赖已改为新接口

已完成：
- `GET /api/document-types`
- `GET /api/documents/list` 支持 `userId`、日期范围等过滤
- `GET /api/v2/system/queue/status`
- `POST /api/upload` 前端已改为扁平 `multipart/form-data`

当前口径：
- 主文件上传已经走新后端
- 合同附件上传仍然是要继续收口的重点场景，因为它与规则抽取、评查触发紧密耦合

### 4. 文档类型 CRUD 与绑定能力已切到新后端

后端已支持：
- `GET /api/document-types`
- `GET /api/document-types/{id}`
- `POST /api/document-types`
- `PUT /api/document-types/{id}`
- `DELETE /api/document-types/{id}`

当前文档类型支持维护：
- 编码 / 名称 / 描述
- 入口模块绑定
- 启停状态
- 规则集绑定（`ruleSetIds`）

说明：
- 这部分是“文档类型绑定入口模块”和“文档类型绑定规则集”的基础设施
- 目前页面 UI 仍在继续按老系统风格收口，但主接口已具备

### 5. 文档类型子页权限问题已收口一轮

已补的关键修复：
- `route-alias` 从零散判断升级为配置表
- 给新建/编辑/详情/结果页补齐父列表权限映射
- 新增约束文档，明确：什么时候该加 alias，什么时候该补真实菜单路由
- 已增加独立测试脚本，`npm run test:route-aliases` 可直接回归

关键文件：
- `new_doc_review/app/utils/route-alias.shared.js`
- `new_doc_review/docs/route-alias-guidelines.md`

已覆盖的典型路径：
- `/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`

### 6. 首页、菜单、最小可见路由与真实 RBAC 路由已补齐

这轮不只是 alias 修了一下，而是把“用户能否看到模块、能否从侧边栏稳定进入”的缺口补了：
- `minimal-scope.ts` 已补 `/contract-template`、`/cross-checking`、`/document-types`
- 后端 `rbacServiceImpl.py` 同步补最小可见路由逻辑
- 已新增并执行首页 / 前端路由范围 seed 脚本

结果：
- `chat-with-llm`
- `contract-template`
- `cross-checking`
- `document-types`

这些模块不再只靠历史残留路由“碰运气出现”，而是进入了真实的 RBAC 可见范围。

### 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/创建sql/precheck_rule_group_migration.sql`
- `scripts/创建sql/migrate_rule_groups_to_business_roots.sql`
- `scripts/创建sql/migrate_rule_groups_to_doc_type_roots.sql`
- `docs/评查点分组/评查点分组迁移执行前检查清单.md`

说明：
- 这部分还属于“迁移方案与执行准备已就绪”
- 是否在正式库落地，需要按检查清单逐步执行

### 12. 合同上传失败原因已开始朝前端可读化方向收口

当前已明确的真实报错语义包括：
- 当前文档类型未绑定可用规则数
- 入口模块配置异常
- 某规则集不可运行 / 规则文件异常

说明：
- 这块产品表达要统一成“可用规则数”，不要再出现“可用版本”旧说法
- 页面上还需要继续把这些错误稳定映射成用户可理解提示

### 13. 系统使用统计口径已经收口到“两份主文档 + 一期三视角”

当前这块不要再按“需求 / 表设计 / 接口设计 / 任务拆解”四散维护，已经统一收口为两份主文档：

- `docs/系统使用统计/系统使用统计最终版.md`
- `docs/系统使用统计/系统使用统计实施版.md`

当前正式口径：

- 功能定位是“使用统计”，不是“全量行为审计”
- 一期只统计：登录、上传、评查
- 一期前端页面只做 3 个视角：
  - 总览
  - 按部门
  - 按地区
- 页面入口放在“系统设置”
- 地区管理员只能看本地区数据，必须由后端做地区隔离

当前实现状态：

- 后端统计接口、登录补数、评查触发人补数、RBAC 与 SQL 已落地
- SQL 已统一整理到 `scripts/创建sql/`
- 上线与验收入口文档统一看：
  - `scripts/创建sql/README.md`
  - `docs/系统使用统计/系统使用统计实施版.md`

---

## 三、当前业务逻辑口径

### 1. 入口模块、文档类型、规则组、规则集之间的关系

当前建议口径：

1. 入口模块：业务入口容器，例如合同、卷宗、后续新增模块
2. 文档类型：属于某个入口模块下的具体业务类型
3. 一级分组：该文档类型所属的评查业务大类
4. 二级分组：该业务大类下的实际子类型
5. 规则集：挂在二级分组下的具体可执行规则包

也就是：

`入口模块 -> 文档类型 -> 一级分组 -> 二级分组 -> 规则集 -> 上传抽取评查`

### 2. 为什么规则集挂在二级分组下

原因不是硬编码，而是为了和老系统评查实际执行逻辑对齐：
- 一级分组负责定义“这类文档能进入哪棵规则树”
- 二级分组才是实际选择具体规则配置的位置
- 上传或评查运行时，最终命中的也是子类型级别的规则集

### 3. 为什么不能继续新增 PostgREST 依赖

因为现在最容易出问题的地方，几乎都和它有关：
- 路径找不到
- 结构和现有后端不一致
- 权限口径分裂
- 老字段命名污染当前页面文案

所以现在的原则已经很明确：
- 已经有新后端接口的页面，不再回退到 PostgREST
- 还没替换完的地方，只做过渡，不扩散

---

## 四、关键代码位置速查

### 后端

| 位置 | 作用 |
|------|------|
| `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` | 规则集列表、可用规则数、规则文件校验 |
| `fastapi_modules/fastapi_leaudit/controllers/usageStatsController.py` | 系统使用统计接口 |
| `fastapi_modules/fastapi_leaudit/services/impl/usageStatsServiceImpl.py` | 登录统计写入、总览/部门/地区统计查询 |

### 前端

| 位置 | 作用 |
|------|------|
| `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` | 上传页 |

### 规则 / 脚本 / 文档

| 位置 | 作用 |
|------|------|
| `rules/contract_loan/rules.yaml` | 借款合同规则集修复点 |
| `scripts/创建sql/README.md` | SQL 总导航、执行顺序、上线手册入口 |
| `scripts/创建sql/seed_frontend_route_scope.sql` | 前端真实路由范围 seed |
| `scripts/创建sql/user_rbac_seed.sql` | RBAC 基础 seed |
| `scripts/创建sql/seed_home_entry_modules.sql` | 首页入口模块 seed |
| `scripts/创建sql/precheck_rule_group_migration.sql` | 分组迁移前检查 |
| `scripts/创建sql/migrate_rule_groups_to_business_roots.sql` | 按业务根迁移分组 |
| `scripts/创建sql/migrate_rule_groups_to_doc_type_roots.sql` | 按文档类型根迁移分组 |
| `docs/README.md` | 当前模块化文档总导航 |

---

## 五、下一步最该做什么

### P0：必须继续做

1. 合同附件上传与抽取评查链路继续收口
   - 当前用户强调：合同附件上传是正式业务链的一部分
   - 需要继续明确：附件追加 -> 合并上传 -> 抽取 -> 评查 的最终接口与页面反馈

2. 文档类型绑定页与规则组页的语义继续收口
   - 用户已经多次反馈“看不直观”
   - 核心不是再堆字段，而是要把“入口模块 / 文档类型 / 一级分组 / 二级分组 / 规则集”的层级展示清楚

3. 上传失败提示继续前端友好化
   - 明确提示“哪个规则集不可用 / 哪个入口模块配置异常 / 当前文档类型没有可用规则数”
   - 避免只弹统一 400/500

4. 系统使用统计前端继续按“一期三视角”联调
   - 只优先保证“总览 + 按部门 + 按地区”整体可用
   - 先不要继续扩展复杂驾驶舱、全量明细审计、额外统计口径页面
   - 所有实现口径统一以 `docs/系统使用统计/系统使用统计最终版.md` 为准

5. 继续清理文档与代码中的旧术语
   - `可用版本` 统一改为 `可用规则数`
   - 避免“规则组 / 分组 / 规则集 / 评查点”混用造成误解

### P1：建议继续做

1. 评查点分组正式迁移是否执行
   - 现在脚本和方案已具备
   - 但正式执行前要先完成 precheck 并确认现网数据

2. 文档列表页与上传页剩余 PostgREST 旁路彻底清理
   - 已经不是主依赖，但要继续排查存量调用

3. 规则组页 UI 再向老系统样式收口
   - 用户多次强调不要大改配色
   - 要沿用现有系统保守风格，不做“新设计感”重构

### P2：后续再做

1. 历史文档与临时脚本继续归档清理
2. 合同管理与 AI 对话模块命名细节再统一
3. 少量无数据导致的详情 404 页面做更友好空态提示

---

## 六、当前用户 / 角色 / 权限状态

当前已知关注角色：
- `super_admin`
- `provincial_admin`
- `admin`
- `common`

当前已经明确生效的权限方向：
- RBAC 管理接口已补细粒度权限检查
- 中文化 403 提示已打通
- 文档相关接口已带地区 / 用户隔离
- 前端子页权限映射已补一轮，但后续新页面仍要按 `route-alias-guidelines.md` 判断是否该进 alias

---

## 七、接手时不要再踩的坑

1. 不要再把“评查点分组页看到的树”理解成纯前端写死结构
   - 现在目标是后端接口给树，前端只负责展示与管理

2. 不要遇到 403 就直接继续堆 alias
   - 先判断：这是子页派生权限问题，还是后端根本没注册真实菜单路由

3. 不要新增 PostgREST 依赖
   - 当前主线是迁出，不是再混回去

4. 不要把“文档类型绑定规则集”和“规则组页绑定规则集”理解成互斥逻辑
   - 它们是不同层级的配置入口，最终都要服务同一条上传评查链路

5. 不要在文档里继续留下带密码的连接信息

---

## 八、配套主文档

- `docs/README.md`：后端 `/docs` 总导航
- `docs/迁移与兼容/旧接口文档导航.md`：接口文档导航
- `docs/权限与地区隔离/权限与地区隔离文档导航.md`：权限主线导航
- `docs/系统使用统计/系统使用统计最终版.md`：系统使用统计业务口径
- `docs/系统使用统计/系统使用统计实施版.md`：系统使用统计实施与上线口径
- `docs/leaudit/README.md`：后端架构主线
- `docs/规则编辑/README.md`：规则链路主线
- `new_doc_review/docs/route-alias-guidelines.md`：前端子页权限映射规范