yunzer_go/server/docs/OA合并接口说明.md

OA 基础数据合并接口说明

概述

为了减少网络请求次数，提升系统性能，新增了一个合并接口，用于一次性获取部门、职位、角色三类基础数据。

接口信息

接口路径

GET /api/oa/base-data/:tenantId

请求参数

• tenantId (路径参数): 租户ID

响应格式

{
  "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%

使用示例

前端使用

import { useOAStore } from '@/stores/oa';

const oaStore = useOAStore();

// 页面初始化时，会自动使用合并接口
onMounted(async () => {
  await oaStore.fetchAllBaseData();
});

后端扩展

如果需要添加更多数据到合并接口，只需：

1. 在 OABaseData 结构体中添加新字段
2. 在 GetOABaseData 方法中添加新的查询逻辑
3. 在 controller 中格式化返回新数据

兼容性

• 合并接口与原有的三个独立接口并存
• 前端 Store 有自动回退机制，确保兼容性
• 如果合并接口失败，会自动使用原有接口

注意事项

1. 租户隔离：确保返回的数据属于指定租户
2. 错误处理：任何查询失败都会返回错误
3. 数据一致性：确保返回的数据是最新的
4. 性能考虑：后端使用并行查询，但仍需注意数据库性能