1084 lines
23 KiB
Markdown
1084 lines
23 KiB
Markdown
# 资金服务平台 API 接口文档
|
||
|
||
> 版本: v1.0
|
||
> 更新日期: 2026-02-13
|
||
> 作者: zhangjf
|
||
|
||
---
|
||
|
||
## 一、API 规范
|
||
|
||
### 1.1 基础信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 协议 | HTTPS（生产环境）/ HTTP（开发环境） |
|
||
| 数据格式 | JSON |
|
||
| 字符编码 | UTF-8 |
|
||
| 时间格式 | ISO 8601（yyyy-MM-dd HH:mm:ss） |
|
||
| 日期格式 | yyyy-MM-dd |
|
||
| 金额格式 | Decimal（保留2位小数） |
|
||
|
||
### 1.2 请求规范
|
||
|
||
#### 请求头（Headers）
|
||
|
||
| 参数名 | 必填 | 说明 |
|
||
|--------|------|------|
|
||
| Content-Type | 是 | 固定值：`application/json` |
|
||
| Authorization | 是 | Bearer Token：`Bearer {accessToken}` |
|
||
| X-Tenant-Id | 是 | 租户ID |
|
||
| X-Trace-Id | 否 | 链路追踪ID（系统自动生成） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /api/v1/user/login HTTP/1.1
|
||
Host: api.fundplatform.com
|
||
Content-Type: application/json
|
||
X-Tenant-Id: 1
|
||
|
||
```
|
||
|
||
### 1.3 响应规范
|
||
|
||
#### 统一响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| code | Integer | 状态码（200成功，其他为错误码） |
|
||
| message | String | 提示信息 |
|
||
| data | Object | 业务数据（可为 null） |
|
||
| timestamp | Long | 时间戳（毫秒） |
|
||
| traceId | String | 链路追踪ID |
|
||
|
||
#### 分页响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [],
|
||
"total": 100,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 10
|
||
},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
#### 分页字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| records | Array | 数据列表 |
|
||
| total | Long | 总记录数 |
|
||
| size | Integer | 每页大小 |
|
||
| current | Integer | 当前页码（从1开始） |
|
||
| pages | Integer | 总页数 |
|
||
|
||
### 1.4 状态码定义
|
||
|
||
#### 成功状态码
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 操作成功 |
|
||
| 201 | 创建成功 |
|
||
| 204 | 删除成功（无返回内容） |
|
||
|
||
#### 错误状态码
|
||
|
||
| 状态码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| 400 | 请求参数错误 | 检查请求参数格式 |
|
||
| 401 | 未授权 | Token无效或过期，重新登录 |
|
||
| 403 | 禁止访问 | 无权限访问该资源 |
|
||
| 404 | 资源不存在 | 检查请求路径或ID |
|
||
| 409 | 资源冲突 | 数据已存在或状态冲突 |
|
||
| 429 | 请求过于频繁 | 稍后重试 |
|
||
| 500 | 服务器内部错误 | 联系管理员 |
|
||
| 503 | 服务不可用 | 服务维护中 |
|
||
|
||
#### 业务错误码（code字段）
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1001 | 用户名或密码错误 |
|
||
| 1002 | 账号已被禁用 |
|
||
| 1003 | Token已过期 |
|
||
| 1004 | Token无效 |
|
||
| 1005 | 无权限访问 |
|
||
| 2001 | 数据已存在 |
|
||
| 2002 | 数据不存在 |
|
||
| 2003 | 数据关联冲突 |
|
||
| 3001 | 租户已过期 |
|
||
| 3002 | 租户已被禁用 |
|
||
|
||
### 1.5 分页请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| current | Integer | 否 | 1 | 当前页码 |
|
||
| size | Integer | 否 | 10 | 每页大小（最大100） |
|
||
| sortField | String | 否 | - | 排序字段 |
|
||
| sortOrder | String | 否 | asc | 排序方式：asc/desc |
|
||
|
||
---
|
||
|
||
## 二、认证接口
|
||
|
||
### 2.1 用户登录
|
||
|
||
**接口地址：** `POST /api/v1/auth/login`
|
||
|
||
**接口说明：** 用户登录获取访问令牌
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | String | 是 | 用户名 |
|
||
| password | String | 是 | 密码（MD5加密后传输） |
|
||
| tenantCode | String | 否 | 租户编码（多租户模式必填） |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "e10adc3949ba59abbe56e057f20f883e",
|
||
"tenantCode": "SYSTEM"
|
||
}
|
||
```
|
||
|
||
**响应参数：**
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| accessToken | String | 访问令牌 |
|
||
| refreshToken | String | 刷新令牌 |
|
||
| expiresIn | Long | 访问令牌过期时间（秒） |
|
||
| tokenType | String | 令牌类型（Bearer） |
|
||
| userInfo | Object | 用户信息 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
|
||
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
|
||
"expiresIn": 7200,
|
||
"tokenType": "Bearer",
|
||
"userInfo": {
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"realName": "系统管理员",
|
||
"avatar": "https://...",
|
||
"tenantId": 1,
|
||
"tenantName": "系统管理租户",
|
||
"deptId": 1,
|
||
"deptName": "总部",
|
||
"roles": ["super_admin"],
|
||
"permissions": ["*:*:*"]
|
||
}
|
||
},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 用户登出
|
||
|
||
**接口地址：** `POST /api/v1/auth/logout`
|
||
|
||
**接口说明：** 用户登出，使Token失效
|
||
|
||
**请求头：**
|
||
|
||
| 参数名 | 必填 | 说明 |
|
||
|--------|------|------|
|
||
| Authorization | 是 | Bearer Token |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登出成功",
|
||
"data": null,
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 刷新Token
|
||
|
||
**接口地址：** `POST /api/v1/auth/refresh`
|
||
|
||
**接口说明：** 使用刷新令牌获取新的访问令牌
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| refreshToken | String | 是 | 刷新令牌 |
|
||
|
||
**响应参数：** 同登录接口
|
||
|
||
---
|
||
|
||
### 2.4 获取当前用户信息
|
||
|
||
**接口地址：** `GET /api/v1/auth/userinfo`
|
||
|
||
**接口说明：** 获取当前登录用户详细信息
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"realName": "系统管理员",
|
||
"gender": 1,
|
||
"phone": "13800138000",
|
||
"email": "admin@fundplatform.com",
|
||
"avatar": "https://...",
|
||
"deptId": 1,
|
||
"deptName": "总部",
|
||
"position": "系统管理员",
|
||
"tenantId": 1,
|
||
"tenantName": "系统管理租户",
|
||
"roles": [
|
||
{
|
||
"roleId": 1,
|
||
"roleCode": "super_admin",
|
||
"roleName": "超级管理员"
|
||
}
|
||
],
|
||
"permissions": ["*:*:*"],
|
||
"menus": [
|
||
{
|
||
"menuId": 1,
|
||
"menuName": "系统管理",
|
||
"menuType": "dir",
|
||
"icon": "Setting",
|
||
"path": "/system",
|
||
"children": [...]
|
||
}
|
||
]
|
||
},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、用户管理接口
|
||
|
||
### 3.1 获取用户列表
|
||
|
||
**接口地址：** `GET /api/v1/user/list`
|
||
|
||
**接口说明：** 分页查询用户列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| username | String | 否 | 用户名（模糊查询） |
|
||
| realName | String | 否 | 真实姓名（模糊查询） |
|
||
| deptId | Long | 否 | 部门ID |
|
||
| status | Integer | 否 | 状态：0-禁用，1-启用 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"realName": "系统管理员",
|
||
"gender": 1,
|
||
"phone": "13800138000",
|
||
"email": "admin@fundplatform.com",
|
||
"deptId": 1,
|
||
"deptName": "总部",
|
||
"position": "系统管理员",
|
||
"status": 1,
|
||
"lastLoginTime": "2026-02-13 14:30:00",
|
||
"createdTime": "2024-01-01 00:00:00"
|
||
}
|
||
],
|
||
"total": 6,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 1
|
||
},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 获取用户详情
|
||
|
||
**接口地址：** `GET /api/v1/user/{userId}`
|
||
|
||
**接口说明：** 根据用户ID获取用户详细信息
|
||
|
||
**路径参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| userId | Long | 是 | 用户ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"realName": "系统管理员",
|
||
"gender": 1,
|
||
"phone": "13800138000",
|
||
"email": "admin@fundplatform.com",
|
||
"avatar": "https://...",
|
||
"deptId": 1,
|
||
"deptName": "总部",
|
||
"position": "系统管理员",
|
||
"status": 1,
|
||
"roleIds": [1],
|
||
"lastLoginTime": "2026-02-13 14:30:00",
|
||
"lastLoginIp": "192.168.1.1",
|
||
"createdTime": "2024-01-01 00:00:00",
|
||
"updatedTime": "2026-02-13 10:00:00"
|
||
},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 新增用户
|
||
|
||
**接口地址：** `POST /api/v1/user`
|
||
|
||
**接口说明：** 创建新用户
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | String | 是 | 用户名（2-20位字母数字） |
|
||
| password | String | 是 | 密码（6-20位） |
|
||
| realName | String | 是 | 真实姓名 |
|
||
| gender | Integer | 否 | 性别：0-未知，1-男，2-女 |
|
||
| phone | String | 否 | 手机号码 |
|
||
| email | String | 否 | 邮箱地址 |
|
||
| deptId | Long | 否 | 部门ID |
|
||
| position | String | 否 | 职位 |
|
||
| roleIds | Array | 否 | 角色ID列表 |
|
||
| status | Integer | 否 | 状态：0-禁用，1-启用（默认1） |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"username": "newuser",
|
||
"password": "123456",
|
||
"realName": "新用户",
|
||
"gender": 1,
|
||
"phone": "13800138010",
|
||
"email": "newuser@fundplatform.com",
|
||
"deptId": 2,
|
||
"position": "开发工程师",
|
||
"roleIds": [5],
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"message": "创建成功",
|
||
"data": {
|
||
"userId": 7,
|
||
"username": "newuser",
|
||
"realName": "新用户",
|
||
"createdTime": "2026-02-13 15:00:00"
|
||
},
|
||
"timestamp": 1707811200000,
|
||
"traceId": "abc123def456"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 更新用户
|
||
|
||
**接口地址：** `PUT /api/v1/user/{userId}`
|
||
|
||
**接口说明：** 更新用户信息
|
||
|
||
**路径参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| userId | Long | 是 | 用户ID |
|
||
|
||
**请求参数：** 同新增用户（password可选）
|
||
|
||
---
|
||
|
||
### 3.5 删除用户
|
||
|
||
**接口地址：** `DELETE /api/v1/user/{userId}`
|
||
|
||
**接口说明：** 删除用户（逻辑删除）
|
||
|
||
**路径参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| userId | Long | 是 | 用户ID |
|
||
|
||
---
|
||
|
||
### 3.6 重置密码
|
||
|
||
**接口地址：** `PUT /api/v1/user/{userId}/reset-password`
|
||
|
||
**接口说明：** 重置用户密码
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| newPassword | String | 是 | 新密码 |
|
||
|
||
---
|
||
|
||
## 四、租户管理接口
|
||
|
||
### 4.1 获取租户列表
|
||
|
||
**接口地址：** `GET /api/v1/tenant/list`
|
||
|
||
**接口说明：** 分页查询租户列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| tenantCode | String | 否 | 租户编码（模糊查询） |
|
||
| tenantName | String | 否 | 租户名称（模糊查询） |
|
||
| status | Integer | 否 | 状态：0-禁用，1-启用 |
|
||
|
||
---
|
||
|
||
### 4.2 获取租户详情
|
||
|
||
**接口地址：** `GET /api/v1/tenant/{tenantId}`
|
||
|
||
**接口说明：** 根据租户ID获取租户详细信息
|
||
|
||
---
|
||
|
||
### 4.3 新增租户
|
||
|
||
**接口地址：** `POST /api/v1/tenant`
|
||
|
||
**接口说明：** 创建新租户
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| tenantCode | String | 是 | 租户编码（唯一） |
|
||
| tenantName | String | 是 | 租户名称 |
|
||
| tenantType | Integer | 是 | 租户类型：1-一库多租户，2-一库一租户 |
|
||
| contactName | String | 否 | 联系人姓名 |
|
||
| contactPhone | String | 否 | 联系人电话 |
|
||
| contactEmail | String | 否 | 联系人邮箱 |
|
||
| expireTime | String | 否 | 过期时间（yyyy-MM-dd HH:mm:ss） |
|
||
|
||
---
|
||
|
||
### 4.4 更新租户
|
||
|
||
**接口地址：** `PUT /api/v1/tenant/{tenantId}`
|
||
|
||
**接口说明：** 更新租户信息
|
||
|
||
---
|
||
|
||
### 4.5 删除租户
|
||
|
||
**接口地址：** `DELETE /api/v1/tenant/{tenantId}`
|
||
|
||
**接口说明：** 删除租户
|
||
|
||
---
|
||
|
||
## 五、客户管理接口
|
||
|
||
### 5.1 获取客户列表
|
||
|
||
**接口地址：** `GET /api/v1/customer/list`
|
||
|
||
**接口说明：** 分页查询客户列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| customerName | String | 否 | 客户名称（模糊查询） |
|
||
| customerType | String | 否 | 客户类型 |
|
||
| level | String | 否 | 客户等级 |
|
||
| status | Integer | 否 | 状态 |
|
||
|
||
---
|
||
|
||
### 5.2 获取客户详情
|
||
|
||
**接口地址：** `GET /api/v1/customer/{customerId}`
|
||
|
||
**接口说明：** 根据客户ID获取客户详细信息
|
||
|
||
---
|
||
|
||
### 5.3 新增客户
|
||
|
||
**接口地址：** `POST /api/v1/customer`
|
||
|
||
**接口说明：** 创建新客户
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| customerCode | String | 是 | 客户编码 |
|
||
| customerName | String | 是 | 客户名称 |
|
||
| customerShort | String | 否 | 客户简称 |
|
||
| customerType | String | 否 | 客户类型 |
|
||
| industry | String | 否 | 所属行业 |
|
||
| scale | String | 否 | 企业规模 |
|
||
| level | String | 否 | 客户等级 |
|
||
| taxNo | String | 否 | 纳税人识别号 |
|
||
| legalPerson | String | 否 | 法定代表人 |
|
||
| address | String | 否 | 公司地址 |
|
||
| phone | String | 否 | 联系电话 |
|
||
| email | String | 否 | 邮箱地址 |
|
||
| website | String | 否 | 公司网站 |
|
||
|
||
---
|
||
|
||
### 5.4 更新客户
|
||
|
||
**接口地址：** `PUT /api/v1/customer/{customerId}`
|
||
|
||
**接口说明：** 更新客户信息
|
||
|
||
---
|
||
|
||
### 5.5 删除客户
|
||
|
||
**接口地址：** `DELETE /api/v1/customer/{customerId}`
|
||
|
||
**接口说明：** 删除客户
|
||
|
||
---
|
||
|
||
### 5.6 获取联系人列表
|
||
|
||
**接口地址：** `GET /api/v1/customer/{customerId}/contacts`
|
||
|
||
**接口说明：** 获取客户的联系人列表
|
||
|
||
---
|
||
|
||
### 5.7 新增联系人
|
||
|
||
**接口地址：** `POST /api/v1/customer/{customerId}/contacts`
|
||
|
||
**接口说明：** 为客户添加联系人
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| contactName | String | 是 | 联系人姓名 |
|
||
| position | String | 否 | 职位 |
|
||
| department | String | 否 | 部门 |
|
||
| phone | String | 否 | 电话 |
|
||
| mobile | String | 否 | 手机 |
|
||
| email | String | 否 | 邮箱 |
|
||
| isPrimary | Integer | 否 | 是否主要联系人：0-否，1-是 |
|
||
|
||
---
|
||
|
||
## 六、项目管理接口
|
||
|
||
### 6.1 获取项目列表
|
||
|
||
**接口地址：** `GET /api/v1/project/list`
|
||
|
||
**接口说明：** 分页查询项目列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| projectName | String | 否 | 项目名称（模糊查询） |
|
||
| customerId | Long | 否 | 客户ID |
|
||
| projectType | String | 否 | 项目类型 |
|
||
| status | String | 否 | 项目状态 |
|
||
|
||
---
|
||
|
||
### 6.2 获取项目详情
|
||
|
||
**接口地址：** `GET /api/v1/project/{projectId}`
|
||
|
||
**接口说明：** 根据项目ID获取项目详细信息
|
||
|
||
---
|
||
|
||
### 6.3 新增项目
|
||
|
||
**接口地址：** `POST /api/v1/project`
|
||
|
||
**接口说明：** 创建新项目
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| projectCode | String | 是 | 项目编号 |
|
||
| projectName | String | 是 | 项目名称 |
|
||
| projectShort | String | 否 | 项目简称 |
|
||
| customerId | Long | 是 | 客户ID |
|
||
| projectType | String | 否 | 项目类型 |
|
||
| projectManagerId | Long | 否 | 项目经理ID |
|
||
| startDate | String | 否 | 开始日期（yyyy-MM-dd） |
|
||
| endDate | String | 否 | 结束日期（yyyy-MM-dd） |
|
||
| budgetAmount | BigDecimal | 否 | 预算金额 |
|
||
| contractAmount | BigDecimal | 否 | 合同金额 |
|
||
| description | String | 否 | 项目描述 |
|
||
|
||
---
|
||
|
||
### 6.4 更新项目
|
||
|
||
**接口地址：** `PUT /api/v1/project/{projectId}`
|
||
|
||
**接口说明：** 更新项目信息
|
||
|
||
---
|
||
|
||
### 6.5 删除项目
|
||
|
||
**接口地址：** `DELETE /api/v1/project/{projectId}`
|
||
|
||
**接口说明：** 删除项目
|
||
|
||
---
|
||
|
||
### 6.6 获取项目成员列表
|
||
|
||
**接口地址：** `GET /api/v1/project/{projectId}/members`
|
||
|
||
**接口说明：** 获取项目成员列表
|
||
|
||
---
|
||
|
||
### 6.7 添加项目成员
|
||
|
||
**接口地址：** `POST /api/v1/project/{projectId}/members`
|
||
|
||
**接口说明：** 为项目添加成员
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| userId | Long | 是 | 用户ID |
|
||
| role | String | 是 | 项目角色 |
|
||
| workload | BigDecimal | 否 | 工作量占比 |
|
||
|
||
---
|
||
|
||
## 七、需求工单接口
|
||
|
||
### 7.1 获取需求列表
|
||
|
||
**接口地址：** `GET /api/v1/requirement/list`
|
||
|
||
**接口说明：** 分页查询需求工单列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| requirementName | String | 否 | 需求名称（模糊查询） |
|
||
| projectId | Long | 否 | 项目ID |
|
||
| priority | String | 否 | 优先级 |
|
||
| status | String | 否 | 状态 |
|
||
|
||
---
|
||
|
||
### 7.2 获取需求详情
|
||
|
||
**接口地址：** `GET /api/v1/requirement/{requirementId}`
|
||
|
||
**接口说明：** 根据需求ID获取需求详细信息
|
||
|
||
---
|
||
|
||
### 7.3 新增需求
|
||
|
||
**接口地址：** `POST /api/v1/requirement`
|
||
|
||
**接口说明：** 创建新需求工单
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| requirementCode | String | 是 | 需求编号 |
|
||
| requirementName | String | 是 | 需求名称 |
|
||
| description | String | 否 | 需求描述 |
|
||
| projectId | Long | 是 | 项目ID |
|
||
| customerId | Long | 是 | 客户ID |
|
||
| priority | String | 否 | 优先级 |
|
||
| estimatedHours | BigDecimal | 否 | 预估工时 |
|
||
| plannedStart | String | 否 | 计划开始日期 |
|
||
| plannedEnd | String | 否 | 计划结束日期 |
|
||
| receivableAmount | BigDecimal | 否 | 应收款金额 |
|
||
| receivableDate | String | 否 | 应收款日期 |
|
||
|
||
---
|
||
|
||
### 7.4 更新需求
|
||
|
||
**接口地址：** `PUT /api/v1/requirement/{requirementId}`
|
||
|
||
**接口说明：** 更新需求信息
|
||
|
||
---
|
||
|
||
### 7.5 删除需求
|
||
|
||
**接口地址：** `DELETE /api/v1/requirement/{requirementId}`
|
||
|
||
**接口说明：** 删除需求
|
||
|
||
---
|
||
|
||
## 八、支出管理接口
|
||
|
||
### 8.1 获取支出类型列表
|
||
|
||
**接口地址：** `GET /api/v1/expense-type/list`
|
||
|
||
**接口说明：** 获取支出类型树形列表
|
||
|
||
---
|
||
|
||
### 8.2 获取支出列表
|
||
|
||
**接口地址：** `GET /api/v1/expense/list`
|
||
|
||
**接口说明：** 分页查询支出列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| expenseTypeId | Long | 否 | 支出类型ID |
|
||
| projectId | Long | 否 | 项目ID |
|
||
| startDate | String | 否 | 开始日期 |
|
||
| endDate | String | 否 | 结束日期 |
|
||
| status | String | 否 | 状态 |
|
||
|
||
---
|
||
|
||
### 8.3 新增支出
|
||
|
||
**接口地址：** `POST /api/v1/expense`
|
||
|
||
**接口说明：** 创建新支出记录
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| expenseCode | String | 是 | 支出编号 |
|
||
| expenseTypeId | Long | 是 | 支出类型ID |
|
||
| expenseAmount | BigDecimal | 是 | 支出金额 |
|
||
| expenseDate | String | 是 | 支出日期 |
|
||
| expenseReason | String | 否 | 支出事由 |
|
||
| projectId | Long | 否 | 项目ID |
|
||
| paymentMethod | String | 否 | 付款方式 |
|
||
|
||
---
|
||
|
||
### 8.4 更新支出
|
||
|
||
**接口地址：** `PUT /api/v1/expense/{expenseId}`
|
||
|
||
**接口说明：** 更新支出信息
|
||
|
||
---
|
||
|
||
### 8.5 删除支出
|
||
|
||
**接口地址：** `DELETE /api/v1/expense/{expenseId}`
|
||
|
||
**接口说明：** 删除支出记录
|
||
|
||
---
|
||
|
||
## 九、应收款管理接口
|
||
|
||
### 9.1 获取应收款列表
|
||
|
||
**接口地址：** `GET /api/v1/receivable/list`
|
||
|
||
**接口说明：** 分页查询应收款列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| current | Integer | 否 | 当前页码 |
|
||
| size | Integer | 否 | 每页大小 |
|
||
| projectId | Long | 否 | 项目ID |
|
||
| customerId | Long | 否 | 客户ID |
|
||
| status | String | 否 | 状态 |
|
||
|
||
---
|
||
|
||
### 9.2 获取应收款详情
|
||
|
||
**接口地址：** `GET /api/v1/receivable/{receivableId}`
|
||
|
||
**接口说明：** 根据应收款ID获取详细信息
|
||
|
||
---
|
||
|
||
### 9.3 新增应收款
|
||
|
||
**接口地址：** `POST /api/v1/receivable`
|
||
|
||
**接口说明：** 创建新应收款
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| receivableCode | String | 是 | 应收款编号 |
|
||
| requirementId | Long | 是 | 需求ID |
|
||
| projectId | Long | 是 | 项目ID |
|
||
| customerId | Long | 是 | 客户ID |
|
||
| receivableAmount | BigDecimal | 是 | 应收款金额 |
|
||
| receivableDate | String | 是 | 应收款日期 |
|
||
| paymentDueDate | String | 否 | 付款截止日期 |
|
||
|
||
---
|
||
|
||
### 9.4 获取收款记录列表
|
||
|
||
**接口地址：** `GET /api/v1/receivable/{receivableId}/receipts`
|
||
|
||
**接口说明：** 获取应收款的收款记录
|
||
|
||
---
|
||
|
||
### 9.5 新增收款记录
|
||
|
||
**接口地址：** `POST /api/v1/receivable/{receivableId}/receipts`
|
||
|
||
**接口说明：** 添加收款记录
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| receiptAmount | BigDecimal | 是 | 收款金额 |
|
||
| receiptDate | String | 是 | 收款日期 |
|
||
| receiptMethod | String | 否 | 收款方式 |
|
||
| receiptAccount | String | 否 | 收款账户 |
|
||
| payerName | String | 否 | 付款方名称 |
|
||
|
||
---
|
||
|
||
## 十、附录
|
||
|
||
### 10.1 枚举值定义
|
||
|
||
#### 性别（gender）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| 0 | 未知 |
|
||
| 1 | 男 |
|
||
| 2 | 女 |
|
||
|
||
#### 状态（status）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| 0 | 禁用/停用 |
|
||
| 1 | 启用/正常 |
|
||
|
||
#### 租户类型（tenantType）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| 1 | 一库多租户 |
|
||
| 2 | 一库一租户 |
|
||
|
||
#### 客户类型（customerType）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| enterprise | 企业 |
|
||
| individual | 个人 |
|
||
|
||
#### 客户等级（level）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| A | A级客户 |
|
||
| B | B级客户 |
|
||
| C | C级客户 |
|
||
| D | D级客户 |
|
||
| normal | 普通客户 |
|
||
|
||
#### 项目类型（projectType）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| development | 开发 |
|
||
| maintenance | 维护 |
|
||
| consulting | 咨询 |
|
||
|
||
#### 项目状态（status）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| preparing | 筹备中 |
|
||
| ongoing | 进行中 |
|
||
| completed | 已完成 |
|
||
| archived | 已归档 |
|
||
| cancelled | 已取消 |
|
||
|
||
#### 需求优先级（priority）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| high | 高 |
|
||
| normal | 中 |
|
||
| low | 低 |
|
||
|
||
#### 需求状态（status）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| pending | 待开发 |
|
||
| developing | 开发中 |
|
||
| delivered | 已交付 |
|
||
| completed | 已完成 |
|
||
|
||
#### 支出状态（status）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| pending | 待付款 |
|
||
| paid | 已付款 |
|
||
| completed | 已完成 |
|
||
| cancelled | 已作废 |
|
||
|
||
#### 应收款状态（status）
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| pending | 待收款 |
|
||
| partial | 部分收款 |
|
||
| received | 已收款 |
|
||
| overdue | 逾期 |
|
||
|
||
---
|
||
|
||
### 10.2 数据类型说明
|
||
|
||
| 类型 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| String | 字符串 | "hello" |
|
||
| Integer | 整数 | 100 |
|
||
| Long | 长整数 | 10000000000 |
|
||
| BigDecimal | 高精度小数（金额） | 100.50 |
|
||
| Boolean | 布尔值 | true/false |
|
||
| Array | 数组 | [1, 2, 3] |
|
||
| Object | 对象 | {"key": "value"} |
|
||
|
||
---
|
||
|
||
**文档结束**
|