TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f8eb2dc817b550e931b3219fbe5222f9288634b1
leaudit-platform-backend/docs/HANDOFF.md
T

16 KiB
Raw Blame History

开发交接文档 — 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/接口/README.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/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_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/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. 合同附件上传与抽取评查链路继续收口

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

  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/接口/README.md：接口文档导航
  • docs/权限与地区隔离文档导航.md：权限主线导航
  • docs/leaudit/README.md：后端架构主线
  • docs/规则编辑/README.md：规则链路主线
  • new_doc_review/docs/route-alias-guidelines.md：前端子页权限映射规范
Reference in New Issue View Git Blame Copy Permalink