contract-manager/API_DOCUMENTATION.md

Contract-Manager API 接口文档

📖 概览

Contract-Manager 系统提供了完整的 RESTful API 接口，用于合同管理系统的各项业务操作。本文档详细描述了所有可用的 API 接口、请求参数、响应格式和错误处理。

API 基础信息

• 基础URL: http://localhost:8080
• 协议: HTTP/HTTPS
• 数据格式: JSON
• 认证方式: Spring Security Session + JWT
• 字符编码: UTF-8

通用响应格式

{
  "success": true|false,
  "data": {...},
  "message": "提示信息",
  "error": "错误信息"
}

状态码说明

• 200: 成功
• 400: 请求参数错误
• 401: 未认证
• 403: 权限不足
• 404: 资源不存在
• 500: 服务器内部错误

---

🔐 认证接口

用户登录 - POST /api/login

用户登录接口，支持用户名密码登录和客户端认证两种方式。

请求参数:

{
  "type": "client|web",           // 登录类型：client=客户端认证，web=用户名密码登录
  "username": "用户名",            // 用户名
  "password": "密码",              // 密码（web模式需要）
  "sign": {                       // 客户端认证信息（client模式需要）
    "MAC地址": "IP地址"
  }
}

响应数据:

{
  "success": true,
  "employeeId": 1,
  "sessionId": "session_id",
  "username": "admin",
  "roles": ["ROLE_ADMIN"],
  "message": "登录成功"
}

错误响应:

{
  "success": false,
  "error": "用户名或密码错误"
}

---

👥 用户管理接口

员工信息 - GET /employee/findById

根据ID获取员工信息。

请求参数:

• id (Integer): 员工ID

响应数据:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "张三",
    "account": "admin",
    "email": "admin@example.com"
  }
}

员工列表 - GET /employee/list

分页获取员工列表。

请求参数:

• page (Integer, 默认0): 页码
• size (Integer, 默认10): 每页大小
• searchText (String, 可选): 搜索关键词

响应数据:

{
  "content": [
    {
      "id": 1,
      "name": "张三",
      "account": "admin"
    }
  ],
  "totalElements": 10,
  "totalPages": 1,
  "size": 10,
  "number": 0
}

保存员工信息 - POST /employee/save

保存或更新员工信息。

请求参数:

{
  "id": 1,
  "name": "张三",
  "account": "admin",
  "email": "admin@example.com"
}

删除员工 - GET /employee/delete

删除指定ID的员工。

请求参数:

• id (Integer): 员工ID

获取当前用户信息 - GET /employee/currentUser

获取当前登录用户的信息。

响应数据:

{
  "success": true,
  "employeeId": 1,
  "sessionId": "session_id"
}

---

🏢 公司管理接口

公司信息 - GET /company/findById

根据ID获取公司信息。

请求参数:

• id (Integer): 公司ID

响应数据:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "示例公司",
    "address": "北京市朝阳区",
    "phone": "010-12345678"
  }
}

公司列表 - GET /company/list

分页获取公司列表。

请求参数:

• page (Integer, 默认0): 页码
• size (Integer, 默认10): 每页大小

响应数据:

{
  "content": [
    {
      "id": 1,
      "name": "示例公司",
      "address": "北京市朝阳区"
    }
  ],
  "totalElements": 10,
  "totalPages": 1,
  "size": 10,
  "number": 0
}

保存公司信息 - GET /company/save

保存或更新公司信息。

请求参数:

{
  "id": 1,
  "name": "示例公司",
  "address": "北京市朝阳区",
  "phone": "010-12345678"
}

删除公司 - GET /company/delete

删除指定ID的公司。

请求参数:

• id (Integer): 公司ID

---

🏦 银行管理接口

银行信息 - GET /bank/findById

根据ID获取银行信息。

请求参数:

• id (Integer): 银行ID

银行列表 - GET /bank/list

分页获取银行列表。

请求参数:

• page (Integer, 默认0): 页码
• size (Integer, 默认10): 每页大小

保存银行信息 - POST /bank/save

保存或更新银行信息。

请求参数:

{
  "id": 1,
  "name": "中国银行",
  "code": "BOC"
}

删除银行 - GET /bank/delete

删除指定ID的银行。

请求参数:

• id (Integer): 银行ID

---

🔑 角色管理接口

角色信息 - GET /employee/role/findById

根据ID获取角色信息。

请求参数:

• id (Integer): 角色ID

角色列表 - GET /employee/role/list

分页获取角色列表，非系统管理员无法查看系统管理员角色。

请求参数:

• page (Integer, 默认0): 页码
• size (Integer, 默认10): 每页大小
• searchText (String, 可选): 搜索关键词

保存角色信息 - GET /employee/role/save

保存角色信息，仅系统管理员可操作。

删除角色 - GET /employee/role/delete

