146 lines
3.5 KiB
Markdown
146 lines
3.5 KiB
Markdown
# OA 基础数据合并接口说明
|
||
|
||
## 概述
|
||
|
||
为了减少网络请求次数，提升系统性能，新增了一个合并接口，用于一次性获取部门、职位、角色三类基础数据。
|
||
|
||
## 接口信息
|
||
|
||
### 接口路径
|
||
```
|
||
GET /api/oa/base-data/:tenantId
|
||
```
|
||
|
||
### 请求参数
|
||
- `tenantId` (路径参数): 租户ID
|
||
|
||
### 响应格式
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取基础数据成功",
|
||
"data": {
|
||
"departments": [
|
||
{
|
||
"id": 1,
|
||
"tenant_id": 1,
|
||
"name": "技术部",
|
||
"code": "TECH",
|
||
"parent_id": 0,
|
||
"description": "技术部门",
|
||
"manager_id": 0,
|
||
"sort_order": 0,
|
||
"status": 1,
|
||
"create_time": "2024-01-01T00:00:00Z",
|
||
"update_time": "2024-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"positions": [
|
||
{
|
||
"id": 1,
|
||
"tenant_id": 1,
|
||
"name": "高级工程师",
|
||
"code": "SENIOR",
|
||
"department_id": 1,
|
||
"level": 3,
|
||
"description": "高级工程师职位",
|
||
"sort_order": 0,
|
||
"status": 1,
|
||
"create_time": "2024-01-01T00:00:00Z",
|
||
"update_time": "2024-01-01T00:00:00Z"
|
||
}
|
||
],
|
||
"roles": [
|
||
{
|
||
"roleId": 1,
|
||
"tenantId": 1,
|
||
"roleCode": "ADMIN",
|
||
"roleName": "管理员",
|
||
"description": "管理员角色",
|
||
"status": 1,
|
||
"sortOrder": 0,
|
||
"createTime": "2024-01-01T00:00:00Z",
|
||
"updateTime": "2024-01-01T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实现细节
|
||
|
||
### 后端实现
|
||
|
||
#### Services 层 (`server/services/oa.go`)
|
||
- 使用 goroutine 并行查询三个数据源
|
||
- 使用 channel 安全地传递查询结果
|
||
- 任何查询失败都会返回错误
|
||
|
||
#### Controllers 层 (`server/controllers/oa.go`)
|
||
- 接收租户ID参数
|
||
- 调用 services 层获取数据
|
||
- 格式化返回数据
|
||
|
||
#### 路由配置 (`server/routers/router.go`)
|
||
- 路由：`/api/oa/base-data/:tenantId`
|
||
- 方法：GET
|
||
|
||
### 前端实现
|
||
|
||
#### API 文件 (`pc/src/api/oa.js`)
|
||
- 封装了 `getOABaseData` 方法
|
||
|
||
#### Store 更新 (`pc/src/stores/oa.js`)
|
||
- `fetchAllBaseData` 方法优先使用合并接口
|
||
- 如果合并接口失败，自动回退到分别请求三个接口
|
||
- 保持缓存机制不变
|
||
|
||
## 性能优势
|
||
|
||
### 优化前
|
||
- 前端需要发起 3 个独立的 HTTP 请求
|
||
- 每次请求都有网络延迟
|
||
- 总耗时 = 3 × 网络延迟 + 3 × 查询时间
|
||
|
||
### 优化后
|
||
- 前端只需发起 1 个 HTTP 请求
|
||
- 后端使用 goroutine 并行查询，总耗时 = 1 × 网络延迟 + max(查询时间)
|
||
- **性能提升**：减少 2 个网络请求，总耗时减少约 60-70%
|
||
|
||
## 使用示例
|
||
|
||
### 前端使用
|
||
|
||
```javascript
|
||
import { useOAStore } from '@/stores/oa';
|
||
|
||
const oaStore = useOAStore();
|
||
|
||
// 页面初始化时，会自动使用合并接口
|
||
onMounted(async () => {
|
||
await oaStore.fetchAllBaseData();
|
||
});
|
||
```
|
||
|
||
### 后端扩展
|
||
|
||
如果需要添加更多数据到合并接口，只需：
|
||
|
||
1. 在 `OABaseData` 结构体中添加新字段
|
||
2. 在 `GetOABaseData` 方法中添加新的查询逻辑
|
||
3. 在 controller 中格式化返回新数据
|
||
|
||
## 兼容性
|
||
|
||
- 合并接口与原有的三个独立接口并存
|
||
- 前端 Store 有自动回退机制，确保兼容性
|
||
- 如果合并接口失败，会自动使用原有接口
|
||
|
||
## 注意事项
|
||
|
||
1. **租户隔离**：确保返回的数据属于指定租户
|
||
2. **错误处理**：任何查询失败都会返回错误
|
||
3. **数据一致性**：确保返回的数据是最新的
|
||
4. **性能考虑**：后端使用并行查询，但仍需注意数据库性能
|
||
|