docs: add comprehensive handoff document

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` 自动补种）。