Flutter人力资源管理插件beetlehr_sdk的使用

简介

The BeetleHR SDK Flutter 是一个强大的软件开发工具包，允许开发者将 BeetleHR 的功能集成到他们的 Flutter 应用程序中。BeetleHR 是一个人力资源管理平台，提供了多种与员工管理相关的功能，例如考勤跟踪、请假管理和员工绩效评估。本文档将指导您如何在 Flutter 项目中集成和使用 BeetleHR SDK。

功能

以下是我们的 SDK 提供的所有功能，利用它们可以简化您的开发过程。

服务器

• ✅ 从指定端点获取服务器状态

员工认证

• ✅ 使用电子邮件和密码登录
• ✅ 使用电子邮件重置密码

员工档案

• ✅ 获取员工档案信息
• ✅ 更新员工档案

员工考勤

• ✅ 获取考勤概览
• ✅ 上传考勤图片
• ✅ 获取考勤记录
• ✅ 检查分支机构
• ✅ 获取考勤详情
• ✅ 检查打卡接受状态
• ✅ 打卡考勤
• ✅ 获取排班信息
• ✅ 检查接受打卡考勤
• ✅ 获取排班日志
• ✅ 获取打卡按钮类型
• ✅ 同步考勤数据
• ✅ 上传考勤图片
• ✅ 取消考勤记录
• ✅ 处理休息时间
• ✅ 检查休息时间设置

员工通知

• ✅ 获取公告板数据
• ✅ 根据指定参数获取所有审批请求
• ✅ 获取审批请求详情
• ✅ 使用提供的 [body] 和 [id] 批准请求
• ✅ 拒绝请求并返回响应
• ✅ 获取通知数据并返回响应
• ✅ 根据 [id] 获取通知详情
• ✅ 根据姓名过滤参数获取员工数据

员工薪资

• ✅ 获取薪资列表
• ✅ 获取薪资详情
• ✅ 获取节日津贴（THR）薪资列表
• ✅ 获取节日津贴（THR）薪资详情

BeetleHR SDK 版本

注意：已更新到带有新功能的新版本 SDK。

文档

开始使用

添加依赖

您可以在 pubspec.yaml 文件中添加 beetlehr_sdk 或使用以下命令以最新稳定版本添加 beetlehr_sdk 作为依赖项：

flutter pub add beetlehr_sdk

如果您想直接从 GitHub 获取 SDK，可以在 pubspec.yaml 中添加如下内容：

dependencies:
  flutter:
    sdk: flutter

  beetlehr_sdk:
    git:
      url: https://github.com/kodingworks/beetlehr_sdk.git
      ref: master # 分支名称

初始化客户端

在使用 SDK 的功能之前，请确保初始化客户端。您可以使用依赖注入（DI），例如 get_it 包。这样就无需每次都初始化客户端。以下是一个初始化示例：

BeetleHRClient client = BeetleHRClient(
  'https://demo.beetlehr.com/api/v1',
  isLog: true,
);

简单使用示例

以下是如何使用电子邮件和密码进行登录的示例。您不需要手动保存令牌，因为该包已经帮助保存了它。但我们仍然会从登录结果中返回令牌，以便您可以用于其他目的。以下是示例代码：

void login() async {
  try {
    final client = BeetleHRClient(
      'https://demo.beetlehr.com/api/v1',
      isLog: true,
    );

    final result = await client.loginWithEmail(
      email: 'email@email.com',
      password: 'password',
    );

    print(result.meta); // 返回元数据
    print(result.token); // 返回字符串
    print(result.user); // 返回用户模型
  } catch (e) {
    print('Something went wrong!');
  }
}

错误处理

以下是可能抛出的异常和失败情况：

社区与讨论组

您可以通过 Telegram 群组加入我们： Telegram Group

贡献

如果您希望贡献并加入我们的社区，非常欢迎！请注意，在提交拉取请求时，请务必清楚地编写提交消息。当您贡献代码时，最好模仿现有的 BeetleHR 代码模式。

许可证

BeetleHR SDK 是在 MIT 许可证 下发布的。

完整示例代码

以下是一个完整的示例代码，展示了如何在 Flutter 应用程序中使用 BeetleHR SDK 进行登录：

import 'package:beetlehr_sdk/beetlehr_sdk.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

// 初始化 BeetleHR 客户端。
final client = BeetleHRClient(
  'https://demo.beetlehr.com/api/v1',
  isLog: true,
);

/// 应用程序根部件。
class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const HomePage(),
    );
  }
}

/// 应用程序主页面。
class HomePage extends StatefulWidget {
  const HomePage({Key? key}) : super(key: key);

  [@override](/user/override)
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final TextEditingController emailController = TextEditingController();
  final TextEditingController passwordController = TextEditingController();

  [@override](/user/override)
  void initState() {
    super.initState();
    // 检查用户是否已认证。
    checkAuth();
  }

  /// 检查用户是否已认证。
  void checkAuth() async {
    final result = await client.checkToken();
    await Future.delayed(const Duration(seconds: 1));
    if (result) {
      // 如果用户已认证，导航到主页面。
      navigate();
    }
  }

  /// 导航到主页面。
  void navigate() {
    Navigator.pushAndRemoveUntil(
      context,
      MaterialPageRoute(
        builder: (context) => const MainPage(),
      ),
      (route) => false,
    );
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('登录')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          TextFormField(
            controller: emailController,
            decoration: const InputDecoration(hintText: '请输入您的邮箱'),
            keyboardType: TextInputType.emailAddress,
            onChanged: (v) {
              setState(() {});
            },
          ),
          const SizedBox(height: 16),
          TextFormField(
            controller: passwordController,
            decoration: const InputDecoration(hintText: '请输入您的密码'),
            keyboardType: TextInputType.visiblePassword,
            onChanged: (v) {
              setState(() {});
            },
          ),
          const SizedBox(height: 42),
          ElevatedButton(
            onPressed: () {
              if (emailController.text.isEmpty) {
                notify('请先输入邮箱！');
              } else if (passwordController.text.isEmpty) {
                notify('请先输入密码！');
              } else if (passwordController.text.isNotEmpty &&
                  emailController.text.isNotEmpty) {
                // 提交登录表单。
                submit();
              }
            },
            child: const Text('登录'),
          )
        ],
      ),
    );
  }

  /// 提交登录表单。
  void submit() async {
    try {
      final result = await client.loginWithEmail(
        email: emailController.text,
        password: passwordController.text,
      );
      if (result.meta?.success == true) {
        // 如果登录成功，导航到主页面。
        navigate();
      } else {
        // 如果登录失败，显示错误消息。
        notify(result.meta?.message ?? '发生错误！');
      }
    } catch (e) {
      // 如果登录过程中发生错误，显示通用错误消息。
      notify('发生错误！');
    }
  }

  /// 显示通知栏。
  void notify(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  }
}

/// 已认证页面。
class MainPage extends StatelessWidget {
  const MainPage({Key? key}) : super(key: key);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(child: Text('已认证')),
    );
  }
}