开发者快速开始指南

欢迎来到源丰后端API！本指南将帮助您快速上手使用我们的API接口。

🚀 快速开始

前置条件

已有有效的用户账户
了解基本的HTTP协议和JSON格式
拥有API测试工具（如Postman、curl等）

1. 获取访问令牌

首先需要通过用户认证获取JWT访问令牌：

bash

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your_email@example.com",
    "password": "your_password"
  }'

成功响应:

json

{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 1,
      "username": "zhangsan",
      "email": "your_email@example.com",
      "nickname": "张三",
      "status": 1,
      "is_admin": false,
      "created_at": "2024-01-15T10:00:00Z"
    }
  }
}

2. 使用访问令牌

在后续的API请求中，需要在请求头中包含JWT令牌：

bash

curl -X GET http://localhost:8080/api/v1/users/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

📋 核心功能概览

用户管理

用户注册和登录
个人资料管理
密码修改

员工管理

员工档案管理
组织架构维护
角色权限分配

业务功能

考勤打卡和统计
薪资计算和发放
待办事项管理
日报系统

🛠️ 开发环境设置

基础配置

javascript

// JavaScript/Node.js 示例
const API_BASE_URL = 'http://localhost:8080/api/v1';

class APIClient {
  constructor(token) {
    this.token = token;
    this.baseURL = API_BASE_URL;
  }

  async request(method, endpoint, data = null) {
    const url = `${this.baseURL}${endpoint}`;
    const options = {
      method,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      }
    };

    if (data) {
      options.body = JSON.stringify(data);
    }

    const response = await fetch(url, options);
    return response.json();
  }
}

// 使用示例
const client = new APIClient('your-jwt-token');
const userProfile = await client.request('GET', '/users/profile');

Python 示例

python

import requests
from typing import Dict, Any, Optional

class APIClient:
    def __init__(self, base_url: str = "http://localhost:8080/api/v1"):
        self.base_url = base_url
        self.token = None

    def login(self, email: str, password: str) -> bool:
        """用户登录获取token"""
        response = requests.post(
            f"{self.base_url}/auth/login",
            json={"email": email, "password": password}
        )

        if response.json().get("success"):
            self.token = response.json()["data"]["token"]
            return True
        return False

    def request(self, method: str, endpoint: str, data: Optional[Dict] = None) -> Dict[str, Any]:
        """发送API请求"""
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.token}"
        }

        response = requests.request(
            method,
            f"{self.base_url}{endpoint}",
            headers=headers,
            json=data
        )

        return response.json()

# 使用示例
client = APIClient()
if client.login("your_email@example.com", "your_password"):
    profile = client.request("GET", "/users/profile")
    print(f"用户信息: {profile}")

📚 常用操作示例

1. 获取个人信息

bash

curl -X GET http://localhost:8080/api/v1/users/profile \
  -H "Authorization: Bearer your_token"

2. 考勤打卡

bash

# 上班打卡
curl -X POST http://localhost:8080/api/v1/attendance/clock-in \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 39.908823,
    "longitude": 116.397470,
    "note": "正常上班打卡"
  }'

# 下班打卡
curl -X POST http://localhost:8080/api/v1/attendance/clock-out \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "完成今日工作"
  }'

3. 提交日报

bash

curl -X POST http://localhost:8080/api/v1/daily-reports \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "report_date": "2024-01-15",
    "content": "今天完成了用户管理模块的开发...",
    "summary": "完成用户管理模块核心功能",
    "plan": "明天开发权限管理模块"
  }'

4. 创建待办事项

bash

curl -X POST http://localhost:8080/api/v1/todos \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "完成API文档编写",
    "description": "编写用户管理相关的API文档",
    "priority": "high",
    "due_date": "2024-01-20"
  }'

🔧 错误处理

常见错误码

状态码	说明	解决方案
401	未授权	检查token是否有效，重新登录
403	权限不足	联系管理员分配相应权限
404	资源不存在	检查请求的URL和参数
422	参数验证失败	检查请求参数格式和必填项

错误处理示例

javascript

try {
  const result = await client.request('GET', '/users/profile');
  if (!result.success) {
    console.error('API请求失败:', result.message);
    return;
  }
  console.log('用户信息:', result.data);
} catch (error) {
  console.error('网络错误:', error);
}

📖 学习路径

1. 基础学习

认证授权指南 - 了解JWT认证机制
错误处理指南 - 学习如何处理API错误
数据格式说明 - 了解请求和响应数据格式

2. 业务模块

用户管理模块 - 用户相关操作
考勤管理模块 - 考勤打卡和统计
待办事项模块 - 任务管理功能

3. 高级功能

文件管理模块 - 文件上传下载
权限管理模块 - 角色权限控制
薪资管理模块 - 薪资计算发放

🛡️ 安全注意事项

令牌安全:
- 不要在客户端代码中硬编码token
- 定期刷新token
- 使用HTTPS传输敏感数据
参数验证:
- 在发送请求前验证参数格式
- 处理服务器返回的验证错误
- 使用适当的参数类型
错误处理:
- 不要暴露详细的错误信息给最终用户
- 记录错误日志以便调试
- 实现优雅的降级处理

📞 获取帮助

如果您在开发过程中遇到问题：

查看API文档: API文档首页
检查错误码: 错误处理指南
查看示例: 示例代码
联系技术支持: 提供详细的错误信息和复现步骤

🎯 下一步

恭喜您完成了快速开始指南！现在您可以：

深入学习各个业务模块的API
查看更多示例代码
开始集成API到您的应用中
探索高级功能和最佳实践

💡 提示: 建议从简单的GET请求开始，逐步尝试更复杂的操作。如果遇到问题，可以参考示例代码或联系技术支持。

开发者快速开始指南 ​

🚀 快速开始 ​

前置条件 ​

1. 获取访问令牌 ​

2. 使用访问令牌 ​

📋 核心功能概览 ​

用户管理 ​

员工管理 ​

业务功能 ​

🛠️ 开发环境设置 ​

基础配置 ​

Python 示例 ​

📚 常用操作示例 ​

1. 获取个人信息 ​

2. 考勤打卡 ​

3. 提交日报 ​

4. 创建待办事项 ​

🔧 错误处理 ​

常见错误码 ​

错误处理示例 ​

📖 学习路径 ​

1. 基础学习 ​

2. 业务模块 ​

3. 高级功能 ​

🛡️ 安全注意事项 ​

📞 获取帮助 ​

🎯 下一步 ​

开发者快速开始指南

🚀 快速开始

前置条件

1. 获取访问令牌

2. 使用访问令牌

📋 核心功能概览

用户管理

员工管理

业务功能

🛠️ 开发环境设置

基础配置

Python 示例

📚 常用操作示例

1. 获取个人信息

2. 考勤打卡

3. 提交日报

4. 创建待办事项

🔧 错误处理

常见错误码

错误处理示例

📖 学习路径

1. 基础学习

2. 业务模块

3. 高级功能

🛡️ 安全注意事项

📞 获取帮助

🎯 下一步