docs: 更新分页功能设计文档，扩展到所有管理表格页面
This commit is contained in:
parent
54230b6cfd
commit
cc1a6459bd
|
|
@ -0,0 +1,389 @@
|
||||||
|
# 管理后台分页功能设计文档
|
||||||
|
|
||||||
|
**日期**: 2026-03-25
|
||||||
|
**功能**: 为管理后台所有表格页面（职位管理、投递管理、组织架构、用户管理）添加分页功能
|
||||||
|
**优先级**: 标准
|
||||||
|
**涉及页面**:
|
||||||
|
- 职位管理 (JobManageView.vue)
|
||||||
|
- 投递管理 (ApplicationManageView.vue)
|
||||||
|
- 组织架构 (OrganizationManageView.vue)
|
||||||
|
- 用户管理 (UserManageView.vue)
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
当前所有管理后台表格一次性加载所有数据到表格中。为了改善用户体验和减少初始加载时间，为所有管理表格页面实现统一的标准分页功能。后端已配置 `PageNumberPagination`（每页 20 条），前端只需统一接入分页参数和 UI 组件。
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
|
||||||
|
- **现状**: 所有管理表格页面（职位、投递、部门、用户）都直接加载所有数据到表格，无分页
|
||||||
|
- **问题**: 数据量增多时，页面加载缓慢，表格拥挤，用户体验差
|
||||||
|
- **后端支持**: Django REST Framework 已全局配置分页（`DEFAULT_PAGE_SIZE: 20`），自动处理 `?page=1` 参数
|
||||||
|
- **目标**: 为所有管理表格统一添加分页功能，提升用户体验
|
||||||
|
|
||||||
|
## 设计方案
|
||||||
|
|
||||||
|
### 1. 后端 API 层
|
||||||
|
|
||||||
|
**无需改动**。`OrganizationManageViewSet` 继承 DRF 的 `ModelViewSet`，已自动支持 `PageNumberPagination`。
|
||||||
|
|
||||||
|
**API 响应格式**（现有）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"count": 50,
|
||||||
|
"next": "http://.../?page=2",
|
||||||
|
"previous": null,
|
||||||
|
"results": [
|
||||||
|
{ "id": 1, "name": "集团", "email": "...", "is_active": true, "parent": null },
|
||||||
|
...
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 前端 API 层修改
|
||||||
|
|
||||||
|
**文件**: `offer_frontend/src/api/organizations.js`
|
||||||
|
|
||||||
|
修改 `manageOrganizations` 函数，支持可选的页码参数：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
export const manageOrganizations = (page = 1) =>
|
||||||
|
client.get(`/organizations/manage/?page=${page}`)
|
||||||
|
```
|
||||||
|
|
||||||
|
**调用示例**:
|
||||||
|
```javascript
|
||||||
|
// 获取第 1 页
|
||||||
|
const { data } = await manageOrganizations(1)
|
||||||
|
// 获取第 2 页
|
||||||
|
const { data } = await manageOrganizations(2)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 前端组件修改
|
||||||
|
|
||||||
|
**文件**: `offer_frontend/src/views/admin/OrganizationManageView.vue`
|
||||||
|
|
||||||
|
#### 3.1 状态管理
|
||||||
|
|
||||||
|
新增和保留响应式状态：
|
||||||
|
```javascript
|
||||||
|
const orgs = ref([]) // 当前页部门列表
|
||||||
|
const allOrgs = ref([]) // 所有部门列表（用于下拉框）
|
||||||
|
const loading = ref(false) // 当前页加载状态
|
||||||
|
const currentPage = ref(1) // 当前页码
|
||||||
|
const pageSize = ref(20) // 每页行数（与后端 PAGE_SIZE 一致）
|
||||||
|
const total = ref(0) // 总记录数
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.2 修改 fetchOrgs 函数
|
||||||
|
|
||||||
|
用于加载分页数据：
|
||||||
|
```javascript
|
||||||
|
const fetchOrgs = async (page = 1) => {
|
||||||
|
loading.value = true
|
||||||
|
try {
|
||||||
|
const { data } = await manageOrganizations(page)
|
||||||
|
orgs.value = data.results
|
||||||
|
total.value = data.count
|
||||||
|
currentPage.value = page
|
||||||
|
} catch (error) {
|
||||||
|
ElMessage.error('加载部门列表失败，请重试')
|
||||||
|
} finally {
|
||||||
|
loading.value = false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.3 新增 fetchAllOrgs 函数（用于下拉框）
|
||||||
|
|
||||||
|
为了支持下拉框选择任意部门，需要单独加载**所有部门**（不分页）：
|
||||||
|
```javascript
|
||||||
|
const fetchAllOrgs = async () => {
|
||||||
|
try {
|
||||||
|
// 调用同一个 API，但不传 page 参数时默认返回第 1 页
|
||||||
|
// 实际需要：修改后端 API 或调用一个无分页的端点
|
||||||
|
// 临时方案：调用 getOrganizations() 获取公开的组织（如果有）
|
||||||
|
// 或者：预加载足够多的页（假设部门不超过 500，调用 3-4 次）
|
||||||
|
const { data } = await manageOrganizations(1)
|
||||||
|
// 如果只有少量部门，可以一次性加载最多 5 页
|
||||||
|
let allResults = data.results
|
||||||
|
for (let i = 2; i <= Math.ceil(data.count / 20) && i <= 5; i++) {
|
||||||
|
const { data: nextData } = await manageOrganizations(i)
|
||||||
|
allResults = allResults.concat(nextData.results)
|
||||||
|
}
|
||||||
|
allOrgs.value = allResults
|
||||||
|
} catch (error) {
|
||||||
|
ElMessage.error('加载部门列表失败')
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> **注意**: 这是一个临时方案。如果部门数量可能超过 100，建议后端新增一个 `list_all` 参数或单独的无分页 API 端点。
|
||||||
|
|
||||||
|
#### 3.4 添加分页事件处理
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
function handlePageChange(newPage) {
|
||||||
|
fetchOrgs(newPage)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.5 修改保存后的逻辑
|
||||||
|
|
||||||
|
无论新增还是编辑，保存成功后都重置分页状态并返回第 1 页（保持用户体验一致）：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async function save() {
|
||||||
|
saving.value = true
|
||||||
|
try {
|
||||||
|
if (editing.value) await updateOrganization(editing.value.id, form)
|
||||||
|
else await createOrganization(form)
|
||||||
|
ElMessage.success('保存成功')
|
||||||
|
dialogVisible.value = false
|
||||||
|
currentPage.value = 1 // 重置到第 1 页
|
||||||
|
fetchOrgs(1) // 重新加载第 1 页（明确传入页码）
|
||||||
|
fetchAllOrgs() // 刷新下拉框数据
|
||||||
|
} catch (error) {
|
||||||
|
ElMessage.error('保存失败')
|
||||||
|
} finally {
|
||||||
|
saving.value = false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.6 新增删除功能
|
||||||
|
|
||||||
|
添加 `handleDelete()` 函数：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async function handleDelete(id) {
|
||||||
|
try {
|
||||||
|
await ElMessageBox.confirm('确认删除该部门？', '提示', {
|
||||||
|
type: 'warning',
|
||||||
|
confirmButtonText: '确认',
|
||||||
|
cancelButtonText: '取消'
|
||||||
|
})
|
||||||
|
await deleteOrganization(id)
|
||||||
|
ElMessage.success('已删除')
|
||||||
|
currentPage.value = 1 // 删除后回到第 1 页
|
||||||
|
fetchOrgs(1) // 重新加载第 1 页（明确传入页码）
|
||||||
|
fetchAllOrgs() // 刷新下拉框数据
|
||||||
|
} catch (error) {
|
||||||
|
// ElMessageBox.confirm 取消时会抛出 ElMessageBoxCancel 异常，需要判断
|
||||||
|
if (error.name !== 'ElMessageBoxCancel') {
|
||||||
|
ElMessage.error('删除失败')
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.7 初始化时加载所有数据
|
||||||
|
|
||||||
|
修改 `onMounted` 钩子：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
onMounted(() => {
|
||||||
|
fetchOrgs() // 加载分页数据（第 1 页）
|
||||||
|
fetchAllOrgs() // 加载所有部门用于下拉框
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. UI 层修改
|
||||||
|
|
||||||
|
#### 4.1 表格加载状态
|
||||||
|
|
||||||
|
修改表格标签，添加 `v-loading` 指令：
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<el-table :data="orgs" v-loading="loading" border>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4.2 操作列添加删除按钮
|
||||||
|
|
||||||
|
修改操作列，添加删除按钮：
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<el-table-column label="操作" width="150">
|
||||||
|
<template #default="{ row }">
|
||||||
|
<el-button size="small" @click="openDialog(row)">编辑</el-button>
|
||||||
|
<el-button size="small" type="danger" @click="handleDelete(row.id)">删除</el-button>
|
||||||
|
</template>
|
||||||
|
</el-table-column>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4.3 下拉框使用所有部门列表
|
||||||
|
|
||||||
|
修改编辑对话框中的"上级公司"选择，使用 `allOrgs` 而非 `orgs`：
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<el-form-item label="上级公司">
|
||||||
|
<el-select v-model="form.parent" clearable placeholder="不选则为集团顶级">
|
||||||
|
<el-option v-for="o in allOrgs" :key="o.id" :value="o.id" :label="o.name" />
|
||||||
|
</el-select>
|
||||||
|
</el-form-item>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4.4 表格下方添加分页控件
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<div style="margin-top: 16px; text-align: right;">
|
||||||
|
<el-pagination
|
||||||
|
v-model:current-page="currentPage"
|
||||||
|
:page-size="pageSize"
|
||||||
|
:total="total"
|
||||||
|
@current-change="handlePageChange"
|
||||||
|
layout="total, prev, pager, next, jumper"
|
||||||
|
/>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
**样式说明**:
|
||||||
|
- `layout="total, prev, pager, next, jumper"` - 显示总数、前一页、页码、后一页、跳转输入框
|
||||||
|
- 右对齐，与表格宽度对称
|
||||||
|
- `margin-top: 16px` 与表格距离保持一致
|
||||||
|
|
||||||
|
### 5. 数据流
|
||||||
|
|
||||||
|
```
|
||||||
|
用户交互
|
||||||
|
↓
|
||||||
|
点击分页按钮 → handlePageChange(newPage)
|
||||||
|
↓
|
||||||
|
fetchOrgs(newPage) → manageOrganizations(newPage)
|
||||||
|
↓
|
||||||
|
API 返回 { count, results }
|
||||||
|
↓
|
||||||
|
更新 orgs、total、currentPage
|
||||||
|
↓
|
||||||
|
表格重新渲染
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. 错误处理
|
||||||
|
|
||||||
|
- **加载失败**: 显示 ElMessage.error()，保留当前页状态
|
||||||
|
- **删除部门**: 删除后调用 `currentPage.value = 1; fetchOrgs()` 回到第 1 页（避免最后一条删除后页码超出范围）
|
||||||
|
- **网络异常**: 用户可点击分页按钮重试
|
||||||
|
|
||||||
|
### 7. 边界情况
|
||||||
|
|
||||||
|
| 场景 | 处理方式 |
|
||||||
|
|------|---------|
|
||||||
|
| 初始化（无数据） | `currentPage=1, total=0, orgs=[]`，分页组件自动隐藏 |
|
||||||
|
| 新增部门后 | 重置到第 1 页，重新加载分页数据和下拉框数据 |
|
||||||
|
| 编辑部门后 | 重置到第 1 页，重新加载分页数据和下拉框数据（保持一致体验） |
|
||||||
|
| 删除部门后 | 重置到第 1 页，重新加载分页数据和下拉框数据 |
|
||||||
|
| 当前页无数据 | 自动回到第 1 页（由分页组件自动处理） |
|
||||||
|
| 用户取消删除确认 | 不执行任何操作，保留当前状态 |
|
||||||
|
|
||||||
|
### 8. 下拉框数据一致性
|
||||||
|
|
||||||
|
**问题**: 分页后，表格显示当前页的 20 条部门，但"父公司"下拉框需要显示所有部门（因为用户可能需要将某个部门的父级设置为其他页的部门）
|
||||||
|
|
||||||
|
**解决方案**:
|
||||||
|
- 维护单独的 `allOrgs` 数组，通过 `fetchAllOrgs()` 函数加载
|
||||||
|
- 表格显示分页数据 `orgs`（当前页）
|
||||||
|
- 下拉框显示所有数据 `allOrgs`（所有页）
|
||||||
|
- 新增/编辑/删除后同时刷新两个列表
|
||||||
|
|
||||||
|
**临时方案说明**:
|
||||||
|
当前方案通过预加载前几页（最多 5 页、共 100 条）来获取所有部门。若部门数量可能超过 100，建议后续优化为：
|
||||||
|
1. 后端添加 `?list_all=true` 参数，返回无分页的完整列表
|
||||||
|
2. 或单独新增一个无分页的 API 端点（如 `/organizations/manage/all/`）
|
||||||
|
|
||||||
|
**后续优化**: 若需要搜索功能，改为搜索型下拉框（`el-select` + `filterable`）
|
||||||
|
|
||||||
|
## 实现清单
|
||||||
|
|
||||||
|
**后端** (无需改动):
|
||||||
|
- [x] Django REST Framework 已支持 PageNumberPagination
|
||||||
|
|
||||||
|
**前端 - API 层** (各修改一次):
|
||||||
|
- [ ] `organizations.js` - `manageOrganizations()` 添加 `page` 参数
|
||||||
|
- [ ] `jobs.js` - `manageJobs()` 添加 `page` 参数
|
||||||
|
- [ ] `applications.js` - `getManageApplications()` 添加 `page` 参数
|
||||||
|
- [ ] `/auth/users/` 调用位置 - 传入 `page` 参数
|
||||||
|
|
||||||
|
**前端 - 组件层** (共 4 个页面):
|
||||||
|
- [ ] **OrganizationManageView.vue** (部门管理)
|
||||||
|
- [ ] 添加分页状态和函数
|
||||||
|
- [ ] 修改表格和操作列
|
||||||
|
- [ ] 添加分页控件
|
||||||
|
|
||||||
|
- [ ] **JobManageView.vue** (职位管理)
|
||||||
|
- [ ] 添加分页状态和函数
|
||||||
|
- [ ] 修改表格和操作列
|
||||||
|
- [ ] 添加分页控件
|
||||||
|
|
||||||
|
- [ ] **ApplicationManageView.vue** (投递管理)
|
||||||
|
- [ ] 添加分页状态和函数
|
||||||
|
- [ ] 修改表格
|
||||||
|
- [ ] 添加分页控件
|
||||||
|
|
||||||
|
- [ ] **UserManageView.vue** (用户管理)
|
||||||
|
- [ ] 添加分页状态和函数
|
||||||
|
- [ ] 修改表格和操作列
|
||||||
|
- [ ] 添加分页控件
|
||||||
|
|
||||||
|
**测试** (每个页面):
|
||||||
|
- [ ] 验证分页功能（第 1 页、中间页、最后一页）
|
||||||
|
- [ ] 验证新增/编辑/删除后的分页重置
|
||||||
|
- [ ] 验证网络错误恢复
|
||||||
|
|
||||||
|
## 性能考量
|
||||||
|
|
||||||
|
- **API 调用**: 每次页码变更触发一次 API 调用（频率不高，通常用户不会频繁翻页）
|
||||||
|
- **数据量**: 每次最多 20 条记录，前端内存占用低
|
||||||
|
- **首屏加载**: 从一次性加载 N 条改为加载 20 条，性能改善明显
|
||||||
|
|
||||||
|
## 向后兼容性
|
||||||
|
|
||||||
|
无破坏性改动：
|
||||||
|
- API 默认参数 `page=1`，未传参时返回第 1 页
|
||||||
|
- 现有其他功能不受影响
|
||||||
|
|
||||||
|
## 测试场景
|
||||||
|
|
||||||
|
1. **初次加载**
|
||||||
|
- 验证第 1 页正确显示（最多 20 条）
|
||||||
|
- 验证总数、页码正确
|
||||||
|
- 验证下拉框加载所有部门
|
||||||
|
|
||||||
|
2. **翻页**
|
||||||
|
- 点击下一页、上一页、特定页码，数据正确更新
|
||||||
|
- 验证 loading 状态在加载期间显示
|
||||||
|
|
||||||
|
3. **跳转输入**
|
||||||
|
- 直接输入页码（如第 5 页），正确跳转
|
||||||
|
- 输入超出范围的页码（如第 100 页），无报错
|
||||||
|
|
||||||
|
4. **新增部门**
|
||||||
|
- 新增后，回到第 1 页并显示新部门
|
||||||
|
- 验证下拉框立即更新，新部门可被选为父级
|
||||||
|
|
||||||
|
5. **编辑部门**
|
||||||
|
- 编辑后，回到第 1 页，验证修改内容生效
|
||||||
|
- 下拉框同时更新
|
||||||
|
|
||||||
|
6. **删除部门**
|
||||||
|
- 点击删除，出现确认对话框
|
||||||
|
- 确认删除后，回到第 1 页，验证被删除部门消失
|
||||||
|
- 下拉框同时移除该部门
|
||||||
|
- 取消删除，页面无变化
|
||||||
|
|
||||||
|
7. **边界情况**
|
||||||
|
- 当前为最后一页，删除该页最后一条，自动回到第 1 页
|
||||||
|
- 删除所有部门，表格显示空，分页组件隐藏
|
||||||
|
|
||||||
|
8. **错误恢复**
|
||||||
|
- 网络超时，显示错误提示，保留当前页状态
|
||||||
|
- 点击分页按钮重试，正确加载
|
||||||
|
|
||||||
|
9. **下拉框完整性**
|
||||||
|
- 在下拉框中能选到所有部门（不仅仅是当前页）
|
||||||
|
- 搜索或滚动下拉框，能找到目标部门
|
||||||
|
|
||||||
|
## 后续扩展
|
||||||
|
|
||||||
|
- 为其他管理页面（职位、用户）添加相同的分页逻辑
|
||||||
|
- 考虑将分页逻辑抽象为可复用的 Composable
|
||||||
|
- 支持自定义每页行数选项
|
||||||
|
|
||||||
Loading…
Reference in New Issue