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

### 通用响应格式
```json
{
  "success": true|false,
  "data": {...},
  "message": "提示信息",
  "error": "错误信息"
}
```

### 状态码说明
- `200`: 成功
- `400`: 请求参数错误
- `401`: 未认证
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器内部错误

---

## 🔐 认证接口

### 用户登录 - POST /api/login

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

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

**响应数据**:
```json
{
  "success": true,
  "employeeId": 1,
  "sessionId": "session_id",
  "username": "admin",
  "roles": ["ROLE_ADMIN"],
  "message": "登录成功"
}
```

**错误响应**:
```json
{
  "success": false,
  "error": "用户名或密码错误"
}
```

---

## 👥 用户管理接口

### 员工信息 - GET /employee/findById

根据ID获取员工信息。

**请求参数**:
- `id` (Integer): 员工ID

**响应数据**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "张三",
    "account": "admin",
    "email": "admin@example.com"
  }
}
```

### 员工列表 - GET /employee/list

分页获取员工列表。

**请求参数**:
- `page` (Integer, 默认0): 页码
- `size` (Integer, 默认10): 每页大小
- `searchText` (String, 可选): 搜索关键词

**响应数据**:
```json
{
  "content": [
    {
      "id": 1,
      "name": "张三",
      "account": "admin"
    }
  ],
  "totalElements": 10,
  "totalPages": 1,
  "size": 10,
  "number": 0
}
```

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

保存或更新员工信息。

**请求参数**:
```json
{
  "id": 1,
  "name": "张三",
  "account": "admin",
  "email": "admin@example.com"
}
```

### 删除员工 - GET /employee/delete

删除指定ID的员工。

**请求参数**:
- `id` (Integer): 员工ID

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

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

**响应数据**:
```json
{
  "success": true,
  "employeeId": 1,
  "sessionId": "session_id"
}
```

---

## 🏢 公司管理接口

### 公司信息 - GET /company/findById

根据ID获取公司信息。

**请求参数**:
- `id` (Integer): 公司ID

**响应数据**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "示例公司",
    "address": "北京市朝阳区",
    "phone": "010-12345678"
  }
}
```

### 公司列表 - GET /company/list

分页获取公司列表。

**请求参数**:
- `page` (Integer, 默认0): 页码
- `size` (Integer, 默认10): 每页大小

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

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

保存或更新公司信息。

**请求参数**:
```json
{
  "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

保存或更新银行信息。

**请求参数**:
```json
{
  "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

获取系统首页信息。

**响应数据**:
```json
{
  "success": true,
  "data": {
    "systemInfo": "Contract Manager System",
    "version": "1.0.0"
  }
}
```

### WebSocket 连接 - GET /websocket

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

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

---

## 🔒 权限说明

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

### 权限控制
- 删除角色操作仅限系统管理员
- 系统管理员角色不可删除
- 非系统管理员无法查看系统管理员角色信息

---

## 🚨 错误处理

### 常见错误码

#### 400 - 请求参数错误
```json
{
  "success": false,
  "error": "请求参数不正确"
}
```

#### 401 - 未认证
```json
{
  "success": false,
  "error": "请先登录"
}
```

#### 403 - 权限不足
```json
{
  "success": false,
  "error": "无权限执行此操作"
}
```

#### 404 - 资源不存在
```json
{
  "success": false,
  "error": "资源不存在"
}
```

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

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

---

## 📝 使用示例

### JavaScript/Ajax 调用示例

```javascript
// 用户登录
$.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 调用示例

```bash
# 用户登录
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 使用指南

### 添加依赖
```xml
<dependency>
    <groupId>com.ecep.contract</groupId>
    <artifactId>contract-client</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 初始化客户端
```java
ContractClient client = new ContractClient("http://localhost:8080");
client.setSessionId(sessionId); // 设置认证session
```

### 调用API
```java
// 获取公司列表
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 接口。请在使用前仔细阅读相关说明，确保正确调用接口。*