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（系统自动生成）

请求示例

POST /api/v1/user/login HTTP/1.1
Host: api.fundplatform.com
Content-Type: application/json
X-Tenant-Id: 1

{
  "username": "admin",
  "password": "admin123"
}

1.3 响应规范

统一响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

响应字段说明

字段	类型	说明
code	Integer	状态码（200成功，其他为错误码）
message	String	提示信息
data	Object	业务数据（可为 null）
timestamp	Long	时间戳（毫秒）
traceId	String	链路追踪ID

分页响应格式

{
  "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	否	租户编码（多租户模式必填）

请求示例：

{
  "username": "admin",
  "password": "e10adc3949ba59abbe56e057f20f883e",
  "tenantCode": "SYSTEM"
}

响应参数：

参数名	类型	说明
accessToken	String	访问令牌
refreshToken	String	刷新令牌
expiresIn	Long	访问令牌过期时间（秒）
tokenType	String	令牌类型（Bearer）
userInfo	Object	用户信息

响应示例：

{
  "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

响应示例：

{
  "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

接口说明： 获取当前登录用户详细信息

响应示例：

{
  "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-启用

响应示例：

{
  "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

响应示例：

{
  "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）

请求示例：

{
  "username": "newuser",
  "password": "123456",
  "realName": "新用户",
  "gender": 1,
  "phone": "13800138010",
  "email": "newuser@fundplatform.com",
  "deptId": 2,
  "position": "开发工程师",
  "roleIds": [5],
  "status": 1
}

响应示例：

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

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

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

请求参数：

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

响应示例：

{
  "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

响应示例：

{
  "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	否	备注说明

请求示例：

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

响应示例：

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

---

10.4 更新收款记录

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

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

路径参数：

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

请求参数： 同创建接口

响应示例：

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

---

10.5 删除收款记录

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

接口说明： 删除收款记录

路径参数：

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

响应示例：

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

---

十一、附录

11.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"}

---

文档结束