fundplatform/doc/API接口文档.md

# 资金服务平台 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 获取部门树

**接口地址：** `GET /api/v1/dept/tree`

**接口说明：** 获取部门树形结构（含层级关系）

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| tenantId | Long | 否 | 租户ID（不传则使用默认租户） |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "deptId": 1,
      "tenantId": 1,
      "deptName": "万家布洛科技",
      "parentId": 0,
      "deptCode": "ROOT",
      "deptLevel": 1,
      "sortOrder": 1,
      "leader": "张三",
      "leaderPhone": "13800138000",
      "status": 1,
      "remark": "总公司",
      "children": [
        {
          "deptId": 2,
          "deptName": "技术部",
          "parentId": 1,
          "deptCode": "TECH",
          "deptLevel": 2,
          "sortOrder": 1,
          "leader": "李四",
          "leaderPhone": "13900139000",
          "status": 1,
          "children": []
        }
      ]
    }
  ]
}
```

---

### 2.2 获取部门列表

**接口地址：** `GET /api/v1/dept/list`

**接口说明：** 获取部门列表（扁平结构）

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| tenantId | Long | 否 | 租户ID（不传则使用默认租户） |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "deptId": 1,
      "tenantId": 1,
      "deptName": "万家布洛科技",
      "parentId": 0,
      "deptCode": "ROOT",
      "deptLevel": 1,
      "sortOrder": 1,
      "leader": "张三",
      "leaderPhone": "13800138000",
      "status": 1,
      "remark": "总公司"
    }
  ]
}
```

---

### 2.3 获取部门详情

**接口地址：** `GET /api/v1/dept/{deptId}`

**接口说明：** 根据ID查询部门详情

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deptId | Long | 是 | 部门ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "deptId": 1,
    "tenantId": 1,
    "deptName": "万家布洛科技",
    "parentId": 0,
    "deptCode": "ROOT",
    "deptLevel": 1,
    "sortOrder": 1,
    "leader": "张三",
    "leaderPhone": "13800138000",
    "status": 1,
    "remark": "总公司",
    "createdTime": "2026-01-01 10:00:00"
  }
}
```

---

### 2.4 新增部门

**接口地址：** `POST /api/v1/dept`

**接口说明：** 创建新部门

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deptName | String | 是 | 部门名称 |
| parentId | Long | 是 | 父部门ID（顶级部门为0） |
| deptCode | String | 否 | 部门编码 |
| deptLevel | Integer | 否 | 部门层级（系统自动计算） |
| sortOrder | Integer | 否 | 排序号 |
| leader | String | 否 | 负责人 |
| leaderPhone | String | 否 | 负责人电话 |
| status | Integer | 否 | 状态（0-禁用，1-启用，默认1） |
| remark | String | 否 | 备注 |

**请求示例：**

```json
{
  "deptName": "技术部",
  "parentId": 1,
  "deptCode": "TECH",
  "sortOrder": 1,
  "leader": "李四",
  "leaderPhone": "13900139000",
  "status": 1,
  "remark": "技术研发部门"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "创建成功",
  "data": null
}
```

---

### 2.5 更新部门

**接口地址：** `PUT /api/v1/dept/{deptId}`

**接口说明：** 更新部门信息

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deptId | Long | 是 | 部门ID |

**请求参数：** 同2.4

**响应示例：**

```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 2.6 删除部门

**接口地址：** `DELETE /api/v1/dept/{deptId}`

**接口说明：** 删除指定部门（若有子部门则无法删除）

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deptId | Long | 是 | 部门ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

## 三、认证接口

### 3.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 | 否 | 工作量占比 |

---

### 6.6 获取项目成员列表（按项目ID）

**接口地址：** `GET /api/v1/project-member/list/project/{projectId}`

**接口说明：** 查询指定项目的所有成员

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| projectId | Long | 是 | 项目ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "memberId": 1,
      "tenantId": 1,
      "projectId": 1,
      "userId": 5,
      "role": "pm",
      "joinDate": "2026-01-01",
      "leaveDate": null,
      "workload": 80.00,
      "status": 1,
      "remark": "项目负责人",
      "createdTime": "2026-01-01 10:00:00"
    }
  ]
}
```

---

### 6.7 获取用户的项目列表（按用户ID）

**接口地址：** `GET /api/v1/project-member/list/user/{userId}`

**接口说明：** 查询指定用户参与的所有项目

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| userId | Long | 是 | 用户ID |

**响应示例：** 同6.6

---

### 6.8 获取项目成员详情

**接口地址：** `GET /api/v1/project-member/{memberId}`

**接口说明：** 根据ID查询项目成员详情

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| memberId | Long | 是 | 成员关系ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "memberId": 1,
    "tenantId": 1,
    "projectId": 1,
    "userId": 5,
    "role": "pm",
    "joinDate": "2026-01-01",
    "leaveDate": null,
    "workload": 80.00,
    "status": 1,
    "remark": "项目负责人",
    "createdTime": "2026-01-01 10:00:00"
  }
}
```

