wren
414 lines
16 KiB
Markdown
414 lines
16 KiB
Markdown
# 开发交接文档 — 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. 合同上传失败原因已开始朝前端可读化方向收口
|
||
|
||
当前已明确的真实报错语义包括：
|
||
- 当前文档类型未绑定可用规则数
|
||
- 入口模块配置异常
|
||
- 某规则集不可运行 / 规则文件异常
|
||
|
||
说明：
|
||
- 这块产品表达要统一成“可用规则数”，不要再出现“可用版本”旧说法
|
||
- 页面上还需要继续把这些错误稳定映射成用户可理解提示
|
||
|
||
---
|
||
|
||
## 三、当前业务逻辑口径
|
||
|
||
### 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` | 规则集列表、可用规则数、规则文件校验 |
|
||
|
||
### 前端
|
||
|
||
| 位置 | 作用 |
|
||
|------|------|
|
||
| `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/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/接口/` | 当前有效接口主文档 |
|
||
|
||
---
|
||
|
||
## 五、下一步最该做什么
|
||
|
||
### P0：必须继续做
|
||
|
||
1. 合同附件上传与抽取评查链路继续收口
|
||
- 当前用户强调：合同附件上传是正式业务链的一部分
|
||
- 需要继续明确：附件追加 -> 合并上传 -> 抽取 -> 评查 的最终接口与页面反馈
|
||
|
||
2. 文档类型绑定页与规则组页的语义继续收口
|
||
- 用户已经多次反馈“看不直观”
|
||
- 核心不是再堆字段，而是要把“入口模块 / 文档类型 / 一级分组 / 二级分组 / 规则集”的层级展示清楚
|
||
|
||
3. 上传失败提示继续前端友好化
|
||
- 明确提示“哪个规则集不可用 / 哪个入口模块配置异常 / 当前文档类型没有可用规则数”
|
||
- 避免只弹统一 400/500
|
||
|
||
4. 继续清理文档与代码中的旧术语
|
||
- `可用版本` 统一改为 `可用规则数`
|
||
- 避免“规则组 / 分组 / 规则集 / 评查点”混用造成误解
|
||
|
||
### 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/leaudit/README.md`：后端架构主线
|
||
- `docs/规则编辑/README.md`：规则链路主线
|
||
- `new_doc_review/docs/route-alias-guidelines.md`：前端子页权限映射规范
|