源丰后端 API

Appearance

公司管理 ​

公司管理模块提供企业信息的创建、查询、更新等功能，支持多公司架构。

接口概览 ​

公开接口 ​

方法路径描述权限要求
GET/api/v1/companies/{id}获取公司详情无

管理员接口 ​

方法路径描述权限要求
POST/api/v1/admin/companies创建公司管理员
GET/api/v1/admin/companies获取所有公司列表管理员
GET/api/v1/admin/companies/active获取活跃公司列表管理员
GET/api/v1/admin/companies/{id}获取公司详情管理员
PUT/api/v1/admin/companies/{id}更新公司信息管理员
PUT/api/v1/admin/companies/{id}/status更新公司状态管理员
DELETE/api/v1/admin/companies/{id}删除公司管理员
POST/api/v1/admin/companies/fix-employee-associations修复员工公司关联管理员
POST/api/v1/admin/companies/{id}/users批量添加用户到公司管理员

用户接口 ​

方法路径描述权限要求
GET/api/v1/companies/{id}/employees获取公司员工列表登录用户

创建公司 ​

创建新的公司档案。

接口信息 ​

  • URL: /api/v1/admin/companies
  • 方法: POST
  • 内容类型: application/json
  • 认证: 需要管理员权限

请求参数 ​

字段类型必填描述示例
namestring是公司名称"源丰科技有限公司"
descriptionstring否公司描述"专注于企业信息化服务"
industrystring否所属行业"软件开发"
addressstring否公司地址"北京市朝阳区xxx街道xxx号"
phonestring否联系电话"010-12345678"
emailstring否公司邮箱"contact@yuanfeng.com"
websitestring否公司网站"https://www.yuanfeng.com"
logostring否公司logo URL"https://example.com/logo.png"
statusint否公司状态（1:活跃, 0:禁用）1

请求示例 ​

json
{
  "name": "源丰科技有限公司",
  "description": "专注于企业信息化服务的高新技术企业",
  "industry": "软件开发",
  "address": "北京市朝阳区xxx街道xxx号",
  "phone": "010-12345678",
  "email": "contact@yuanfeng.com",
  "website": "https://www.yuanfeng.com",
  "logo": "https://example.com/logo.png",
  "status": 1
}

响应示例 ​

成功响应 (201) ​