---

### 6.9 添加项目成员

**接口地址：** `POST /api/v1/project-member`

**接口说明：** 添加新的项目成员

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| projectId | Long | 是 | 项目ID |
| userId | Long | 是 | 用户ID |
| role | String | 是 | 项目角色（pm/dev/test/finance/member） |
| joinDate | Date | 否 | 加入日期 |
| workload | Decimal | 否 | 工作量占比（0-100） |
| remark | String | 否 | 备注说明 |

**请求示例：**

```json
{
  "projectId": 1,
  "userId": 5,
  "role": "dev",
  "joinDate": "2026-02-16",
  "workload": 50.00,
  "remark": "后端开发"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

---

### 6.10 更新项目成员

**接口地址：** `PUT /api/v1/project-member/{memberId}`

**接口说明：** 更新项目成员信息

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| memberId | Long | 是 | 成员关系ID |

**请求参数：** 同6.9

**响应示例：**

```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 6.11 移除项目成员

**接口地址：** `DELETE /api/v1/project-member/{memberId}`

**接口说明：** 从项目中移除成员

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| memberId | Long | 是 | 成员关系ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "移除成功",
  "data": null
}
```

---

### 6.12 更新成员状态

**接口地址：** `PUT /api/v1/project-member/{memberId}/status`

**接口说明：** 更新项目成员状态（在职/离开）

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| memberId | Long | 是 | 成员关系ID |

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| status | Integer | 是 | 状态（0-已离开，1-在职） |

**响应示例：**

```json
{
  "code": 200,
  "message": "状态更新成功",
  "data": null
}
```

---

## 八、需求工单接口

### 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 获取收款记录列表

**接口地址：** `GET /api/v1/receipt/list`

**接口说明：** 分页查询收款记录列表

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| current | Integer | 否 | 当前页码（默认1） |
| size | Integer | 否 | 每页大小（默认10） |
| receiptCode | String | 否 | 收款编号（模糊查询） |
| receivableId | Long | 否 | 应收款ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "receiptId": 1,
        "tenantId": 1,
        "receiptCode": "REC-2026-001",
        "receivableId": 1,
        "receiptAmount": 5000.00,
        "receiptDate": "2026-02-15",
        "receiptMethod": "transfer",
        "receiptAccount": "6222021234567890",
        "payerName": "阿里巴巴集团",
        "receiptVoucher": "V-20260215-001",
        "operatorId": 1,
        "remark": "首次付款",
        "createdTime": "2026-02-15 10:30:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}
```

---

### 10.2 获取收款记录详情

**接口地址：** `GET /api/v1/receipt/{receiptId}`

**接口说明：** 根据ID查询收款记录详情

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| receiptId | Long | 是 | 收款记录ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "receiptId": 1,
    "tenantId": 1,
    "receiptCode": "REC-2026-001",
    "receivableId": 1,
    "receiptAmount": 5000.00,
    "receiptDate": "2026-02-15",
    "receiptMethod": "transfer",
    "receiptAccount": "6222021234567890",
    "payerName": "阿里巴巴集团",
    "receiptVoucher": "V-20260215-001",
    "operatorId": 1,
    "remark": "首次付款",
    "createdTime": "2026-02-15 10:30:00"
  }
}
```

---

### 10.3 创建收款记录

**接口地址：** `POST /api/v1/receipt`

**接口说明：** 创建新的收款记录

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| receiptCode | String | 是 | 收款编号 |
| receivableId | Long | 是 | 应收款ID |
| receiptAmount | Decimal | 是 | 收款金额 |
| receiptDate | Date | 否 | 收款日期 |
| receiptMethod | String | 否 | 收款方式（transfer/cash/check/other） |
| receiptAccount | String | 否 | 收款账户 |
| payerName | String | 否 | 付款方名称 |
| receiptVoucher | String | 否 | 收款凭证 |
| operatorId | Long | 否 | 经办人ID（默认为当前用户） |
| remark | String | 否 | 备注说明 |

**请求示例：**

```json
{
  "receiptCode": "REC-2026-002",
  "receivableId": 1,
  "receiptAmount": 3000.00,
  "receiptDate": "2026-02-16",
  "receiptMethod": "transfer",
  "receiptAccount": "6222021234567890",
  "payerName": "阿里巴巴集团",
  "receiptVoucher": "V-20260216-001",
  "remark": "二次付款"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "创建成功",
  "data": null
}
```

---

### 10.4 更新收款记录

**接口地址：** `PUT /api/v1/receipt/{receiptId}`

**接口说明：** 更新收款记录信息

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| receiptId | Long | 是 | 收款记录ID |

**请求参数：** 同创建接口

**响应示例：**

```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 10.5 删除收款记录

