From 23b5445ff825fd4200e4f85b4c2ceebdac959f6d Mon Sep 17 00:00:00 2001 From: wren <“porlong@qq.com”> Date: Thu, 30 Apr 2026 14:31:53 +0800 Subject: [PATCH] docs: add comprehensive handoff document --- docs/HANDOFF.md | 231 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 docs/HANDOFF.md diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md new file mode 100644 index 0000000..a1a7fcc --- /dev/null +++ b/docs/HANDOFF.md @@ -0,0 +1,231 @@ +# 开发交接文档 — 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` | +| 密码 | `zhfw*123*` | +| 数据库 | `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` | 系统路由定义 | + +--- + +## 三、未完成 / 待做 + +### 高优先级 + +1. **上传端到端验证** — 上传接口已重写但未实际测试。需在前端上传一份文件，确认 `POST /api/upload` 返回正确、文件入 MinIO、`leaudit_documents` 有记录。 + +2. **附件上传** — `appendContractAttachments` 和 `uploadContractTemplate` 仍调用旧 API，后端无对应接口。需新增： + - `POST /api/documents/{id}/attachments`（fileRole=attachment） + - `POST /api/documents/{id}/template`（fileRole=template） + +3. **文档列表字段精简** — `documents.ts` 里 `LeauditListItem → DocumentUI` 有 80 行映射代码（`mapLeauditDocToAuditStatus`、`mapProcessingStatusToFileStatus` 等）。建议逐步直接消费新后端字段名。 + +### 中优先级 + +4. **文档 CRUD 补全** — 后端缺： + - `DELETE /api/documents/{id}` — 软删除 + - `PUT /api/documents/{id}` — 更新元数据（备注、测试标记） + - `GET /api/documents/{id}` — 文档详情 + +5. **文档类型管理页 CSS** — `document-types._index.tsx` 用了 `.data-table`、`.tag`、`.status-badge` 等类名，需要检查 `document-types_index.css` 是否包含这些样式，或改用现有组件（如 `Table`）。 + +6. **前端 role-permissions 页面权限 UI** — 规则集绑定已改为 `ruleSetIds`（替代老系统的 `group_ids`），但 role-permissions 页面显示的权限分组文案可能需要更新。 + +### 低优先级 + +7. **规则集选择器优化** — 当前新建/编辑文档类型页以 checkbox 列表展示所有规则集。规则集数量增长后需要加搜索/分组。 + +8. **队列状态接口完善** — 当前 `/api/v2/system/queue/status` 只查了数据库的 `processing_status`，未接入 Celery 实时队列深度。后续可以调 Celery inspect API 补充 `pending_tasks` / `processing_tasks`。 + +9. **后端推送** — 后端仓库无 git remote，需要配置后推送。 + +10. **旧 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` 自动补种）。