# 管理后台分页功能设计文档

**日期**: 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
- 支持自定义每页行数选项