leaudit-platform-backend/docs/HANDOFF.md

# 开发交接文档 — 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` 自动补种）。