**接口地址：** `DELETE /api/v1/receipt/{receiptId}`

**接口说明：** 删除收款记录

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| receiptId | Long | 是 | 收款记录ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

## 十二、操作日志管理接口

### 11.1 获取操作日志列表

**接口地址：** `GET /api/v1/operation-log/list`

**接口说明：** 分页查询操作日志列表，支持多条件过滤

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| current | Long | 否 | 当前页码，默认1 |
| size | Long | 否 | 每页条数，默认10 |
| module | String | 否 | 模块名称（模糊查询） |
| operationType | String | 否 | 操作类型（SELECT/INSERT/UPDATE/DELETE/IMPORT/EXPORT/LOGIN/LOGOUT） |
| operatorId | Long | 否 | 操作人ID |
| startTime | DateTime | 否 | 开始时间（格式：yyyy-MM-dd HH:mm:ss） |
| endTime | DateTime | 否 | 结束时间（格式：yyyy-MM-dd HH:mm:ss） |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "logId": 1,
        "tenantId": 1,
        "module": "用户管理",
        "operationType": "INSERT",
        "description": "创建用户",
        "requestMethod": "POST",
        "requestUrl": "/api/v1/user",
        "requestParams": "{\"username\":\"test\"}",
        "responseResult": "{\"code\":200}",
        "executionTime": 150,
        "operatorId": 1,
        "operatorName": "admin",
        "operatorIp": "192.168.1.100",
        "operatorLocation": "北京市",
        "status": 1,
        "errorMsg": null,
        "createdTime": "2026-02-13 10:00:00"
      }
    ],
    "total": 100,
    "size": 10,
    "current": 1
  }
}
```

---

### 11.2 获取操作日志详情

**接口地址：** `GET /api/v1/operation-log/{logId}`

**接口说明：** 根据ID查询操作日志详情

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| logId | Long | 是 | 日志ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "logId": 1,
    "tenantId": 1,
    "module": "用户管理",
    "operationType": "INSERT",
    "description": "创建用户",
    "requestMethod": "POST",
    "requestUrl": "/api/v1/user",
    "requestParams": "{\"username\":\"test\",\"email\":\"test@example.com\"}",
    "responseResult": "{\"code\":200,\"message\":\"操作成功\"}",
    "executionTime": 150,
    "operatorId": 1,
    "operatorName": "admin",
    "operatorIp": "192.168.1.100",
    "operatorLocation": "北京市",
    "status": 1,
    "errorMsg": null,
    "createdTime": "2026-02-13 10:00:00"
  }
}
```

---

### 11.3 删除操作日志

**接口地址：** `DELETE /api/v1/operation-log/{logId}`

**接口说明：** 删除指定的操作日志

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| logId | Long | 是 | 日志ID |

**响应示例：**

```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

### 11.4 批量删除操作日志

**接口地址：** `DELETE /api/v1/operation-log/batch`

**接口说明：** 批量删除指定天数之前的操作日志

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| days | Long | 是 | 天数（删除N天前的日志，建议7-365） |

**响应示例：**

```json
{
  "code": 200,
  "message": "批量删除成功",
  "data": null
}
```

---

### 11.5 操作类型说明

| 操作类型 | 说明 | 标签颜色 |
|----------|------|----------|
| SELECT | 查询操作 | 默认 |
| INSERT | 新增操作 | 绿色 |
| UPDATE | 更新操作 | 橙色 |
| DELETE | 删除操作 | 红色 |
| IMPORT | 导入操作 | 灰色 |
| EXPORT | 导出操作 | 灰色 |
| LOGIN | 登录操作 | 绿色 |
| LOGOUT | 登出操作 | 灰色 |

---

## 十三、附录

### 12.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"} |

---

**文档结束**