删除指定ID的角色，仅系统管理员可操作。

请求参数:

• id (Integer): 角色ID

注意: 不能删除系统管理员角色。

获取角色权限 - GET /employee/role/getFunctionsByRoleId

根据角色ID获取该角色的权限功能列表。

请求参数:

• roleId (Integer): 角色ID

---

☁️ 云服务接口

天眼查服务 - /cloudTyc

天眼查第三方数据服务接口。

获取天眼查信息 - GET /cloudTyc/findById

天眼查列表 - GET /cloudTyc/list

保存天眼查信息 - GET /cloudTyc/save

删除天眼查信息 - GET /cloudTyc/delete

企查查服务 - /cloudRk

企查查第三方数据服务接口。

获取企查查信息 - GET /cloudRk/findById

企查查列表 - GET /cloudRk/list

保存企查查信息 - GET /cloudRk/save

删除企查查信息 - GET /cloudRk/delete

用友云服务 - /cloudYu

用友云第三方数据服务接口。

获取用友云信息 - GET /cloudYu/findById

用友云列表 - GET /cloudYu/list

保存用友云信息 - GET /cloudYu/save

删除用友云信息 - GET /cloudYu/delete

---

📊 其他接口

系统首页 - GET /index

获取系统首页信息。

响应数据:

{
  "success": true,
  "data": {
    "systemInfo": "Contract Manager System",
    "version": "1.0.0"
  }
}

WebSocket 连接 - GET /websocket

建立WebSocket连接，用于实时通信。

连接地址: ws://localhost:8080/websocket

---

🔒 权限说明

角色权限

• ROLE_ADMIN: 系统管理员，拥有所有权限
• 普通用户: 只能查看和操作非系统管理员级别的数据

权限控制

• 删除角色操作仅限系统管理员
• 系统管理员角色不可删除
• 非系统管理员无法查看系统管理员角色信息

---

🚨 错误处理

常见错误码

400 - 请求参数错误

{
  "success": false,
  "error": "请求参数不正确"
}

401 - 未认证

{
  "success": false,
  "error": "请先登录"
}

403 - 权限不足

{
  "success": false,
  "error": "无权限执行此操作"
}

404 - 资源不存在

{
  "success": false,
  "error": "资源不存在"
}

认证错误

• 客户端认证模式下，需要提供正确的MAC地址和IP地址映射
• 用户名密码模式下，需要提供正确的用户名和密码

业务错误

• 系统管理员角色不可删除
• 用户未绑定认证信息无法登录
• 认证信息错误登录失败

---

📝 使用示例

JavaScript/Ajax 调用示例

// 用户登录
$.ajax({
  url: '/api/login',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({
    type: 'web',
    username: 'admin',
    password: 'password123'
  }),
  success: function(response) {
    if (response.success) {
      console.log('登录成功', response);
      // 保存sessionId等认证信息
      sessionStorage.setItem('sessionId', response.sessionId);
    }
  }
});

// 获取公司列表
$.ajax({
  url: '/company/list',
  type: 'GET',
  data: {
    page: 0,
    size: 10
  },
  success: function(response) {
    console.log('公司列表', response);
  }
});

// 保存公司信息
$.ajax({
  url: '/company/save',
  type: 'GET',
  data: {
    id: 1,
    name: '新公司名称',
    address: '新地址'
  },
  success: function(response) {
    console.log('保存成功', response);
  }
});

curl 调用示例

# 用户登录
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "web",
    "username": "admin",
    "password": "password123"
  }'

# 获取公司列表
curl "http://localhost:8080/company/list?page=0&size=10"

# 获取员工信息
curl "http://localhost:8080/employee/findById?id=1"

---

🔧 SDK 使用指南

添加依赖

<dependency>
    <groupId>com.ecep.contract</groupId>
    <artifactId>contract-client</artifactId>
    <version>1.0.0</version>
</dependency>

初始化客户端

ContractClient client = new ContractClient("http://localhost:8080");
client.setSessionId(sessionId); // 设置认证session

调用API

// 获取公司列表
Page<CompanyVo> companies = client.company().list(0, 10);

// 保存公司信息
CompanyVo company = new CompanyVo();
company.setName("新公司");
CompanyVo saved = client.company().save(company);

---

📈 版本历史

版本	日期	变更说明
v1.0.0	2024-01-01	初始版本，包含基础CRUD操作
v1.1.0	2024-02-01	新增角色权限管理接口
v1.2.0	2024-03-01	新增云服务集成接口

---

📞 技术支持

如有技术问题，请联系：

• 技术支持邮箱: support@contractmanager.com
• 开发团队: Contract Manager Development Team
• 文档版本: v1.2.0
• 最后更新: 2024-03-01

---

本文档详细描述了 Contract-Manager 系统的所有 API 接口。请在使用前仔细阅读相关说明，确保正确调用接口。