docs: 添加项目文档和架构设计文件
删除旧的package.json文件 添加天眼查下载信用报告文档 添加项目文档总览、架构设计、API文档、开发指南和数据库设计文档
This commit is contained in:
546
docs/API_DOCUMENTATION.md
Normal file
546
docs/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,546 @@
|
||||
# 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 接口。请在使用前仔细阅读相关说明，确保正确调用接口。*
|
||||
Reference in New Issue
Block a user