TanWenyan/leaudit-platform-backend

Fork 0

Files

T

wren 23b5445ff8 docs: add comprehensive handoff document

2026-04-30 14:31:53 +08:00

10 KiB

Raw Blame History

开发交接文档 — leaudit-platform 前后端

本会话时间：2026-04-29 ~ 2026-04-30 工作目录：/home/wren-dev/Porject/leaudit-platform/

仓库信息

项目	路径	分支	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`

后端未推送（无 remote），前端 wren 分支领先 origin 7 个提交。

数据库

项	值
Host	`nas.7bm.co:54302`
用户	`docauditai_admin`
密码	`zhfw123`
数据库	`leaudit_platform`

一、已完成的工作

1. 首页入口模块 RBAC 过滤修复

问题：内部公文 入口模块配置存在（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

2. 首页地区过滤修正

问题：provincial_admin 跳过了入口模块的 areas 地区过滤，导致取消地区后仍可见。
修复：homeServiceImpl.py 的 bypass_area 逻辑从包含 provincial_admin 改为只包含 super_admin。
后端提交：c16bb84

3. 细粒度权限执行

问题：后端 _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

4. 统一异常处理

问题：LeauditException 没有注册 FastAPI exception handler，所有业务异常都变成 500。
修复：app.py 新增 @app.exception_handler(BusinessException)，返回带状态码的 JSON。
后端提交：292b187

5. 403 错误信息中文化

问题：403 返回 "缺少权限: rbac:roles:delete" 显示的是 permission key。
修复：_assertPermission 查 permissions 表的 display_name，改为显示 "缺少「删除角色」权限"。
后端提交：ab31c80

前端：axios 拦截器不再硬编码 "无权限"，改为透传后端的具体消息。frontendJWT 改为 canEdit，包含 provincial_admin + admin 两个角色。
前端提交：185f55c, e2ae791

6. 上传页 PostgREST 依赖替换

问题：上传页 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

前端：

getDocumentTypes() → GET /api/document-types
getTodayDocuments() → GET /api/documents/list?userId=&dateFrom=
getQueueStatus() → 404 时返回空状态不报错 前端提交：dd249cc

7. 上传接口对齐

问题：前端上传 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

8. 文档类型 CRUD 后端

新增端点：

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）

关键实现：

DocumentTypeItemVO 新增 description, entryModuleId, isEnabled, ruleSetIds
DocumentTypeCreateDTO / DocumentTypeUpdateDTO 支持 ruleSetIds 传入
创建/更新时自动调用 _syncRuleBindings() 全量替换 leaudit_rule_type_bindings
软删除级联清理 bindings 后端提交：52c2bed

9. 文档类型管理前端页面

文件：

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 — 新建/编辑页（编码、名称、描述、入口模块下拉、规则集多选）

前端提交：81c5e98, 477bcaf

10. 文档类型路由注册

修复：

_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

二、关键代码位置速查

后端

功能	文件
异常处理	`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`

前端

功能	文件
上传 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`

数据库关键表

表	用途
`leaudit_document_types`	文档类型（20 条种子数据）
`leaudit_rule_type_bindings`	文档类型→规则集绑定
`leaudit_rule_sets`	规则集
`leaudit_documents`	文档（含版本管理）
`leaudit_document_files`	文档文件
`role_permissions`	角色细粒度权限
`role_route`	角色路由授权
`sys_routes`	系统路由定义

三、未完成 / 待做

高优先级

上传端到端验证 — 上传接口已重写但未实际测试。需在前端上传一份文件，确认 POST /api/upload 返回正确、文件入 MinIO、leaudit_documents 有记录。
附件上传 — appendContractAttachments 和 uploadContractTemplate 仍调用旧 API，后端无对应接口。需新增：
- POST /api/documents/{id}/attachments（fileRole=attachment）
- POST /api/documents/{id}/template（fileRole=template）
文档列表字段精简 — documents.ts 里 LeauditListItem → DocumentUI 有 80 行映射代码（mapLeauditDocToAuditStatus、mapProcessingStatusToFileStatus 等）。建议逐步直接消费新后端字段名。

中优先级

文档 CRUD 补全 — 后端缺：
- DELETE /api/documents/{id} — 软删除
- PUT /api/documents/{id} — 更新元数据（备注、测试标记）
- GET /api/documents/{id} — 文档详情
文档类型管理页 CSS — document-types._index.tsx 用了 .data-table、.tag、.status-badge 等类名，需要检查 document-types_index.css 是否包含这些样式，或改用现有组件（如 Table）。
前端 role-permissions 页面权限 UI — 规则集绑定已改为 ruleSetIds（替代老系统的 group_ids），但 role-permissions 页面显示的权限分组文案可能需要更新。

低优先级

规则集选择器优化 — 当前新建/编辑文档类型页以 checkbox 列表展示所有规则集。规则集数量增长后需要加搜索/分组。
队列状态接口完善 — 当前 /api/v2/system/queue/status 只查了数据库的 processing_status，未接入 Celery 实时队列深度。后续可以调 Celery inspect API 补充 pending_tasks / processing_tasks。
后端推送 — 后端仓库无 git remote，需要配置后推送。
旧 PostgREST 完全清理 — 确认无其他 PostgREST 调用后移除旧 RPC 函数。

四、当前用户/角色状态

角色	role_key	ID	用户数
系统超级管理员	super_admin	1	0
省级管理员	provincial_admin	2	1 (id=5, username=admin, area=梅州)
地区管理员	admin	3	4 (揭阳惠来烟草, 梅州烟草, 云浮烟草, 潮州烟草)
普通用户	common	4	~200 (000... 用户)

省级管理员 (id=5) 拥有所有权限点，包括新增的 doc_type:*（通过 _ensureAdminSeeds 自动补种）。

10 KiB Raw Blame History Unescape Escape