json
{
  "code": 201,
  "message": "公司创建成功",
  "data": {
    "id": 1,
    "name": "源丰科技有限公司",
    "description": "专注于企业信息化服务的高新技术企业",
    "industry": "软件开发",
    "address": "北京市朝阳区xxx街道xxx号",
    "phone": "010-12345678",
    "email": "contact@yuanfeng.com",
    "website": "https://www.yuanfeng.com",
    "logo": "https://example.com/logo.png",
    "status": 1,
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取所有公司列表 ​

获取系统中所有公司的列表，支持分页。

接口信息 ​

  • URL: /api/v1/admin/companies
  • 方法: GET
  • 认证: 需要管理员权限

查询参数 ​

参数类型必填描述默认值
pageint否页码1
page_sizeint否每页数量10
searchstring否搜索关键词-
industrystring否行业筛选-
statusint否状态筛选-

请求示例 ​

bash
GET /api/v1/admin/companies?page=1&page_size=20&search=科技

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "companies": [
      {
        "id": 1,
        "name": "源丰科技有限公司",
        "description": "专注于企业信息化服务",
        "industry": "软件开发",
        "address": "北京市朝阳区xxx街道xxx号",
        "phone": "010-12345678",
        "email": "contact@yuanfeng.com",
        "website": "https://www.yuanfeng.com",
        "logo": "https://example.com/logo.png",
        "status": 1,
        "employee_count": 50,
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "pages": 1
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取公司详情 ​

获取指定公司的详细信息。

接口信息 ​

  • URL: /api/v1/companies/{id}
  • 方法: GET
  • 认证: 无（公开接口）或管理员权限

路径参数 ​

参数类型必填描述示例
idint是公司ID1

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "源丰科技有限公司",
    "description": "专注于企业信息化服务的高新技术企业，为企业提供全方位的数字化解决方案",
    "industry": "软件开发",
    "address": "北京市朝阳区xxx街道xxx号",
    "phone": "010-12345678",
    "email": "contact@yuanfeng.com",
    "website": "https://www.yuanfeng.com",
    "logo": "https://example.com/logo.png",
    "status": 1,
    "employee_count": 50,
    "departments": [
      {
        "id": 1,
        "name": "技术部",
        "employee_count": 20
      },
      {
        "id": 2,
        "name": "销售部",
        "employee_count": 15
      }
    ],
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

更新公司信息 ​

更新指定公司的基本信息。

接口信息 ​

  • URL: /api/v1/admin/companies/{id}
  • 方法: PUT
  • 内容类型: application/json
  • 认证: 需要管理员权限

路径参数 ​

参数类型必填描述示例
idint是公司ID1

请求参数 ​

字段类型必填描述示例
namestring否公司名称"源丰科技集团"
descriptionstring否公司描述"更新的公司描述"
industrystring否所属行业"信息技术服务"
addressstring否公司地址"上海市浦东新区xxx路xxx号"
phonestring否联系电话"021-87654321"
emailstring否公司邮箱"info@yuanfeng.com"
websitestring否公司网站"https://www.yuanfeng-group.com"
logostring否公司logo URL"https://example.com/new-logo.png"

请求示例 ​

json
{
  "name": "源丰科技集团",
  "description": "专注于企业信息化服务的综合性高新技术企业集团",
  "address": "上海市浦东新区xxx路xxx号",
  "phone": "021-87654321"
}

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "更新成功",
  "data": null,
  "timestamp": "2024-01-01T12:00:00Z"
}

更新公司状态 ​

更新公司的运营状态（启用/禁用）。

接口信息 ​

  • URL: /api/v1/admin/companies/{id}/status
  • 方法: PUT
  • 内容类型: application/json
  • 认证: 需要管理员权限

路径参数 ​

参数类型必填描述示例
idint是公司ID1

请求参数 ​

字段类型必填描述示例
statusint是公司状态（0:禁用, 1:启用）1

请求示例 ​

json
{
  "status": 1
}

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "状态更新成功",
  "data": null,
  "timestamp": "2024-01-01T12:00:00Z"
}

获取公司员工列表 ​

获取指定公司的员工列表。

接口信息 ​

  • URL: /api/v1/companies/{id}/employees
  • 方法: GET
  • 认证: 需要登录

路径参数 ​

参数类型必填描述示例
idint是公司ID1

查询参数 ​

参数类型必填描述默认值
pageint否页码1
page_sizeint否每页数量10
department_idint否部门ID筛选-
searchstring否搜索关键词-

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "employees": [
      {
        "id": 1,
        "employee_no": "EMP001",
        "full_name": "张三",
        "position": "技术总监",
        "department_name": "技术部",
        "email": "zhangsan@yuanfeng.com",
        "phone": "13800138000",
        "status": 1
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 1,
      "pages": 1
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

批量添加用户到公司 ​

将多个用户批量添加到指定公司。

接口信息 ​

  • URL: /api/v1/admin/companies/{id}/users
  • 方法: POST
  • 内容类型: application/json
  • 认证: 需要管理员权限

路径参数 ​

参数类型必填描述示例
idint是公司ID1

请求参数 ​

字段类型必填描述示例
user_idsint[]是用户ID列表[1, 2, 3]
department_idint否默认部门ID1
positionstring否默认职位"员工"

请求示例 ​

json
{
  "user_ids": [1, 2, 3],
  "department_id": 1,
  "position": "软件工程师"
}

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "批量添加完成",
  "data": {
    "total": 3,
    "success": 3,
    "failed": 0,
    "results": [
      {
        "user_id": 1,
        "status": "success",
        "employee_id": 10
      },
      {
        "user_id": 2,
        "status": "success",
        "employee_id": 11
      },
      {
        "user_id": 3,
        "status": "success",
        "employee_id": 12
      }
    ]
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

数据模型 ​

CompanyResponse ​

typescript
interface CompanyResponse {
  id: number;                    // 公司ID
  name: string;                  // 公司名称
  description?: string;          // 公司描述
  industry?: string;             // 所属行业
  address?: string;              // 公司地址
  phone?: string;                // 联系电话
  email?: string;                // 公司邮箱
  website?: string;              // 公司网站
  logo?: string;                 // 公司logo URL
  status: number;                // 公司状态
  employee_count?: number;       // 员工数量
  departments?: Department[];    // 部门列表
  created_at: string;            // 创建时间
  updated_at: string;            // 更新时间
}

CompanyListResponse ​

typescript
interface CompanyListResponse {
  companies: CompanyResponse[];  // 公司列表
  pagination: {                  // 分页信息
    page: number;
    page_size: number;
    total: number;
    pages: number;
  };
}

错误代码 ​

错误代码描述解决方案
400请求参数错误检查请求参数格式和必填字段
401未认证检查 JWT token 是否有效
403无权限确认用户具有管理员权限
404公司不存在检查公司ID是否正确
409公司名称已存在使用其他公司名称
500服务器内部错误联系系统管理员

集成示例 ​

JavaScript Company API ​

javascript
class CompanyAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  // 获取公司详情（公开接口）
  async getPublicCompany(companyId) {
    const response = await fetch(`${this.baseURL}/api/v1/companies/${companyId}`);
    return response.json();
  }

  // 创建公司（管理员）
  async createCompany(companyData) {
    const response = await fetch(`${this.baseURL}/api/v1/admin/companies`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(companyData)
    });
    return response.json();
  }

  // 获取公司列表（管理员）
  async getCompanies(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseURL}/api/v1/admin/companies?${queryString}`, {
      headers: this.headers
    });
    return response.json();
  }

  // 更新公司信息（管理员）
  async updateCompany(companyId, updateData) {
    const response = await fetch(`${this.baseURL}/api/v1/admin/companies/${companyId}`, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(updateData)
    });
    return response.json();
  }

  // 获取公司员工列表
  async getCompanyEmployees(companyId, params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseURL}/api/v1/companies/${companyId}/employees?${queryString}`, {
      headers: this.headers
    });
    return response.json();
  }

  // 批量添加用户到公司（管理员）
  async addUsersToCompany(companyId, userIds, departmentId, position) {
    const response = await fetch(`${this.baseURL}/api/v1/admin/companies/${companyId}/users`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        user_ids: userIds,
        department_id: departmentId,
        position: position
      })
    });
    return response.json();
  }
}

// 使用示例
const companyAPI = new CompanyAPI('http://localhost:8080', 'your-jwt-token');

// 获取公开公司信息
const companyInfo = await companyAPI.getPublicCompany(1);
console.log('公司信息:', companyInfo.data);

// 创建新公司（管理员）
const newCompany = await companyAPI.createCompany({
  name: '新科技公司',
  description: '专注于人工智能研发',
  industry: '人工智能',
  status: 1
});
console.log('新公司ID:', newCompany.data.id);

相关链接 ​

基于 MIT 许可发布

Copyright © 2024-2025 源丰科技